Learn

Agent Teams

Multiple AI agents working in parallel on a shared task, coordinating with each other rather than operating in isolation.

What Agent Teams Are

Agent teams are a coordination pattern where multiple Claude instances work simultaneously on different aspects of a task, with a team lead orchestrating the work. Unlike subagents (isolated, one-way communication), team members have shared awareness and can build on each other’s work.

Team Lead (Opus 4.6)
├── Teammate 1: "Implement API endpoints"    ──┐
├── Teammate 2: "Write database migrations"  ──┼── Can reference
└── Teammate 3: "Create test suite"          ──┘   each other's work

Teams vs Subagents

SubagentsAgent Teams
CommunicationOne-way (parent to child)Bidirectional
ContextIsolated (own context window)Shared awareness of team state
CoordinationManual (parent manages results)Automatic (team lead orchestrates)
Failure handlingParent retries or routes aroundTeam adapts, reassigns work
Best forIndependent parallel tasksInterdependent collaborative work

The Team Lead Pattern

The team lead is the orchestrating agent. It:

  1. Decomposes the task into work items for teammates
  2. Assigns work based on teammate specializations
  3. Monitors progress and handles blockers
  4. Synthesizes results into a coherent output
# Claude Agent SDK
from claude_agent_sdk import query, AgentDefinition

api_agent = AgentDefinition(
    name="api-developer",
    instructions="Implement REST API endpoints. Follow existing patterns in src/api/.",
    model="claude-sonnet-4-6",
)

db_agent = AgentDefinition(
    name="db-developer",
    instructions="Write database migrations and queries. Use sqlx for type-safe queries.",
    model="claude-sonnet-4-6",
)

test_agent = AgentDefinition(
    name="test-writer",
    instructions="Write integration tests for the new endpoints and migrations.",
    model="claude-sonnet-4-6",
)

async for msg in query(
    prompt="Add a user favorites feature: API endpoints, database schema, and tests",
    options={
        "model": "claude-opus-4-6",  # Team lead uses Opus
        "agents": [api_agent, db_agent, test_agent],
    },
):
    print(msg)

Use Cases

Large Codebase Refactors

A team lead analyzes the full scope, then dispatches teammates to different modules:

  • Teammate 1: Refactor the auth module
  • Teammate 2: Update API consumers of auth
  • Teammate 3: Fix tests broken by changes

Multi-File Feature Implementation

When a feature touches many files that depend on each other:

  • Teammate 1: Database layer (schema, queries)
  • Teammate 2: Business logic (services, validation)
  • Teammate 3: API layer (endpoints, middleware)

The team lead ensures interfaces match between layers.

Research Tasks

Parallel information gathering with synthesis:

  • Teammate 1: Search documentation for relevant patterns
  • Teammate 2: Analyze existing codebase for precedents
  • Teammate 3: Research external libraries and approaches

The team lead synthesizes findings into a recommendation.

Worktree Isolation

For safety, teammates can work in isolated git worktrees:

agent = AgentDefinition(
    name="experimental-refactor",
    instructions="Try refactoring auth to use JWT",
    isolation="worktree",  # Gets its own copy of the repo
)

Each worktree is a separate branch. If the work is useful, it can be merged. If not, the worktree is cleaned up automatically.

Tradeoffs

Benefits

  • Parallelism - multiple agents work simultaneously, wall-clock time drops
  • Specialization - each agent focuses on what it does best
  • Larger scope - tackle tasks that would overflow a single agent’s context

Costs

  • Coordination overhead - the team lead spends tokens managing the team
  • Token cost - N agents = N context windows = N times the cost
  • Merge complexity - concurrent file edits may conflict
  • Diminishing returns - more than 3-4 teammates rarely helps

When to Use Teams

Use teams when:

  • The task is too large for one agent’s context window
  • Multiple independent workstreams exist
  • Speed matters more than cost
  • The work touches different areas of the codebase

Use subagents when:

  • Tasks are truly independent (no shared state)
  • You need simple parallel execution
  • Cost matters more than coordination quality

Use a single agent when:

  • The task fits in one context window
  • Changes are tightly coupled
  • Coordination overhead would exceed the parallelism benefit

Next