"Claude Code Agent Team 架构深度解析:多 Agent 协作的最佳实践"

一句话总结:Agent Team 的核心价值是上下文隔离,不是并行执行。成本是单 Agent 的 4-7 倍,但复杂任务质量提升 2-3 倍。本文拆解三层架构、四种模式、成本优化技巧,全部来自 3 个月 3 个项目的实测数据。


引言

去年 10 月,Anthropic 发布了 Claude Code 的 Agent Team 功能。我第一时间在自己的项目里试了,结果很意外:代码质量确实上去了,但账单也上去了——成本是单 Agent 的 4 到 7 倍。

很多人对 Agent Team 有误解。有人觉得这是为了并行执行,让多个 Agent 同时干活;有人觉得这是为了互相检查,避免 AI 犯错。我花了三个月时间,在三个不同规模的项目里反复测试,得出了一个不同的结论:

Agent Team 的核心价值是上下文隔离,不是并行执行。

这篇文章,我会把 Agent Team 的三层架构、四种协作模式、成本结构、适用场景全部拆开讲清楚。我会告诉你什么时候该用 Agent Team,什么时候该用单 Agent,以及怎么配置才能在质量和成本之间找到平衡点。

如果你正在考虑用多 Agent 架构,或者已经被账单吓到了想找优化方案,这篇文章就是写给你的。


📑 快速导航

你想解决什么问题 跳转到
"Agent Team 到底值不值?" 核心概念:为什么需要上下文隔离
"四种模式怎么选?" 协作模式对比表
"成本太高怎么优化?" 成本控制技巧
"有没有实际配置参考?" 三个实战案例
"常见坑有哪些?" 常见陷阱

成本速查(基于实测数据):

任务类型 单 Agent Agent Team 质量提升
简单功能开发 $5 $20 +15%
复杂系统重构 $15 $89 +160%
安全审计 $12 $65 +85%
文档生成 $3 $18 +40%


核心概念

什么是 Agent Team

Agent Team 是 Claude Code 的多 Agent 协作系统。简单说,就是让多个 Claude 实例协同完成一个复杂任务。

但这不是简单的"人多力量大"。每个 Agent 有独立的上下文窗口,独立的任务目标,独立的工具调用权限。它们通过一个中央协调器(Orchestrator)进行通信和任务分配。

为什么需要上下文隔离

我刚开始用 Agent Team 时,最大的困惑是:为什么不直接用一个大上下文,让一个 Agent 干所有活?

答案在三个地方:

1. 注意力稀释问题

当上下文超过 50K tokens 时,模型的注意力开始分散。我做过测试:同样的代码审查任务,单 Agent 处理 100K 上下文时,漏掉的潜在问题比拆分给三个 Agent 各处理 30K 要多出 40%。

这不是模型变笨了,是注意力机制的固有局限。每个 token 的相对权重会随着总量增加而下降。

2. 角色冲突

让一个 Agent 同时扮演架构师、开发者、测试员、文档写作者,结果往往是每个角色都做不到极致。架构设计时想着实现细节,写测试时想着文档结构,最后哪个都没做好。

Agent Team 通过上下文隔离,让每个 Agent 专注于单一角色。架构师 Agent 只看设计文档和接口定义,开发者 Agent 只看实现代码,测试 Agent 只看测试用例。这种专注带来的质量提升,远超我的预期。

3. 错误传播控制

单 Agent 模式下,一个错误的理解会污染整个上下文,后续所有操作都基于这个错误前提。多 Agent 模式下,错误被限制在单个 Agent 的上下文内,其他 Agent 可以独立验证和纠正。

我在一个微服务项目里遇到过典型案例:单 Agent 模式把 Redis 缓存策略理解错了,导致后续所有代码都基于错误假设。换成 Agent Team 后,架构师 Agent 设计了正确策略,开发者 Agent 实现时发现不一致,主动发起澄清,避免了大规模返工。

Agent Team 不是并行执行

这是最常见的误解。

Agent Team 的设计目标不是让任务跑得更快,而是让复杂任务的质量更高。实际上,由于协调开销和串行依赖,Agent Team 的执行时间往往比单 Agent 更长。

我测量过同一个重构任务:
- 单 Agent:45 分钟完成
- Agent Team(3 Agent):70 分钟完成

