Workflows API

Workflows enable complex multi-agent orchestration with support for sequential execution, fan-out/collect patterns, conditional branching, loops, and error handling.

Create Workflow

curl -X POST http://127.0.0.1:4200/api/workflows \
  -H "Content-Type: application/json" \
  -d '{
    "name": "code-review-pipeline",
    "description": "Review code changes with multiple agents",
    "steps": [
      {
        "name": "analyze",
        "agent_name": "coder",
        "prompt": "Analyze this code for potential issues: {{input}}",
        "mode": "sequential",
        "timeout_secs": 120,
        "error_mode": "fail",
        "output_var": "analysis"
      },
      {
        "name": "security-check",
        "agent_name": "security-auditor",
        "prompt": "Review this code analysis for security vulnerabilities: {{analysis}}",
        "mode": "sequential",
        "timeout_secs": 120,
        "error_mode": "skip"
      },
      {
        "name": "summarize",
        "agent_name": "writer",
        "prompt": "Write a concise code review summary based on: {{analysis}}",
        "mode": "sequential",
        "timeout_secs": 60,
        "error_mode": "fail"
      }
    ]
  }'

name

string

required

Workflow name

description

string

Human-readable description

steps

array

required

Workflow steps

Show Step configuration

name

string

required

Step name

agent_id

string

Agent UUID (use either agent_id or agent_name)

agent_name

string

Agent name (use either agent_id or agent_name)

prompt

string

required

Prompt template. Supports placeholders:

{{input}} — Workflow input or previous step output
{{output_var}} — Output from a named step

mode

string

default:"sequential"

Execution mode:

sequential — Run in order
fan_out — Spawn parallel branches
collect — Wait for all branches to complete
conditional — Run if condition is true
loop — Repeat until condition or max iterations

condition

string

Condition expression (for conditional mode)

max_iterations

integer

default:"5"

Max loop iterations (for loop mode)

until

string

Stop condition (for loop mode)

timeout_secs

integer

default:"120"

Step timeout in seconds

error_mode

string

default:"fail"

Error handling:

fail — Stop workflow on error
skip — Continue to next step
retry — Retry up to max_retries

max_retries

integer

default:"3"

Max retries (for retry error mode)

output_var

string

Variable name to store output for later steps

