Choosing Between Sub‑agents and Agent Teams in Claude Code: Key Differences Explained

1. Sub‑agents: Independent Context + Compressed Output

Sub‑agent is a dedicated Claude instance running in its own context window. Analogy: a research lead delegates specific questions to researchers who return concise conclusions for aggregation. Each Sub‑agent receives a specialized system prompt, tool permissions, an isolated context, and a clear task.

Dedicated system prompt defining its domain

Specific tool permissions

Clean, isolated context window

A single well‑defined task

After completion, only the final compressed result is returned to the main Agent; intermediate reasoning is omitted. This design keeps the main Agent’s context clean and predictable. A hard constraint: Sub‑agents cannot nest or communicate with each other; all results flow back to the main Agent, which remains the sole coordinator.

Minimal SDK example:

from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

async def main():
    async for message in query(
        prompt="Review the authentication module for security vulnerabilities",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Grep", "Glob", "Agent"],
            agents={
                "security-reviewer": AgentDefinition(
                    description="Security specialist. Use for vulnerability checks and security audits.",
                    prompt="You are a security specialist with expertise in identifying vulnerabilities.",
                    tools=["Read", "Grep", "Glob"],
                    model="sonnet",
                ),
                "performance-optimizer": AgentDefinition(
                    description="Performance specialist. Use for latency issues and optimization reviews.",
                    prompt="You are a performance engineer with expertise in identifying bottlenecks.",
                    tools=["Read", "Grep", "Glob"],
                    model="sonnet",
                ),
            },
        ),
    ):
        print(message)

The description field acts as a routing signal; a prompt mentioning “security vulnerabilities” routes to security-reviewer, while a latency‑related prompt routes to performance-optimizer.

2. Agent Teams: Long‑Running + Peer‑to‑Peer Communication

Agent Teams differ fundamentally: they are persistent agents that maintain state and can communicate directly with each other via shared task lists. Analogy: temporary contractors versus a permanent team that collaborates in the same workspace.

Team Lead – coordinates work, assigns tasks, aggregates results

Teammates – independent Agent instances with their own context windows, working in parallel

Shared task list – tracks pending, in‑progress, and completed tasks and their dependencies

Typical lifecycle example:

Claude (Team Lead):
└── spawnTeam("auth-feature")
    Phase 1 - Planning:
    └── spawn("architect", prompt="Design OAuth flow", plan_mode_required=true)
    Phase 2 - Implementation (parallel):
    └── spawn("backend-dev", prompt="Implement OAuth controller")
    └── spawn("frontend-dev", prompt="Build login UI components")
    └── spawn("test-writer", prompt="Write integration tests", blockedBy=["backend-dev"])

The blockedBy field ensures the test writer waits for backend completion without manual sequencing. Unlike Sub‑agents, teammates can exchange messages, share discoveries, and negotiate without always routing through the Lead.

3. When to Choose Sub‑agents vs. Agent Teams

Use Sub‑agents for embarrassingly parallel tasks where each sub‑task can run in isolation and only the final aggregated result is needed (e.g., independent research, code exploration, query). Use Agent Teams when tasks require ongoing coordination, shared state, or when the output of one sub‑task influences another (e.g., front‑end discovering API changes that need immediate back‑end adjustments).

4. Common Reasons Multi‑Agent Designs Fail

Most failures stem from splitting work by role rather than by context. Role‑based splits (Planner, Implementer, Tester) create a “telephone game” where information degrades at each hand‑off. The article argues that a context‑centric split preserves signal quality.

5. Five Typical Multi‑Agent Patterns

Prompt Chaining – sequential execution where each step consumes the previous output.

Routing – a classifier directs tasks to the appropriate specialized handler.

Parallelization – independent sub‑tasks run simultaneously, either for voting or sectioning.

Orchestrator‑Worker – a central Agent decomposes work, delegates to workers, and aggregates results (the core pattern for both Sub‑agents and Agent Teams).

Evaluator‑Optimizer – one Agent generates output, another evaluates and feeds back for iterative improvement.

6. When Multi‑Agent Systems Are Actually Needed

They are justified when a sub‑task’s context is irrelevant to the main task (preventing context bloat), when independent research or search benefits from parallel coverage, or when conflicting system prompts or excessive tool usage would degrade a single Agent’s performance.

Conversely, multi‑Agent setups are unnecessary when agents must frequently share context, when cross‑Agent dependencies outweigh execution benefits, or when a single well‑prompted Agent can handle the job.

7. Three Typical Failure Modes

7.1 Vague Task Descriptions

Agents need clear goals, expected output formats, tool usage guidance, and explicit boundaries; otherwise they duplicate work.

7.2 Inadequate Verification

Completion should be gated by concrete, test‑driven criteria; vague acceptance leads to false positives.

7.3 High Token Costs

Mitigate by hierarchical routing: use the strongest model only where needed, route routine work to cheaper models, and enforce budget controls.

8. Final Guidance

Design around context boundaries rather than organizational roles. Start with a single Agent, expand only until its context limit is reached, then decompose where failures occur. Add complexity only where it solves measurable problems.

Complexity should be introduced only when it addresses a real, quantifiable need.