Ch 9: Supervisor and Worker Agents
Imagine you have a genius who can do anything — write code, write tests, update documentation. But here is the problem: you just handed them a task that requires changing ten files across three packages. The genius starts strong, but halfway through they forget what they changed in file one. Their desk is buried under notes. They keep re-reading the same files because they lost track.
Now imagine a different approach. Instead of one genius doing everything, you hire a project manager and three specialists. The project manager never writes a single line of code. Instead, they read the task, break it into three focused assignments, and hand each one to a specialist. One specialist implements the feature. Another writes the tests. A third updates the documentation.
Each specialist works in their own room with a clean desk. They do not know about each other. They do not get distracted by the other parts of the task. They each finish their piece and slide the result back to the project manager.
The project manager reads all three results, checks that nothing looks wrong, and assembles the final deliverable. If a specialist's work looks suspicious or incomplete, the project manager throws it away and either retries or reports the gap.
This is the supervisor-worker pattern. The supervisor is the project manager. It never does the work — it plans, delegates, monitors, and validates. The workers are the specialists. They are focused, isolated, and disposable.
Why One Agent Cannot Do It All
A single agent running a complex task hits three walls at once:
The context wall. Every file the agent reads, every tool result it receives, every decision it makes — all of it piles into the same context window. After a few thousand tokens of tool results, the agent starts losing track of earlier work. It re-reads files it already read. It makes contradictory changes.
The focus wall. When one agent is responsible for implementation, testing, and documentation, it constantly switches modes. It is writing production code one moment and test assertions the next. Each context switch introduces errors. A specialist who only writes tests does not get confused by implementation details.
The parallelism wall. A single agent runs one tool call at a time. If the implementation, tests, and docs are independent, a single agent works on them sequentially. Three workers can finish in one-third the time.
The supervisor-worker pattern breaks through all three walls. Each worker gets a clean context. Each worker focuses on one job. And workers run in parallel.
You are the Supervisor. A user just asked you to add a new 'export' feature to a dashboard. This involves building the feature, testing it, and updating the guide. Let's walk through how you handle it.
Order the supervisor-worker workflow
Drag to reorder, or use Tab + Enter + Arrow keys.
- Supervisor receives user request
- Decompose into sub-tasks
- Dispatch workers for each sub-task
- Monitor worker progress
- Aggregate results and respond
Key Insight
The supervisor never does the work — it orchestrates. This is not a limitation; it is the design. The moment the supervisor starts writing code itself, it loses its ability to maintain the big picture. Its context fills up with implementation details instead of coordination state.
Think of it this way: a project manager who starts coding alongside their team stops managing. They lose track of who is doing what, which tasks are blocked, and whether the pieces will fit together. The same applies to the supervisor agent.
The supervisor's job is to decompose (break the goal into parts), delegate (assign each part to a worker), validate (check that worker outputs are safe and correct), and aggregate (combine results into a coherent response). Four verbs, none of which involve touching the actual code.
This separation also creates a natural security boundary. Worker outputs are untrusted — a worker might process something containing hidden instructions that try to hijack the system. Because the supervisor never runs raw worker output as instructions, it stays in control. It cleans, checks, and only then uses the results.
What's Next
You have a supervisor that can delegate work and validate results. But right now, it dispatches all workers at once. What if Worker B depends on Worker A's output? What if five workers need to run but you only have capacity for three?
In Chapter 10, you will build a scheduler that understands task dependencies, runs independent tasks in parallel, and respects concurrency limits. The supervisor becomes smarter about when and how to dispatch.