Workflow Schema Guide

Learn how to write valid AKIOS workflows. This guide explains the workflow structure, validation rules, and provides examples to get you started.

Why Workflows Are Validated

AKIOS validates workflows before execution to:

• Catch errors early (before spending money on API calls)
• Prevent security issues
• Ensure predictable behavior
• Provide clear error messages

Validation is automatic - just run your workflow and AKIOS will tell you if something's wrong.

Basic Workflow Structure

Every workflow needs:

name: "My Workflow"              # Required: Workflow name
description: "What it does"     # Recommended: Description

steps:                           # Required: List of steps
  - name: "Step 1"              # Required: Step name
    agent: "llm"                # Required: Which agent
    action: "complete"          # Required: What action
    parameters:                 # Required: Action parameters
      prompt: "Hello"

Minimum valid workflow:

name: "Hello"
description: "Simple greeting"
steps:
  - name: "Greet"
    agent: llm
    action: complete
    parameters:
      prompt: "Say hello"

Available Agents

AKIOS provides four core agents:

Agent: llm (AI Models)

Generate text using AI models.

Actions:

• complete - Generate text completion
• chat - Chat-style conversation

Example:

- name: "Generate text"
  agent: llm
  action: complete
  parameters:
    model: "gpt-4o"
    prompt: "Write a poem about security"
    max_tokens: 500

Agent: http (Web Requests)

Make HTTP/HTTPS requests to APIs.

Actions:

• get - HTTP GET request
• post - HTTP POST request
• put - HTTP PUT request
• delete - HTTP DELETE request

Example:

- name: "Fetch data"
  agent: http
  action: get
  parameters:
    url: "https://api.example.com/data"
    headers:
      Authorization: "Bearer {{API_TOKEN}}"
    timeout: 30

Agent: filesystem (File Operations)

Read and write files safely.

Actions:

• read - Read file content
• write - Write content to file
• list - List directory contents
• stat - Get file metadata
• exists - Check if file exists

Example:

- name: "Read document"
  agent: filesystem
  action: read
  parameters:
    path: "data/input/document.txt"

Agent: tool_executor (Commands)

Run allowlisted commands safely.

Actions:

• run - Execute command

Example:

- name: "List files"
  agent: tool_executor
  action: run
  parameters:
    command: ["ls", "-la", "data/"]
    timeout: 10

Complete Workflow Examples

Example 1: Simple AI Generation

name: "Creative Writer"
description: "Generate creative content with AI"

steps:
  - name: "Generate story"
    agent: llm
    action: complete
    parameters:
      model: "gpt-4o"
      prompt: "Write a short story about a security-conscious robot"
      max_tokens: 1000
      
  - name: "Save story"
    agent: filesystem
    action: write
    parameters:
      path: "data/output/story.txt"
      content: "{{previous_output}}"

Example 2: Multi-Step Pipeline

name: "Document Summarizer"
description: "Read document, summarize, and save"

steps:
  - name: "Read input"
    agent: filesystem
    action: read
    parameters:
      path: "data/input/report.txt"
      
  - name: "Generate summary"
    agent: llm
    action: complete
    parameters:
      model: "gpt-4o"
      prompt: "Summarize this report: {{previous_output}}"
      max_tokens: 200
      
  - name: "Save summary"
    agent: filesystem
    action: write
    parameters:
      path: "data/output/summary.txt"
      content: "{{summary}}"

Example 3: API Integration

name: "Data Enrichment"
description: "Fetch data from API and analyze"

steps:
  - name: "Fetch customer data"
    agent: http
    action: get
    parameters:
      url: "https://api.example.com/customers/{{customer_id}}"
      headers:
        Authorization: "Bearer {{API_TOKEN}}"
      
  - name: "Analyze data"
    agent: llm
    action: complete
    parameters:
      prompt: "Analyze this customer profile: {{previous_output}}"
      
  - name: "Save analysis"
    agent: filesystem
    action: write
    parameters:
      path: "data/output/analysis_{{customer_id}}.json"
      content: "{{analysis}}"

Common Validation Failures

Missing Required Fields

❌ Invalid:

steps:
  - name: "Step 1"
    agent: llm
    # Missing: action and parameters

