Agent Teams

Let multiple AI agents communicate, claim tasks from a shared list, and merge their own work, so the human stops being the coordination bottleneck.

Understand This First

• Parallelization – agent teams automate what parallelization requires you to manage by hand.
• Subagent – subagents delegate hierarchically; agent teams add peer-to-peer coordination.
• Worktree Isolation – the manual alternative to agent teams: you run multiple sessions yourself, each in its own worktree.

Context

At the agentic level, Agent Teams sit above Parallelization and Subagent. Where parallelization requires a human to decompose work, assign tasks, monitor progress, and integrate results, Agent Teams push that coordination into the agents themselves. One session acts as team lead. It breaks the work down, spawns teammates, and maintains a shared task list. The teammates claim tasks, work independently in their own context windows, and talk to each other directly when they discover something relevant.

The human coordination bottleneck is what limits parallelism in practice. A developer can comfortably direct two or three agents. Beyond that, context-switching between agent sessions, tracking who’s doing what, and reconciling conflicts eats into the throughput gains. Agent Teams remove that bottleneck by letting agents coordinate among themselves.

Problem

How do you scale agentic work beyond a handful of parallel agents without drowning in coordination overhead?

Manual parallelization works at small scale. But as agent count grows, the human director becomes the bottleneck. You have to decompose the work, write task descriptions, assign agents, monitor progress, answer questions, resolve conflicts, and integrate results. The agents can’t talk to each other, so every piece of shared information routes through you. At five or ten agents, the management burden can exceed the time saved by parallelizing.

Forces

• Coordination cost grows with agent count. Each additional agent adds management overhead for the human.
• Agents discover things during work that other agents need to know, but with no communication channel between them, those discoveries are trapped.
• File conflicts multiply when agents work on related parts of a codebase, and without an explicit coordination primitive every overlap becomes the human’s problem to detect and untangle.
• Task dependencies shift during execution. A task that seemed independent turns out to need results from another task, but neither agent knows about the other’s progress.

Solution

Designate one agent session as the team lead. The lead decomposes the work into a shared task list with dependency tracking, then spawns teammates, each running in its own context window. The teammates share one working directory and self-organize: they claim tasks from the shared list, work independently, and communicate discoveries through a mailbox. The lead monitors progress, resolves disputes, and coordinates final integration.

Three coordination mechanisms distinguish Agent Teams from manual parallelization:

Shared task list. The lead creates a list of tasks with dependencies. Teammates claim tasks when they’re ready, rather than waiting for you to assign them. When a task’s prerequisites are complete, it becomes available. This removes the human as a scheduling bottleneck.

Peer-to-peer messaging through a mailbox. Teammates post messages to a shared mailbox rather than routing through the lead or through you. When one teammate discovers that a shared utility function’s signature has changed, it notifies the others directly. This prevents three agents from independently discovering the same breaking change by trial and error.

Shared workspace with file-level coordination. All teammates work in the same directory, not in separate worktrees. Task claiming uses file locking, so two teammates cannot grab the same task at the same instant, and the standard practice is to scope each task to a different set of files so editing collisions never arise in the first place. This is the explicit tradeoff: you give up the merge-time isolation that worktrees provide in exchange for faster cross-teammate visibility into the live state of the codebase.

A small set of additional primitives rounds out the model. Plan-approval gating lets the lead require a teammate to plan in read-only mode and submit the plan for approval before touching files. Task lifecycle hooks (TeammateIdle, TaskCreated, TaskCompleted) fire on team events and let you wire in quality gates without rewriting the orchestrator. Reusable definitions mean a single subagent specification (say, security-reviewer) can serve both as a one-shot subagent and as a teammate in a longer-running team, so investments in either mode pay off in the other.

Your role shifts from director to reviewer. Instead of assigning tasks, monitoring chat windows, and ferrying information between agents, you review the team’s output, approve merges, and intervene only when the team gets stuck.

Orchestration Topologies

Not all agent teams coordinate the same way. Four topologies have emerged in practice, and most real systems mix them:

Sequential pipeline. Agents form a chain. Each one transforms the output and passes it to the next. A code-generation agent writes the implementation, a review agent checks it, a test agent verifies it. This works well when each stage has a clear input and output. The risk is that errors compound downstream.