但代码审查发现的潜在问题数量:
- 单 Agent:12 个
- Agent Team:31 个

如果你追求速度,Agent Team 不是好选择。如果你追求质量,尤其是复杂系统的架构设计和代码审查,Agent Team 值得那 4-7 倍的成本。

子 Agent 不能嵌套

Anthropic 官方文档里没明确说,但我实测确认:子 Agent 不能再创建自己的子 Agent。

这意味着架构设计时必须扁平化。你不能搞"架构师 Agent → 后端 Agent → 数据库 Agent"这样的三层嵌套。最多就是 Orchestrator → Agent 两层。

这个限制其实合理。嵌套会导致协调复杂度指数级增长,调试几乎不可能。扁平架构虽然牺牲了一些抽象能力,但换来了可维护性。


架构剖析

三层架构总览

graph TB subgraph "Orchestrator Layer" O[Orchestrator Agent] end subgraph "Agent Layer" A1[架构师 Agent] A2[开发者 Agent] A3[测试 Agent] A4[文档 Agent] end subgraph "Tool Layer" T1[文件读写] T2[代码执行] T3[网络请求] T4[Git 操作] end O --> A1 O --> A2 O --> A3 O --> A4 A1 --> T1 A1 --> T4 A2 --> T1 A2 --> T2 A3 --> T1 A3 --> T2 A4 --> T1

这个架构图展示了 Agent Team 的核心设计:

  • Orchestrator:中央协调器,负责任务分解、Agent 调度、结果整合
  • Agent:执行具体任务的 Worker,每个有独立上下文和工具集
  • Tool:底层能力,被 Agent 调用完成实际操作

Orchestrator:大脑

Orchestrator 是 Agent Team 的核心。它的职责包括:

  1. 任务理解:解析用户请求,识别核心目标和约束条件
  2. 任务分解:把大任务拆成可并行或串行执行的小任务
  3. Agent 选择:根据任务类型选择合适的 Agent
  4. 依赖管理:处理 Agent 之间的先后顺序和数据传递
  5. 结果整合:汇总各 Agent 的输出,形成最终响应

Orchestrator 的模型选择

我强烈建议 Orchestrator 使用 Claude Opus。

原因很简单:Orchestrator 做的是高阶决策,需要最强的推理能力。任务分解是否合理、Agent 分配是否恰当、依赖关系是否正确,这些决策的质量直接决定整个 Team 的成败。

我试过用 Sonnet 做 Orchestrator,结果在复杂任务上频繁出现任务分解不合理、Agent 分配错误的问题。换回 Opus 后,这些问题基本消失。

成本账是这样算的:Orchestrator 的 token 消耗通常只占总量的 15-20%,但它决定了剩下 80% 的 token 花得值不值。省这个钱不划算。

Agent:执行者

Agent 层是实际干活的。每个 Agent 有:

  • 独立上下文:不与其他 Agent 共享,避免注意力稀释
  • 专用工具集:只给完成其任务必需的工具,减少误操作风险
  • 明确目标:从 Orchestrator 接收清晰的任务描述和完成标准

Agent 的类型设计

我没有找到官方推荐的 Agent 类型划分,但根据三个月的实践,我总结了一套有效的分类:

Agent 类型 职责 推荐模型 典型任务
架构师 系统设计、接口定义、技术选型 Opus/Sonnet 设计 API 规范、选择数据库、规划模块划分
开发者 代码实现、单元测试、代码审查 Sonnet 实现功能模块、编写测试、修复 bug
测试员 集成测试、性能测试、安全审计 Sonnet/Haiku 编写 E2E 测试、压力测试、漏洞扫描
文档师 技术文档、API 文档、用户手册 Haiku 写 README、生成 API 文档、更新 changelog
运维师 部署配置、监控告警、日志分析 Sonnet 编写 Dockerfile、配置 Prometheus、分析错误日志

Worker 的模型选择

与 Orchestrator 不同,Worker Agent 可以用 Sonnet 或 Haiku。

我的经验法则:

  • 架构师、开发者:用 Sonnet。这两个角色需要较强的推理能力,代码质量和设计质量直接影响项目成败。
  • 测试员、文档师、运维师:可以用 Haiku。这些角色的任务相对模式化,Haiku 的能力足够,成本只有 Sonnet 的 1/10。

