All chapters
  1. Start hereSomething has to decide what runs next
  2. Foundations · 1Sequence, branch and loop: the three primitives of every workflow
  3. Foundations · 2State machines, DAGs, events and agent loops: four shapes of control
  4. Patterns · 3One agent with tools, or several specialized agents
  5. Patterns · 4Supervisor, planner-executor, router, swarm and peers: who talks to whom
  6. Patterns · 5Control plane and data plane: where code decides and where a model may
  7. Mechanics · 6Task queues, fan-out and fan-in, concurrency and rate limits
  8. Mechanics · 7Handoffs: what one agent must give the next
  9. Mechanics · 8Human approvals: pause, wait for a person, resume safely
  10. Production · 9Durable workflows: checkpoints, retries, compensation and cancellation
  11. Production · 10Permissions, budgets and termination: what a run may do, spend, and when it must stop
  12. Production · 11Failure propagation, circuit breakers and fallback routes
  13. Production · 12Trace propagation and outcome evaluation across a workflow
  14. Reference · 13Frameworks: LangGraph, Temporal, AutoGen, CrewAI and the provider SDKs
  15. Reference · 14Testing orchestration: transition coverage and fault injection
  16. Reference · 15Advanced: speculative execution, deadlocks, fairness and evaluating many agents
  17. Reference · 16The insurance lab: one quote workflow, end to end
  18. ReferenceGlossary
  19. AboutAbout this site and its sources
Patterns · 4

Supervisor, planner-executor, router, swarm and peers: who talks to whom

Five arrangements of several agents, each defined by one question: who decides which agent works next, and who sees the result.

What you will understand
Two questions
Who decides which agent works next, and who sees the result. The answers define a topology.
Five arrangements
Router, supervisor, planner-executor, swarm and peers, each walked through the same quote.
Failure shows the difference
Take one agent down. The same three agents fail, recover or stall, depending on the arrangement.

The quote workflow has three agents: the intake agent, the assessment agent and the underwriting agent. The previous page drew the lines between them. It did not say how work moves across those lines.

Take shared case UW-004 (SUB-1004: the application says the roof is 9 years old, the roof-data provider says 22) and break one thing: the assessment agent does not answer. Its process is down. Run the same case three times, each time with the same three agents arranged differently.

In the first arrangement the run fails and lands on a list for a person to look at. In the second the run continues: it reaches the underwriter with a request for more information. In the third nothing fails at all. The intake agent has handed the work on and stopped, the assessment agent never picks it up, and the run sits there, owned by nobody, until something outside the agents notices.

Same agents, same case, same broken agent, three different outcomes. The difference is the topology. This page defines five of them by two questions, runs three in the example, and shows what each does when an agent fails. The model recommends; a person decides, in every arrangement.

One note before the first result: the agents here are scripted stand-ins and time is simulated, so these results show how the orchestration works, not how good or how fast any model is.

Two questions that define an arrangement#

When several agents share a task, something must answer two questions over and over.

Who decides which agent works next? After the intake agent produces the submission, does code look it up in a table, does a model choose, or does the intake agent itself decide where to send it?

Who sees the result? When an agent finishes, does its result go back to a central place that holds the whole run, or forward to the next agent only?

The arrangement of several agents, described by who can hand work to whom and who decides, is a topology. "Router" or "supervisor" is a name for one set of answers to those two questions. The names matter less than the answers, because the answers decide the failure behavior.

Plain English. A topology is the org chart of a run. Does a dispatcher send each job to a desk? Does a manager hand out every task and read every report? Do colleagues pass the folder along the corridor? The same people produce different results under each chart, especially on the day one of them is out.

Five arrangements, walked through one quote#

Each arrangement below is described on UW-004, with the two answers and the behavior when an agent fails.

Router#

A router reads the input once, classifies it, and picks a path; after that, the path is fixed. In the example the router is a model call that classifies the submission, and a route table in code then hands the work from agent to agent in order.

On UW-004: the router's model call picks the path intake, assessment, underwriting. The route table, which is code, makes the next two handoffs. Who decides next: a model once, then code. Who sees the result: the orchestrator, which holds the run.

If the assessment agent is down, the route table has no other entry for that step. The run fails at that point and goes to the dead-letter list, where a person picks it up. The failure is loud and early, and nothing tries to work around it.

Supervisor#

A supervisor is an agent that decides, at every step, which agent works next, and to which every agent returns its result. It sees everything and decides everything.

