BuildPython

Supervisor / Orchestrator-Worker Pattern

One lead agent plans and delegates, and specialized workers run in parallel contexts and report back. Anthropic's Research system uses this pattern with Claude Opus 4 as lead and Sonnet 4 as subagents, and measured +90.2% over single-agent Opus 4 on internal research evals. Their engineering post reports that token usage alone explains 80% of the variance on BrowseComp, which suggests fresh context per subagent accounts for much of the win. Here you build the pattern from primitives, then walk through the production lessons from that post.

TIME: ~75 minutesPREREQUISITES: Phase 16 · 04 (Primitive Model)

Learning Objectives

Explain why a lead plus parallel workers beats a single agent on research tasks, using fresh context, prompt specialization and parallelism.
Describe the Anthropic Research system's pairing, results and production lessons: scale effort, broad then narrow, rainbow deployment, token cost.
Run the threaded toy supervisor and read its trace, separating measured values from printed strings.
Identify the failure modes (hallucinated plan, over-exploring workers, synthesis conflict) and the cases where a supervisor is the wrong choice.
Apply the Ship It checklist to a supervisor design.

Problem

Research is a task single agents tend to fail. Ask "what changed in multi-agent systems between 2023 and 2026?" and a single agent reads five papers one after another, fills half its context with their text, and then has to reason over all of them at once. By the fifth paper it is liable to lose its grip on the first. It also cannot parallelize.

The supervisor pattern splits the job. One lead agent plans the search, hands each sub-question to a worker, and synthesizes the answers. Each worker gets its own 200k-token window for a narrow question. The lead sees the worker summaries rather than the raw papers.

Anthropic's production Research system reports +90.2% on internal research evals against a single Opus 4. The same post says 80% of the BrowseComp variance is explained by token usage alone, and fresh context per subagent is the main mechanism behind that.

Warm-up0/3

1. In the four-primitive model from Phase 16 · 04, which primitive decides who acts next?Warm-up

Three agent boxes in a row joined by dashed lines with no arrowheads, and a dashed question box below asking what decides who goes next.

2. In the primitive model, an agent is stateless. What does a fresh run of one start from?Warm-up

3. Two agents must both read and append to one list of findings. Which primitive provides that?Warm-up

Agent A and Agent B each joined by two-way arrows to one shared box labelled list of findings, with a dashed box asking which primitive this is.

Check: Problem0/2

1. What does the term token dominance claim about research evals?Define

Bar heights are placeholders; the real split is not drawn here.

2. Why does the lead read worker summaries rather than the raw papers?Explain

A raw-papers box marked as what workers see above the lead-and-three-worker diagram, with a dashed question box asking why the lead reads summaries instead of the raw papers. — Typed schematic, not captured output.

Concept

The pattern

                 ┌──────────────┐
                 │   Lead       │  plans, decomposes,
                 │  (Opus 4)    │  synthesizes
                 └──┬────┬───┬──┘
                    │    │   │
            ┌───────┘    │   └───────┐
            ▼            ▼           ▼
      ┌─────────┐  ┌─────────┐  ┌─────────┐
      │ Worker1 │  │ Worker2 │  │ Worker3 │
      │(Sonnet) │  │(Sonnet) │  │(Sonnet) │
      └─────────┘  └─────────┘  └─────────┘
         fresh       fresh        fresh
         context     context      context

The lead reads worker summaries, not the raw materials. Workers don't see each other's work until the lead synthesizes. Each arrow is a handoff with a narrow artifact.

Why it wins

Three mechanisms:

Fresh context per subagent. A worker exploring "FIPA-ACL heritage" does not carry the 40k tokens the lead spent planning. It gets a 200k window for one question.
Specialization via prompt. The lead's prompt is "decompose and synthesize," not "research." Each worker's prompt is narrow: "find what changed in X." Focused prompts produce focused outputs.
Parallelism. Workers run concurrently, so wall-clock time is roughly max(worker_times) + plan + synthesis, not sum(worker_times).

Engineering lessons (Anthropic 2025)

The Anthropic post lists several production lessons that still hold in 2026:

Scale effort to query complexity. Simple queries get one agent making 3-10 tool calls. Complex queries get 10+ agents. The lead has to estimate this, not the caller.
Broad then narrow. Decompose into broad sub-questions first, then spawn more workers per sub-question if the answer warrants depth.
Rainbow deployments. Agents are long-running and stateful, so blue-green doesn't work. Anthropic uses rainbow: a gradual rollout of new versions while old ones drain.
Token usage dominates. Multi-agent uses roughly 15× the tokens of single-agent, so run it only when the task value justifies the cost.

