AKIOS Logo AKIOS
EN | FR

Best Practices

Proven patterns for building reliable, secure AKIOS workflows. Follow these guidelines to avoid common pitfalls and maximize productivity.

Project Organization

Directory Structure

Organize your project for clarity:

my-akios-project/
├── config.yaml           # Runtime configuration
├── .env                  # API keys (DON'T COMMIT)
├── .gitignore           # Exclude .env, audit/, data/
├── workflows/
│   ├── production/      # Production workflows
│   │   └── process-docs.yml
│   └── development/     # Dev workflows
│       └── test-flow.yml
├── templates/           # Reusable workflow templates
│   └── common-tasks.yml
├── data/
│   ├── input/          # Source files
│   ├── output/         # Results
│   └── archive/        # Old runs
└── audit/              # Tamper-evident logs
    └── audit_events.jsonl

Version Control

Commit to git:

  • ✅ config.yaml
  • ✅ workflows/
  • ✅ templates/
  • ✅ .gitignore

NEVER commit:

  • ❌ .env (contains API keys)
  • ❌ audit/ (contains sensitive logs)
  • ❌ data/ (contains user data)

Example .gitignore:

.env
*.env
audit/
data/
*.log

Configuration Management

Environment-Specific Configs

Use different settings per environment:

# Development
cp .env.development .env
akios run workflows/development/test.yml

# Production
cp .env.production .env
akios run workflows/production/process.yml

Example .env.development:

AKIOS_LLM_PROVIDER=grok
GROK_API_KEY=dev-key-here
AKIOS_LLM_MODEL=grok-3
AKIOS_BUDGET_LIMIT_PER_RUN=5.0
AKIOS_NETWORK_ACCESS_ALLOWED=1

Example .env.production:

AKIOS_LLM_PROVIDER=grok
GROK_API_KEY=prod-key-here
AKIOS_LLM_MODEL=grok-3
AKIOS_BUDGET_LIMIT_PER_RUN=1.0
AKIOS_NETWORK_ACCESS_ALLOWED=0

Least Privilege Configuration

Always restrict access to minimum needed:

# config.yaml - Production example
filesystem:
  allowed_paths:
    - "./data/input"      # Only read from input
    - "./data/output"     # Only write to output
  # DON'T allow: ./config, ./.env, /etc, /home

network_access_allowed: false  # Deny unless required

sandbox_enabled: true         # Always true

Workflow Design

Keep Steps Small

Break complex workflows into simple steps:

❌ Don't: One giant step

steps:
  - agent: llm
    action: complete
    parameters:
      prompt: "Read file, analyze, summarize, translate, format"

✅ Do: Multiple focused steps

steps:
  - name: "Read document"
    agent: filesystem
    action: read
    
  - name: "Analyze content"
    agent: llm
    action: complete
    
  - name: "Summarize"
    agent: llm
    action: complete
    
  - name: "Save result"
    agent: filesystem
    action: write

Input Validation

Validate early, fail fast:

steps:
  - name: "Check file exists"
    agent: filesystem
    action: stat
    parameters:
      path: "data/input/document.txt"
      
  - name: "Check file size"
    agent: filesystem
    action: stat
    parameters:
      path: "data/input/document.txt"
    # Skip if too large (condition uses AST-safe evaluator)
    condition: "size <= 10485760"  # 10MB
    
  - name: "Process document"
    agent: llm
    action: complete

Tip: Use condition for conditional step execution. The older skip_if syntax still works as an alias.

Error Handling

Handle failures gracefully with on_error:

steps:
  - name: "Fetch data from API"
    agent: http
    action: get
    on_error: retry          # retry, skip, or fail (default)
    parameters:
      url: "https://api.example.com/data"
      retry_count: 3        # Retry on failure
      retry_delay: 5        # Wait 5 seconds
      timeout: 30           # 30 second timeout

on_error strategies:

  • fail — Stop workflow immediately (default)
  • skip — Log warning and continue to next step
  • retry — Retry with retry_count and retry_delay

Security Practices

Restrict File Access

Only allow necessary paths:

# config.yaml
filesystem:
  allowed_paths:
    - "./data/input"
    - "./data/output"

Never allow:

  • ./config - Configuration files
  • ./.env - API keys
  • /etc - System files
  • /home - User directories
  • .. - Parent directories

Rotate API Keys

Change keys regularly:

# Development keys: Monthly
# Production keys: Quarterly
# Compromised keys: Immediately

Enable Audit Logging

Always keep audit trail:

# config.yaml
audit_enabled: true
audit_storage_path: "./audit/"

Verify audit integrity:

# Check audit logs
akios audit verify

# Export for compliance
akios audit export --format json > audit-report.json

Use PII Redaction

Protect sensitive data:

# config.yaml
pii_redaction_enabled: true
pii_redaction_outputs: true
redaction_strategy: "mask"

Redacts:

  • Email addresses
  • Phone numbers
  • Credit cards
  • Social Security Numbers
  • 53 other patterns (including insurance identifiers)

Performance Optimization

Set Appropriate Limits

# Development: More resources
cpu_limit: 0.8
memory_limit_mb: 512

# Production: Conservative
cpu_limit: 0.5
memory_limit_mb: 256

Handle Large Files

Check size before processing:

steps:
  - name: "Check file size"
    agent: filesystem
    action: stat
    parameters:
      path: "data/input/large-file.txt"
      
  - name: "Process if small"
    agent: llm
    action: complete
    condition: "size <= 1048576"  # Only if ≤ 1MB
    
  - name: "Summarize if large"
    agent: llm
    action: complete
    condition: "size > 1048576"   # Only if > 1MB
    parameters:
      prompt: "Generate brief summary only"

Clean Old Runs

Manage disk space:

# Keep last 7 days
akios clean --old-runs 7

# Clean specific workflow
akios clean --workflow my-workflow

Testing Workflows

Use Mock Mode

Test without real API calls:

# Set mock mode
export AKIOS_MOCK_LLM=1
export AKIOS_NETWORK_ACCESS_ALLOWED=0

# Run workflow
akios run workflows/test-flow.yml

Create Test Data

# Use templates with known inputs
mkdir -p data/input/test
echo "Test document" > data/input/test/sample.txt

# Run against test data
akios run workflows/process.yml

Validate Outputs

# Check output exists
test -f data/output/result.txt && echo "Success"

# Verify content
cat data/output/result.txt

Monitoring & Operations

Health Checks

Monitor AKIOS status:

# Basic health check
akios status

# Verbose status
akios status --verbose

# Security status
akios status --security

Audit Maintenance

Regularly export and verify:

# Weekly audit export
akios audit export --format json > audit-$(date +%Y-%m-%d).json

# Verify integrity
akios audit verify

# Archive old logs
mv audit/audit_events.jsonl audit/archive/audit-$(date +%Y-%m-%d).jsonl

Disk Space Management

# Monitor usage
du -sh data/ audit/

# Clean old runs
akios clean --old-runs 30

# Archive completed runs
tar -czf archive-$(date +%Y-%m-%d).tar.gz data/output/

Related Docs

ESC