The supervisor pattern: one boss agent, several specialists

My best supervisor graph and my most embarrassing one were the same architecture, six months apart. In January I wired a supervisor over three specialists to help chip away at our 400k-line monorepo, and it earned every millisecond of its overhead. Last autumn I shipped a two-agent split that was, in hindsight, one agent wearing a fake mustache. Same picture. Opposite outcomes. The gap between them is the whole article.

what the supervisor actually is

A supervisor is a routing node. It reads shared state, decides which specialist should act next, and returns a Command that points an edge at that specialist (research, code, or review, in my case). Each specialist is its own subgraph with its own tools and its own slice of context, and control always returns to the supervisor to pick the next hop.

def supervisor(state) -> Command:
    nxt = route(state)  # research | code | review | END
    return Command(goto=nxt, update={"last": nxt})

The subgraph is the mechanism; the supervisor is just a node that keeps choosing. The reason to reach for it is two concrete pressures a single agent handles badly.

pressure one: tool count

The refactor agent started life as one node with every tool bolted on: read a file, grep the repo, run the type checker, apply an edit, run the tests, open a scratch file, query the code graph. Thirty-one tools by the time I bothered to count. Somewhere past fifteen, the model began picking plausible-but-wrong tools, the way I do in a strange kitchen. Splitting into a researcher with seven tools, a coder with three, and a reviewer with two dropped each to a short menu, and tool-selection mistakes fell off a cliff. Nothing clever happened. The model just had less to get wrong.

pressure two: context isolation

The researcher's job is to read a lot and hand back a short brief. Its context fills with whole files, twenty-odd thousand tokens of source it will never need again. If that same agent then writes the patch, all that noise rides along and the edits get worse. A supervisor lets the researcher's context die at the handoff. The coder starts fresh with the brief, not the reading. A clean context per specialist is the one thing you cannot buy from one-agent-many-tools, and it's the same case I made for claude-code-subagents in a different tool.

A specialist is worth its latency only when it carries either fewer tools or a cleaner context than the generalist it replaced.

the handoff is the design

Everyone draws the boxes. What decides whether this works is what crosses them. My first handoff passed the entire message history between specialists, which undid the context isolation I'd just paid for. The fix was to make the handoff a small typed payload: a task brief, a list of artifact references (file paths, not file contents), and a status. The transcripts stay inside each subgraph and never cross the boundary. State at the supervisor level is deliberately thin: who ran, what they produced, what's left to do. advanced-agent-architecture goes deeper on why fat shared state is exactly where multi-agent systems rot.

the two-agent system that was theater

Now the embarrassing one. For three weeks last autumn I ran a planner agent and an executor agent for a client's onboarding-doc generator and called it separation of concerns. In practice the two carried the same tools, saw the same context, and passed a nearly identical blob back and forth. The planner reasoned about the task, the executor reasoned about it again before acting, and I had bought two extra model calls and roughly four seconds of latency per turn to accomplish nothing a single prompt couldn't. I collapsed them into one agent with a plan-then-act instruction; the output was identical and p50 latency dropped by about a third.

Before I split anything now, three questions settle it:

• Would the specialists carry genuinely different tools, or the same set with new labels?
• Does one agent's context actively poison the next one's work?
• Can I route them to different models and save real money doing it?

Two yeses and the split is real. All nos and I'm building a slower version of one agent, then drawing a diagram to feel better about it.

cost accounting, per specialist

Once the specialists are real, tag their runs. I label every trace with the specialist name, and the first week's numbers were lopsided in a useful way: the researcher ate 68% of the budget, the reviewer barely 9%. That's a routing decision waiting to happen: I moved the researcher onto a cheaper model and left the reviewer on the strong one, because reading tolerates a weaker model and judgment doesn't. You can't make that call until you can see spend per role. That's the quiet third payoff of the pattern, after tool count and context.

The supervisor earns its keep when the specialists genuinely differ. When they don't, you've bought latency and a nice picture.