✅ Valid:

steps:
  - name: "Step 1"
    agent: llm
    action: complete
    parameters:
      prompt: "Hello"

Unknown Agent

❌ Invalid:

steps:
  - agent: gpt  # Wrong agent name
    action: complete

✅ Valid:

steps:
  - agent: llm  # Correct agent name
    action: complete

Invalid Action for Agent

❌ Invalid:

steps:
  - agent: filesystem
    action: execute  # 'execute' doesn't exist for filesystem

✅ Valid:

steps:
  - agent: filesystem
    action: read  # 'read' is valid

Missing Parameters

❌ Invalid:

steps:
  - agent: llm
    action: complete
    # Missing parameters

✅ Valid:

steps:
  - agent: llm
    action: complete
    parameters:
      prompt: "Hello"

Variable Substitution

Reference previous step outputs:

steps:
  - name: "step1"
    agent: filesystem
    action: read
    parameters:
      path: "input.txt"
      
  - name: "step2"
    agent: llm
    action: complete
    parameters:
      prompt: "Analyze: {{previous_output}}"
      # Or: {{step1.content}}

Available variables:

• {{previous_output}} - Output from previous step
• {{step_name.field}} - Specific field from named step
• {{ENV_VAR}} - Environment variable from .env

Validation Tips

✓ Do:

• Use valid agent names (llm, http, filesystem, tool_executor)
• Include all required fields (name, agent, action, parameters)
• Match actions to agents correctly
• Provide all required parameters for each action

✗ Don't:

• Use made-up agent names
• Skip required fields
• Use invalid actions for agents
• Forget parameters

Testing Workflows

Validate before running:

# AKIOS validates automatically on run
akios run workflow.yml

# If invalid, you'll see clear error:
# Error in step 'analyze': action 'execute' not allowed for agent 'filesystem'
# Hint: Did you mean 'read'?

Test in mock mode (free):

export AKIOS_MOCK_LLM=1
akios run workflow.yml

Advanced Features

Conditional Execution

Skip steps based on conditions using the condition field. Conditions are evaluated using a safe AST-based evaluator (no eval(), no code injection risk):

steps:
  - name: "Check size"
    agent: filesystem
    action: stat
    parameters:
      path: "data/input/file.txt"
      
  - name: "Process if small"
    agent: llm
    action: complete
    condition: "previous_output.size <= 1048576"
    parameters:
      prompt: "Analyze: {{file}}"

Note: The skip_if parameter is still accepted as a backward-compatible alias.

Error Recovery

Control what happens when a step fails using the on_error field:

steps:
  - name: "Fetch data"
    agent: http
    action: get
    on_error: retry        # retry with exponential backoff
    parameters:
      url: "https://api.example.com/data"

  - name: "Fallback processing"
    agent: llm
    action: complete
    on_error: skip         # skip on failure, continue workflow
    parameters:
      prompt: "Process: {previous_output}"

Retry Logic

Retry failed steps with explicit parameters:

steps:
  - name: "Fetch data"
    agent: http
    action: get
    parameters:
      url: "https://api.example.com/data"
      retry_count: 3
      retry_delay: 5

Timeouts

Set execution timeouts:

steps:
  - name: "Long operation"
    agent: tool_executor
    action: run
    parameters:
      command: ["python", "script.py"]
      timeout: 300  # 5 minutes

Workflow Best Practices

✓ Good workflow structure:

name: "Clear Name"
description: "What this workflow does and why"

steps:
  - name: "Descriptive step name"
    agent: filesystem
    action: read
    parameters:
      path: "data/input/doc.txt"
    # Clear, single responsibility
    
  - name: "Another clear step"
    agent: llm
    action: complete
    parameters:
      prompt: "Specific task: {{previous_output}}"
    # References previous step clearly

✗ Poor workflow structure:

name: "workflow"  # Too vague

steps:
  - name: "do stuff"  # Unclear
    agent: llm
    action: complete
    parameters:
      prompt: "do everything"  # Too broad

Related Docs

• Quickstart - Build your first workflow
• Concepts - Understanding agents
• Use Cases - Real-world examples
• Debugging - Fix validation errors