The Workflow API enables you to create and execute multi-step agent workflows with support for sequential, parallel, conditional, and loop execution modes.
Workflow Concepts Workflows in AgentOS support five execution modes:
Sequential : Steps execute one after another, with output passed to the next stepFanout : Multiple steps execute in parallelCollect : Aggregates results from fanout stepsConditional : Step executes only if a condition is metLoop : Repeats a step until a condition is met or max iterations reached
List Workflows Get all registered workflows.
Response Array of workflow objects with their configurations.
Example curl -X GET http://localhost:3111/api/workflows \ -H "Authorization: Bearer YOUR_API_KEY"
Create Workflow Register a new workflow definition.
Request Optional workflow ID. Auto-generated if not provided.
The name of the workflow.
Description of what the workflow does.
Array of workflow step objects. The function to execute (e.g., agent::chat, tools::web_search).
Execution mode: sequential, fanout, collect, conditional, or loop.
Template string with {{variable}} placeholders for variable interpolation.
Timeout in milliseconds for this step.
Error handling: fail, skip, or retry.
Maximum retry attempts when errorMode is retry.
Variable name to store the step’s output.
Condition string for conditional mode (checks if previous output contains this string).
Maximum iterations for loop mode.
Exit condition for loop mode (stops when output contains this string).
Response The unique identifier for the created workflow.
Example curl -X POST http://localhost:3111/api/workflows \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "research-and-summarize", "description": "Research a topic and create a summary", "steps": [ { "name": "research", "functionId": "tools::web_search", "mode": "sequential", "promptTemplate": "{{input}}", "timeoutMs": 30000, "errorMode": "retry", "maxRetries": 3, "outputVar": "searchResults" }, { "name": "summarize", "functionId": "agent::chat", "mode": "sequential", "promptTemplate": "Summarize these search results: {{searchResults}}", "timeoutMs": 60000, "errorMode": "fail" } ] }'
Run Workflow Execute a workflow with input data.
Request The ID of the workflow to execute.
Input data to pass to the workflow. Available as {{input}} in step templates.
Optional agent ID for capability checks on workflow steps.
Response Unique identifier for this workflow run.
Array of step results. Name of the step that executed.
The output produced by the step.
Execution time in milliseconds.
Error message if the step failed.
Final state of all workflow variables.
Example curl -X POST http://localhost:3111/api/workflows/run \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "workflowId": "wf-123", "input": "Latest developments in quantum computing", "agentId": "agent-456" }'
Response Example { "runId" : "run-a1b2c3d4" , "results" : [ { "stepName" : "research" , "output" : { "results" : [ { "title" : "Quantum Computing Breakthrough" , "url" : "..." } ] }, "durationMs" : 1250 }, { "stepName" : "summarize" , "output" : "Recent quantum computing advances include..." , "durationMs" : 3420 } ], "vars" : { "input" : "Recent quantum computing advances include..." , "searchResults" : { "results" : [ ... ]} } }
Get Workflow Runs Retrieve execution history for a workflow.
GET /api/workflows/:id/runs
Path Parameters Query Parameters Maximum number of runs to return (1-100).
Number of runs to skip for pagination.
Response Array of workflow run objects.
Total number of runs for this workflow.
The limit used for this request.
The offset used for this request.
Advanced Workflow Examples Parallel Processing with Fanout/Collect { "name" : "multi-source-research" , "description" : "Search multiple sources in parallel" , "steps" : [ { "name" : "search-web" , "functionId" : "tools::web_search" , "mode" : "fanout" , "promptTemplate" : "{{input}}" , "timeoutMs" : 30000 , "outputVar" : "webResults" }, { "name" : "search-academic" , "functionId" : "tools::academic_search" , "mode" : "fanout" , "promptTemplate" : "{{input}}" , "timeoutMs" : 30000 , "outputVar" : "academicResults" }, { "name" : "merge-results" , "functionId" : "agent::chat" , "mode" : "collect" , "promptTemplate" : "Merge these research results: {{__fanout}}" , "timeoutMs" : 60000 } ] }
Conditional Execution { "name" : "conditional-analysis" , "description" : "Perform deep analysis only if initial check warrants it" , "steps" : [ { "name" : "initial-check" , "functionId" : "agent::chat" , "mode" : "sequential" , "promptTemplate" : "Quick check: {{input}}" , "outputVar" : "checkResult" }, { "name" : "deep-analysis" , "functionId" : "agent::chat" , "mode" : "conditional" , "condition" : "needs analysis" , "promptTemplate" : "Perform deep analysis on: {{input}}" , "timeoutMs" : 120000 } ] }
Loop Until Condition { "name" : "iterative-refinement" , "description" : "Refine output until quality threshold is met" , "steps" : [ { "name" : "refine" , "functionId" : "agent::chat" , "mode" : "loop" , "promptTemplate" : "Refine this text: {{input}}" , "maxIterations" : 5 , "until" : "quality: excellent" , "timeoutMs" : 60000 } ] }
Error Handling Workflow steps support three error modes:
fail : Stop workflow execution and return error (default)skip : Skip the failed step and continueretry : Retry the step up to maxRetries times before failing
Failed workflow runs store:
Run status: "failed"
Error message
Results from successfully completed steps
Timestamp of failure
Rate Limiting
List workflows: 200 requests/hour
Create workflow: 100 requests/hour
Run workflow: 100 requests/hour
Security When agentId is provided in workflow run requests, the system:
Checks RBAC capabilities for each step’s function
Enforces tool policies
Validates against the agent’s allowed capabilities
Records execution in audit log
This ensures workflows respect agent-level security constraints. 