Workflows API

Multi-agent pipelines and orchestration

Overview

Workflows enable complex multi-agent pipelines where tasks flow between agents in sequence or parallel. Each workflow consists of steps that route tasks to specific agents.

Workflow Concepts

Workflow Structure

id · string

Unique workflow ID (UUID)

name · string

Human-readable workflow name

description · string

Description of what the workflow does

steps · array

Array of workflow steps (see below)

created_at · string

ISO 8601 creation timestamp

Step Structure

name · string

Step name for logging/display

agent · object

Agent reference (by ID or name)

Show Agent Reference

// By ID
{"id": "550e8400-e29b-41d4-a716-446655440000"}

// By name
{"name": "code-reviewer"}

prompt · string

Prompt template. Use {{input}} for previous output, {{var_name}} for variables.

mode · enum

Execution mode:

• sequential (default)
• fan_out - Run in parallel with subsequent fan-out steps
• collect - Collect results from all preceding fan-out steps
• conditional - Skip if condition not met
• loop - Repeat until condition or max iterations

timeout_secs · integer

Step timeout in seconds (default: 120)

error_mode · enum

Error handling:

• fail (default) - Abort workflow on error
• skip - Skip step and continue
• retry - Retry up to N times

output_var · string

Optional variable name to store step output

Create Workflow

Register a new workflow definition:

POST /api/workflows

curl -X POST http://127.0.0.1:4200/api/workflows \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Code Review Pipeline",
    "description": "Analyze, review, and approve code changes",
    "steps": [
      {
        "name": "analyze",
        "agent_name": "code-analyzer",
        "prompt": "Analyze this code: {{input}}",
        "mode": "sequential",
        "output_var": "analysis"
      },
      {
        "name": "review",
        "agent_name": "code-reviewer",
        "prompt": "Review based on: {{analysis}}",
        "mode": "sequential",
        "error_mode": "retry",
        "max_retries": 3
      }
    ]
  }'

201 Created

{
  "workflow_id": "abc123-def456-789012"
}

List Workflows

Get all registered workflows:

GET /api/workflows

curl http://127.0.0.1:4200/api/workflows

200 OK

[
  {
    "id": "abc123-def456-789012",
    "name": "Code Review Pipeline",
    "description": "Analyze, review, and approve code changes",
    "steps": 2,
    "created_at": "2025-03-06T12:00:00Z"
  }
]

Run Workflow

Execute a workflow with input:

POST /api/workflows/{id}/run

curl -X POST http://127.0.0.1:4200/api/workflows/abc123-def456-789012/run \
  -H "Content-Type: application/json" \
  -d '{
    "input": "function add(a, b) { return a + b; }"
  }'

200 OK

{
  "run_id": "run-xyz789",
  "output": "Code approved. Function is clean and well-structured.",
  "status": "completed"
}

List Workflow Runs

Get execution history for a workflow:

GET /api/workflows/{id}/runs

curl http://127.0.0.1:4200/api/workflows/abc123-def456-789012/runs

200 OK

[
  {
    "id": "run-xyz789",
    "workflow_name": "Code Review Pipeline",
    "state": {
      "status": "completed"
    },
    "steps_completed": 2,
    "started_at": "2025-03-06T12:00:00Z",
    "completed_at": "2025-03-06T12:01:30Z"
  }
]

Workflow Patterns

Sequential Pipeline

Steps execute one after another:

{
  "steps": [
    {
      "name": "step1",
      "agent_name": "agent1",
      "prompt": "Process: {{input}}",
      "mode": "sequential"
    },
    {
      "name": "step2",
      "agent_name": "agent2",
      "prompt": "Refine: {{input}}",
      "mode": "sequential"
    }
  ]
}

Fan-Out / Collect

Run multiple agents in parallel, then collect results:

{
  "steps": [
    {
      "name": "analyze_security",
      "agent_name": "security-agent",
      "prompt": "Security audit: {{input}}",
      "mode": "fan_out"
    },
    {
      "name": "analyze_performance",
      "agent_name": "perf-agent",
      "prompt": "Performance audit: {{input}}",
      "mode": "fan_out"
    },
    {
      "name": "analyze_style",
      "agent_name": "style-agent",
      "prompt": "Style audit: {{input}}",
      "mode": "fan_out"
    },
    {
      "name": "summarize",
      "agent_name": "summarizer",
      "prompt": "Summarize audits: {{input}}",
      "mode": "collect"
    }
  ]
}

