Claude Code Agent Teams: When to Go Multi-Agent and How

An orchestrated team of agents that talk to one another inside the Claude Code ecosystem is within reach, and a finished version can work nicely. Getting one to work is harder than it sounds, though, and plenty of people are charging into agent teams without weighing the trade-offs. Teams of agents seem like the obvious next move once subagents are running smoothly. They aren't automatically that. A team is a coordination layer with a real token cost, known ways of failing and a narrow set of problems it handles well.

The least glamorous lesson from months of real multi-agent use is also the most useful: begin with one well-configured agent, good tools and disciplined context management. Add more agents only when you can name a particular reason. Anthropic's guidance on building effective agents says the same, advising teams to look for the simplest workable solution and add complexity only when it's needed.

What follows is a way to think the decision through, and what to do after making it. It assumes you're familiar with subagents, the way they differ from skills and why keeping context isolated is the chief reason to use one. The open question is when a single subagent reporting back stops being enough, and what to build in its place.

The material covers these areas:

• Why most teams don't yet need several agents, and the usual mistake of reaching for teams because they feel more powerful.
• Four concrete triggers that show one agent has run out of room.
• Four patterns for combining agents, in a provider-neutral taxonomy: orchestrator, pipeline, parallel specialists and swarm.
• The Anthropic stack for agent teams, separating what is stable from what is experimental or preview-only.
• What Claude Code agent teams are and how they differ from subagents.
• How agents communicate: three forms, four timing patterns and what to pass between them.
• Eight failure modes with practical mitigations.
• A decision framework for native, do-it-yourself or hybrid orchestration.

Most teams don't need more than one agent

Many people who go looking for agent teams are solving the wrong problem. The usual reasoning is that subagents worked, the system is getting complicated and teams are the next rung. That logic confuses capability with complexity. A team doesn't make the system more capable; it makes it more distributed, and distribution is a cost rather than an upgrade.

Anthropic's post on building effective agents spells out the economics. Workflows that aren't agentic are more predictable, cheaper and easier to debug, and the advice boils down to this: when an ordinary function can do the job, write the function instead of convening a committee of probability distributions. The point is easy to miss for people who haven't absorbed that LLMs are probabilistic. Even an explicit instruction may or may not be followed correctly. Every agent added is one more component that can fail, hallucinate or emit output the next agent misreads, so adding agents compounds the odds of error at scale.

The ceiling for a single agent is higher than people assume. A single agent given suitable tools, a tight system prompt, tidy delegation of heavy work to subagents and careful context management can take on a surprising amount. The ceiling is reached when at least one of four things holds:

1. The work is too large for one context window, even with subagent delegation.
2. Different parts need genuinely different specializations, meaning different tool access and behavioral limits and not merely different prompts.
3. Some of the work can proceed in parallel, and elapsed time matters.
4. Output quality needs independent critique, for example from a second agent that hasn't seen the first one's reasoning.

None of these is a statement about capability. All of them concern architecture. When one applies, extra agents are justified. When none does, they only add friction, and if you can't point to a specific one, the single-agent path is still open.

The four triggers, with examples

Context isolation. Suppose the work means reading dozens of files, running extensive searches and holding large intermediate outputs, none of which needs to stay in the main session. A subagent covers that. But if the investigation is so big that even a subagent's context fills, or the job splits into independent parallel investigations, you're into multiple agents. This is the most common legitimate trigger.

Specialization. The work calls for more than separate instructions; it needs different tool access and different behavioral constraints. A code reviewer that can't write files or run shell commands has a categorically different risk profile from a code generator. Yet those differences can often be encoded as separate subagents, each with its own system prompt and restricted tool list, so specialization alone shouldn't be the reason to move up to teams. The agent-teams documentation itself says subagents shine here: isolated contexts, summaries returned to the caller and task-specific instructions.

Parallel work. The task breaks into independent subtasks that share no mutable state: three agents examining different angles of a codebase bug at once, or four agents each reviewing another chapter of a document. This is the situation where multi-agent systems deliver real wall-clock savings, since the agents run simultaneously. The price is more total tokens, so the trade is sound only when elapsed time matters more than spend.

Independent critique. The output needs a second opinion that hasn't been tainted by the first one's reasoning. Picture an evaluator that reads only the final output and none of the reasoning behind it, or a red-team agent that hunts for flaws instead of validating claims. This is the idea behind Anthropic's multi-agent research system, where parallel subagents explore different aspects and a lead agent synthesizes independently.

