Supervisor Pattern
One manager agent decides who works next and checks each result. Workers never talk to each other, so the whole job stays easy to trace.
Why Does This Exist?
Put three agents in a shared chat and tell them to sort it out. The demo charms you. The third real job does not. The coder answers the researcher directly, the writer quotes a number nobody sent, and two agents reword the same plan until your token meter climbs. Nobody decided anything, so nobody can say where it went wrong.
A supervisor fixes that with a boring shape. One manager sits in the middle. Every message passes through it. Workers never message each other. You lose the freewheeling cross talk. You gain a log where each step names who was asked, what came back, and who goes next.
This page covers that strict star: the parts, the routing loop, and what it costs. The broader team idea lives in multi-agent systems. The single loop inside each agent lives in AI agent architecture. How a delegation is built lives in sub-agents and handoffs. How each message is validated lives in agent-to-agent protocols.
One idea first. A model call keeps nothing by itself. It reads only the tokens in front of it right now. So the manager must carry the plan, the results so far, and the stop rule in its prompt on every turn. If that clicks, the rest reads cleanly.
Think of It Like This
A control tower on a busy evening
Three planes need to land, refuel, and take off again. The tower clears each move. The pilots never coordinate among themselves on an open channel. Each clearance uses closed phraseology, a small fixed set of phrases, so there is no mistaking a suggestion for an order. When the fuel rule says divert, the tower diverts, even mid queue.
Your manager is the tower. Your workers are the crews. Your handoff is the clearance. Your closed decision list is the phraseology. Your turn cap is the fuel rule.
Where it stops: a real tower watches radar truth. Your manager sees only text the workers wrote. If a report drops the key number, the manager routes on the gap and bills you for the extra trips.
How It Actually Works
Call the manager . is the supervisor, the router that reads each result and picks who works next. It holds a small routing prompt and no work tools. Call the team . is the set of workers, here three: , the researcher; , the coder; , the writer. Each worker carries two things: , its prompt in tokens, which is the instruction text it reads every turn; and , its tool set, which is the actions it may call. One handoff is , a single message between and one worker. Its payload is , the useful tokens inside . A routing decision is , the manager choice, which comes from a closed list. Turns are counted by , the step number, which runs until , the hard cap on turns that stops a loop. The routing rule is , the function applies to the task plus the history to produce the next .
The parts
The star topology is the whole constraint. Edges run only between and one . There are no worker to worker edges. That is what the diagram proves: three mint arrows down from , report backs up to , and amber crosses where peer links would be.
holds tokens of routing rules and , no work tools. Least privilege does the heavy lifting here. The researcher holds , web search only. The coder holds , the Python runner only. The writer holds , drafting only. A narrow tool list leaves no wrong tool to grab. If the writer could call Python, it eventually would.
comes from , four options and nothing else. A closed vocabulary turns routing into a checkable choice. Vague prose like handle it next fails validation. caps the job. When reaches 6, stops and reports, even mid debate. No cap, no production team.
How one task moves
Take the plotting job from the diagram: find two quarterly figures, plot the latest, draft the email. You ask once. Then:
- : applies to your task and sets . It sends with of 60 tokens of instruction to the researcher.
- : the researcher returns tokens of finding. reads it, checks the key numbers are present, and sets .
- : the coder returns tokens. The script is ready. sets .
- : the writer returns tokens of draft. sets and sends tokens of final answer to you.
Three worker calls plus four manager calls. Seven model calls in total. Each is validated before the next agent wakes, the way agent-to-agent protocols describes. If a result is missing its numbers, reasks the same worker instead of routing forward.
Worked example
Use the numbers from the diagram and check them by hand.
The researcher returns and , two quarterly figures. Growth is . The difference is . Divide: , about percent. Quick check: , so sits just under ten percent. That matches the footer.
Handoffs written are for the finding, for the plot result, for the draft, for the final. Total written is tokens. Check it: , plus , plus . Each written token is read at least once after it is written, so transit costs about tokens before you count any prompt. Routing reads add tokens.
So the trade is concrete. You replace peer chat and its mystery loops with tokens of routing plus of transit. Every message passes through the manager. That is the price of the trace.
Do not use this shape for a straight line job. One tool, two steps, no checking: a single agent with a short prompt wins on cost, latency, and debug time. The assumption underneath the star is that the job splits cleanly and each carries its key numbers. When a handoff drops , or misroutes to the writer before the data exists, the team fails exactly like a tower with a bad strip: fast, confident, and aimed at the wrong runway.
Code
The point here is the accounting, not a framework. This snippet rebuilds the trace and recomputes the three numbers from the worked example, so you can check your own logs the same way.
from dataclasses import dataclass
@dataclassclass Handoff: label: str tokens: int
handoffs: list[Handoff] = [ Handoff("finding", 120), Handoff("plot", 90), Handoff("draft", 60), Handoff("final", 30),]
written: int = sum(h.tokens for h in handoffs)transit: int = written * 2 # written once, read oncesupervisor_prompt: int = 300supervisor_calls: int = 4routing_cost: int = supervisor_prompt * supervisor_calls
print(written) # -> 300print(transit) # -> 600print(routing_cost) # -> 1200print(written == 120 + 90 + 60 + 30) # -> TrueWritten sums to 300, transit to 600, routing to 1200. Change any handoff size and the first two lines move together, which is the behavior to watch in your own meter.
Watch Out For
The manager becomes the bill
Symptom: the job is correct and slow, and the meter climbs faster than the work. Every result passes through , so four manager calls re-read tokens each, tokens of routing before any worker thinks. A big slow model in multiplies that on every turn.
Fix it with a small fast router and a closed list. Enforce in code, not in prose. Make quote the key numbers back before routing, and stop the job when two turns change nothing. Never fix the bill by asking the workers to write shorter reports while stays huge.
A clean handoff with a dropped number
Symptom: each step looks fine and the answer is wrong. The coder plots instead of . The writer quotes last quarter as this quarter. No crash, no retry, just a confident wrong figure. You have seen this shape in agent failure modes: a partial win the log does not back up.
Fix it at the handoff. Give each a schema that requires the key figures by name, and reject results that omit them. Make check the finding contains before it sets . Route the error back to the same worker once, then stop and report. A dropped number is a validation miss, not a reasoning gap.
The Quick Version
- A supervisor puts one manager in the middle and forbids worker to worker messages, so each step names who was asked and what came back.
- The manager holds 300 tokens of routing rules and no work tools, and picks the next step from researcher, coder, writer, or finish.
- The example job runs four turns and writes 120 plus 90 plus 60 plus 30 tokens, which sums to 300 written and about 600 in transit.
- The finding 81.4 to 89.5 is about 9.9 percent growth, and the manager checks those figures are present before routing onward.
- The star trades 1200 tokens of routing plus transit for a traceable run with a hard stop at six turns.
- Skip the star for a one tool, two step job, since a single short prompt agent costs less and breaks less.