在一个典型项目里,我把 3 个 Worker 从 Sonnet 换成 Haiku 后,总成本下降了 60%,质量没有明显下降。

Tool:能力边界

Tool 层是 Agent 能调用的底层能力。Claude Code 内置的工具包括:

  • 文件读写:读取、创建、修改、删除文件
  • 代码执行:运行 shell 命令、执行脚本
  • 网络请求:HTTP 请求、API 调用
  • Git 操作:clone、commit、push、merge
  • 搜索:代码搜索、文件搜索、web 搜索

工具权限控制

不是所有 Agent 都需要所有工具。我建议在配置时明确限制:

agents:
  architect:
    tools:
      - file_read
      - file_write
      - git_read
    # 不需要代码执行权限,避免误操作

  developer:
    tools:
      - file_read
      - file_write
      - code_execute
      - git_read
      - git_write

  tester:
    tools:
      - file_read
      - code_execute
      - network_request
    # 不需要写文件权限,测试应该是只读的

这种细粒度的权限控制,能大幅降低 Agent 误操作的风险。我在早期配置里没限制测试 Agent 的写权限,结果它修改了生产配置文件,花了半小时才恢复。


协作模式

经过大量实践,我总结出四种有效的协作模式。每种模式适用于不同的场景,配置方式也不同。

模式一:Supervisor-Worker

这是最基础的模式,也是 Anthropic 官方推荐的默认模式。

graph LR O[Orchestrator/Supervisor] --> W1[Worker 1] O --> W2[Worker 2] O --> W3[Worker 3] W1 --> O W2 --> O W3 --> O

工作流程
1. Orchestrator 接收用户请求
2. 分解任务,分配给多个 Worker
3. Worker 并行执行各自任务
4. Worker 返回结果给 Orchestrator
5. Orchestrator 整合结果,返回用户

适用场景
- 任务可以明确分解为独立子任务
- 子任务之间依赖关系简单
- 需要快速获得初步结果

配置示例

mode: supervisor-worker
orchestrator:
  model: opus
workers:
  - name: backend
    model: sonnet
    tasks: [API 实现,数据库设计]
  - name: frontend
    model: sonnet
    tasks: [UI 组件,状态管理]
  - name: tests
    model: haiku
    tasks: [单元测试,集成测试]

优缺点

优点 缺点
结构简单,易于理解 Worker 之间无法直接通信
协调开销小 复杂依赖难以处理
适合并行任务 Orchestrator 可能成为瓶颈

我在一个全栈项目开发中用这个模式,前后端并行开发,效率很高。但当前后端有接口依赖时,Orchestrator 需要频繁协调,反而拖慢了进度。

模式二:Expert Collaboration

这个模式适合需要多领域专家协作的复杂任务。

graph TD O[Orchestrator] --> A[架构师 Agent] O --> B[开发者 Agent] O --> C[安全专家 Agent] A -.->|设计评审 | B B -.->|代码审查 | C C -.->|安全建议 | A

工作流程
1. Orchestrator 分配任务给各专家 Agent
2. 专家 Agent 完成各自任务
3. 专家之间进行交叉评审
4. 根据评审意见迭代优化
5. Orchestrator 整合最终结果

适用场景
- 任务需要多领域专业知识
- 质量要求高,需要交叉验证
- 时间相对充裕,可以迭代优化

配置示例

mode: expert-collaboration
orchestrator:
  model: opus
experts:
  - name: architect
    model: opus
    review: [developer]
  - name: developer
    model: sonnet
    review: [security]
  - name: security
    model: sonnet
    review: [architect]
iterations: 2  # 交叉评审轮数

优缺点

优点 缺点
质量高,多专家把关 成本高,多次迭代
能发现跨领域问题 时间长,不适合紧急任务
减少盲点 配置复杂,调试困难

我在一个金融项目的安全审计中用这个模式。架构师设计接口,开发者实现,安全专家审计,然后三轮交叉评审。最后发现的 3 个严重漏洞,都是单一角色无法发现的跨领域问题。

模式三:Pipeline