When one of these is plainly true and you can say which, adding agents earns its cost.

Four ways to combine agents

Suppose the decision is made. Research quickly turns up a mess, because the frontier labs have each developed multi-agent patterns differently, though a few common threads exist. What follows is a synthesized taxonomy drawn from Anthropic's workflow documentation and its engineering team's production experience. It isn't an official Anthropic classification; it's an analytic summary that maps back to what those sources describe.

Sequential pipeline

Agents or stages run in a fixed order, and later stages consume earlier output. Of the four, this one is simplest to explain to engineers, since it looks like ordinary software: research then synthesis, drafting then critique, extraction then validation.

Its strength is explicit contracts between stages. Its weakness is cascading mistakes, since an extraction error in stage one can leave later stages wrong at great expense. Validation gates between stages are mandatory, because they keep the pipeline from marching confidently in the wrong direction. JSON contract schemas and other artifacts that preserve lineage through the run make the best gates.

Central orchestrator, or planner-executor

One lead agent breaks the task down, delegates to workers and synthesizes the results. Workers don't coordinate with each other; they report to the orchestrator. It's the most common and most useful default. Use it when the structure of the subtasks isn't known beforehand but clear top-level ownership matters. Anthropic's Research feature follows exactly this shape: a lead agent analyzes the query, launches specialized subagents in parallel and later merges what they found.

Don't use it if the workflow is already settled enough to script; a pipeline will be simpler and more predictable there.

Its characteristic failure is orchestrator failure: a lead agent whose delegation prompts are vague makes workers repeat each other's searches, miss boundaries or produce results that don't fit together. The remedy is to give each worker an objective, an expected output format, guidance on sources and clear task boundaries.

Parallel specialists, debate and red team

Here several agents take on the same task, or neighboring subtasks, all at once, and their results are then voted on, critiqued or aggregated. It suits cases where resilience counts for more than neatness: competing explanations for a bug, adversarial review of a policy call, security review from multiple angles.

The cost is plain. More agents means far more tokens, more aggregation work and a risk of false confidence born of consensus. Anthropic's research system reportedly had to add effort budgets and sharper delegation to stop workers fanning out without discipline. Use this pattern only when the domain truly demands it.

Swarm, or decentralized shared context

Coordination emerges from shared state, shared message threads or changes in the environment instead of from a strict leader. Here multi-agent systems start to become distributed systems, with the complexity that brings: murky ownership, race conditions on shared state and hard debugging. It fits genuinely open-ended problems where agents must interoperate across session or runtime boundaries. Avoid it where easy accountability or tight compliance is needed.

For most practitioners, the first two patterns cover nearly everything.

What Anthropic offers today

Before building a stack of your own, it's worth checking what Anthropic already provides and what its ideas teach. Several surfaces exist for agentic work, and they aren't interchangeable. Think of a ladder that runs from raw control to hosted management. The picture below reflects a snapshot from around April 2026, and these products change quickly.

1. Messages API. You own the loop completely. Tool use exists, but you write the execution logic, and there's no built-in multi-agent support. It's the most flexible tier and the most work.
2. Claude Agent SDK. The agent loop, tools, context handling, subagents, hooks and cost tracking come from Anthropic but run on infrastructure you operate. Subagents are native, and anything multi-agent beyond them is mostly your own design. Authentication works through Bedrock, Vertex AI and Azure Foundry, so this is the most portable tier.
3. Claude Managed Agents. Anthropic runs the runtime for you: containers, compaction, prompt caching, event history, stateful sessions and a set of built-in tools. Single-agent use has matured, whereas multi-agent sessions sit in a separate gated preview.
4. Managed Agents multiagent. A research preview with restricted access and a notable constraint: the design supports one coordinator level only. A coordinator can call other agents, but the agents it calls can't call further ones. That's multi-agent orchestration, though not yet a general recursive society of agents.
5. Claude Code subagents. Isolated worker contexts inside one main session that report results back. An official feature, but not peer-to-peer teams.
6. Claude Code agent teams. As of that April 2026 snapshot, experimental and disabled by default, switched on through a specific environment variable. Known limitations include session-resumption behavior, edge cases in task coordination and resumed sessions that refer to teammates who no longer exist.

Put practically, the sentence "Claude supports agent teams" holds true, while "Claude offers production-grade, general-purpose multi-agent orchestration on every surface" does not.

