The orchestrator-worker pattern for agents

The orchestrator-worker pattern is one agent that breaks a job into pieces, hands each piece to a worker running in its own context, and then combines the results into one answer. Reach for it when the work is broad, parallelisable, or too large for a single context windowThe fixed amount of text a model can hold in mind at once for a given request. Stay with a single agent when the steps depend tightly on each other.

The shape

There is one lead agent, the orchestratorThe lead agent that plans the job, splits it into pieces, and combines what the workers return, and several short-lived workers. The orchestrator does not do the detailed work itself. It plans, it delegates, and it synthesises. Each worker gets one well-scoped task, runs it in isolation, and returns a distilled result.

The thing that makes this work is context isolationEach worker runs in its own context window and returns only its conclusion, not its whole transcript. A worker that reads forty files, runs a dozen searches, and skims long logs returns only its conclusion. The orchestrator never sees that mess. So the system can explore far more than a single window could hold, because each worker holds its own slice and throws the rest away.

When does it beat a single agent?

A single agent in a loop is the right default. It is cheaper, simpler to debug, and good enough for most tasks. Multiple agents earn their cost only in specific shapes:

• Broad, parallel work. The job splits into independent pieces that do not need to talk to each other while they run. Researching ten competitors. Auditing twenty services for one config mistake. Summarising a folder of reports.
• The information exceeds one window. No single context can hold all the source material, so you fan it out and let each worker hold a piece.
• Many tools or many sources. One agent juggling fifteen tools gets confused. Specialised workers, each with a narrow toolset, stay focused.

The cost is real. Agents use far more tokens than a chat, and multi-agent systems multiply that again because every worker re-reads its own context. Anthropic's guidance is to start with the simplest thing that works and add agents only when they clearly pay for themselves. A multi-agent research system can beat a strong single agent on open-ended research, but that is a high-value task where the fan-out is worth the spend.

When should I stay with one agent?

Do not reach for orchestrator-worker when the subtasks depend tightly on each other, or when every worker would need the same large shared context anyway.

• Tightly coupled steps. If step two needs the full reasoning from step one, splitting them loses information at the handoff. Use a single agent, or a prompt chain where one step feeds the next.
• Shared state that keeps changing. Workers cannot watch each other think. Editing one file that several pieces all touch is a coordination nightmare, not a parallel win.
• Most coding. Code changes are usually coupled: a rename here breaks a call there. Models are still not great at delegating to each other mid-task, so coding is mostly a single-agent job.

A quick test: if you can write down the pieces up front and they do not reference each other, the pattern fits. If the split only becomes clear once you are deep in the work, or the pieces keep needing to sync, it does not.

How do I run workers in the Claude Code CLI?

Claude Code has this pattern built in as subagentsA specialised agent Claude Code spawns for a side task; it runs in its own context window and returns only a summary. The main session is the orchestrator. When a task matches a subagent's description, Claude delegates to it; the subagent runs in its own context window, with its own tools, and returns only its result. Your main conversation stays clean.

You define a subagent as a markdown file with YAML frontmatter. Project subagents live in .claude/agents/ in the repo (check them in so the team shares them); personal ones live in ~/.claude/agents/ and are available everywhere.

---
name: dependency-auditor
description: Checks one service for outdated or vulnerable dependencies. Use when auditing services across a monorepo.
tools: Read, Grep, Glob, Bash
model: haiku
---
 
You audit a single service for dependency problems. Read its manifest,
list outdated and vulnerable packages, and return a short table. Do not
edit any files. Return only the table and a one-line risk summary.

The frontmatter fields are small and worth knowing:

Two things matter most. The description is the routing signal: the orchestrator reads it to decide when to hand work over, so make it specific. And tools is your blast radius: a research worker that only has Read, Grep, and Glob cannot edit or delete anything, which makes parallel fan-out safe.Common gotchaDo not hand parallel workers Edit or Write "just in case". Two workers writing the same files at once corrupt each other's changes.Keep fan-out workers read-only, or give each its own git worktree before any of them can edit.

You can also point the orchestrator at subagents explicitly. Run Claude Code and ask it to delegate:

The orchestrator splits the job per service, runs the workers, and synthesises their tables. Each worker reads its own service in isolation, so a forty-service monorepo never floods the main window.

Workers in separate working trees

When the pieces touch files, isolation has to extend to the filesystem, not just the context. The clean way to do that is git worktree: it gives each worker its own checkout of the same repo, on its own branch, in its own directory. Workers never collide on the same files.

# One worktree per worker, each on its own branch
git worktree add ../audit-payments -b audit/payments
git worktree add ../audit-search   -b audit/search
 
# See what is checked out where
git worktree list
 
# Clean up when a worker is done
git worktree remove ../audit-payments

Point one Claude Code session at each directory. They run in parallel without stepping on each other, and you merge the branches back when the work is done. For a job that is read-only (auditing, summarising, research), you do not need separate trees at all; subagents alone give you the context isolation.

How does the synthesis step work?

The combine step is where orchestrator-worker projects most often go soft. Workers return partial, independent results, and stitching them into one coherent answer is real work, not a concatenation.Common gotchaThe trap is feeding every worker's full transcript back into the orchestrator to combine. That refloods the main window you isolated the workers to protect, and the synthesis quality drops as the context fills.Make each worker return one distilled result in a fixed shape, and have the orchestrator merge those, never the raw worker logs.

Give the orchestrator a clear synthesis instruction. Tell it what shape the final answer takes, how to resolve conflicts between workers, and what to do when one worker fails.

Note the failure handling. A worker can return nothing, time out, or go down a wrong path. The orchestrator should surface a partial answer with the gap marked, not crash the whole run because one piece failed.

How do I keep it from sprawling?

The failure mode of this pattern is sprawl: too many workers, runaway loops, and a token bill with nothing to show. Bound it from the start.

• Cap the fan-out. Decide a maximum number of workers per job. Early multi-agent systems failed by spawning dozens of subagents for trivial queries. Tell the orchestrator the limit.
• Set a budget. Enforce a per-run token and cost ceiling. The token multiplier on multi-agent work makes this non-optional.
• Define a stop condition. Every worker needs a clear "done", and the orchestrator needs a clear "stop combining". Without one, a verifier loop can run forever.
• Scope each worker tightly. One task, one narrow toolset. A vague worker wanders; a scoped one returns and exits.
• Trace every delegation. Agents are non-deterministic between runs. Log which worker got which task and what it returned, or you cannot debug a bad result.

The pattern in one line

Use orchestrator-worker when a job splits cleanly into independent pieces that are too much for one context. Give each worker a narrow task, an isolated context, and a small toolset. Spend most of your design effort on the synthesis step and on the budget that stops it sprawling. Everywhere else, a single agent is the simpler, cheaper, better choice.

If you are choosing between this and the other coordination shapes, the companion guide on multi-agent architectures lays them side by side.