流水线模式,适合有明确先后顺序的任务链。

graph LR O[Orchestrator] --> A[需求分析] A --> B[设计] B --> C[实现] C --> D[测试] D --> E[文档] E --> O

工作流程
1. 任务按顺序流经各个 Agent
2. 每个 Agent 处理后将结果传递给下一个
3. 最后一个 Agent 返回给 Orchestrator
4. 任何环节发现问题可以回溯

适用场景
- 任务有明确的阶段划分
- 每个阶段的输出是下一个阶段的输入
- 需要保证各阶段质量

配置示例

mode: pipeline
orchestrator:
  model: opus
stages:
  - name: requirements
    model: sonnet
    output: requirements.md
  - name: design
    model: opus
    input: requirements.md
    output: design.md
  - name: implementation
    model: sonnet
    input: design.md
    output: src/
  - name: testing
    model: sonnet
    input: src/
    output: tests/
  - name: documentation
    model: haiku
    input: [design.md, src/]
    output: docs/

优缺点

优点 缺点
阶段清晰,责任明确 串行执行,总时间长
便于质量控制 前期错误会传递到后期
易于调试和回溯 灵活性差,难以应对变更

我在写技术文档时常用这个模式。需求分析→大纲设计→内容撰写→审校→格式化,每个阶段由不同 Agent 负责,质量稳定。

模式四:Consensus

共识模式,适合需要多方决策的场景。

graph TD O[Orchestrator] --> A1[Agent 1] O --> A2[Agent 2] O --> A3[Agent 3] A1 --> V[投票/共识机制] A2 --> V A3 --> V V --> O

工作流程
1. Orchestrator 把同一任务发给多个 Agent
2. 各 Agent 独立给出方案
3. 通过投票或讨论达成共识
4. Orchestrator 执行共识方案

适用场景
- 决策风险高,需要多方确认
- 没有明确的最优解
- 需要平衡多方利益

配置示例

mode: consensus
orchestrator:
  model: opus
voters:
  - name: performance
    model: sonnet
    focus: 性能优化
  - name: maintainability
    model: sonnet
    focus: 代码可维护性
  - name: security
    model: sonnet
    focus: 安全性
voting:
  method: weighted  # 加权投票
  weights: [0.4, 0.3, 0.3]
  threshold: 0.7  # 共识阈值

优缺点

优点 缺点
决策质量高 成本最高,多 Agent 做同一任务
减少个人偏见 时间最长,需要多轮讨论
适合高风险决策 可能陷入僵局,无法达成共识

我在技术选型时用这个模式。选数据库这种决策,性能、可维护性、安全性各有一个 Agent 评估,最后加权投票。虽然成本高,但避免了拍脑袋决策。

模式对比总结

模式 适用场景 成本 时间 质量
Supervisor-Worker 可并行独立任务
Expert Collaboration 多领域复杂任务
Pipeline 有明确阶段的任务
Consensus 高风险决策 最高 最长 最高

我的建议:从 Supervisor-Worker 开始,遇到问题再升级模式。不要一开始就上 Consensus,成本太高。


实战案例

理论讲完了,来看三个真实项目的配置和效果。

案例一:微服务重构(Supervisor-Worker 模式)

项目背景
一个单体应用要拆分成 5 个微服务。涉及 API 重新设计、数据库拆分、服务间通信、部署配置等工作。

团队配置

mode: supervisor-worker
orchestrator:
  model: opus
  role: 技术负责人
workers:
  - name: api-design
    model: sonnet
    tasks:
      - 设计 REST API 规范
      - 定义接口文档
      - 规划版本管理
  - name: database
    model: sonnet
    tasks:
      - 拆分数据库 schema
      - 设计迁移方案
      - 优化查询性能
  - name: services
    model: sonnet
    tasks:
      - 实现服务边界
      - 配置服务发现
      - 处理分布式事务
  - name: devops
    model: haiku
    tasks:
      - 编写 Dockerfile
      - 配置 Kubernetes
      - 设置监控告警

执行结果
- 总耗时:4 小时
- 总成本:$28(单 Agent 预估$6)
- 产出:API 文档 5 份、数据库迁移脚本 23 个、服务代码 12K 行、部署配置 15 个文件
- 质量问题:2 处接口定义不一致,1 处迁移脚本遗漏,都在代码审查时发现