Claude Code agent teams in practice

A quick refresher on the difference:

• Subagents run inside a single main session. The main Claude Code instance spawns them, each works alone within its own context window and sends results back, with you doing the orchestrating, and the main session never absorbs the work done to produce a result.
• Agent teams are separate Claude Code sessions that talk to each other. Each teammate has its own context window and session state, plus a shared task list and a mailbox for direct messages. Teammates can hand tasks to one another and coordinate themselves without waiting for the lead to relay each instruction. The lead sets direction, and teammates can act on it and converse among themselves.

The setup

1. A team configuration sits at ~/.claude/teams/{name}/config.json.
2. A shared task list sits at ~/.claude/tasks/{name}/.
3. Teammates are defined in reusable agent files, in effect subagent definitions that are assigned teammate roles.
4. Hooks can act as quality gates between task transitions.

Two architectural points matter for design. First, subagents can keep their own auto memory. That helps with specialization, but once work is split across several agents with separate memories, you're taking an architecture decision about which knowledge stays local, which is shared and which is summarized back. That's a system design question.

Second, the documentation is blunt about when teams do worse than subagents: sequential tasks, edits to the same file and work with many dependencies between steps. If agents must pass the same artifact along in order, not work in parallel, subagents in a sequential pipeline are simpler and more predictable.

Since teams were still experimental and off by default at that point, enable them only for a clear reason from the list above, and expect rough edges.

How agents talk to each other

Communication between agents is often treated as a prompting issue. At scale it's a systems issue. There are three broad forms.

1. Plain-language messages. The most obvious form and the least reliable at scale. Claude Code teammates message each other directly through the mailbox. That's flexible, but natural language is less precise than structured invocation, leaving more room for misreading between agents.
2. Structured invocation. JSON Schema tool definitions and strict tool use. Anthropic's tool definitions guarantee arguments that conform to the schema. This layer makes agent-to-tool communication dependable, and the same mechanism makes agent-to-agent calls more precise when modeled as tool calls instead of free-form messages.
3. Shared state or artifacts. The most underrated form. Anthropic's multi-agent research write-up recommends having subagents write outputs to a filesystem or external system and return lightweight references, instead of routing everything through the lead agent's context. The reason is simple: a file can be audited, versioned and inspected directly, and a message summarizing a file can be none of those things.

Timing matters as much as format. Four patterns come up:

• Synchronous calls. A manager calls a specialist, waits, then carries on. Easy to reason about, but a potential bottleneck. Anthropic's research team reportedly found that synchronous lead execution was blocked by slow workers and ruled out steering mid-flight.
• Sequential handoffs. Ownership moves from one agent to the next, one producing a result and the next picking it up. OpenAI draws a formal line between two styles: a handoff gives the specialist ownership of what happens next, while an agent used as a tool leaves the manager in charge. Who is accountable depends on which one is used.
• Event-driven or streaming. Agents react to events instead of synchronous calls. Better for long-running work, harder to debug and test, and hooks sometimes help.
• Shared-state polling. Unglamorous, yet frequently the sturdiest option. Agents look in a shared file or data store for progress, record their updates there and move on. Anthropic's long-running harness work keeps JSON feature lists, progress files and git commits as durable shared state, and human checkpoints slot in naturally.

What agents hand each other shapes the reliability of the whole system. Passing the full conversation history maximizes continuity but grows cost and latency linearly. A compressed summary is often better, and it's what Claude Code subagents do by design. Passing task-specific artifacts such as structured output files, code patches, JSON feature lists and stored reports tends to be the practical sweet spot. The agent on the receiving end can inspect the artifact directly instead of trusting a summary, which makes the system auditable in a way conversational handoffs can't match.

What gets passed also determines how and when it gets passed, which reinforces the central point: building agent teams is a systems design problem, and those are harder to solve than a linear orchestrated flow.

Eight ways agent teams fail

Most multi-agent tutorials skip this part. Anthropic's engineering notes are a good source. They read less like a research paper than like the diary of a team that learned, one bug at a time, that extra agents multiply management problems. Eight lessons can be drawn from them.

