Workflow Orchestration

What is a Workflow Run?

A workflow run is one execution instance of a directed acyclic graph of work nodes. Each node names an agent profile and a prompt template. The conductor validates the DAG, schedules ready nodes, dispatches runs through the runner pool, and persists state in the workflow store. Workflow runs are useful when a request has clear parallel or ordered subtasks, such as research -> synthesis -> review.

Shape

type WorkflowRun = Plan       // legacy alias kept during the migration
type WorkflowNode = PlanNode

type Plan struct {
  ID                    string
  UserPrompt            string
  OrchestratorRunID     string
  OrchestratorSessionID string
  Status                PlanStatus
  AutoStart             bool
  Nodes                 []PlanNode
  CreatedAt             time.Time
  StartedAt             time.Time
  FinishedAt            time.Time
  RepairCount           int
  Deadline              time.Time
  DelegationDepth       int
}

type PlanNode struct {
  ID             string
  Title          string
  Profile        string
  SessionID      string
  PromptTemplate string
  DependsOn      []string
  OutputSchema   json.RawMessage
  Status         NodeStatus
  RunID          string
  Output         string
  Fields         json.RawMessage
  Error          string
  Attempt        int
  StartedAt      time.Time
  FinishedAt     time.Time
}

Plan / PlanNode are the legacy Go names; WorkflowRun / WorkflowNode are aliases. The wire shape and storage layer are unchanged. Status fields are numeric enums in full snapshots.

Run value	Label
`0`	`pending`
`1`	`running`
`2`	`paused`
`3`	`completed`
`4`	`failed`
`5`	`cancelled`

Node value	Label
`0`	`pending`
`1`	`ready`
`2`	`running`
`3`	`ok`
`4`	`error`
`5`	`skipped`
`6`	`cancelled`

Example DAG

{
  "userPrompt": "Compare LangGraph and AutoGen",
  "nodes": [
    {
      "id": "research-langgraph",
      "title": "Research LangGraph",
      "profile": "researcher",
      "promptTemplate": "Summarize LangGraph features and use cases."
    },
    {
      "id": "research-autogen",
      "title": "Research AutoGen",
      "profile": "researcher",
      "promptTemplate": "Summarize AutoGen features and use cases."
    },
    {
      "id": "compare",
      "title": "Compare results",
      "profile": "analyst",
      "promptTemplate": "Compare these findings:\n\nLangGraph:\n{{research-langgraph.output}}\n\nAutoGen:\n{{research-autogen.output}}",
      "dependsOn": ["research-langgraph", "research-autogen"]
    },
    {
      "id": "review",
      "title": "Review comparison",
      "profile": "reviewer",
      "promptTemplate": "Review this comparison for accuracy:\n\n{{compare.output}}",
      "dependsOn": ["compare"]
    }
  ]
}

Execution order:

research-langgraph and research-autogen run in parallel.
compare starts after both research nodes reach ok.
review starts after compare reaches ok.

Prompt Templates

Node prompt templates can reference upstream outputs:

Template	Meaning
`{{node-id.output}}`	Raw output text from an upstream node
`{{node-id.fields.key}}`	Structured output field when `outputSchema` was provided

Template validation happens before a workflow run is accepted. Bad references return 400 with a bad_template error.

Creating Workflow Runs

curl -X POST https://api.orcapods.ai/api/workflows/runs \
  -H 'Content-Type: application/json' \
  -d @workflow.json

Create response:

{
  "workflowRunId": "workflow-8b2a9c4f",
  "status": "pending"
}

autoStart defaults to true. Set "autoStart": false to create a workflow run without submitting it to the engine, then call:

curl -X POST https://api.orcapods.ai/api/workflows/runs/workflow-8b2a9c4f/start

Streaming

curl -N https://api.orcapods.ai/api/workflows/runs/workflow-8b2a9c4f/stream

The stream sends an initial snapshot event followed by plan_status events. Each frame carries the full workflow-run snapshot under the workflowRun key:

event: snapshot
data: {"type":"snapshot","workflowRun":{...}}

event: plan_status
data: {"type":"plan_status","workflowRun":{...}}

Repair

When execution pauses, a coordinator can repair the workflow run:

{
  "type": "retry_node",
  "nodeId": "research-langgraph"
}

Supported repair actions:

Type	Effect
`retry_node`	Re-runs a failed node
`replace_node`	Replaces a node definition
`add_dependency`	Adds dependency edges and revalidates the DAG
`abort`	Ends the workflow run

AGENT_ORC_PLAN_MAX_REPAIRS limits how many repairs a workflow run can consume.

Orchestrator-Driven Mode

A coordinator agent can create a workflow run with autoStart: false, delegate node work itself, then mark nodes terminal with POST /api/workflows/runs/{workflowRunId}/nodes/{nodeId}/status.

{
  "workflowRunId": "workflow-8b2a9c4f",
  "nodeId": "research-langgraph",
  "status": "ok",
  "output": "Research result..."
}

This mode is useful when the orchestrator needs to inspect, transform, or gate each node result before unlocking downstream work.

Configuration

Env Var	Default	Scope
`AGENT_ORC_PLANS_DIR`	unset	JSONL file path for workflow run persistence (MemStore fallback)
`AGENT_ORC_PLAN_NODE_PARALLELISM`	`8`	Max in-flight nodes per workflow run
`AGENT_ORC_PLAN_GLOBAL_PARALLELISM`	`64`	Max in-flight nodes process-wide
`AGENT_ORC_PLAN_NODE_RETRIES`	`0`	Transport-error retry budget per node
`AGENT_ORC_PLAN_MAX_NODES`	`64`	Validation cap on workflow size
`AGENT_ORC_PLAN_MAX_REPAIRS`	`5`	Repair budget before auto-fail

Env vars retain their AGENT_ORC_PLAN_* prefix because the planner engine is still the underlying substrate.

Validation Errors

The conductor returns 400 with stable prefixes for user-correctable workflow errors:

Prefix	Meaning
`cycle_detected`	DAG has a cycle
`unknown_profile`	A node references a missing profile
`bad_template`	Prompt template references invalid data
`too_many_nodes`	Workflow exceeds `AGENT_ORC_PLAN_MAX_NODES`
`duplicate_node_id`	Node IDs are not unique
`dependency_unresolved`	A dependency references a missing node

Get Started

Core Concepts

Guides

Workflow Orchestration

What is a Workflow Run?

Shape

Example DAG

Prompt Templates

Creating Workflow Runs

Streaming

Repair

Orchestrator-Driven Mode

Configuration

Validation Errors

​What is a Workflow Run?

​Shape

​Example DAG

​Prompt Templates

​Creating Workflow Runs

​Streaming

​Repair

​Orchestrator-Driven Mode

​Configuration

​Validation Errors

What is a Workflow Run?

Shape

Example DAG

Prompt Templates

Creating Workflow Runs

Streaming

Repair

Orchestrator-Driven Mode

Configuration

Validation Errors