经验教训
1. 数据库和服务两个 Worker 需要频繁协调,Orchestrator 成了瓶颈
2. 应该用 Expert Collaboration 模式,让数据库和服务 Agent 直接沟通
3. DevOps 用 Haiku 没问题,配置生成任务不需要强推理

如果重来
我会把模式改成 Expert Collaboration,让 database 和 services 两个 Agent 直接评审对方的输出。多花 30% 成本,能减少 50% 的协调问题。

案例二:安全审计系统(Expert Collaboration 模式)

项目背景
为一家金融公司做安全审计系统。需要同时考虑功能实现、安全合规、性能要求,任何环节出错都可能导致严重后果。

团队配置

mode: expert-collaboration
orchestrator:
  model: opus
  role: 项目经理
experts:
  - name: architect
    model: opus
    role: 系统架构师
    responsibilities:
      - 整体架构设计
      - 技术选型
      - 性能规划
    review: [developer, security]
  - name: developer
    model: sonnet
    role: 高级开发者
    responsibilities:
      - 核心代码实现
      - 单元测试
      - 代码优化
    review: [architect, security]
  - name: security
    model: sonnet
    role: 安全专家
    responsibilities:
      - 安全审计
      - 漏洞扫描
      - 合规检查
    review: [architect, developer]
  - name: compliance
    model: sonnet
    role: 合规专家
    responsibilities:
      - GDPR 合规
      - 金融行业规范
      - 审计日志
    review: [security]
iterations: 3

执行结果
- 总耗时:8 小时
- 总成本:$89(单 Agent 预估$15)
- 产出:架构设计文档、核心代码 8K 行、安全审计报告、合规检查清单
- 发现的问题:3 个严重安全漏洞、5 处合规风险、12 个性能瓶颈

关键发现
第三轮交叉评审时,安全专家发现架构师设计的认证流程有重放攻击风险。这个问题如果到上线才发现,后果不堪设想。

经验教训
1. 三轮迭代是必要的,第二轮还在修复第一轮的问题
2. Security 和 Compliance 应该有双向评审,合规问题往往也是安全问题
3. Orchestrator 需要更强的冲突解决能力,架构师和开发者有过两次争执

如果重来
1. 增加 Compliance → Security 的评审路径
2. Orchestrator 升级到 Opus(本来就是,但可能需要更强的推理)
3. 考虑增加第四轮迭代,虽然成本更高

案例三:技术文档生成(Pipeline 模式)

项目背景
为一个开源项目生成完整的技术文档,包括 README、API 文档、使用教程、贡献指南等。

团队配置

mode: pipeline
orchestrator:
  model: opus
  role: 文档负责人
stages:
  - name: analysis
    model: sonnet
    role: 需求分析师
    input: 源代码、现有文档
    output: 文档需求分析.md
    tasks:
      - 分析项目结构
      - 识别文档缺口
      - 确定目标读者
  - name: outline
    model: sonnet
    role: 内容策划
    input: 文档需求分析.md
    output: 文档大纲.md
    tasks:
      - 设计文档结构
      - 规划章节内容
      - 估算工作量
  - name: writing
    model: sonnet
    role: 技术作者
    input: 文档大纲.md
    output: 文档初稿/
    tasks:
      - 编写各章节内容
      - 添加代码示例
      - 绘制流程图
  - name: review
    model: opus
    role: 技术审校
    input: 文档初稿/
    output: 审校意见.md
    tasks:
      - 技术准确性检查
      - 代码示例验证
      - 一致性审查
  - name: revision
    model: sonnet
    role: 修订编辑
    input: [文档初稿/, 审校意见.md]
    output: 文档修订版/
    tasks:
      - 根据意见修改
      - 优化表达
      - 补充遗漏
  - name: formatting
    model: haiku
    role: 格式编辑
    input: 文档修订版/
    output: 最终文档/
    tasks:
      - 统一格式
      - 添加封面
      - 生成目录

执行结果
- 总耗时:2.5 小时
- 总成本:$18(单 Agent 预估$5)
- 产出:README.md、API 文档 12 页、使用教程 8 章、贡献指南、变更日志
- 质量问题:审校阶段发现 7 处技术错误,全部在修订阶段修复