• Coordination drift. Vague delegation makes workers repeat each other's searches, miss boundaries or return output that doesn't compose. Anthropic's research system post found this directly, and the fix was teaching the orchestrator to state the objective, output format, source guidance and scope for each worker. Where ownership isn't defined, agents improvise it, and badly, much as humans do.
• Hallucinated ownership. Agent A believes agent B verified something that nobody actually verified. The cure is explicit completion artifacts: task hooks, end-to-end verification before anything is marked done and durable state files that record what was actually confirmed, not what was assumed.
• Silent intermediate failure. Debugging required full production tracing, because nothing revealed whether a failure traced back to poor search queries, weak sources or a tooling fault. The top-level session stream is only a condensed view, and understanding what a called agent really did means inspecting worker-level history. Wire up tracing at the outset, well before the first incident in production.
• Context bloat and memory pollution. The context window is a finite resource, and shared memory that goes stale or noisy degrades the whole system. Every tool call, file read and partial analysis lands in context and stays there, and across a team this compounds. The known mitigations are summarizing completed phases, isolating heavy work in subagents and preferring small focused memory files to large shared ones.
• Schema mismatch and brittle prompt contracts. Agents trading data in natural language are fragile. The second agent misreads the first one's summary and the error spreads silently. Strict tool use exists because non-strict calls can produce incompatible types or missing fields. Narrow contracts between agents and tools shrink the surface where this can happen, an ironic role for plain old engineering contracts in an AI setting.
• Tool misuse and security failure. More open environments mean more entry points for prompt injection, and more tools mean more ways for an attacker to act once inside. Anthropic's research on trustworthy agents names prompt injection as a cyberattack vector instead of an edge case, and METR's red-teaming of Anthropic's internal agent monitoring reportedly found novel vulnerabilities even in a well-resourced internal system. Mitigate with limited permissions, tools scoped to what the task needs and human approval for consequential actions.
• Cost explosion and latency stacking. Teams use far more tokens than a single session. Parallelism can cut wall-clock time, but it raises total token spend instead of lowering it, since the speedup comes from spending more structured effort at once. Unless the task warrants that spend, a single carefully built agent comes out quicker and cheaper.
• Evaluation difficulty. Quite different internal paths can all arrive at a result that looks successful. If the only test is whether the final prose sounds plausible, the system is being admired instead of evaluated. Anthropic's recommendation is to check whether the correct final state was reached, not whether the intended process was followed. The process varies, and the outcome is what you can verify.

Native, DIY or hybrid

So the big question: build the orchestration yourself, or use an off-the-shelf solution? It's an architectural trade-off among three options, and there are surely more, so take this as one opinionated framing.

1. Native managed means Anthropic owns the runtime and the coordination surface: Claude Managed Agents and, more narrowly, Managed Agents multiagent or Claude Code agent teams. The gains are lower engineering overhead, a hosted harness and infrastructure you needn't maintain. The costs are limited portability (Managed Agents is reachable only through the direct Claude API), a multi-agent surface that's experimental or in gated preview, and dependence on a third party. Choose it when infrastructure is the pain and Anthropic-specific constraints are tolerable.
2. DIY means you own the orchestration logic and usually the runtime as well, with the Messages API as the purest example. It offers the most control at the highest engineering cost. Choose it if your business logic is out of the ordinary, compliance rules are strict, routing is specific to your domain, or provider portability is a real requirement.
3. Hybrid means Anthropic supplies the loop and tools while you architect the system, and the Claude Agent SDK is the clearest example. You get Anthropic's agent loop, context management, hooks, subagents and observability, and you still own the higher-level design. Authentication through Bedrock, Vertex AI and Azure Foundry is a meaningful portability advantage over native managed. Choose it when you want Anthropic's loop without marrying the entire architecture to Anthropic's current view of how multi-agent systems should work.

In short: native managed when infrastructure is the pain, DIY when topology and policy are the pain, and hybrid when you want Anthropic's primitives but need room for your own architectural decisions.

The architecture question

The frame most people bring to agent teams is capability, on the theory that more agents means more capability. The frame that helps is architecture: what problem does an extra agent solve, and what does it cost?

Subagents settle who does the work, in which context and with which tools. Agent teams add a coordination layer on top, with shared task state, teammates who message each other directly, and parallel runs that organize themselves. Such a layer pays off only for problems that truly call for it.

A single well-configured agent team for a real use case is a reasonable week's work. Complexity can grow from there, but it needn't start there. The failure catalogue and communication patterns above serve as reference material, not as a plan to build all of it at once. Begin by naming which of the four triggers is actually true, and if none is, the single-agent path is still the right one.