Skip to content
AI360XpertBeta

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.

A central supervisor routes three workers in a star with no peer links, finishing in four handoffs that move 300 written tokens
A central supervisor routes three workers in a star with no peer links, finishing in four handoffs that move 300 written tokens

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 SS. SS 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 WW. WW is the set of workers, here three: w1w_1, the researcher; w2w_2, the coder; w3w_3, the writer. Each worker wiw_i carries two things: PiP_i, its prompt in tokens, which is the instruction text it reads every turn; and TiT_i, its tool set, which is the actions it may call. One handoff is MM, a single message between SS and one worker. Its payload is pp, the useful tokens inside MM. A routing decision is dd, the manager choice, which comes from a closed list. Turns are counted by tt, the step number, which runs until Tmax⁡T_{\max}, the hard cap on turns that stops a loop. The routing rule is RR, the function SS applies to the task plus the history to produce the next dd.

The parts

The star topology is the whole constraint. Edges run only between SS and one wiw_i. There are no worker to worker edges. That is what the diagram proves: three mint arrows down from SS, report backs up to SS, and amber crosses where peer links would be.

SS holds PS=300P_S = 300 tokens of routing rules and TS={}T_S = \{\}, no work tools. Least privilege does the heavy lifting here. The researcher holds T1={web}T_1 = \{\text{web}\}, web search only. The coder holds T2={python}T_2 = \{\text{python}\}, the Python runner only. The writer holds T3={email}T_3 = \{\text{email}\}, drafting only. A narrow tool list leaves no wrong tool to grab. If the writer could call Python, it eventually would.

dd comes from {w1,w2,w3,FINISH}\{w_1, w_2, w_3, \text{FINISH}\}, four options and nothing else. A closed vocabulary turns routing into a checkable choice. Vague prose like handle it next fails validation. Tmax⁡=6T_{\max} = 6 caps the job. When tt reaches 6, SS 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:

  • t=1t = 1: SS applies RR to your task and sets d=w1d = w_1. It sends MM with pp of 60 tokens of instruction to the researcher.
  • t=2t = 2: the researcher returns h1=120h_1 = 120 tokens of finding. SS reads it, checks the key numbers are present, and sets d=w2d = w_2.
  • t=3t = 3: the coder returns h2=90h_2 = 90 tokens. The script is ready. SS sets d=w3d = w_3.
  • t=4t = 4: the writer returns h3=60h_3 = 60 tokens of draft. SS sets d=FINISHd = \text{FINISH} and sends h4=30h_4 = 30 tokens of final answer to you.

Three worker calls plus four manager calls. Seven model calls in total. Each MM is validated before the next agent wakes, the way agent-to-agent protocols describes. If a result is missing its numbers, SS reasks the same worker instead of routing forward.

Worked example

Use the numbers from the diagram and check them by hand.

The researcher returns 81.481.4 and 89.589.5, two quarterly figures. Growth is (89.5−81.4)/81.4(89.5 - 81.4) / 81.4. The difference is 89.5−81.4=8.189.5 - 81.4 = 8.1. Divide: 8.1/81.4≈0.09958.1 / 81.4 \approx 0.0995, about 9.99.9 percent. Quick check: 81.4×0.1=8.1481.4 \times 0.1 = 8.14, so 8.18.1 sits just under ten percent. That matches the footer.

Handoffs written are h1=120h_1 = 120 for the finding, h2=90h_2 = 90 for the plot result, h3=60h_3 = 60 for the draft, h4=30h_4 = 30 for the final. Total written is W=120+90+60+30=300W = 120 + 90 + 60 + 30 = 300 tokens. Check it: 120+90=210120 + 90 = 210, plus 60=27060 = 270, plus 30=30030 = 300. Each written token is read at least once after it is written, so transit costs about 2×W=6002 \times W = 600 tokens before you count any prompt. Routing reads add 4×PS=4×300=12004 \times P_S = 4 \times 300 = 1200 tokens.

So the trade is concrete. You replace peer chat and its mystery loops with 12001200 tokens of routing plus 600600 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 pp carries its key numbers. When a handoff drops 89.589.5, or SS 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)  # -> True

Written 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 SS, so four manager calls re-read PS=300P_S = 300 tokens each, 12001200 tokens of routing before any worker thinks. A big slow model in SS multiplies that on every turn.

Fix it with a small fast router and a closed dd list. Enforce Tmax⁡=6T_{\max} = 6 in code, not in prose. Make SS 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 SS stays huge.

A clean handoff with a dropped number

Symptom: each step looks fine and the answer is wrong. The coder plots 81.481.4 instead of 89.589.5. 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 MM a schema that requires the key figures by name, and reject results that omit them. Make SS check the finding contains 89.589.5 before it sets d=w2d = w_2. 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.