The LangGraph turn

LangGraph originally shipped a langgraph-supervisor library with a high-level create_supervisor helper. In 2025 LangChain moved the recommendation to implementing the supervisor pattern via tool-calling directly, because tool calls give more control over what the supervisor sees (context engineering). The library still works, but the docs now recommend the tool-calling form.

The failure modes

Lead hallucinates the plan. If the lead generates sub-questions that do not decompose the real question, workers do precise research on the wrong target.
Workers over-explore. Without explicit scope boundaries, workers drift beyond their assigned sub-question and pollute the synthesis step.
Synthesis conflicts. Two workers return contradictory facts. The lead must either re-ask (add a round) or note the disagreement explicitly. Silently picking one side is the worst failure, because the user never learns a disagreement happened.

When supervisor is wrong

Sequential tasks. If step 2 literally needs step 1's output, parallelism buys nothing. Use a pipeline (CrewAI Sequential, LangGraph linear graph).
Simple queries. A single agent handles them faster and cheaper. Run the lead's "scale effort" check before spawning workers.
Strict determinism. The supervisor delegates by LLM choice. Static graphs fit better when audit and replay matter more than adaptability.

Check: Concept0/20

1. What is a supervisor in the orchestrator-worker pattern?Define

A highlighted Lead box above three worker boxes, with arrows from the lead down to each worker, and a dashed question box over the lead asking its role.

2. What is a worker in the supervisor pattern?Define

The same architecture with Worker 1 highlighted, and a dashed question box over Worker 1 asking its role.

3. How does the term orchestrator-worker relate to the supervisor pattern?Define

Typed schematic, not captured output.

4. What does fresh context mean for a worker?Define

Typed schematic, not captured output.

5. What is scale effort in a supervisor design?Define

Typed schematic, not captured output.

6. What does rainbow deployment mean in the Engineering lessons section?Define

A version A box marked running now and a version B box marked new, above a bare time axis, with a dashed question box asking the deployment style.

7. What is a synthesis conflict?Define

The lead-and-three-worker diagram above two boxes quoting Worker 1 saying X = 5 and Worker 2 saying X = 9, with a dashed question box asking what this situation is called. — Worker values are illustrative placeholders, not from the lesson.

8. Which three mechanisms explain why the supervisor pattern wins, per the Why it wins section?Explain

A single-agent box reading five papers in a row above the lead-and-three-worker diagram, with a dashed box asking for the three mechanisms behind the difference.

9. What changed in 2025 about the recommended way to build a LangGraph supervisor, per The LangGraph turn?Explain

10. Multi-agent runs use roughly 15 times the tokens of a single agent. What follows from that?Explain

A single-agent box marked 1x tokens and a multi-agent box marked about 15 times the tokens, with a dashed question box below asking what follows from the ratio.

11. What is the broad then narrow strategy in Engineering lessons?Explain

Three sub-question boxes, A, B and C, each above a dashed box asking whether it gets expanded with more workers.

12. Why do static graphs fit better than a supervisor when audit and replay matter most?Explain

A static-graph box marked same edges every run next to a supervisor box marked lead decides with a question mark, and a dashed question box asking why static graphs fit audit and replay better. — Typed schematic, not captured output.

13. Why is silently picking one side in a synthesis conflict called the worst failure?Explain

The lead-and-three-worker diagram above a kept answer box and a discarded, dashed answer box, with a dashed question box asking why silently picking one side is the worst failure. — Values are illustrative placeholders, not from the lesson.

14. A user sends a one-line factual lookup. What should a lead following scale effort to query complexity do?Apply

15. Three workers take 2, 5 and 3 seconds in parallel, planning takes 1 second and synthesis 1 second. About how long is the run?Apply

A plan box at 1 second, three parallel worker boxes at 2, 5 and 3 seconds, and a synthesis box at 1 second, with a note that the workers start together and a dashed question box asking for the total run time.

16. A lead splits "compare vendor pricing" into sub-questions about vendor history only. Which failure mode is this?Analyze

A query box asking to compare vendor pricing feeding three sub-question boxes that are all about vendor history, with a note that none of them asks about pricing, and a dashed box asking the failure mode.

17. Workers given no scope boundaries wander past their sub-question and muddy the final answer. Which failure mode is that?Analyze

An assigned sub-question box about pricing tiers feeding a worker's-output box that also covers company culture, office locations and favorite coffee, with a note that the extra topics were never assigned, and a dashed box asking the failure mode.

18. A three-worker design promised about 5 seconds plus overhead, but takes about 15 when each worker call takes 5 seconds. Most likely cause?Analyze

