Sub-Agents vs Agent Teams: The Architecture Decision That Changes Everything

Most AI Systems Are Built Wrong
Most people reach for multi-agent systems the moment a task feels complex. That’s usually the wrong instinct.

The real question isn’t “should I use multiple agents?” It’s “what kind of coordination does this task actually need?”

That answer determines everything about your architecture.
Claude-style systems give you two distinct approaches: sub-agents and agent teams. They may look similar, but they solve completely different problems.

Sub-Agents: Parallelism with Isolation

A sub-agent is a specialized instance that runs in its own isolated context. Think of it like delegation. You assign focused work, it returns a clean result.

Each sub-agent gets:

A system prompt defining its role

A limited set of tools

A completely isolated context

A single, well-scoped task

When it finishes, it returns only the final output, not reasoning or intermediate steps.

This matters because sub-agents are about compression, not just speed. They turn messy exploration into a clean signal.

There are strict constraints:

Sub-agents cannot talk to each other

Sub-agents cannot spawn new agents

Everything flows through the parent

This keeps the system predictable and clean.

Here’s what it looks like in practice:

from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

async def main():
    async for message in query(
        prompt="Review the authentication module for issues",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Grep", "Glob", "Agent"],
            agents={
                "security-reviewer": AgentDefinition(
                    description="Find vulnerabilities and security risks",
                    prompt="You are a security expert.",
                    tools=["Read", "Grep", "Glob"],
                    model="sonnet",
                ),
                "performance-optimizer": AgentDefinition(
                    description="Identify performance bottlenecks",
                    prompt="You are a performance engineer.",
                    tools=["Read", "Grep", "Glob"],
                    model="sonnet",
                ),
            },
        ),
    ):
        print(message)

The key detail is the description field. It acts as a routing signal.

Agent Teams: Coordination Through Communication

Agent teams are built for collaboration. Instead of isolated workers, you have agents that maintain context, communicate, and adapt in real time.

They include:

A lead agent that assigns and synthesizes

Teammates that execute tasks

A shared task layer that tracks progress and dependencies

This allows real coordination. A frontend agent can signal backend changes and things update instantly.

The Core Difference

Sub-agents and agent teams are fundamentally different.

Sub-agents are execution-focused:

Isolated

Stateless

One-shot

Parent-controlled

Agent teams are collaboration-focused:

Persistent

Interactive

Context-sharing

Peer-to-peer

Use sub-agents when tasks are independent. Use teams when tasks depend on each other.

Where Most People Go Wrong

Most systems are split by roles like planner, developer, tester. This creates context loss at every handoff.

The implementer doesn’t know what the planner knew

The tester doesn’t know what the implementer decided

Quality drops at every boundary.

The better approach is context-based decomposition.

Ask: What information does this task actually need?

If two tasks share deep context, keep them in the same agent. Split only when context can be cleanly separated.

The 5 Patterns That Actually Matter

1. Prompt chaining — sequential steps

. Routing — send tasks to the right agent

3. Parallelization — run independent work together

4. Orchestrator–worker — one agent delegates

5. Evaluator–optimizer — generate and refine

When Not to Use Multi-Agent Systems

Sometimes a single agent is enough

Use multi-agent systems when:

You need context isolation

You have parallel tasks

You need specialization

Avoid them when:

Agents depend heavily on each other

Coordination overhead is too high

The task is simple

Final Principle

Design around context boundaries, not roles. Start simple and add complexity only when needed.