Supervisor Subagent Patterns

One manager agent decides who works next and checks each result. Workers never talk to each other, so every step stays easy to trace.

A central supervisor routes a researcher, a coder, and a writer 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 the token meter climbs. Nobody decided anything, so nobody can say where it went wrong.

A supervisor fixes that with a strict 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 orchestration. How messages are validated lives in agent communication protocols. How the job is split before routing lives in task decomposition, and the lookup leg lives in retrieval-augmented agents.

Basics 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.

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 a small fixed set of phrases, so nobody mistakes 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 phrase book. 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 $S$ . $S$ 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 $W$ . $W$ is three workers: $w_1$ the researcher with web search only, $w_2$ the coder with the Python runner only, $w_3$ the writer with drafting only. One handoff is $M$ , a single message between $S$ and one worker. A routing decision is $d$ , which comes from a closed list. Turns are counted by $t$ , which runs until $T_{\max}$ , the hard cap on turns.

The parts

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

$S$ holds $P_S = 300$ tokens of routing rules and no work tools. A narrow tool list per worker leaves no wrong tool to grab. If the writer could call Python, it eventually would.

$d$ comes from four options and nothing else: researcher, coder, writer, or FINISH. A closed vocabulary turns routing into a checkable choice. $T_{\max} = 6$ caps the job. When $t$ reaches $6$ , $S$ stops and reports, even mid debate.

Worked example

Take the plotting job from the diagram: find two quarterly figures, plot the latest, draft the note. You ask once. Then $S$ sends $60$ tokens of instruction to the researcher, who returns $h_1 = 120$ tokens of finding. $S$ checks the key numbers are present and routes to the coder, who returns $h_2 = 90$ tokens. $S$ routes to the writer, who returns $h_3 = 60$ tokens of draft. $S$ sets $d$ to FINISH and sends $h_4 = 30$ tokens of final answer to you. Three worker calls plus four manager calls make seven model calls in total.

Use the numbers from the diagram and check them by hand. The researcher returns $81.4$ and $89.5$ . Growth is $(89.5 - 81.4) / 81.4$ . The difference is $89.5 - 81.4 = 8.1$ . Divide: $8.1 / 81.4 \approx 0.0995$ , about $9.9$ percent. Quick check: $81.4 \times 0.1 = 8.14$ , so $8.1$ sits just under ten percent.

Handoffs written are $120$ , $90$ , $60$ , and $30$ . Total written is $W = 120 + 90 + 60 + 30 = 300$ tokens. Check it: $120 + 90 = 210$ , plus $60 = 270$ , plus $30 = 300$ . Each written token is read at least once after it is written, so transit costs about $2 \times 300 = 600$ tokens before you count any prompt. Routing reads add $4 \times 300 = 1200$ tokens.

Skip 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.

Code

The point here is the accounting, not a framework. This stdlib-only snippet rebuilds the trace and recomputes the three numbers, so you can check your own logs the same way:

1from dataclasses import dataclass2
3
4@dataclass5class Handoff:6    label: str7    tokens: int8
9
10handoffs: list[Handoff] = [11    Handoff("finding", 120),12    Handoff("plot", 90),13    Handoff("draft", 60),14    Handoff("final", 30),15]16
17written: int = sum(h.tokens for h in handoffs)18transit: int = written * 2  # written once, read once19routing_cost: int = 300 * 4  # routing prompt times manager calls20
21print(written)  # -> 30022print(transit)  # -> 60023print(routing_cost)  # -> 120024print((89.5 - 81.4) / 81.4)  # -> 0.099507...

Written sums to $300$ , transit to $600$ , routing to $1200$ , and the growth line reproduces the $0.0995$ from the worked example. 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 $S$ , so four manager calls re-read $300$ tokens of routing each, $1200$ tokens before any worker thinks. A big slow model in $S$ multiplies that on every turn.

Fix it with a small fast router and a closed decision list. Enforce the six-turn cap in code, not in prose. Make $S$ quote the key numbers back before routing, and stop the job when two turns change nothing.

A clean handoff with a dropped number

Symptom: each step looks fine and the answer is wrong. The coder plots $81.4$ instead of $89.5$ . The writer quotes last quarter as this quarter. No crash, no retry, just a confident wrong figure.

Fix it at the handoff. Give each message a schema that requires the key figures by name, and reject results that omit them. Route the error back to the same worker once, then stop and report.

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.