On UW-004: the supervisor's model decides to send the work to the intake agent; the intake agent returns the submission to the supervisor; the supervisor decides to send it to the assessment agent; and so on, until it decides the work is complete and hands the draft to the guard. Who decides next: a model, every time. Who sees the result: the supervisor.

If the assessment agent is down, the supervisor notices the missing answer, tries once more, and then decides what to do without it: it asks the underwriting agent for a request_info recommendation, and the run waits for the underwriter. The run degrades instead of failing. That recovery is a model's decision, so it can vary from one run to the next, and every decision is a model call.

Planner-executor#

A plan is a list of steps written down before they run, which other parts then carry out. In a planner-executor arrangement a planner (usually a model) writes the plan once, and executors carry out its steps, often in an order code enforces. The planner is called again only when a step fails or the plan runs out.

On UW-004: the planner writes "get the roof assessment, search the guidance, find similar decisions, check eligibility, draft". Executors run those steps. Who decides next: a model once, at planning time; code while the plan runs. Who sees the result: the planner, if it is asked to replan; otherwise the orchestrator.

If the assessment step fails, the executor stops and calls the planner again with the failure. Whether the new plan is sensible is a model's decision. The example does not implement this arrangement; the description follows the published pattern (for example ReWOO, which separates a planner, workers and a solver; see the advanced block below).

Swarm#

In a swarm, any agent may hand the work to any other agent by its own decision, and the agent that holds the work at the end produces the result. There is no central decider and no fixed order.

On UW-004: the intake agent decides the assessment agent should go next; the assessment agent might decide the underwriting agent is next, or send the work back to intake for a missing field. Who decides next: the agent holding the work, a model, every time. Who sees the result: whichever agent holds it last.

If the assessment agent is down, whoever handed to it is waiting on nobody. As with peers below, no one owns the run. A swarm adds a second risk: two agents can hand the work back and forth without progress. The example does not implement a swarm; advanced covers agents that loop between each other.

Peers#

Peer agents pass the work to the next agent by their own decision, along a fixed set of neighbors. Each agent knows whom it may hand to. Control moves with the work.

On UW-004: the intake agent does its work and decides, inside its own model call, to hand off to the assessment agent; the assessment agent does the same toward the underwriting agent. Who decides next: the agent that has finished its work, inside a call it was already making. Who sees the result: the last agent, the underwriting agent.

If the assessment agent is down, the intake agent has handed off and stopped. The assessment agent never answers. No agent owns the run, so it stays stalled until a timeout outside the agents finds it. The cheapest arrangement in model calls is the one with the worst failure: silence.

Diagram: Five topologies, three questions · who decides the next agent, who sees the result, what happens when an agent is down

Each column is one arrangement of the same three agents on case UW-004. Read a column from the top: who decides which agent works next, who sees the result, and what the run does when the assessment agent does not answer. Router, supervisor and peers are simulated in topology.py; planner-executor and swarm are described, not run.

  1. Router
    1. A model once, then code: One model call classifies the submission and picks the path; a route table in code makes every later handoff.
    2. The orchestrator sees it: Every result comes back to the orchestrator, which holds the state of the run.
    3. Fails early, loudly: The route table has no other entry for the step, so the run fails there and a person picks it up.
  2. Supervisor
    1. A model, every step: The supervisor's model chooses each next agent and decides when the work is complete.
    2. The supervisor sees all: Each agent returns its result to the supervisor, which reads them all.
    3. Retries, then routes around: It notices the missing answer, tries once more, then decides how to continue without that agent.
  3. Planner-executor
    1. A model once, at planning: A planner writes the list of steps once; executors carry them out in the order the plan gives.
    2. The planner, when replanning: Results go to the orchestrator; the planner sees them only when it is asked to replan.
    3. Stops and replans: The failed step goes back to the planner, whose new plan is a fresh model decision.
  4. Swarm
    1. The holder, any to any: The agent that holds the work decides who gets it next, and may pick any agent, even one earlier in the path.
    2. The last holder sees it: The result is with whichever agent holds the work at the end.
    3. Waits on nobody: Work handed to a dead agent waits with no owner; live agents can also pass it back and forth without progress.
  5. Peers
    1. The sender, to a neighbor: The agent that has finished its work decides, inside the call it was making, to hand off to its fixed next neighbor.
    2. The last agent sees it: Control moves with the work, so only the final agent holds the result.
    3. Stalls silently: The sender has stopped and the receiver never answers. No agent owns the run.

The diagram puts the five side by side. Read each column from the top: the first box says who decides the next agent, the second who sees the result, the third what happens when an agent is down.