A promised box reading about 5 seconds plus overhead next to an actual box reading about 15 seconds with a gap marked between them, and a note that each of the 3 workers takes about 5 seconds on its own, above a dashed question box asking the likely cause.

19. Design A has the lead read each worker's raw materials. Design B has it read only worker summaries. Lead context errors appear on big queries. Which design, and why?Analyze

Design A, three workers handing raw materials down to a Lead box, next to Design B, three workers handing summaries down to a Lead box, with a note that the lead of one design starts erroring on big queries and a dashed question box asking which design and why. — Typed schematic, not captured output.

20. A job must fetch a record, then use that record's ID to query a second system. Per When supervisor is wrong, what fits best?Design

Build It

code/main.py implements a supervisor with three parallel workers using threading. The lead decomposes a query into sub-questions, the workers run concurrently, one sub-question each, and the lead synthesizes. The workers are scripted to simulate fetch-and-summarize, so there are no LLM calls.

Key structure:

Lead.plan(query) returns three sub-questions built from fixed templates (historical origins, state of the art 2026, open problems). A real lead would use an LLM here.
Worker.run(sub_q, results, idx) sleeps 0.3 seconds to stand in for a fetch, then writes a WorkerResult into its own slot of a shared list. Each thread owns one index, so only the trace needs a lock.
Lead.run(query) starts one thread per sub-question, joins them all, and calls synthesize, which concatenates the worker summaries into one answer. It does not compare them against each other.

Run:

python3 code/main.py

Output shows the trace with start and done events per worker, the final synthesis, and a stats block. You can see the wall-clock win: three 0.3-second workers finish in about 0.35 seconds, not 0.9. Threads work here because time.sleep releases the GIL, which is also what an agent waiting on a model or tool call does. The token counts in the stats are constants (800 per worker plus 1200 for the lead), not measurements.

Check: Build It0/10

1. The demo locks only the trace, not the results list. Why is that enough?Explain

A results-list box with three empty slots and a locked trace box above three worker boxes, with a note that all three workers write to both structures, and a dashed question box asking why locking only the trace is enough. — Typed schematic, not captured output.

2. Why do threads give a real speedup in the Build It demo even with the GIL?Explain

Three worker-thread boxes each running the line time.sleep(0.3), with a GIL circle below them and a dashed question box asking whether it is held or released during the sleep.

3. The demo ends by printing that parallel actual is about 0.35 seconds. Which value reports the real run?Explain

A code card quoting the closing printed line about 0.35 seconds next to a code card showing wall_clock_seconds from the stats dict, with a dashed question box asking which reports the real run. — The closing line is quoted exactly as main.py prints it; wall_clock_seconds is from a real run and varies slightly between runs.

4. In the Build It demo, three simulated 0.3-second workers run under threading. What is the timing?Apply

Three equal bars stacked to show running at the same time, with a dashed total box beneath, above three equal bars placed end to end to show running one after another. — Each bar represents one of the three simulated 0.3-second workers.

5. What does Lead.plan return when the demo calls it with a query?Apply

A query box feeding a plan function box, with its output replaced by a dashed question mark, and a note that the demo calls no model inside plan.

6. Three workers each record 800 tokens and the lead adds 1200. What does total_tokens in the demo's stats show?Apply

A box for 3 workers at 800 tokens each plus a box for the lead at 1200 tokens, with a dashed question box asking for the total.

7. One worker thread dies before writing its result slot. What does the demo's synthesize do?Apply

A dead worker-0 box with no result, next to two normal worker boxes, feeding a synthesize function box, with a line asking what the final answer does with the missing slot. — Typed schematic, not captured output.

8. In the demo's trace, what order do the events print in?Apply

A vertical list of eight dashed slots, each marked position and a question mark, with a note listing the unordered event kinds: plan, three starts, three dones, synthesize.

9. Two worker summaries contradict each other in the demo's final answer, with no warning. Which code explains that?Analyze

A worker A box reading Price twelve dollars and a worker B box reading Price nineteen dollars, both feeding a final-answer box that lists both lines with no warning. — Prices are illustrative placeholders, not from the lesson.

10. In the demo, one worker's fetch hangs forever. What happens to the run?Analyze

Worker 0 and worker 2 marked done, worker 1 marked hung in a dashed box, all three feeding a lead box reading th.join() times three, with a dashed question box asking what happens to the run. — Typed schematic, not captured output.

Use It

outputs/skill-supervisor-designer.md takes a user query and produces a supervisor design: lead system prompt, worker roles, decomposition rules, and the synthesis template. Run it before building a new research-style agent system.

Ship It

Checklist before deploying a supervisor pattern:

Model pairing. Lead on a reasoning-tier model (Opus class, o3 class). Workers on a faster, cheaper model (Sonnet, o4-mini).
Worker timeout. Kill any worker that exceeds 2× median runtime. The lead either re-spawns it with narrower scope or proceeds without it.
Token cap per worker. A hard limit (say 10× the expected synthesis input) keeps a runaway worker from blowing the budget.
Observability. Trace the lead's plan, each worker's tool calls, and the synthesis. This is the basis for post-hoc debugging.
Rainbow rollout. Stateful long-running agents need a gradual version transition, not a hot swap.

Check: Ship It0/5

1. Why does the checklist put the lead on a reasoning-tier model and the workers on a cheaper, faster one?Explain

A Lead box marked Opus-class, reasoning tier above three worker boxes each marked Sonnet-class, fast and cheap, with a dashed question box asking why this pairing. — Typed schematic, not captured output.

2. Which Ship It item lets you tell a bad plan from a bad worker after an answer goes wrong?Explain

Four checklist boxes, worker timeout, token cap per worker, observability and rainbow rollout, with a dashed question box asking which one tells a bad plan apart from a bad worker.

3. Which two numeric guardrails does Ship It give for worker management?Explain

A worker-timeout box reading kill past question-mark times median runtime, next to a token-cap box reading about question-mark times synthesis input, with a dashed question box asking to fill in both numbers.

4. One worker sometimes loops on its sub-question and burns budget while the others finish. Which Ship It controls address it?Design

5. You will ship a new lead prompt while research runs that last minutes and hold state are in flight. Which rollout fits?Design

An in-flight-runs box described as minutes long, holding state and on the old prompt, next to a new-lead-prompt box marked ready to ship, with a dashed question box asking which rollout fits.

Author's Note

I'd run code/main.py and read the trace before anything else. The three worker start lines print almost together and the done lines follow about 0.3 seconds later, which puts the case for parallel subagents on one screen. The "~0.9s sequential versus ~0.35s parallel" lines at the bottom are printed strings, though, so trust wall_clock_seconds in the stats instead.

The part I'd study is how little the lead does after the workers return. synthesize formats the summaries into a list, so a contradiction between two workers passes straight into the answer, unflagged. That is the synthesis-conflict failure from the Concept section, and Exercise 3 is where I'd spend my time, because detecting disagreement without an LLM call is harder than it sounds.

I'd also keep the toy in proportion. It has no worker timeout and no token cap, and total_tokens is bookkeeping rather than cost. Those two items from the Ship It checklist are what I'd add first.

Exercises

Run code/main.py, then modify the lead to spawn 5 workers instead of 3. Observe the wall-clock effect. At what worker count does spawn overhead exceed parallel savings in this demo?
Implement a worker timeout: kill any worker that runs longer than 0.5 seconds and have the lead synthesize the remaining results. What observability do you need to know a worker was cut?
Add a conflict-detection step to the lead's synthesis: if two workers return contradictory answers, the lead notes the disagreement rather than picking one. How do you detect contradiction without calling an LLM?
Read Anthropic's Research-system engineering post. List three practices that this toy demo would need to adopt to run in production.
Compare LangGraph's create_supervisor (legacy) vs the new tool-calling recommendation. Which gives you better control over what the supervisor sees? Why does Anthropic explicitly pass only sub-answers and not raw worker context into synthesis?

Key Terms

Term	What people say	What it actually means
Supervisor	"Lead agent"	An orchestrator agent that plans, delegates, and synthesizes. Does not do the work itself.
Worker	"Subagent"	A focused agent invoked by the supervisor with narrow scope and its own context window.
Orchestrator-worker	"Supervisor pattern"	Same thing, different name. The 2026 literature uses both.
Fresh context	"Clean window"	A worker's context starts from its system prompt and assigned question, not the lead's history.
Rainbow deployment	"Gradual rollout"	Long-running stateful agents need versioned drain-and-replace, not blue-green.
Token dominance	"Context is the variable"	80% of research-eval variance comes from total tokens used, not model choice, per Anthropic.
Scale effort	"Match agent count to complexity"	Lead estimates query difficulty, spawns 1 vs 10+ workers accordingly.
Synthesis conflict	"Workers disagree"	Two workers return contradictory facts; the lead must surface disagreement, not silently pick one.

Supervisor / Orchestrator-Worker Pattern

Learning Objectives

Problem

Concept

The pattern

Why it wins

Engineering lessons (Anthropic 2025)

The LangGraph turn

The failure modes

When supervisor is wrong

Build It

Use It

Ship It

Exercises

Key Terms

Further Reading

Code

Ships With