Skip to main content
Workflow commands enable you to create, manage, and execute multi-step automated workflows that orchestrate multiple agents and tools.

​
Overview

Workflows in AgentOS allow you to:
  • Chain multiple agent interactions
  • Execute complex multi-step processes
  • Pass data between steps
  • Handle conditional logic
  • Run parallel operations

​
workflow list

List all registered workflows. 
agentos workflow list
Example output: 
[
  {
    "id": "wf-research-and-write",
    "name": "Research and Write",
    "steps": 3,
    "created": "2026-03-09T10:00:00Z",
    "status": "active"
  },
  {
    "id": "wf-code-review",
    "name": "Code Review Pipeline",
    "steps": 5,
    "created": "2026-03-08T15:30:00Z",
    "status": "active"
  }
]

​
workflow create

Create a new workflow from a JSON definition file. 
agentos workflow create <file>
​
file
string
required
Path to workflow JSON definition file
Example: 
agentos workflow create workflows/research-pipeline.json
Output: 
✓ Created workflow: wf-research-pipeline

​
workflow run

Execute a workflow. 
agentos workflow run <id>
​
id
string
required
Workflow ID to execute
Example: 
agentos workflow run wf-research-pipeline
Output: 
{
  "workflowId": "wf-research-pipeline",
  "executionId": "exec-abc123",
  "status": "running",
  "startedAt": "2026-03-09T10:30:00Z",
  "steps": [
    {
      "id": "step-1",
      "name": "Research",
      "status": "completed",
      "output": "..."
    },
    {
      "id": "step-2",
      "name": "Analyze",
      "status": "running"
    }
  ]
}

​
Workflow Definition Format

Workflows are defined in JSON with the following structure:

​
Basic Workflow

{
  "id": "wf-example",
  "name": "Example Workflow",
  "description": "A simple example workflow",
  "steps": [
    {
      "id": "step-1",
      "type": "agent",
      "agentId": "researcher",
      "input": "Research topic: AI agents"
    },
    {
      "id": "step-2",
      "type": "agent",
      "agentId": "writer",
      "input": "Write summary based on: ${steps['step-1'].output}"
    }
  ]
}

​
Step Types

Workflows support 5 step modes: 
{
  "type": "agent",
  "agentId": "coder",
  "input": "Write a function to parse JSON"
}

{
  "type": "tool",
  "toolId": "web_search",
  "args": {
    "query": "latest AI news"
  }
}

{
  "type": "function",
  "functionId": "data::transform",
  "args": {
    "data": "${steps['step-1'].output}"
  }
}

{
  "type": "parallel",
  "steps": [
    {
      "type": "agent",
      "agentId": "researcher-1",
      "input": "Research topic A"
    },
    {
      "type": "agent",
      "agentId": "researcher-2",
      "input": "Research topic B"
    }
  ]
}

{
  "type": "conditional",
  "condition": "${steps['step-1'].output.sentiment} == 'positive'",
  "then": {
    "type": "agent",
    "agentId": "writer",
    "input": "Write positive response"
  },
  "else": {
    "type": "agent",
    "agentId": "support",
    "input": "Handle concern"
  }
}

​
Variable Interpolation

Workflows support variable interpolation using ${} syntax: 
{
  "steps": [
    {
      "id": "research",
      "type": "agent",
      "agentId": "researcher",
      "input": "Research: ${input.topic}"
    },
    {
      "id": "write",
      "type": "agent",
      "agentId": "writer",
      "input": "Write article about ${steps['research'].output}"
    }
  ]
}
Available variables:
  • ${input.*} - Workflow input parameters
  • ${steps['step-id'].output} - Output from a specific step
  • ${steps[0].output} - Output from step by index
  • ${env.KEY} - Environment variables

​
Example Workflows

{
  "id": "wf-research-pipeline",
  "name": "Research and Summarize",
  "steps": [
    {
      "id": "search",
      "type": "tool",
      "toolId": "web_search",
      "args": {
        "query": "${input.query}"
      }
    },
    {
      "id": "research",
      "type": "agent",
      "agentId": "researcher",
      "input": "Analyze these search results: ${steps['search'].output}"
    },
    {
      "id": "summarize",
      "type": "agent",
      "agentId": "writer",
      "input": "Write a summary: ${steps['research'].output}"
    }
  ]
}

​
Advanced Features

​
Error Handling

Add error handling to steps: 
{
  "id": "risky-step",
  "type": "agent",
  "agentId": "coder",
  "input": "Execute task",
  "onError": {
    "type": "agent",
    "agentId": "debugger",
    "input": "Debug error: ${error.message}"
  }
}

​
Retries

Configure retry behavior: 
{
  "id": "api-call",
  "type": "tool",
  "toolId": "web_fetch",
  "args": { "url": "https://api.example.com" },
  "retry": {
    "maxAttempts": 3,
    "backoff": "exponential"
  }
}

​
Timeouts

Set step timeouts: 
{
  "id": "long-task",
  "type": "agent",
  "agentId": "researcher",
  "input": "Deep research",
  "timeout": 300000
}

​
Workflow Execution

Monitor workflow execution: 
# Start workflow
agentos workflow run wf-research-pipeline

# Check status via API or TUI
agentos tui  # Press 7 for Workflows screen
Workflows execute asynchronously. Use the TUI or API to monitor progress.

​
Trigger Integration

Workflows can be triggered by:
  • CLI command (workflow run)
  • Cron schedule (cron commands)
  • HTTP API endpoint
  • Agent delegation
  • Event triggers
Example cron trigger: 
agentos cron create "0 9 * * 1" "workflow::run" --args '{"workflowId": "wf-weekly-report"}'

​
Best Practices

Each step should perform a single, well-defined task. This makes workflows easier to debug and reuse.
Use clear, descriptive step IDs like research-tech-news instead of step-1.
Always include error handling for steps that might fail (API calls, file operations).
Use parallel steps for independent operations to reduce total execution time.
Store workflow definitions in version control and include version numbers in IDs.

​
Next Steps

Agent Commands

Learn about the agents used in workflows

Trigger Commands

Set up automated workflow triggers

Security

Configure approval gates for workflows

Cron Jobs

Schedule recurring workflow execution

Build docs developers (and LLMs) love

Get started for freeTalk to us