Orchestrate multi-agent systems with coordinator-subagent patterns

In a coordinator-subagent system, the coordinator is the single hub through which every message flows. Subagents are the spokes: they receive a task from the coordinator, do their specialized work in isolation, and return a result to the coordinator. Subagents never call each other directly. If the synthesis agent needs a fact the search agent could provide, it returns control to the coordinator, which then invokes the search agent.

This centralization is a deliberate design choice, not an accident. Routing all traffic through one place gives you observability (a single trace of who was asked what and what came back), consistent error handling (one place decides how to react to a subagent failure), and controlled information flow (the coordinator decides exactly what context each subagent sees). Peer-to-peer chatter between subagents would scatter that logic and make the system nearly impossible to debug.

In the Claude Agent SDK, the coordinator spawns subagents with the Task tool, so the coordinator's allowedTools must include "Task". Each subagent is described by an AgentDefinition (its own system prompt and restricted tool set). Because the coordinator holds the only complete picture of the run, it is also the natural owner of retries, partial-result handling, and the decision to stop.

The most tested fact in this task statement: a subagent does not inherit the coordinator's conversation history. It starts fresh. Whatever the subagent needs to know, prior findings, the specific question, the source URLs, the output format, must be written explicitly into the prompt the coordinator sends when it spawns the subagent.

This isolation is a feature. It keeps each subagent's context window small and focused, which improves reliability and lets you run many subagents in parallel without their contexts colliding. But it means "the coordinator already discussed this" is never a reason a subagent will know something. If the synthesis agent needs the web search results, the coordinator must pass those results into the synthesis prompt; the synthesis agent cannot reach back into the coordinator's memory.

A practical consequence: design subagents to return structured, self-contained results (claims plus source URLs plus dates) so the coordinator can hand them to the next subagent without loss. Verbose free text that only makes sense inside the producing agent's context is expensive to pass and easy to misread downstream.

The coordinator has four jobs. First, task decomposition: break the user's request into subtasks that map to specialized subagents. Second, delegation: send each subtask, with all needed context, to the right subagent. Third, dynamic selection: decide which subagents to invoke based on the query, rather than always running every stage. Fourth, aggregation: collect the results and combine them into a coherent answer.

Dynamic selection is worth emphasizing. A well-designed coordinator analyzes the query first and invokes only the subagents that query needs. A simple factual lookup might need only the search agent; a full research report needs search, analysis, synthesis, and report generation. Hard-coding every request through the entire pipeline wastes tokens and latency and can even degrade quality by forcing empty or irrelevant stages.

The coordinator prompt should specify goals and quality criteria, what a good result looks like, rather than a rigid step-by-step script. That lets the coordinator adapt its delegation to the specific query instead of mechanically following one fixed path.

When you fan out to multiple subagents (say, several search agents), give each a distinct slice of the problem. Assign non-overlapping subtopics or distinct source types: one agent handles academic papers, another handles news, another handles the company's own docs. Without explicit partitioning, parallel agents tend to converge on the same obvious queries and return largely the same results, so you pay for N agents and get roughly one agent's worth of coverage.

Good partitioning does two things at once: it minimizes duplication and it maximizes breadth. Each agent's isolated context stays focused on its slice, and the union of slices covers the topic. The coordinator is responsible for choosing the partition, because it is the only component that sees the whole scope.

A single pass of decompose, delegate, and synthesize is often not enough for open-ended research. The stronger pattern is a loop: after the synthesis subagent produces a draft, the coordinator evaluates that output for gaps against the original goal. Where coverage is thin or missing, the coordinator formulates targeted follow-up queries, re-delegates them to the search and analysis subagents, and then re-invokes synthesis with the new material. It repeats until coverage is sufficient.

This loop is what turns a brittle one-shot pipeline into a system that can recover from its own blind spots. It is also the direct remedy for narrow decomposition (see the next concept): even if the first decomposition missed a dimension, a coverage check against the topic can surface the gap and trigger another round.

Concretely, the coordinator's evaluation step asks "does this synthesis address every part of the user's request?" and produces a list of uncovered subtopics. Those become the next round of subagent tasks. The stopping condition is coverage sufficiency, not a fixed iteration count.

The classic multi-agent bug: every subagent succeeds, yet the final report is incomplete. The web search agent found good articles, the analysis agent summarized them correctly, the synthesis agent wrote coherent prose, but whole branches of the topic are missing. When this happens, the subagents are not at fault, they did exactly what they were told. The root cause is upstream, in how the coordinator decomposed the task.

The tell is in the coordinator's decomposition log. If a request to research "creative industries" was split into "digital art," "graphic design," and "photography," the coordinator silently narrowed the topic to visual arts and never assigned music, writing, or film. No downstream agent can recover coverage that was never delegated.

Guard against this in two ways: write coordinator prompts that decompose at the right altitude (enumerate the major dimensions of a broad topic before slicing it), and add the iterative refinement loop so a coverage check can catch and fill gaps the first decomposition missed.