Orchestrating multiple AI agents as a team

An orchestrator dispatches; specialists execute

After this, you'll be able to design a multi-agent workflow using Claude Code or the Anthropic Agent SDK where one orchestrator agent breaks work into subtasks and dispatches them to specialist subagents.

Before you start

Complete Background Agents first; this lesson builds on running agents autonomously and monitoring their structured output.

The idea

A single agent trying to research, write, and verify in one session trades off between three different jobs and does all three worse than a focused specialist would. Multi-agent architecture solves this by separating concerns: an orchestrator agent breaks the work into subtasks and hands each one to a specialist. The specialist focuses on one job, produces structured output, and returns it to the orchestrator for the next step. Real tools: Claude Code supports spawning subagents natively through its Task tool; the Anthropic Agent SDK in Python gives you full control over orchestration logic with Claude as the underlying model for each agent.

Here is the before and after: a single agent asked to 'research our top three competitors and write a positioning section' produces shallow results because it cannot hold enough context to research and write well at the same time. An orchestrator that sends 'research competitor X and return structured findings in this exact format' to a research agent, waits for the output, then sends that output to a writing agent with 'draft a positioning paragraph using only these specific findings' produces a section that is both well-researched and well-written.

Now try it: design a two-agent sequence in Claude Code where Agent 1 reads a document and extracts a structured list, and Agent 2 uses that list to write a summary. The key discipline is passing Agent 1's actual structured output to Agent 2, not a paraphrase of it.

Try it (20 min)

Watch out for

Having the orchestrator summarize Agent 1's output before passing it to Agent 2; pass the actual structured output to preserve all the detail
Designing agents with overlapping responsibilities; if two agents could both handle a task, one of them is unnecessary
Over-specifying the orchestrator's prompt so it tries to do the work instead of delegating; if its prompt contains detailed content instructions, it is no longer orchestrating.
Skipping a validation step between agents; check that Agent 1's output meets the format Agent 2 requires before passing it

Paste this into Claude

I want to design a two-agent pipeline for [describe the end goal, e.g., turning raw research notes into a formatted client report]. Agent 1 (the specialist) should [describe its specific task and the exact output format it should return; be precise about structure]. Agent 2 (the composer) should [describe its task and how it uses Agent 1's output as input]. I am using [Claude Code / Anthropic Agent SDK / describe your setup]. Please: 1) write the task description for Agent 1 with the exact output format it must return, 2) write the task description for Agent 2 that explicitly includes a slot for Agent 1's output, 3) show me how to pass Agent 1's output to Agent 2 in my chosen tool, and 4) describe one thing that could go wrong at the handoff and how to detect it before it reaches the final output.

What good looks like

Agent 1's output is in the exact format that Agent 2's prompt expects as input
Agent 2's prompt explicitly includes Agent 1's full structured output as input, not a paraphrase
Running the pipeline on a second input produces consistent output without you manually editing the handoff
You can identify which agent produced which part of the final output

When this breaks

Breaks when Agent 1's output format changes unexpectedly because Agent 2 assumed a specific structure and generates plausible-sounding but incorrect content to fill the gap
Breaks when there is no validation between agents because errors in Agent 1's output pass through silently and the final output looks correct but is wrong in ways that are hard to trace

You can now

Run the pipeline and confirm Agent 2's prompt explicitly included Agent 1's full structured output as a literal input. If you can trace which content came from Agent 1 specifically, the pipeline worked as designed.

Key takeaways

Multi-agent architecture separates concerns. An orchestrator that dispatches to specialists produces better output at every step than a single agent trying to do everything at once.

An orchestrator breaks work into subtasks; specialist agents each do one job and return structured output
Real tools: Claude Code's native Task tool for spawning subagents and the Anthropic Agent SDK for Python
The handoff format between agents is the one design decision that breaks everything else if you get it wrong; bad format means errors compound silently
Test sequentially before parallelizing; the handoff needs to work correctly before you optimize for speed

Was this helpful?

← Back to lessons

I want to design a two-agent pipeline for [describe the end goal, e.g., turning raw research notes into a formatted client report]. Agent 1 (the specialist) should [describe its specific task and the exact output format it should return; be precise about structure]. Agent 2 (the composer) should [describe its task and how it uses Agent 1's output as input]. I am using [Claude Code / Anthropic Agent SDK / describe your setup]. Please: 1) write the task description for Agent 1 with the exact output format it must return, 2) write the task description for Agent 2 that explicitly includes a slot for Agent 1's output, 3) show me how to pass Agent 1's output to Agent 2 in my chosen tool, and 4) describe one thing that could go wrong at the handoff and how to detect it before it reaches the final output.