Workflows API

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

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

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
      }
    ]
  }'

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

List Workflows

Get all registered workflows:

GET /api/workflows

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

[
  {
    "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; }"
  }'

{
  "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

[
  {
    "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:

Output contains “no more improvements”, or
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
    }
  ]
}

REST API

CLI Reference

OpenAI Compatibility

Overview

Workflow Concepts

Workflow Structure

Step Structure

Create Workflow

List Workflows

Run Workflow

List Workflow Runs

Workflow Patterns

Sequential Pipeline

Fan-Out / Collect

Conditional Steps

Loop Steps

Error Handling

Fail (Default)

Skip

Retry

Variable Substitution

Workflow State

Step Results

Run Retention

Best Practices

Timeouts

Error Handling

Fan-Out

Variables

Example: CI/CD Pipeline

Next Steps

Agents API

Memory API

REST API

CLI Reference

OpenAI Compatibility

​Overview

​Workflow Concepts

​Workflow Structure

​Step Structure

​Create Workflow

​List Workflows

​Run Workflow

​List Workflow Runs

​Workflow Patterns

​Sequential Pipeline

​Fan-Out / Collect

​Conditional Steps

​Loop Steps

​Error Handling

​Fail (Default)

​Skip

​Retry

​Variable Substitution

​Workflow State

​Step Results

​Run Retention

​Best Practices

Timeouts

Error Handling

Fan-Out

Variables

​Example: CI/CD Pipeline

​Next Steps

Agents API

Memory API

Overview

Workflow Concepts

Workflow Structure

Step Structure

Create Workflow

List Workflows

Run Workflow

List Workflow Runs

Workflow Patterns

Sequential Pipeline

Fan-Out / Collect

Conditional Steps

Loop Steps

Error Handling

Fail (Default)

Skip

Retry

Variable Substitution

Workflow State

Step Results

Run Retention

Best Practices

Example: CI/CD Pipeline

Next Steps