Conditional Steps

Skip steps based on conditions:

{
  "steps": [
    {
      "name": "check_tests",
      "agent_name": "test-runner",
      "prompt": "Run tests on: {{input}}",
      "mode": "sequential",
      "output_var": "test_result"
    },
    {
      "name": "deploy",
      "agent_name": "deployer",
      "prompt": "Deploy if tests pass: {{test_result}}",
      "mode": "conditional",
      "condition": "passed"
    }
  ]
}

The deploy step only runs if test_result contains “passed” (case-insensitive).

Loop Steps

Repeat a step until a condition is met:

{
  "steps": [
    {
      "name": "refine_code",
      "agent_name": "code-refiner",
      "prompt": "Improve this code: {{input}}",
      "mode": "loop",
      "max_iterations": 5,
      "until": "no more improvements"
    }
  ]
}

The step repeats until:

1. Output contains “no more improvements”, or
2. max_iterations (5) is reached

Error Handling

Fail (Default)

Abort the workflow on any error:

{
  "error_mode": "fail"
}

Skip

Skip failed steps and continue:

{
  "error_mode": "skip"
}

Retry

Retry failed steps up to N times:

{
  "error_mode": "retry",
  "max_retries": 3
}

Variable Substitution

Use variables in prompt templates:

• {{input}} - Previous step’s output
• {{var_name}} - Named output variable from any step

{
  "steps": [
    {
      "name": "analyze",
      "agent_name": "analyzer",
      "prompt": "Analyze: {{input}}",
      "output_var": "analysis"
    },
    {
      "name": "summarize",
      "agent_name": "summarizer",
      "prompt": "Summarize: {{analysis}}"
    }
  ]
}

Workflow State

Workflow runs progress through states:

• pending - Queued but not started
• running - Currently executing
• completed - Successfully finished
• failed - Encountered an error

Step Results

Each completed step stores:

step_name · string

Name of the step

agent_id · string

UUID of the agent that executed the step

agent_name · string

Name of the agent

output · string

Step output text

input_tokens · integer

Input tokens consumed

output_tokens · integer

Output tokens generated

duration_ms · integer

Step duration in milliseconds

Run Retention

The workflow engine retains up to 200 workflow runs. When this limit is exceeded, the oldest completed/failed runs are evicted automatically.

Best Practices

Timeouts

Set realistic timeouts for each step (default: 120s)

Error Handling

Use retry for transient failures, skip for optional steps

Fan-Out

Parallelize independent tasks with fan-out/collect

Variables

Store intermediate results in variables for reuse

Example: CI/CD Pipeline

{
  "name": "CI/CD Pipeline",
  "description": "Test, build, and deploy application",
  "steps": [
    {
      "name": "run_tests",
      "agent_name": "test-agent",
      "prompt": "Run all tests for: {{input}}",
      "mode": "sequential",
      "output_var": "test_results",
      "error_mode": "fail"
    },
    {
      "name": "build",
      "agent_name": "build-agent",
      "prompt": "Build application: {{input}}",
      "mode": "sequential",
      "output_var": "build_artifact"
    },
    {
      "name": "security_scan",
      "agent_name": "security-agent",
      "prompt": "Scan for vulnerabilities: {{build_artifact}}",
      "mode": "sequential",
      "error_mode": "retry",
      "max_retries": 2
    },
    {
      "name": "deploy_staging",
      "agent_name": "deploy-agent",
      "prompt": "Deploy to staging: {{build_artifact}}",
      "mode": "sequential",
      "timeout_secs": 300
    },
    {
      "name": "smoke_tests",
      "agent_name": "test-agent",
      "prompt": "Run smoke tests on staging",
      "mode": "sequential"
    },
    {
      "name": "deploy_production",
      "agent_name": "deploy-agent",
      "prompt": "Deploy to production: {{build_artifact}}",
      "mode": "conditional",
      "condition": "all tests passed",
      "timeout_secs": 600
    }
  ]
}

Next Steps

Agents API

Learn how to spawn workflow agents

Memory API

Store workflow state in memory