构建 Claude 多代理团队

10 步教你用 Claude Managed Agents 构建多代理协作团队，实现并行处理、专业分工和成本优化。

原文来自 Codez（@0xcodez） 的 X 帖子。

一句话总结

单个代理处理复杂任务会变慢变笨，多代理团队通过并行化和专业分工解决这个问题。

你给一个代理加了太多能力：研究、写报告、数据分析、代码审查。每加一个功能，系统提示就更长，工具列表更大，上下文窗口更拥挤。最终代理变慢、变混乱，在原本擅长的事情上也开始出错。

这不是模型的问题，是架构问题。

三个核心概念

为什么需要多代理？

多代理设计解决三类问题：

1. 并行化：工作可以拆成独立子任务（比如分别检查日志、metrics、工单），单代理只能串行处理，团队可以同时处理
2. 专业化：不同问题需要不同专长（安全审查、文档写作、定价建模），一个全能代理切换上下文会降低所有任务的质量
3. 升级：大部分工作简单，但某些子任务异常复杂，团队可以只在需要时路由到更强的模型

架构基础

Claude Managed Agents 的三个关键事实：

• ✅ 最多 20 个唯一代理在一个团队中
• ✅ 每个代理有独立的上下文窗口
• ✅ 所有代理共享一个文件系统

隔离思考，共享工作空间 —— 这就是团队能并行协作而不混乱的原因。

成本优化

关键技巧：每个代理可以运行不同的模型。

Netflix 和 Spiral 的生产级模式：用 Haiku 做协调器（便宜快速），用 Opus 做写作专家（强力但贵）。协调器只是路由和排序，快速便宜的模型就够了。昂贵的重型工作只在需要的专业代理中执行。

为每个角色匹配合适的模型，这是成本和速度的最大杠杆。

10 步构建团队

第 1 步：确认你真的需要团队

别因为听起来酷就用多代理。它会增加 token 消耗和协调开销。只有当以下三种情况之一成立时才用：

• ✅ 工作可以拆成独立子任务
• ✅ 不同问题需要不同专长
• ✅ 需要把复杂任务路由到更强的模型

第 2 步：在写代码前先规划角色

多代理设计是组织设计。在写任何代码之前，在纸上画出团队结构：

• 1 个协调器（coordinator）
• 多个专家（specialists），每个有清晰的单一职责

参考 Anthropic 的事件响应案例：

• 协调器运行调查
• 4 个子代理并行处理：部署历史、错误日志、指标、工单

命名每个角色，给它一句话的工作描述，指定模型和工具。如果两个角色重叠，合并它们。更少、更清晰的专家胜过更多模糊的专家。

第 3 步：为每个角色选择模型

大多数人忽略的技巧：团队中的每个代理可以运行不同的模型。

Spiral by Every 的生产模式：

• Haiku 做协调器（快速便宜）
• Opus 做写作专家（强力但贵）

协调器只负责路由和排序，快速便宜的模型就够了。昂贵的重型工作只在需要的专业代理中执行。

为每个角色匹配合适的模型，这是成本和速度的最大杠杆。

第 4 步：设置 Managed Agents

所有多代理请求都运行在 Claude Managed Agents 上，需要 beta header：managed-agents-2026-04-01（SDK 自动设置）。

为什么用 Managed Agents 而不是自己搭建？因为当团队需要：

• 远程运行
• 扩展到多个用户
• 共享文件系统
• 持久化状态

你就会面临基础设施问题 —— 会话、内存、安全、沙箱。Managed Agents 处理了所有这些，你只需要设计团队。

安装 Anthropic SDK，设置 API Key，就能开始。

第 5 步：创建专家代理

自底向上构建。每个专家是独立的代理，有自己的模型、提示词和工具集。创建它们并保留 agent ID，协调器会引用它们。

关键原则：严格限制每个专家的工具范围。

例子（销售提案团队）：

• 研究员 → 只有网页搜索
• 文档管理员 → 只有文件读取
• 定价建模师 → 只看到规则文件和席位数

每个代理只接触它工作需要的东西，不多也不少 —— 这保持它的专注，整个系统也更可审计。

第 6 步：创建协调器并声明团队

现在创建领导代理。通过设置 multiagent 字段标记为协调器，列出它可以委派的子代理 ID。

配置示例：

name: Engineering Lead
model: claude-opus-4-7
system: >
  You coordinate engineering work. Delegate code review
  to the reviewer agent and test writing to the test agent.
tools:
  - type: agent_toolset_20260401
multiagent:
  type: coordinator
  agents:
    - type: agent
      id: $REVIEWER_AGENT_ID
    - type: agent
      id: $TEST_WRITER_AGENT_ID

agent_toolset_20260401 工具赋予协调器委派能力。团队最多支持 20 个条目。

你还可以：

