Skip to main content

Orchestrator

The Orchestrator executes multi-step workflows as directed acyclic graphs (DAGs). Steps run in parallel where possible, with automatic dependency resolution and result composition.

How It Works​

An orchestration is a sequence of steps. Each step invokes a grid operation and can reference outputs from earlier steps. Independent steps run in parallel; dependent steps wait for their inputs.

Step 0: Extract invoice data     ─┐
Step 1: Look up vendor           ─┤── (parallel, no dependencies)
Step 2: Validate (needs 0 + 1)   ─┘── (waits for both)
Step 3: Approve (needs 2)        ──── (sequential)

Defining an Orchestration​

Orchestrations are defined as operation assets with an orchestrator adapter:

{
  "name": "Invoice Pipeline",
  "operation": {
    "adapter": "orchestrator",
    "steps": [
      {
        "op": "v/ops/agent/request",
        "input": {
          "agentId": ["const", "Alice"],
          "input": ["input", "invoice"],
          "timeout": ["const", 60000]
        }
      },
      {
        "op": "v/ops/agent/request",
        "input": {
          "agentId": ["const", "Bob"],
          "input": [0, "output"],
          "timeout": ["const", 60000]
        }
      },
      {
        "op": "v/ops/agent/request",
        "input": {
          "agentId": ["const", "Carol"],
          "input": [1, "output"],
          "timeout": ["const", 60000]
        }
      }
    ],
    "result": {
      "scanned": [0, "output"],
      "enriched": [1, "output"],
      "decision": [2, "output"]
    }
  }
}

Input Resolution​

Step inputs are built using a resolution syntax that references the orchestration input, constants, or outputs from earlier steps:

SyntaxMeaningExample
["input", "key"]Extract from orchestration input["input", "invoice"]
["const", value]Constant value["const", true]
[N, "field"]Output from step N[0, "output"]
["concat", parts...]String concatenation["concat", "prefix-", ["input", "id"]]

Resolution is recursive — maps and arrays within step inputs are resolved recursively.

Dependency rule: Step N can only reference steps 0 to N-1. This enforces a DAG structure with no circular dependencies.

Execution​

  1. Steps with no dependencies start immediately (in parallel, using virtual threads)
  2. As each step completes, dependent steps become ready and start
  3. When all steps complete, the result expression is resolved and returned
  4. If a step fails and strict mode is on, the orchestration fails immediately

Step Structure​

{
  "op": "v/ops/agent/request",
  "input": { ... },
  "venue": "https://remote-venue.example.com",
  "strict": true
}
FieldTypeRequiredDescription
opstringYesOperation to invoke
inputobjectNoInput with resolution expressions
venuestringNoRemote venue URL or DID (omit for local)
strictbooleanNoValidate output against operation schema
foreachobjectNoRun the step once per element of a collection — see Fan out over a collection

Result Composition​

The result field defines what the orchestration returns, using the same resolution syntax:

"result": {
  "scanned": [0, "output"],
  "enriched": [1, "output"],
  "decision": [2, "output"],
  "timestamp": ["const", "2026-04-12"]
}

Error Handling​

  • If strict: true on a step, its output is validated against the operation's schema — violations fail the orchestration immediately
  • If a step's operation fails, all steps depending on it also fail
  • Independent steps continue running even if a sibling fails (unless global strict mode is set)

Patterns​

Fan out over a collection (foreach)​

A step with a foreach object runs its operation once per element, as concurrent child jobs, and returns an ordered array of the per-element outputs:

"steps": [
  { "op": "v/ops/covia/read", "input": { "path": ["const", "w/invoices"] } },
  {
    "op": "v/ops/agent/request",
    "foreach": { "in": [0, "value"], "maxConcurrency": 4 },
    "input": {
      "agentId": ["const", "Classifier"],
      "input": { "invoice": ["item"], "position": ["index"] },
      "timeout": ["const", 60000]
    }
  }
]

Inside a foreach step's input, ["item"] binds the current element (["item", "field"] for a path within it) and ["index"] its zero-based position. Arrays iterate element-wise; maps iterate as [key, value] pairs. Output order matches source order regardless of completion order. The first failing element fails the step (in-flight elements finish), and the venue caps collection size and concurrency — see COG-12 § Foreach Steps for the full semantics.

Agent Pipeline​

Chain agents where each processes the previous one's output:

"steps": [
  { "op": "v/ops/agent/request", "input": { "agentId": ["const", "Scanner"], "input": ["input"], "timeout": ["const", 60000] } },
  { "op": "v/ops/agent/request", "input": { "agentId": ["const", "Enricher"], "input": [0, "output"], "timeout": ["const", 60000] } },
  { "op": "v/ops/agent/request", "input": { "agentId": ["const", "Approver"], "input": [1, "output"], "timeout": ["const", 60000] } }
]

Parallel Fan-Out​

Independent steps run concurrently:

"steps": [
  { "op": "v/ops/http/get", "input": { "url": ["const", "https://api-a.example.com/data"] } },
  { "op": "v/ops/http/get", "input": { "url": ["const", "https://api-b.example.com/data"] } },
  { "op": "v/ops/json/merge", "input": { "values": [[0, "body"], [1, "body"]] } }
]

Steps 0 and 1 run in parallel; step 2 waits for both.

Cross-Venue Federation​

Route individual steps to remote venues:

"steps": [
  { "op": "v/ops/covia/read", "input": { "path": ["const", "w/data"] } },
  { "op": "v/ops/covia/read", "input": { "path": ["const", "w/data"] }, "venue": "did:web:partner.example.com" },
  { "op": "v/ops/json/merge", "input": { "values": [[0, "value"], [1, "value"]] } }
]