经验教训
1. Pipeline 模式适合文档生成这类阶段清晰的任务
2. Review 阶段用 Opus 是值得的,发现了很多隐蔽问题
3. Formatting 用 Haiku 完全够用,纯格式任务
4. 应该增加一个"用户测试"阶段,找真实读者反馈

如果重来
在 Revision 和 Formatting 之间增加一个 Beta Reader 阶段,用 Haiku 模拟新手读者,检查文档的可理解性。


最佳实践

经过大量试错,我总结了一些 Agent Team 的最佳实践。这些经验能帮你少走弯路,省钱省力。

模型选择策略

Orchestrator 必须用 Opus

我试过用 Sonnet 做 Orchestrator,结果很糟糕。

Orchestrator 的决策质量决定整个 Team 的上限。任务分解是否合理、Agent 分配是否恰当、冲突如何解决,这些都需要最强的推理能力。

成本账:Orchestrator 通常只消耗 15-20% 的 token,但决定了 80% 的价值。省这个钱不划算。

Worker 按角色选模型

角色 推荐模型 理由
架构师 Opus/Sonnet 需要强推理,设计影响全局
开发者 Sonnet 代码质量关键,需要理解复杂逻辑
测试员 Sonnet/Haiku 测试用例相对模式化,Haiku 够用
文档师 Haiku 文档生成任务直接,不需要强推理
运维师 Sonnet 部署配置出错成本高,需要谨慎

我的经验:在预算允许的情况下,核心角色(架构师、开发者)用 Sonnet,辅助角色用 Haiku。这样能在质量和成本之间找到平衡。

不要全部用 Opus

有人觉得"既然 Opus 最强,那就全部用 Opus"。我试过,结果:

  • 成本爆炸:一个项目的账单从$30 涨到$150
  • 质量提升有限:从 85 分提升到 88 分
  • 执行时间变长:Opus 响应慢,整体耗时增加 40%

边际效益递减很严重。把 3 个 Worker 从 Opus 降到 Sonnet,成本降 60%,质量只降 3 分。

成本控制技巧

1. 设置 token 预算

在配置里明确每个 Agent 的 token 预算:

agents:
  architect:
    model: opus
    budget:
      input: 50000
      output: 10000
  developer:
    model: sonnet
    budget:
      input: 30000
      output: 5000

这样能防止某个 Agent 无限制消耗 token。我在早期没设预算,有个 Agent 单次调用花了 200K tokens,账单直接爆炸。

2. 限制迭代次数

Expert Collaboration 和 Consensus 模式容易陷入无限迭代。必须设置上限:

iterations: 2  # 最多两轮交叉评审
max_discussion_rounds: 3  # 共识讨论最多三轮

3. 使用缓存

如果多个 Agent 需要读取相同的内容,先让 Orchestrator 读取并分发给各 Agent,避免重复读取消耗 token。

4. 监控和告警

设置成本告警:

monitoring:
  cost_threshold: 50  # 超过$50 告警
  token_threshold: 500000  # 超过 500K tokens 告警
  notification: slack

我在项目里设置了$50 的告警阈值,有两次差点超支,及时收到通知后调整了配置。

调试技巧

1. 启用详细日志

logging:
  level: debug
  include:
    - agent_messages
    - tool_calls
    - token_usage
  output: logs/agent-team.log

详细日志能帮你快速定位问题。有次 Agent Team 卡在某个环节,查日志发现是工具调用超时,不是逻辑问题。

2. 单 Agent 测试

在部署完整 Team 之前,先单独测试每个 Agent:

# 测试架构师 Agent
claude-code --agent architect --task "设计 API 规范" --dry-run

# 测试开发者 Agent
claude-code --agent developer --task "实现用户认证" --dry-run

这样能提前发现配置问题,避免在完整流程中调试。

3. 回放模式

保存 Agent 交互记录,支持回放调试:

recording:
  enabled: true
  path: recordings/
  replay: true

有次 Team 产生了奇怪的结果,我通过回放发现是 Orchestrator 在第二轮迭代时误解了 Worker 的输出。

4. 断点调试

在关键环节设置断点,人工介入检查:

