Have you ever been in this situation? You’re halfway through a project, realize you need to handle multiple things simultaneously, so you excitedly build a “multi-agent system.” After hours of orchestration, the code runs—but the output always feels a bit off. Where did it go wrong?

The architecture was wrong from the start.

When you need multiple agents working together, your first instinct might be “let’s get a bunch of small agents to help.” But once you actually start, you find these agents stepping on each other’s toes, context getting passed around until it becomes a mess. Even worse, you can’t clearly define what each agent should or shouldn’t do.

Don’t worry—this isn’t your fault. Most people haven’t figured out one thing: Sub-Agents and Agent Teams are fundamentally different concepts that solve completely different problems.

Sub-Agents: The Outsourcing Approach

Sub-Agents are like outsourcing part of your work to a specialized temp worker. You tell them what to do, they finish it and give you the result—no small talk, no progress reports, no sudden offers to “optimize that other code while I’m at it.”

When created, each Sub-Agent receives three things: a clearly defined role description, a limited set of tools, and a completely isolated working context.

The benefit? You can run multiple Sub-Agents simultaneously. They don’t interfere with each other, each completing their portion of work, then汇总ing results back to the main agent. It’s like handling multiple dishes in a kitchen—each dish has its own pot and stove, finished dishes are taken away, flavors don’t mix.

But Sub-Agents have a strict limitation: they cannot directly talk to each other. All information must flow through the parent agent. This means if you have two Sub-Agents “collaborating” on a task, they’re not really collaborating—they’re working in their own vacuum.

Here’s what it looks like in Claude Agent SDK:

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 description field tells the system which Sub-Agent should handle which task.

Agent Teams: True Collaboration

If Sub-Agents are temp worker outsourcing, Agent Teams are a real project team. There’s a lead, team members, a shared task board—everyone can communicate in real-time, report progress, and adjust direction as needed.

The core of Agent Teams is a Lead Agent plus several executing agents. They share a task layer, tracking progress and dependencies. Team members truly collaborate: when a frontend agent notices a backend API change, it can immediately notify other agents. The system responds in real-time.

It’s like running an open kitchen. Chefs don’t just cook their own dishes—they see each other’s progress. Someone notices ingredients running low and calls out; someone else sees a dish about to burn and jumps in to help.

The key difference is context sharing. Sub-Agents have isolated contexts, while Agent Teams members share context—so information doesn’t get lost in transit. This is crucial for tasks requiring multiple rounds of collaboration.

When to Choose Which?

There’s no standard answer, but here’s a simple rule: if your task can be decomposed into completely independent subtasks, choose Sub-Agents. If subtasks need frequent communication and context sharing, choose Agent Teams.

Let’s look at some examples. In code review, security review and performance optimization are independent tasks. They don’t need to know each other’s findings—they just need to summarize results. Sub-Agents work perfectly here.

But if you’re building a feature requiring frontend, backend, and testing coordination—where each party’s progress affects others—Agent Teams’ real-time coordination becomes essential.

Most people’s mistake is decomposing by role: creating a Planner Agent, a Developer Agent, a Tester Agent. The problem is, every time a task passes between agents, context gets lost. What the Planner knows, the Implementer might not; what the Implementer decides, the Tester might not understand. Quality drops at every handoff.

The correct approach is decomposing by context boundaries. Ask yourself: what information does this task actually need? If two tasks share a lot of context, keep them in the same agent. Only split into different Sub-Agents or team members when context can be truly separated.

Five Proven Agent Collaboration Patterns

In practice, five patterns have been repeatedly proven effective. First, Prompt Chaining—breaking a complex task into sequential steps, each based on the previous result. Second, Routing—distributing tasks to specialized agents based on type. Third, Parallelization—running independent subtasks simultaneously and aggregating results. Fourth, Orchestrator-Worker pattern—a central agent coordinating multiple executing agents. Fifth, Evaluator-Optimizer—one agent generates solutions, another evaluates and improves them.

These patterns aren’t mutually exclusive—you can combine them based on actual needs. The key is not using multi-agent for the sake of using multi-agent. Architecture should reflect genuine task requirements.

When to Skip Multi-Agent Entirely?

Multi-agent systems sound appealing, but they’re not needed everywhere. If you find agents highly interdependent, with coordination overhead exceeding task complexity, a single strong agent might be better.

Single-agent suffices when: task complexity isn’t high, inter-agent dependencies are too complex to maintain, or coordination costs outweigh parallel benefits. Remember, architecture solves problems—it’s not for showing off.

Summary

For isolated execution, independent tasks, and one-shot completion—Sub-Agents are the right choice. For continuous collaboration, context sharing, and real-time response—Agent Teams fit better.

The core of architecture choice is context boundary划分, not role division. Master this principle, and your multi-agent system will deliver real value instead of becoming a bunch of isolated agents talking past each other.

FAQ

Is there a big performance gap between Sub-Agents and Agent Teams?

Sub-Agents suit independent task parallel processing; Agent Teams suit complex work needing real-time coordination. Purely by speed, Sub-Agents are usually faster—no message passing overhead. But if tasks need extensive context synchronization, Agent Teams’ overall efficiency can be higher.

How many Sub-Agents can a parent agent manage?

It depends on the scenario and model capability. Claude’s documentation suggests 5-10 Sub-Agents per parent agent is reasonable—beyond that, coordination costs rise significantly. If you need more, consider hierarchical management or switching to Agent Teams architecture.

Can Agent Teams’ Lead Agent become a performance bottleneck?

Possibly. If the Lead Agent handles too much, it becomes a chokepoint. The solution: let Lead Agent only handle task distribution and result aggregation, leaving all execution to team members—don’t participate in execution yourself.