{
  "workflow_id": "w1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

List Workflows

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

workflows

array

Show Workflow object

string

Workflow UUID

name

string

Workflow name

description

string

Workflow description

steps

integer

Number of steps

created_at

string

RFC3339 timestamp

[
  {
    "id": "w1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "code-review-pipeline",
    "description": "Automated code review workflow",
    "steps": 3,
    "created_at": "2025-01-15T10:30:00Z"
  }
]

Run Workflow

Execute a workflow with input data.

curl -X POST http://127.0.0.1:4200/api/workflows/{id}/run \
  -H "Content-Type: application/json" \
  -d '{"input": "Review this pull request: ..."}'

string

required

Workflow UUID

input

string

required

Workflow input (passed to first step as {{input}})

run_id

string

Workflow run UUID

output

string

Final workflow output

status

string

Run status: completed, failed, or cancelled

{
  "run_id": "r1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "output": "Code review summary:\n- No critical issues found\n- 2 minor style improvements suggested\n",
  "status": "completed"
}

List Workflow Runs

Retrieve execution history for a workflow.

curl http://127.0.0.1:4200/api/workflows/{id}/runs

string

required

Workflow UUID

runs

array

Show Run object

string

Run UUID

workflow_name

string

Workflow name

state

string

Run state: Running, Completed, Failed, Cancelled

steps_completed

integer

Number of completed steps

started_at

string

Start timestamp

completed_at

string

Completion timestamp (null if still running)

[
  {
    "id": "r1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "workflow_name": "code-review-pipeline",
    "state": "Completed",
    "steps_completed": 3,
    "started_at": "2025-01-15T10:30:00Z",
    "completed_at": "2025-01-15T10:32:15Z"
  }
]

Workflow Patterns

Sequential Pipeline

Run steps in order, passing output to the next step:

{
  "steps": [
    {
      "name": "fetch",
      "agent_name": "researcher",
      "prompt": "Research {{input}}",
      "output_var": "research"
    },
    {
      "name": "summarize",
      "agent_name": "writer",
      "prompt": "Summarize: {{research}}"
    }
  ]
}

Fan-Out / Collect

Run multiple agents in parallel, then collect results:

{
  "steps": [
    {
      "name": "parallel_analysis",
      "mode": "fan_out",
      "agent_name": "analyst",
      "prompt": "Analyze aspect: {{input}}"
    },
    {
      "name": "collect_results",
      "mode": "collect",
      "agent_name": "aggregator",
      "prompt": "Combine all analyses"
    }
  ]
}

Conditional Execution

Run a step only if a condition is met:

{
  "steps": [
    {
      "name": "check_quality",
      "agent_name": "reviewer",
      "prompt": "Check quality: {{input}}",
      "output_var": "quality_score"
    },
    {
      "name": "fix_issues",
      "mode": "conditional",
      "condition": "quality_score < 80",
      "agent_name": "fixer",
      "prompt": "Fix issues in: {{input}}"
    }
  ]
}

Loop Until Success

Retry a step until it succeeds or max iterations:

{
  "steps": [
    {
      "name": "try_compile",
      "mode": "loop",
      "max_iterations": 5,
      "until": "compilation_successful",
      "agent_name": "coder",
      "prompt": "Fix compilation errors: {{input}}"
    }
  ]
}

Error Handling

Retry on failure with exponential backoff:

{
  "steps": [
    {
      "name": "api_call",
      "agent_name": "api_agent",
      "prompt": "Call API: {{input}}",
      "error_mode": "retry",
      "max_retries": 3
    }
  ]
}

Skip step on error and continue:

{
  "steps": [
    {
      "name": "optional_step",
      "agent_name": "helper",
      "prompt": "Try to enhance: {{input}}",
      "error_mode": "skip"
    }
  ]
}

Variable Interpolation

Prompts support Mustache-style placeholders:

{{input}} — Workflow input or previous step output
{{step_name}} — Output from a step with output_var: "step_name"
{{agent.name}} — Current agent’s name
{{workflow.name}} — Workflow name

Example:

{
  "steps": [
    {
      "name": "analyze",
      "agent_name": "analyst",
      "prompt": "Analyze: {{input}}",
      "output_var": "analysis"
    },
    {
      "name": "report",
      "agent_name": "reporter",
      "prompt": "Write report for workflow {{workflow.name}} based on: {{analysis}}"
    }
  ]
}

Workflow Execution State

Workflow runs track detailed execution state:

Running — Currently executing
Completed — All steps finished successfully
Failed — A step failed with error_mode: fail
Cancelled — Manually stopped

Each run stores:

Step outputs
Error messages
Token usage per step
Total execution time

Best Practices

Use timeouts for long-running steps

Set reasonable timeout_secs to prevent workflows from hanging:

{
  "name": "web_scrape",
  "agent_name": "scraper",
  "prompt": "Scrape {{url}}",
  "timeout_secs": 300  // 5 minutes
}

Name output variables for complex workflows

Use output_var to reference step outputs by name:

{
  "steps": [
    {"name": "research", "output_var": "research_data", ...},
    {"name": "analyze", "output_var": "analysis", ...},
    {"name": "report", "prompt": "Combine {{research_data}} and {{analysis}}"}
  ]
}

Use error_mode: skip for optional steps

Non-critical steps should skip on error:

{
  "name": "optional_enhancement",
  "agent_name": "enhancer",
  "prompt": "Enhance: {{input}}",
  "error_mode": "skip"
}

Limit loop iterations to prevent infinite loops

Always set max_iterations for loop mode:

{
  "name": "iterative_improvement",
  "mode": "loop",
  "max_iterations": 10,
  "until": "quality >= 90",
  "agent_name": "improver",
  "prompt": "Improve: {{input}}"
}

Next Steps

Agents API

Manage agents for workflows

Triggers

Auto-run workflows on events

Memory API

Store workflow state

Usage API

Track workflow costs

Overview

Core Endpoints

Tools & Extensions

OpenAI Compatible

Create Workflow

List Workflows

Run Workflow

List Workflow Runs

Workflow Patterns

Sequential Pipeline

Fan-Out / Collect

Conditional Execution

Loop Until Success

Error Handling

Variable Interpolation

Workflow Execution State

Best Practices

Next Steps

Agents API

Triggers

Memory API

Usage API

Build docs developers (and LLMs) love

Overview

Core Endpoints

Tools & Extensions

OpenAI Compatible

​Create Workflow

​List Workflows

​Run Workflow

​List Workflow Runs

​Workflow Patterns

​Sequential Pipeline

​Fan-Out / Collect

​Conditional Execution

​Loop Until Success

​Error Handling

​Variable Interpolation

​Workflow Execution State

​Best Practices

​Next Steps

Agents API

Triggers

Memory API

Usage API

Build docs developers (and LLMs) love

Create Workflow

List Workflows

Run Workflow

List Workflow Runs

Workflow Patterns

Sequential Pipeline

Fan-Out / Collect

Conditional Execution

Loop Until Success

Error Handling

Variable Interpolation

Workflow Execution State

Best Practices

Next Steps