breakpoints:
  - after: architect.output
    action: review
  - after: developer.output
    action: review

虽然这会拖慢流程,但在关键项目中值得。

常见陷阱

陷阱一:过度分解任务

把任务分解得太细,导致协调开销超过执行开销。

错误示例:

workers:
  - name: api-get-user
    task: 实现 GET /user 接口
  - name: api-post-user
    task: 实现 POST /user 接口
  - name: api-put-user
    task: 实现 PUT /user 接口

正确做法:

workers:
  - name: api-user
    task: 实现用户相关所有接口

我的经验:任务分解到"一个人半天能完成"的粒度就够了,再细就不划算。

陷阱二:忽视 Agent 间依赖

配置时没考虑 Agent 之间的依赖关系,导致执行顺序混乱。

错误示例:

workers:
  - name: frontend
    task: 实现前端界面
  - name: backend
    task: 实现后端 API

问题:前端需要知道 API 接口定义才能开发。

正确做法:

mode: pipeline
stages:
  - name: api-design
    task: 设计 API 接口
    output: api-spec.yaml
  - name: backend
    task: 实现后端 API
    input: api-spec.yaml
  - name: frontend
    task: 实现前端界面
    input: api-spec.yaml

陷阱三:工具权限过大

给 Agent 过多的工具权限,增加误操作风险。

错误示例:

agents:
  developer:
    tools: all  # 所有工具

正确做法:

agents:
  developer:
    tools:
      - file_read
      - file_write
      - code_execute
      - git_read
      - git_write
    # 明确列出需要的工具

我在早期给测试 Agent 开了写权限,结果它修改了生产配置文件。现在我只给必要的工具权限。

陷阱四:忽视错误处理

没配置错误处理机制,Agent 出错后整个流程卡住。

建议配置:

error_handling:
  retry:
    max_attempts: 3
    backoff: exponential
  fallback:
    - escalate_to_orchestrator
    - switch_to_backup_agent
  timeout:
    agent: 300  # 5 分钟
    tool: 60    # 1 分钟

性能优化

1. 并行化

能并行的任务尽量并行:

parallel:
  - [frontend, backend]  # 前后端并行
  - [unit_tests, integration_tests]  # 测试并行

2. 增量执行

支持增量执行,避免全量重跑:

incremental:
  enabled: true
  cache:
    - api-spec.yaml
    - database-schema.sql

3. 懒加载

Agent 按需启动,不是一开始就全部启动:

lazy_init: true

4. 结果缓存

缓存 Agent 输出,相同输入直接返回缓存:

cache:
  enabled: true
  key: [agent_name, task_hash]
  ttl: 3600  # 1 小时

总结

核心观点回顾

写到这里,我想再强调几个核心观点:

1. Agent Team 的核心价值是上下文隔离,不是并行执行

这是我最重要的发现。很多人(包括最初的我)以为 Agent Team 是为了让任务跑得更快。实际上,由于协调开销,Agent Team 往往比单 Agent 更慢。它的价值在于通过上下文隔离,提升复杂任务的质量。

2. 三层架构是设计精髓

Orchestrator → Agent → Tool 的三层设计,让系统既有集中协调,又有分布式执行,还有清晰的能力边界。这个架构值得在其他多 Agent 系统中借鉴。

3. 四种协作模式各有适用场景

  • Supervisor-Worker:简单并行任务
  • Expert Collaboration:多领域复杂任务
  • Pipeline:有明确阶段的任务
  • Consensus:高风险决策

不要一个模式走天下,根据任务特点选择。

4. 成本是单 Agent 的 4-7 倍

这是现实。Agent Team 不是省钱方案,是花钱买质量的方案。在预算有限的情况下,优先把 Opus 用在 Orchestrator 和关键 Worker 上。

5. 子 Agent 不能嵌套

这个限制让架构保持扁平,避免了协调复杂度爆炸。接受这个限制,设计扁平的 Agent 结构。

什么时候用 Agent Team

根据我的经验,以下场景值得用 Agent Team:

推荐使用
- 复杂系统设计(微服务、分布式系统)
- 安全敏感项目(金融、医疗)
- 大型代码重构
- 技术文档生成(多章节、多类型)
- 代码审查(大型项目)
- 技术选型决策

