Claude Agent SDK: Building a Multi-Agent System Step by Step

A multi-agent system is only worth building when a task genuinely decomposes into independent pieces — otherwise it's coordination overhead with no benefit. Here's how to structure one with the Claude Agent SDK when that condition actually holds.

Step 1: Define the Coordinator's Role as Delegation, Not Execution

The coordinator's job is to break a task into subtasks, dispatch them, and synthesize the results — not to do the work itself.

python

If the coordinator's system prompt needs task-specific tools to function, that's usually a sign the task wasn't actually being delegated — it's a signal to revisit whether multi-agent is the right shape here.

Step 2: Define Narrowly-Scoped Subagents

Each subagent should have one clear responsibility and only the tools that responsibility requires.

python

Narrow scope is what makes a subagent's output predictable enough for the coordinator to aggregate reliably — a subagent with a broad, vague mandate produces inconsistent output shapes that are harder to synthesize.

Step 3: Pass Only the Task-Specific Context Subagents Need

python

Forwarding the coordinator's entire conversation history into every subagent call multiplies token cost across every dispatch for context most subagents don't need. A subagent reviewing one file needs that file's path and the review criteria — not the full history of how the coordinator arrived at that decision.

Step 4: Run Independent Subagents in Parallel

python

Reviewing five files sequentially takes roughly five times as long as running five independent reviews concurrently. The SDK supports launching multiple subagents at once precisely for cases like this, where subtasks don't depend on each other's output.

Step 5: Synthesize Subagent Results Back Together

python

The coordinator's final call is where the actual judgment happens — deciding which findings matter most, resolving any conflicting subagent conclusions, and producing one coherent output instead of a raw dump of every subagent's individual report.

Step 6: Handle Partial Subagent Failures

python

A multi-agent system that fails entirely because one of five subagents errored is worse than a single agent that at least completes the other four tasks — return_exceptions=True (or the equivalent in your runtime) lets the coordinator synthesize partial results and surface the failure explicitly rather than losing everything.

Key Takeaways

A multi-agent system built on the Claude Agent SDK pays off when subtasks are genuinely independent — narrowly-scoped subagents run in parallel with only the task-specific context they need, while the coordinator's job stays limited to delegation and synthesis; if the coordinator ends up doing the real work itself, the task likely didn't need decomposition in the first place.

Frequently Asked Questions

When does a multi-agent setup with the Claude Agent SDK make sense over a single agent?

When a task decomposes into genuinely independent subtasks — reviewing several unrelated files, researching multiple unrelated questions, or running parallel checks that don't depend on each other's intermediate results. If subtasks need to see each other's output to proceed, a single sequential agent is simpler and avoids coordination overhead for no benefit.

Should subagents share the coordinator's full conversation history?

No — passing the entire prior context into every subagent multiplies token cost across every subagent call for information most subagents don't need. Give each subagent only the specific task description and inputs required for its job; the coordinator handles synthesizing results back together afterward.

Can subagents run in parallel with the Claude Agent SDK?

Yes — independent subagent tasks can be launched concurrently and their results awaited together, which reduces wall-clock time significantly versus running them one after another. This only applies to tasks that don't depend on each other's output; dependent subtasks still need to run in sequence.

What's a sign that a multi-agent architecture was the wrong choice?

If the coordinator agent ends up doing most of the actual work itself and subagents only handle trivial fetch-and-return steps, the task probably didn't need decomposition — a single agent with the same tools would have been simpler and cheaper, since coordination itself has overhead that must be justified by genuine parallelism or specialization.