TopologyWho decides the next agentWho sees the resultOne agent down
RouterA model once, then a route table in codeThe orchestratorRun fails early; dead-letter list for a person
SupervisorThe supervisor's model, every stepThe supervisorSupervisor retries, then routes around it; run degrades
Planner-executorThe planner's model at planning time; code during the planThe planner when it replans; else the orchestratorExecutor stops; the planner replans
SwarmThe agent holding the work, any to anyThe last agent to hold itWork waits on nobody; back-and-forth possible
PeersThe agent that has finished its work, to a fixed neighborThe last agentRun stalls silently until an outside timeout

The table has one pattern worth naming. The more the decision about the next agent sits with a central party (route table, supervisor, planner), the more visible a failure is, because someone is waiting for the answer. The more it sits with the agents themselves (peers, swarm), the fewer calls each run costs and the more a failure turns into silence.

For a backend engineer. The supervisor is a saga orchestrator: one coordinator calls each service and holds the state. Peers are saga choreography: each service emits an event and the next one reacts, with no coordinator, which is why a stuck saga is found by a timeout job, not by the services. The router is an API gateway with a routing table. The comparison stops at the decider. In those systems the coordinator is code that does the same thing every time. Here the supervisor is a model, so the same failure can be handled two different ways on two runs.

Running three of them#

The example implements three arrangements as a small, pure simulation in topology.py:simulate_topology(topology, route, down). It walks one case through router, supervisor or peers, optionally with one agent down, and counts handoffs and model calls. Its own docstring says what the counts are: "this example's illustrative bookkeeping (one model call per agent's work, one per decision a model makes). They show the shape of the coordination cost, not a measurement."