Router/dispatcher. A central agent classifies incoming work and routes it to the right specialist. A user request about database performance goes to the query-optimization agent; a request about UI layout goes to the frontend agent. This topology scales well when the task space is broad but each individual task is narrow.

Hierarchical delegation. A manager agent decomposes work and assigns it to supervisors, who further delegate to workers. This is the default topology for Agent Teams in most harnesses, where the team lead acts as the top-level manager. It handles complex projects with layered decomposition but can bottleneck at the manager if too many decisions flow upward.

Swarm/mesh. Agents communicate peer-to-peer with no fixed hierarchy. Each agent makes local routing decisions about who to hand work to next. This is the most flexible topology and handles unpredictable workflows, but it’s harder to observe and debug because there’s no single point of control.

Most practical agent teams blend these. A hierarchical team lead might use a sequential pipeline for the build-test-deploy phase of each task, while teammates within the same level communicate peer-to-peer when they discover shared concerns.

How It Plays Out

A developer needs to add a payment processing module with four components: a database schema, an API layer, a webhook handler, and an integration test suite. She starts a team lead session and describes the goal. The lead decomposes it into four tasks, notes that the API and webhook handler both depend on the schema, and spawns four teammates. The schema teammate finishes first and messages the API and webhook teammates: “Schema is done, here’s the table structure.” Both pick up their tasks without the developer copy-pasting anything between sessions. The test teammate waits until the API is ready, then writes integration tests against the actual endpoints. The whole module takes forty minutes. The developer described the goal, reviewed the decomposition, and approved the final merge. That was it.

An engineering team is migrating a monolithic Python application to a package-based architecture. The lead agent analyzes the dependency graph and creates 12 extraction tasks, ordered so that leaf packages (those with no internal dependencies) go first. Eight teammates work through the list over several hours, each claiming the next available task. When one teammate discovers a circular dependency the original analysis missed, it messages the lead, which re-plans those two tasks as a single combined extraction. The human intervenes twice: once to approve a naming convention the agents disagreed on, and once to override a teammate’s decision to add a compatibility shim that would have made the migration harder to finish later.

Consequences

Agent Teams unlock parallelism at a scale that manual coordination can’t sustain. Five or ten agents working on a well-decomposed problem can finish in an hour what would take a full day of sequential work. Peer messaging means discoveries propagate without you becoming the information bottleneck, and the shared task list means agents don’t sit idle waiting for assignments.

The costs are real. Team coordination consumes tokens. Every peer message, every task status update, every merge operation uses context in each involved agent’s window. For small tasks that a single agent can handle in one session, spawning a team adds overhead without benefit. There’s also a visibility tradeoff: when agents coordinate among themselves, you have less insight into why decisions were made. Good team implementations log all inter-agent communication, but reviewing those logs takes time.

The sweet spot is projects with clear module boundaries, well-defined interfaces, and enough independent work to keep multiple agents busy. If your codebase is tangled with circular dependencies, agents will spend more time messaging each other about conflicts than doing productive work. Fix the architecture first, then parallelize.

Related Patterns

Sources

The foundations of multi-agent coordination trace to Distributed Artificial Intelligence research in the 1970s and 1980s, with Reid G. Smith’s Contract Net Protocol (1980) formalizing one of the earliest task-delegation mechanisms between autonomous software agents.

Anthropic shipped Agent Teams as an experimental feature in Claude Code in February 2026, introducing the shared task list, mailbox, file-locking task claims, plan-approval gating, and lifecycle hooks that distinguish teams from manual parallelization.

Addy Osmani’s “The Code Agent Orchestra” (2026) framed the architectural shift as the move from a “conductor model” (one agent, synchronous, limited by a single context window) to an “orchestrator model” (multiple agents with independent context windows, working asynchronously and communicating peer-to-peer).

Google’s Agent Development Kit (ADK) formalizes sequential, parallel, loop, hierarchical, and router/coordinator patterns. Microsoft’s Azure Architecture Center publishes a parallel taxonomy of agent orchestration patterns. Practitioner writeups (notably Osmani’s “Code Agent Orchestra”) extend the catalog to include swarm and mesh topologies that none of the vendor docs name explicitly.