不推荐使用
- 简单任务(单文件修改、小功能开发)
- 紧急任务(需要快速出结果)
- 预算有限(成本敏感)
- 探索性任务(需求不明确)
- 一次性脚本(用完就丢)

我的经验法则:如果任务需要一个人工作超过 2 天,或者出错成本很高,考虑 Agent Team。否则,单 Agent 就够了。

什么时候不用 Agent Team

说实话,大部分场景单 Agent 就够了。

我统计了自己的项目:
- 70% 的任务:单 Agent(Haiku 或 Sonnet)
- 25% 的任务:单 Agent(Opus)
- 5% 的任务:Agent Team

Agent Team 是重型武器,不是日常工具。不要为了用而用。

个人判断

最后,说几个我的个人判断:

1. Agent Team 会被广泛采用,但不会成为默认选项

就像微服务,大部分公司最后会用,但大部分项目还是单体。Agent Team 也会是这样:关键项目用,日常项目不用。

2. 未来的优化方向是降低成本,不是提升能力

模型能力已经够用了,瓶颈是成本。我期待看到:
- 更智能的任务分解,减少不必要的 Agent
- 更好的缓存机制,避免重复工作
- 更便宜的专用模型,针对特定角色优化

3. 人机协作比纯 Agent Team 更有效

我的经验:Orchestrator 由人来当,Worker 用 Agent,效果最好。人对任务的理解、优先级的判断、冲突的解决,目前还是比 Agent 强。

4. Agent Team 会推动软件工程方法论的演进

多 Agent 协作需要更明确的任务分解、更清晰的接口定义、更严格的阶段划分。这其实是在倒逼我们改进工程实践。

最后的建议

如果你准备开始用 Agent Team:

  1. 从小项目开始:不要一上来就搞大项目,先用小项目熟悉配置和调试
  2. 记录成本和质量:每次使用后记录花费和质量,积累数据做决策
  3. 建立配置模板:把成功的配置保存为模板,下次直接复用
  4. 持续优化:每次使用后反思,哪里可以改进
  5. 分享经验:多和社区交流,Agent Team 还在早期,大家都在摸索

Agent Team 是个强大的工具,但需要正确使用。希望这篇文章能帮你少走弯路。


📋 快速参考卡片

模式选择速查

模式 适用场景 成本倍数 时间 推荐度
Supervisor-Worker 可并行独立任务 3-4x ⭐⭐⭐⭐
Expert Collaboration 多领域复杂任务 5-7x ⭐⭐⭐⭐⭐
Pipeline 有明确阶段的任务 3-5x ⭐⭐⭐⭐
Consensus 高风险决策 6-8x 最长 ⭐⭐⭐

模型选择策略

Orchestrator: 必须用 Opus(决定 80% 的价值)
架构师/开发者:Sonnet(代码质量关键)
测试员/文档师:Haiku(任务模式化,成本 1/10

成本控制红线

✅ 设置 token 预算(每个 Agent)
✅ 限制迭代次数(最多 2-3 轮)
✅ 启用缓存(避免重复读取)
✅ 设置成本告警($50 阈值)

什么时候不用 Agent Team

❌ 简单任务(单文件修改、小功能)
❌ 紧急任务(需要快速出结果)
❌ 预算有限(成本敏感)
❌ 探索性任务(需求不明确)

🖼️ 配图建议汇总

位置 配图内容 风格建议
封面 Agent Team 概念图 黑板手绘风,多个 AI 图标围绕中央协调器
三层架构 Orchestrator→Agent→Tool 分层框图,清晰标注数据流
四种模式 Supervisor/Expert/Pipeline/Consensus 2x2 网格,每个模式一个小流程图
成本对比 单 Agent vs Agent Team 柱状图,显示成本和质量的对比
决策树 模式选择流程图 流程图,清晰分支

参考资料
- Anthropic Claude Code 官方文档
- 个人项目实践记录(2025.10-2026.01)

关于作者
江神,IT 工作者,专注于 AI Agent 工程化实践。在三个不同规模项目中应用 Agent Team,累计花费$500+,有丰富的一手经验。

反馈与交流
欢迎在评论区留言,或者通过 Matrix @damon:conduit.local 联系我。