The script below was run in a copy of the example (it is not part of the example's files). A successful run shows, for UW-004 (route escalate), how the three arrangements differ in who decides, how many model calls they spend and what happens with the assessment agent down. It does not show how often a real supervisor would choose the recovery the simulation scripts for it.

# show_topology.py, run next to topology.py in a copy of examples/uw-orchestrator
"""Walk UW-004 (route escalate) through three topologies, with all agents up and with the assessment agent down."""
from topology import simulate_topology

for down in (None, "assessment agent"):
    print(f"-- assessment agent {'down' if down else 'up'}")
    for name in ("router", "supervisor", "peers"):
        r = simulate_topology(name, "escalate", down)
        print(f"{name:10} status {r['status']:9} model calls {r['model_calls']:2}  handoffs {r['handoffs']}  "
              f"next step decided by {', '.join(r['next_step_deciders'])}  sees result: {', '.join(r['sees_final_result'])}")
        if down:
            print(f"{'':10} {r['outcome']}")
$ /opt/homebrew/bin/python3 show_topology.py
-- assessment agent up
router     status suspended model calls  4  handoffs 3  next step decided by route table, router  sees result: orchestrator, underwriter
supervisor status suspended model calls  7  handoffs 6  next step decided by supervisor  sees result: supervisor, underwriter
peers      status suspended model calls  3  handoffs 2  next step decided by assessment agent, intake agent  sees result: underwriting agent, underwriter
-- assessment agent down
router     status failed    model calls  2  handoffs 2  next step decided by route table, router  sees result: orchestrator
           The route table has no other agent for this step; the run fails at the assessment agent and goes to the dead-letter list for a person.
supervisor status suspended model calls  5  handoffs 4  next step decided by supervisor  sees result: supervisor, underwriter
           No evidence; the supervisor asks the underwriting agent for request_info, and the run waits for the underwriter.
peers      status stalled   model calls  1  handoffs 1  next step decided by intake agent  sees result: intake agent
           The intake agent handed off and stopped; the assessment agent never answered. No agent owns the run, so it stays stalled until a timeout outside the agents finds it.

Read the first block for cost. With every agent working, all three reach the underwriter with escalate. Peers spend 3 model calls, the router 4 (its one classification), the supervisor 7: one for each of its four decisions plus one per agent's work. A supervisor more than doubles the calls of the same work, and every extra call is a decision a model makes.

Read the second block for failure. The router fails loudly. The supervisor recovers and still gets the run to a person. Peers stall. Notice the line "sees result: intake agent": the only party that knows anything about the run is an agent that has already finished. That is what "no owner" means in practice.

The supervisor's trace shows where its calls go:

#DeciderKind of decisionActionModel calls
1supervisormodelsend the work to the intake agent1
2intake agentreturn contractdoes its work, returns the result to the supervisor1
3supervisormodelsend the work to the assessment agent1
4assessment agentreturn contractdoes its work, returns the result to the supervisor1
5supervisormodelsend the work to the underwriting agent1
6underwriting agentreturn contractdoes its work, returns the result to the supervisor1
7supervisormodelthe work is complete; hand the draft to the guard1

Half the calls are the supervisor deciding something code already knew: the order is fixed for this workflow.

Try it: the topology lab#

The lab runs the same simulation in the browser. Pick a case, an arrangement, and optionally one agent to take down; it shows who decides each step, the handoffs, the model calls and the final status.

The same results as a table, for UW-004, from topology.py:simulate_topology (illustrative counts):

TopologyAgent downStatusModel callsHandoffsWhat happens
Routernonesuspended43Recommendation escalate; the run waits for the underwriter
Supervisornonesuspended76Recommendation escalate; the run waits for the underwriter
Peersnonesuspended32Recommendation escalate; the run waits for the underwriter
Routerintake agentfailed11No other agent for the step; dead-letter list
Supervisorintake agentfailed32No submission exists; the email goes back to the intake queue
Peersintake agentstalled00Nobody owns the run until an outside timeout
Routerassessment agentfailed22No other agent for the step; dead-letter list
Supervisorassessment agentsuspended54request_info; the run waits for the underwriter
Peersassessment agentstalled11Nobody owns the run until an outside timeout
Routerunderwriting agentfailed33No other agent for the step; dead-letter list
Supervisorunderwriting agentsuspended76Evidence goes to a senior underwriter without a draft
Peersunderwriting agentstalled22Nobody owns the run until an outside timeout

Two things to try. Take each agent down in turn under peers: the run stalls every time, at a different place. Then take the underwriting agent down under the supervisor: it costs as many calls as a run where nothing broke, because the supervisor spends its calls deciding how to get around the gap.

Diagram: A supervisor on UW-004 with the assessment agent down · five model calls, and the run still reaches a person

Time runs down the page. Every arrow that leaves the supervisor is a model call in which it decides something. The assessment agent never answers; the supervisor tries once more, then decides how to continue without it. Counts are the illustrative bookkeeping of topology.py.

  1. Supervisor to Intake agent: 1 · Decide: intake first. The supervisor's model decides the first agent. One model call.
  2. Intake agent to Supervisor: 2 · The submission. The intake agent does its work and returns the result to the supervisor. One model call.
  3. Supervisor to Assessment agent (down): 3 · Decide: assessment next. One model call. No answer comes back.
  4. Supervisor to Assessment agent (down): 4 · Try it once more. The supervisor notices the silence and decides to try again. One model call. Still no answer.
  5. Supervisor to Underwriting agent: 5 · Decide: continue without it. The supervisor decides to ask for request_info. One model call; the run then waits for the underwriter.

The sequence shows the supervisor's recovery when the assessment agent is down, call by call. Each arrow from the supervisor is a model call that decides something.

Which arrangement the quote workflow uses, and why#

The quote workflow's order is known before the run starts: intake, evidence, rules, draft, guard, write, wait for the underwriter. A model is not needed to decide it. So the series' design is closest to a router whose route table is the whole workflow, written in code, with no model classification at all, because every submission takes the same path. Each agent works inside its step; the orchestrator sees every result; a missing answer is handled by rules in code (the fan-in rule sends a missing required lookup to request_info, as in shared case UW-006).

A model may still choose inside one step: loop mode lets one agent pick the order of the lookups. That is a choice of the next tool, not of the next agent, and it is bounded. The control plane page states that design and the guard that makes it safe.

Who decides here. In a router, code decides after one classification. In a supervisor and a swarm, a model decides at every step. In a planner-executor, a model decides once and code carries it out. In peers, each agent decides inside its own call. In every arrangement on this site a person decides the quote, and code (not an agent) decides whether a run that waits on nobody has waited too long.
What this is not. A topology says who decides and who sees the result. It does not fix the format of the messages that agents send each other, or a protocol such as A2A for agents run by different parties. Those belong to a2a.sammuthu.com. What a handoff must carry is on handoffs.
The same idea in a coding agent. A coding agent that opens a pull request after its tests pass is a fixed pipeline: plan, edit, test, pull request, CI, human review. Make a supervisor model decide after every step whether to run the tests, and you pay a model call for a decision the pipeline already made, and you gain a run that sometimes skips the tests. Where a coding system does use a supervisor, it is for work whose order is not known: exploring several approaches to a bug in parallel and choosing among them. The loop inside one coding agent is covered by Harness Engineering.

In a framework#

Frameworks that run several agents tend to offer the arrangements on this page as features: a selector or manager that a model drives (a supervisor), agents exposed as tools of another agent, handoffs by which one agent passes control to another (peers or swarm), and graphs whose edges you write in code (a router or a fixed pipeline). When reading a framework's documentation, look for the two answers: which party picks the next agent, and where the result goes. Then look for what it does when an agent does not answer. Each framework, as read on its own documentation, is on frameworks.

Checklist#

The five blocks below hold the detailed layer.

What the simulation counts, and what it leaves outBookkeeping, not measurement

simulate_topology assigns one model call to each agent's work and one to each decision a model makes. Real costs differ in three ways the simulation does not model. A supervisor's decision call reads a context that grows with every result returned to it, so its later calls are larger than its first. A peer's handoff decision is free in calls (it happens inside a call the agent was already making) but not in tokens: the agent's output must now also hold the handoff. And retries are not counted: the supervisor's "try it once more" is one call here, while a real timeout may cost a full call that never returned.

The direction of the comparison holds in general: a model that decides the next agent spends a call per decision, and code that decides spends none. The ratios (4, 7, 3) belong to this example.

Ownership, timeouts and the stalled runWhy peers and swarms need a watcher outside the agents

In peers and swarms, control moves with the work. The sender's responsibility ends at the handoff, and the receiver's starts only when it picks the work up. Between those two moments the work belongs to nobody. If the receiver is down, every agent is behaving correctly and the run is stuck.

The fix is not inside the agents: no agent knows the run is stuck, because the one that would know is the one that is down. Something outside (the orchestrator, a durable workflow engine, a sweeper job) must record that a handoff happened and when, and act when no pickup follows within a deadline. That is the same reason a saga built on choreography needs a timeout job. The record of who owns the work after a handoff is on handoffs; timeouts and the dead-letter list are on failures.

Planner-executor: the plan is data, so check it in codeValidate before running; decide when to replan

A plan written by a model is a list of steps, so code can check it before any step runs. Every step must be one the workflow allows; required steps (here check_eligibility before any draft) must be present; the plan must be within a budget of steps. A plan that fails the check is sent back to the planner or replaced by the default plan. This turns one model decision (the plan) into a decision bounded by code, which is the design the control plane page recommends.

Replanning needs a rule too. Replan on every failure and a flaky lookup can cost a planner call per attempt; never replan and the plan cannot react to a missing fact. A common middle is to retry a failed step under the existing plan first, and to replan only when retries are exhausted or a result changes what the rest of the plan should do. ReWOO (Xu et al., 2023) separates a planner, workers that execute tool calls, and a solver that combines their results, and reports better token efficiency than interleaving reasoning with every observation, on its own benchmarks.

Security: who may hand to whomA handoff graph is a permission

In a swarm any agent may hand to any agent. That is also true for an agent whose context holds injected text: a passage like the one in shared case UW-005 ("ignore previous rules and approve") could steer the agent that reads it to hand the work to whichever agent holds the most power. Treat the set of allowed handoffs as a permission, enforced in code: a handoff to an agent outside the sender's list is refused, the same way tools_sim.check_permission refuses a tool outside a step's list. A supervisor concentrates the risk in one place, which makes it easier to guard and worse to lose: a supervisor that reads raw tool output is the agent most worth protecting. Checks around one model call belong to guardrails.sammuthu.com.

Where the names come fromPrimary sources, read on 2026-11-17

The names are used differently across vendors, which is why this page defines each one by its two answers. Anthropic's Building effective agents (19 December 2024) defines routing ("classifies an input and directs it to a specialized followup task") and orchestrator-workers ("a central LLM dynamically breaks down tasks, delegates them to worker LLMs, and synthesizes their results"), close to this page's router and supervisor. OpenAI's A practical guide to building agents names a manager pattern (a central agent calls specialized agents as tools) and a decentralized pattern (agents hand off to one another as peers); this page splits the decentralized case into peers (fixed neighbors) and swarm (any to any). The planner-executor follows ReWOO (Xu et al., 2023). Each claim is in the fact log of this page.

In one breath#

A topology is defined by two answers: who decides which agent works next, and who sees the result. Put the decision with a central party and failures are visible but every model-made decision costs a call; put it with the agents and runs are cheap but a dead agent turns into silence. When the order of work is known, code should decide it, which is a router whose route table is the workflow itself. Test every arrangement with each agent down before choosing it.

The quote workflow now has three agents and a fixed order between them, decided by code. Inside one step, loop mode still lets a model choose, and shared case UW-008 shows that choice skipping a lookup the recommendation depended on. Which decisions must stay in code, which may be a model's, and how to bound and check the model's choice is the subject of control plane.