# Claude Subagents vs. Agent Teams, clearly explained
**作者**: Avi Chawla
**日期**: 2026-05-02T06:33:14.000Z
**来源**: [https://x.com/_avichawla/status/2050463606719000627](https://x.com/_avichawla/status/2050463606719000627)
---
Most people reach for multi-agent systems the moment a task feels complex.
That's almost always the wrong instinct.
The right question isn't "should I use multiple agents?" It's "what kind of coordination does this task actually need?"
The answer to that determines everything about your architecture.
Claude gives you two distinct multi-agent paradigms: sub-agents and agent teams. They look similar on the surface but architecturally, they solve completely different problems.
# Sub-Agents: Parallelism through isolation
A sub-agent is a specialized Claude instance that runs in its own isolated context window.
Here's the mental model: imagine you're a research lead. You don't read every primary source yourself. You delegate focused questions to researchers, they come back with distilled findings, and you synthesize everything into a coherent output.
That's exactly what sub-agents do.
Each sub-agent gets:
- Its own system prompt defining its specialty
- A specific set of tools it can access
- A clean, isolated context window
- One job to do
```
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 is what tells the parent agent which sub-agent to invoke. Here, the prompt mentions "security vulnerabilities" so the parent routes to security-reviewer, not performance-optimizer.
If the prompt had asked about latency or bottlenecks instead, the other agent would have been picked. The description is the routing signal. Keep it specific.
# Agent Teams: Coordination through communication
Agent teams are a fundamentally different model.
Where sub-agents are short-lived workers that complete a task and disappear, agent teams are long-running instances that persist, communicate directly with each other, and coordinate through shared state.
Think of it like the difference between hiring contractors for isolated tasks vs. assembling a team that works together in the same room.
An agent team has three moving parts:
- A team lead that coordinates work, assigns tasks, and synthesizes results
- Teammates that are independent agent instances, each with their own context window, working in parallel
- A shared task list that tracks what's pending, in progress, and done, along with dependencies between tasks
A typical lifecycle looks like this:
```
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"])
```
Notice the blockedBy field on the test writer. That's the shared task list doing real coordination work: the test writer won't start until the backend agent is done, without the lead having to manually manage that sequencing.
The big difference from sub-agents is direct peer-to-peer communication. Teammates can send messages to each other, share findings, surface blockers, and negotiate without routing everything through the lead.
You can also interact with individual teammates directly. You're not forced to go through the lead agent for everything.
# The core distinction
Here's how to think about the choice between them.
Sub-agents are fire-and-forget.
- You give them a task, they complete it, and report back
- No conversation between agents
- No shared memory
- No ongoing state
- Each sub-agent lives and dies within a single session
Agent teams are collaborative.
- Agents persist and accumulate context over time
- Mid-task discoveries surface to teammates immediately
- A frontend agent can tell a backend agent "the API response structure needs to change" and the backend agent adjusts without waiting for the lead to mediate
The clearest way to choose between them:
- Use sub-agents when your work is embarrassingly parallel: independent research streams, codebase exploration, or lookups where the parent only needs the summary
- Use agent teams when your work requires ongoing negotiation: agents that need to reconcile their outputs before proceeding, or where a discovery in one thread changes what another thread should do
# How to design agent systems from first principles
Most multi-agent designs fail because people split work by role instead of by context.
The intuitive instinct is to split by role: planner, implementer, tester. It feels organized. But it creates a telephone game where information degrades at every handoff.
- The implementer doesn't have what the planner knew
- The tester doesn't have what the implementer decided
- Quality drops at every boundary
The right mental model is context-centric decomposition.
Ask what context does this subtask actually needs? If two subtasks need deeply overlapping information, they probably belong to the same agent. If they can operate with truly isolated information and clean interfaces between them, that's where you split.
A practical example: an agent implementing a feature should also write the tests for that feature. It already has the context. Splitting those two into separate agents creates a handoff problem that costs more than the parallelism saves.
Only separate when context can be genuinely isolated.
# The five orchestration patterns
Regardless of which paradigm you use, these five patterns cover most real-world needs:
1. Prompt chaining: Sequential steps where each call processes the previous output. Use when order matters and steps are dependent.
2. Routing: A classifier decides which specialized handler gets the task. Easy questions go to cheaper, faster models. Hard questions go to more capable ones. This is how you keep costs from exploding.
3. Parallelization: Independent subtasks run simultaneously. Either the same task runs multiple times for diverse outputs (voting), or different subtasks run at the same time (sectioning).
4. Orchestrator-worker: A central agent breaks down the task, delegates to workers, and synthesizes results. This is the dominant architecture for both sub-agents and agent teams, and what most production systems actually use.
5. Evaluator-optimizer: One agent generates, another evaluates and provides feedback in a loop. Useful when quality matters more than speed and a single pass isn't reliable enough.
# When not to use multi-agent systems
Teams have spent months building elaborate multi-agent pipelines only to discover that better prompting on a single agent achieved equivalent results.
Start simple and add complexity only when you can clearly measure that it's needed.
Multi-agent systems earn their cost in three situations:
- Context protection: A subtask generates information irrelevant to the main task. Keeping it in a sub-agent prevents context bloat.
- True parallelization: Independent research or search tasks that benefit from simultaneous coverage.
- Specialization: The task requires conflicting system prompts, or one agent is juggling so many tools that its performance degrades.
But they're the wrong call when:
- Agents constantly need to share context with each other
- Inter-agent dependencies create more overhead than execution value
- The task is simple enough that one well-prompted agent handles it
One specific warning for coding: parallel agents writing code make incompatible assumptions. When you merge their work, those implicit decisions conflict in ways that are hard to debug. Sub-agents for coding should answer questions and explore, not write code simultaneously with the main agent.
# What makes multi-agent systems fail
Three failure modes show up constantly.
1. Vague task descriptions cause agents to duplicate each other's work.
Every agent needs a clear objective, an expected output format, guidance on what tools or sources to use, and explicit boundaries on what it should not cover. Without this, two agents will research the same thing and neither will notice.
2. Verification agents declare victory without verifying.
Explicit, concrete instructions are non-negotiable: run the full test suite, cover these specific cases, do not mark as complete until each one passes. Vague approval criteria produce false positives.
3. Token costs compound faster than you expect.
The solution is to tier your models intelligently:
- Use your most capable model where it genuinely matters
- Route routine work to faster, cheaper models
- Build in budget controls so costs can't run away unchecked
Design around context boundaries, not around roles or org charts.
Start with a single agent. Push it until you find where it breaks. That failure point tells you exactly what to add next.
Add complexity only where it solves a real, measured problem.
That's a wrap!
If you enjoyed this tutorial:
Find me → @_avichawla
Every day, I share tutorials and insights on DS, ML, LLMs, and RAGs.
## 相关链接
- [Avi Chawla](https://x.com/_avichawla)
- [@_avichawla](https://x.com/_avichawla)
- [2.3K](https://x.com/_avichawla/status/2050463606719000627/analytics)
- [@_avichawla](https://x.com/@_avichawla)
- [Upgrade to Premium](https://x.com/i/premium_sign_up)
- [2:33 PM · May 2, 2026](https://x.com/_avichawla/status/2050463606719000627)
- [2,361 Views](https://x.com/_avichawla/status/2050463606719000627/analytics)
- [View quotes](https://x.com/_avichawla/status/2050463606719000627/quotes)
---
*导出时间: 2026/5/2 16:21:02*
---
## 中文翻译
# Claude 子代理与代理团队，清晰解析
**作者**: Avi Chawla
**日期**: 2026-05-02T06:33:14.000Z
**来源**: [https://x.com/_avichawla/status/2050463606719000627](https://x.com/_avichawla/status/2050463606719000627)
---
大多数人一遇到感觉复杂的任务，就会立刻求助于多智能体系统。
这几乎总是错误的直觉。
正确的问题不是“我应该使用多个智能体吗？”而是“这个任务实际上需要什么样的协调？”
这个问题的答案决定了你架构的方方面面。
Claude 为你提供了两种截然不同的多智能体范式：子代理和代理团队。表面上看它们很相似，但在架构上，它们解决的问题完全不同。
# 子代理：通过隔离实现并行
子代理是一个在其独立的上下文窗口中运行的专用 Claude 实例。
这是一个心智模型：想象你是一个研究主管。你不会亲自阅读每一份原始资料。你会将焦点问题委托给研究员，他们回来时带给你提炼好的发现，然后你将所有内容综合成一个连贯的输出。
这正是子代理所做的事情。
每个子代理拥有：
- 定义其专业的独立系统提示词
- 它可以访问的一组特定工具
- 干净、隔离的上下文窗口
- 一项单一任务
```
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition
async def main():
async for message in query(
prompt="审查认证模块的安全漏洞",
options=ClaudeAgentOptions(
allowed_tools=["Read", "Grep", "Glob", "Agent"],
agents={
"security-reviewer": AgentDefinition(
description="安全专家。用于漏洞检查和安全审计。",
prompt="你是一名安全专家，专长于识别漏洞。",
tools=["Read", "Grep", "Glob"],
model="sonnet",
),
"performance-optimizer": AgentDefinition(
description="性能专家。用于延迟问题和优化审查。",
prompt="你是一名性能工程师，专长于识别瓶颈。",
tools=["Read", "Grep", "Glob"],
model="sonnet",
),
},
),
):
print(message)
```
描述字段是告诉父代理调用哪个子代理的关键。在这里，提示词提到了“安全漏洞”，所以父代理将其路由给 security-reviewer，而不是 performance-optimizer。
如果提示词询问的是延迟或瓶颈，则会选择另一个代理。描述就是路由信号。请保持其具体性。
# 代理团队：通过沟通进行协调
代理团队是一种根本不同的模式。
如果说子代理是完成任务后随即消失的短期工作者，那么代理团队就是持久存在的长期实例，它们之间直接沟通，并通过共享状态进行协调。
这就像是雇佣承包商处理孤立任务与组建一个在同一房间协同工作的团队之间的区别。
代理团队包含三个运作部分：
- 一个负责协调工作、分配任务并综合结果的团队主管
- 作为独立代理实例的队友，每个都有自己的上下文窗口，并行工作
- 一个共享任务列表，跟踪待处理、进行中和已完成的任务，以及任务之间的依赖关系
典型的生命周期如下所示：
```
Claude (Team Lead):
└── spawnTeam("auth-feature")
Phase 1 - Planning:
└── spawn("architect", prompt="设计 OAuth 流程", plan_mode_required=true)
Phase 2 - Implementation (parallel):
└── spawn("backend-dev", prompt="实现 OAuth 控制器")
└── spawn("frontend-dev", prompt="构建登录 UI 组件")
└── spawn("test-writer", prompt="编写集成测试", blockedBy=["backend-dev"])
```
注意测试编写者的 blockedBy 字段。这是共享任务列表在进行真正的协调工作：测试编写者直到后端代理完成后才会开始，而无需主管手动管理这种顺序。
与子代理最大的区别在于直接的点对点通信。队友之间可以互发消息、分享发现、暴露障碍，并进行协商，而无需将所有内容都通过主管进行路由。
你也可以直接与单个队友交互。你不必事事都通过主管代理。
# 核心区别
以下是关于如何在这两者之间进行选择的思考方式。
子代理是“即发即弃”的。
- 你给它们一个任务，它们完成后汇报回来
- 代理之间没有对话
- 没有共享记忆
- 没有持续的状态
- 每个子代理在单个会话内生存和消亡
代理团队是协作式的。
- 代理持久存在并随时间积累上下文
- 任务进行中的发现会立即暴露给队友
- 前端代理可以告诉后端代理“API 响应结构需要更改”，后端代理会进行调整，无需等待主管进行调解
在它们之间做出选择的最清晰方式是：
- 当你的工作是天然并行时使用子代理：独立的研究流、代码库探索，或者父代理只需要摘要的查找工作
- 当你的工作需要持续的协商时使用代理团队：代理在继续之前需要协调它们的输出，或者其中一个线程的发现会改变另一个线程应该做的事情
# 如何从第一性原理设计代理系统
大多数多智能体设计失败，是因为人们按角色而不是按上下文来拆分工作。
直觉上的本能是按角色拆分：规划者、实现者、测试者。这看起来很有条理。但这创造了一种“传声筒”游戏，信息在每次交接中都会退化。
- 实现者并不具备规划者所知道的上下文
- 测试者并不具备实现者所决定的内容
- 质量在每一个边界处都会下降
正确的心智模型是以上下文为中心的分解。
问问这个子任务实际上需要什么上下文？如果两个子任务需要深度重叠的信息，它们可能属于同一个代理。如果它们可以在真正隔离的信息和它们之间干净的接口下运作，那就是你应该拆分的地方。
一个实际的例子：实现功能的代理也应该编写该功能的测试。它已经具备了上下文。将这两者拆分为单独的代理会产生交接问题，其成本超过了并行带来的节省。
只有在上下文可以真正隔离时才进行拆分。
# 五种编排模式
无论你使用哪种范式，这五种模式都涵盖了大多数现实世界的需求：
1. **提示链**: 顺序步骤，其中每个调用处理前一个输出。当顺序很重要且步骤相互依赖时使用。
2. **路由**: 分类器决定将任务交给哪个专用处理程序。简单的问题交给更便宜、更快的模型。困难的问题交给能力更强的模型。这是防止成本爆炸的方法。
3. **并行化**: 独立的子任务同时运行。要么同一任务运行多次以获得不同的输出（投票），要么不同的子任务同时运行（分段）。
4. **编排器-工作器**: 中央代理分解任务，委托给工作器，并综合结果。这是子代理和代理团队的主导架构，也是大多数生产系统实际使用的架构。
5. **评估器-优化器**: 一个代理生成，另一个代理评估并在循环中提供反馈。当质量比速度更重要且单次传递不够可靠时，这非常有用。
# 何时不应使用多智能体系统
一些团队花费数月时间构建复杂的多智能体流水线，结果却发现，在单个智能体上进行更好的提示也能达到等效的结果。
从简单开始，只有当你能明确测出需要时才增加复杂性。
多智能体系统在以下三种情况下才值得其成本：
- **上下文保护**: 子任务生成了与主任务无关的信息。将其保留在子代理中可以防止上下文膨胀。
- **真正的并行化**: 独立的研究或搜索任务，可从同时覆盖中受益。
- **专业化**: 任务需要冲突的系统提示词，或者一个代理正在使用过多的工具导致其性能下降。
但在以下情况下，它们是错误的选择：
- 代理之间需要不断共享上下文
- 代理间的依赖关系产生的开销超过了执行价值
- 任务足够简单，一个提示良好的代理就能处理
针对编码的一个具体警告：并行编写代码的代理会做出不兼容的假设。当你合并它们的工作时，这些隐含的决策会以难以调试的方式发生冲突。编码用的子代理应该回答问题和探索，而不是与主代理同时编写代码。
# 是什么导致多智能体系统失败
三种失败模式反复出现。
1. **模糊的任务描述导致代理重复彼此的工作。**
每个代理都需要一个明确的目标、预期的输出格式、关于使用哪些工具或来源的指导，以及关于它不应涵盖什么的明确界限。没有这些，两个代理就会研究同一个东西，而谁也不会注意到。
2. **验证代理在不验证的情况下就宣布胜利。**
明确、具体的指示是不可协商的：运行完整的测试套件，覆盖这些特定情况，在每一个通过之前不要标记为完成。模糊的批准标准会产生误报。
3. **Token 成本的增长速度超出你的预期。**
解决方案是智能地对模型进行分层：
- 在真正重要的地方使用你最强大的模型
- 将日常工作路由到更快、更便宜的模型
- 建立预算控制，以免成本失控。
围绕上下文边界进行设计，而不是围绕角色或组织结构图。
从单个代理开始。 pushing it until you find where it breaks. 那个故障点会准确告诉你接下来应该添加什么。
只在复杂性解决了一个真实的、可衡量的问题的地方才增加复杂性。
这就收尾了！
如果你喜欢这个教程：
在这里找到我 → @_avichawla
每天，我都会分享关于 DS、ML、LLM 和 RAG 的教程和见解。
## 相关链接
- [Avi Chawla](https://x.com/_avichawla)
- [@_avichawla](https://x.com/_avichawla)
- [2.3K](https://x.com/_avichawla/status/2050463606719000627/analytics)
- [@_avichawla](https://x.com/@_avichawla)
- [Upgrade to Premium](https://x.com/i/premium_sign_up)
- [2:33 PM · May 2, 2026](https://x.com/_avichawla/status/2050463606719000627)
- [2,361 Views](https://x.com/_avichawla/status/2050463606719000627/analytics)
- [View quotes](https://x.com/_avichawla/status/2050463606719000627/quotes)
---
*导出时间: 2026/5/2 16:21:02*