Multi-Agent Orchestration

Overview

A single custom agent can accomplish focused tasks with precision. But real-world software development rarely involves just one task in isolation. A feature request might need architecture analysis, code implementation, test writing, and documentation -- each requiring different skills and different permissions. This lesson explores multi-agent orchestration: patterns for coordinating multiple agents to tackle complex, multi-step work. You will learn three core patterns -- teams, pipelines, and fan-out -- and when to use each.

These patterns use Claude Code's subagent capability. An orchestrating agent can delegate work when its configured tools permit use of the Agent tool; its prompt should define when to delegate, which specialist to select, and how to combine results. Test that routing explicitly rather than assuming a prompt alone creates orchestration. Other agent frameworks may implement delegation differently.

Why Multiple Agents?

You might wonder: why not just make one powerful agent that does everything? You already know part of the answer from earlier in this module -- least privilege and separation of concerns. But orchestration adds a second reason: cognitive specialization.

When a single agent tries to review code, write tests, and update documentation in one session, it has to hold all three mindsets simultaneously. Its attention is split. Its system prompt is bloated. The quality of each output suffers.

Multiple agents, each focused on one concern, produce better results than one agent juggling many concerns. The challenge is coordinating them.

Comparison of single-agent versus multi-agent approaches: a single agent handling review, tests, and docs leads to split attention, bloated prompts, and inconsistent quality. Multiple specialized agents (Review, Test, Docs) each have focused attention, clean prompts, and consistent quality.

Pattern 1: The Team (Leader + Workers)

The team pattern uses an orchestrator agent that decomposes a task, delegates subtasks to specialized worker agents, and synthesizes their results. The orchestrator is the only agent the developer interacts with directly.

Team pattern: a developer communicates with an orchestrator agent (team leader), which delegates to three specialized workers — Code Reviewer (read-only), Test Writer (read and write), and Doc Generator (read and write) — and collects their results.

The orchestrator agent has broader permissions -- it needs to read the codebase to understand the task and invoke sub-agents. But the worker agents remain tightly scoped.

Here is how you define an orchestrator:

When to use the team pattern:

• Complex tasks that require multiple skill sets
• Tasks where the order of operations matters (review before implementation)
• Scenarios where you want a single point of contact for the developer

Pattern 2: The Pipeline (Sequential Stages)

The pipeline pattern passes work through a sequence of agents, where each agent's output becomes the next agent's input. Unlike the team pattern, there is no central orchestrator -- the stages are predefined.

Pipeline pattern sequence: a feature request flows through four sequential stages — Analyzer (analyzes requirements), Implementer (implements changes), Reviewer (reviews implementation), and Tester (writes and runs tests) — with each stage's output feeding the next.

Each stage in the pipeline has a single responsibility and a clear contract for what it passes to the next stage:

When to use the pipeline pattern:

• Tasks with a natural sequential flow (analyze, implement, review, test)
• When each stage's output is well-defined and serves as input for the next
• CI/CD-like workflows where stages gate progression

Pattern 3: Fan-Out (Parallel Independent Tasks)

The fan-out pattern dispatches multiple agents simultaneously on independent tasks. Unlike the pipeline, there is no sequential dependency between agents -- they all work in parallel.

Fan-out pattern: a dispatcher sends the same task to four agents in parallel (each linting a different module — auth, api, db, ui), and a collector gathers all results back to the developer.

Fan-out is ideal when you have the same task applied to independent units of work -- reviewing multiple modules, analyzing separate services, or running checks across different parts of the codebase.

The dispatcher sends each instance of this agent to a different module. Since modules are independent, all reviews run in parallel with no coordination overhead.

When to use the fan-out pattern:

• The same task applies to multiple independent units (modules, services, packages)
• Tasks have no shared state or dependencies between units
• You want to reduce wall-clock time by parallelizing work

Choosing the Right Pattern

Here is a decision framework for selecting the orchestration pattern:

Decision flowchart for choosing an orchestration pattern: if subtasks have no dependencies, use fan-out. If they are sequential and the sequence is fixed, use pipeline. If the sequence requires judgment, use the team pattern with an orchestrator.

Combining Patterns

In practice, real workflows often combine multiple patterns. A team leader might fan out reviews across modules, then pipeline the results through implementation and testing:

Combined pattern sequence: a team lead fans out parallel reviews across three files (login.ts, session.ts, tokens.ts), collects all review reports, then pipelines the consolidated findings through an implementer and tester in sequence.

The team leader uses fan-out for the review phase (parallel, independent reviews) and then switches to a pipeline for implementation and verification (sequential, dependent stages).

Anti-Patterns in Multi-Agent Orchestration

Orchestration can go wrong. Watch out for these common mistakes:

• Over-orchestration -- Using three agents for a task that one agent handles perfectly. Multi-agent orchestration has coordination overhead. If a single focused agent can do the job, let it.
• Shared state conflicts -- Two agents trying to edit the same file simultaneously. Fan-out only works when tasks are truly independent.
• Missing error handling -- A pipeline where stage 2 fails but stage 3 runs anyway. Every pipeline needs stop-on-failure semantics.
• Orchestrator bloat -- The team leader agent doing all the work itself instead of delegating. If the orchestrator's system prompt includes implementation details, it is not delegating enough.
• Circular dependencies -- Agent A needs output from Agent B, which needs output from Agent A. Design your workflows as directed acyclic graphs.

Start with a single agent. Add orchestration only when you have a clear reason -- either the task requires different permission levels, different skill sets, or parallelism for performance.

Practical Considerations

When implementing multi-agent workflows, keep these operational details in mind:

• Token costs multiply -- Each agent consumes its own context window. A team of four agents uses roughly four times the tokens of a single agent. Make sure the quality improvement justifies the cost.
• Latency compounds in pipelines -- Four sequential stages each taking 30 seconds means two minutes of wall-clock time. Parallelize where possible.
• Debugging is harder -- When something goes wrong in a multi-agent workflow, you need to identify which agent failed and why. Keep each agent's output structured and logged.
• Start simple, add agents gradually -- Do not design a five-agent pipeline on day one. Start with one agent, then split responsibilities as pain points emerge.

Summary

Multi-agent orchestration lets you tackle complex tasks by coordinating specialized agents. The three core patterns are teams (an orchestrator delegates to workers and synthesizes results), pipelines (sequential stages where each agent's output feeds the next), and fan-out (parallel execution of independent tasks). Each pattern has clear use cases: teams for tasks requiring dynamic judgment, pipelines for fixed sequential workflows, fan-out for parallelizable independent work. The key is to start simple -- use a single agent until you have a clear reason to add coordination -- and to watch out for anti-patterns like over-orchestration and shared state conflicts. With custom agents from this module and the CLAUDE.md foundation from Module 3, you now have the tools to build agent workflows that match the complexity of real-world software development.