A central orchestrator routes tasks to specialized worker agents based on context

Supervisor

The supervisor pattern uses a central orchestrator agent that analyzes incoming work and routes it to specialized workers. The orchestrator inspects outputs from each worker to determine the next step, acting as a decision-making hub.

When to Use Supervisor

Customer support — route tickets to billing, technical, or general agents based on issue type
Project management — assign tasks to specialists based on requirements
Complex workflows — when the next step depends on dynamic conditions rather than a fixed sequence
Any system where routing logic is too complex for static flow edges

Supervisor is the right choice when you need intelligent, context-dependent routing. If your flow is a fixed sequence, use pipeline. If all agents run at once, use fan-out.

How It Works

The orchestrator block defines the central agent. It receives all incoming work, delegates to workers, and uses their outputs to decide the next routing step.

topology support-team : [supervisor] {
  meta {
    version: "1.0.0"
    description: "Customer support routing with specialized agents"
  }

  orchestrator {
    model: opus
    handles: [intake, resolved]
    outputs: { route: billing | technical | general | escalate }
  }

  agent billing-agent {
    model: sonnet
    tools: [Read, Grep]
    outputs: { status: resolved | needs-escalation }
  }

  agent technical-agent {
    model: sonnet
    tools: [Read, Grep, Bash]
    outputs: { status: resolved | needs-escalation }
  }

  agent general-agent {
    model: haiku
    tools: [Read]
    outputs: { status: resolved | needs-escalation }
  }

  flow {
    intake -> orchestrator
    orchestrator -> billing-agent   [when orchestrator.route == billing]
    orchestrator -> technical-agent  [when orchestrator.route == technical]
    orchestrator -> general-agent    [when orchestrator.route == general]
    billing-agent -> resolved        [when billing-agent.status == resolved]
    technical-agent -> resolved      [when technical-agent.status == resolved]
    general-agent -> resolved        [when general-agent.status == resolved]
    billing-agent -> orchestrator    [when billing-agent.status == needs-escalation]
    technical-agent -> orchestrator  [when technical-agent.status == needs-escalation]
    general-agent -> orchestrator    [when general-agent.status == needs-escalation]
  }
}

Key Concepts

Orchestrator Outputs

The orchestrator declares outputs that determine routing. Each output value maps to a conditional flow edge:

orchestrator {
  outputs: { route: billing | technical | general | escalate }
}

Conditional Routing

Flow edges use when clauses to inspect the orchestrator's output and route accordingly:

flow {
  orchestrator -> billing-agent  [when orchestrator.route == billing]
  orchestrator -> technical-agent [when orchestrator.route == technical]
}

Escalation Loops

Workers can route back to the orchestrator for re-evaluation. This creates a supervision loop where the orchestrator can reassign work or escalate:

flow {
  billing-agent -> orchestrator [when billing-agent.status == needs-escalation]
}

Flow Diagram

                      +---> billing-agent ---+
                      |                      |
intake -> orchestrator+---> technical-agent -+--> resolved
                 ^    |                      |
                 |    +---> general-agent ---+
                 |               |
                 +_______________+
                  (needs-escalation)

Combining with Other Patterns

Supervisor works well with:

pipeline — workers themselves can be multi-phase pipelines
fan-out — orchestrator fans out to multiple workers simultaneously
human-gate — require human approval before the orchestrator routes to sensitive workers

Supervisor

On this page