• 固定特定代理版本
• 引用最新版本
• 使用 {"type": "self"} 让协调器生成自己的副本进行递归并行化

第 7 步：编写协调器提示词（管理者而非执行者）

这是团队成败的关键。协调器的系统提示不应该尝试做具体工作，而应该描述如何委派工作。

好的协调器提示说明：

• 这里是你的专家团队
• 每个专家是做什么的
• 如何决定谁得到什么任务
• 如何组合他们的输出

它负责排序和综合，而不是领域细节 —— 那些属于专家。

事件响应团队的协调器提示示例

You are the incident-response coordinator. You do NOT
investigate anything yourself. Your only job is to delegate
to your specialists and synthesize what they return.

Your specialists:
- deploy_agent  → reviews recent deploy history for changes
- logs_agent    → searches error logs for anomalies
- metrics_agent → checks dashboards for abnormal patterns
- tickets_agent → scans support tickets for user reports

How to work:
1. When an incident arrives, delegate to ALL FOUR
   specialists in parallel — do not wait for one before
   starting the next.
2. Give each specialist only the incident description and
   the time window. Nothing else.
3. When results return, look for correlation across them
   (e.g. a deploy that lines up with a log spike and ticket
   surge points to a root cause).
4. If one specialist's finding is unclear, send it a
   follow-up — it remembers its previous turn.

Output format:
- ROOT CAUSE: one sentence, or "unconfirmed"
- EVIDENCE: one bullet per specialist that contributed
- RECOMMENDED ACTION: one clear next step

Never include raw logs or full ticket text in your final
answer — synthesize, do not dump.

每一行都关于委派、关联和输出形状。实际的日志搜索和指标读取在专家那里。

第 8 步：理解团队通信机制

当你运行协调器时，机制是具体的：

• 每个协调器委派的子代理都会生成自己的会话线程（context-isolated event stream）
• 协调器在主线程中报告
• 新线程在运行时委派时出现
• 关键：线程是持久的 —— 协调器可以发送后续请求给之前调用的代理，该代理保留之前所有轮次的信息

重要约束：协调器只能委派一层深度。超过 1 层的深度会被忽略。专家不能运行自己的子团队。这是故意的 —— 保持系统可预测和可追踪。

第 9 步：在 Claude Console 中观察

生产级多代理系统和实验系统的区别是可观测性。

每次运行都会在 Claude Console 中产生完整的追踪：

• 哪个代理做了什么
• 什么顺序
• 为什么

你可以看到每个委派决策，检查每个子代理的推理，端到端地跟踪序列。

当结果错误时，追踪告诉你哪个专家失败了，问题是委派还是专家本身。不要盲目运行团队 —— 读追踪。

第 10 步：扩展到 20 个代理并添加共享记忆

小团队工作后，扩展它：

• 添加专家直到 20 个代理的上限
• 让协调器并行扇出到所有专家

然后用共享记忆闭环：当多个子代理在相同领域工作时，Dreaming 功能可以聚合他们集体学到的东西，并发布共享洞察到团队级的内存存储 —— 这是单个代理会话无法产生的。

团队不仅并行工作，而且作为一个整体随时间变得更聪明。

Netflix 的平台团队在生产中运行这个：

• 多代理编排处理数百个同时构建的日志
• 并行子代理在数千个应用程序中发现重复问题
• 这在单代理设置中是完全无法串行完成的

常见错误

❌ 单代理够用时建团队

多代理成本更高，协调更慢。如果工作不能并行化、专业化或升级，你只是增加了复杂性。

❌ 协调器自己做工作

如果领导代理有领域指令而不是委派逻辑，你建的是一个穿着团队服装的臃肿单代理。

❌ 工具范围太松

当每个专家都能接触一切，专注就崩溃了，追踪变得不可读。严格限制每个代理只接触它的工作范围。

❌ 对抗深度-1 限制

协调器只能委派一层深度。设计隐藏的子协调器层次浪费时间 —— 深度会被忽略。

❌ 盲目运行

Console 追踪存在是为了让你看到哪个代理做了什么。跳过它，你就无法调试有移动部件的系统。

实战建议

大多数人会继续往一个代理里塞更多能力，看着它变慢变笨，然后得出"代理还没准备好"的结论。

而那些构建团队的人会得到：

• ✅ 一个负责委派的协调器
• ✅ 多个专业代理并行工作，各自有独立上下文
• ✅ 一个共享文件系统让他们协作
• ✅ 一个内存存储让整个团队随时间变得更聪明

从一个小任务开始：选一个能拆成并行部分的任务，规划 3 个专家和 1 个协调器，先建这个小团队。这会改变你的代理能处理的工作量。

相关资源

• Claude Managed Agents 官方文档
• Anthropic Cookbook - Multi-agent Examples
• Claude Agent SDK