《Harness Engineering --- AI Agent 工程方法论》完整目录
- 前言
- 第1章 Agent 不等于大模型：Harness 的价值
- 第2章 Agent 架构模式全景
- 第3章 Agent Loop：心跳与决策循环
- 第4章 上下文工程：比 Prompt Engineering 更重要的事
- 第5章 Tool Design：给 Agent 造趁手的兵器
- 第6章 工具编排与并发执行
- 第7章 工具结果处理与错误恢复
- 第8章 System Prompt 分层设计
- 第9章 指令优先级与冲突消解
- 第10章 Few-shot、CoT 与动态提示策略
- 第11章 短期记忆：上下文窗口管理
- 第12章 长期记忆：持久化与检索
- 第13章 多轮对话与会话状态机
- 第14章 Agent 权限模型设计
- 第15章 沙箱、隔离与防御性编程
- 第16章 多 Agent 协调模式（当前）
- 第17章 Human-in-the-Loop：人机协作设计
- 第18章 评估与测试方法论
- 第19章 可观测性与调试
- 第20章 成本控制与性能优化
- 第21章 设计模式与架构决策
第16章 多 Agent 协调模式
"The strength of the team is each individual member. The strength of each member is the team." --- Phil Jackson
:::tip 本章要点
- 多 Agent 的核心价值：专业化分工 + 上下文隔离
- 四种协调模式：Coordinator、Pipeline、Swarm、Debate
- 上下文隔离是关键------每个子 Agent 有独立的上下文窗口
- 成本控制：多 Agent 意味着多倍 API 调用，必须有预算机制 :::
16.1 为什么需要多 Agent
单 Agent 面临两个根本限制：
- 上下文窗口有限------一个复杂任务可能需要读几十个文件、执行几十步操作，单一上下文装不下
- 专业化困难------用一个 system prompt 让模型既擅长写代码、又擅长写测试、又擅长做 code review，效果不如专门的 Agent 各司其职
多 Agent 的解法：把大问题拆成子问题，每个子 Agent 专注解决一个子问题，各自拥有独立的上下文窗口。
16.2 Coordinator 模式
一个"管理者"Agent 负责理解需求、拆分任务、分派给专业 Agent、汇总结果。
scss
┌──── 研究 Agent (探索代码库)
│
主 Agent ─┼──── 实现 Agent (编写代码)
│
└──── 测试 Agent (运行测试)Claude Code 的 Agent 工具就是这个模式：
typescript
// 主 Agent 决定启动子 Agent
const result = await spawnAgent({
description: "探索认证模块结构",
prompt: "在项目中搜索所有与认证相关的文件，分析架构...",
subagent_type: "Explore", // 专业化的探索 Agent
})
// 子 Agent 完成后，结果返回给主 Agent
// 主 Agent 基于结果决定下一步关键设计决策
任务描述的质量决定子 Agent 的输出质量。主 Agent 需要给子 Agent 清晰、完整的任务描述------就像一个好的经理给下属的任务指派：
arduino
❌ "帮我查一下代码"
✅ "在 /src 目录下搜索所有使用了 AuthContext 的文件，
列出每个文件中 AuthContext 的用法（读取/修改/创建），
特别关注是否有直接操作 session token 的地方"结果传递方式 ：子 Agent 的输出返回给主 Agent 的上下文。如果子 Agent 输出过长，会挤占主 Agent 的上下文空间。因此子 Agent 应该返回结论而非原始数据。
16.3 Pipeline 模式
Agent 按顺序串联，每个处理一个阶段：
需求分析 Agent → 方案设计 Agent → 代码实现 Agent → Review Agent → 测试 Agent
python
# LangGraph 实现 Pipeline
from langgraph.graph import StateGraph
graph = StateGraph(PipelineState)
graph.add_node("analyst", analyst_agent)
graph.add_node("architect", architect_agent)
graph.add_node("developer", developer_agent)
graph.add_node("reviewer", reviewer_agent)
graph.add_edge("analyst", "architect")
graph.add_edge("architect", "developer")
graph.add_edge("developer", "reviewer")
# reviewer 可以打回给 developer 修改
graph.add_conditional_edges("reviewer", route_review)Pipeline 的优势是流程清晰、职责明确 。劣势是延迟累加------每个阶段都是一次完整的 LLM 交互。
16.4 Swarm 模式
没有固定的管理者，Agent 之间根据当前需要动态切换控制权：
arduino
用户 → 路由 Agent → "这是个前端问题" → 前端 Agent
↓
"需要改 API" → 后端 Agent
↓
"需要更新文档" → 文档 AgentOpenAI Swarm 的核心概念是 handoff------当前 Agent 发现任务超出自己专长时，主动将控制权交给更合适的 Agent：
python
def frontend_agent(context):
# 处理前端问题...
if needs_api_change:
return handoff(backend_agent, context="需要修改 /api/users 端点")
def backend_agent(context):
# 处理后端问题...
if needs_docs:
return handoff(docs_agent, context="API 变更需要更新文档")Swarm 的优势是灵活性高 ，适合需求不明确的探索性任务。劣势是控制流不可预测------你不知道任务会被传递几次、最终由谁完成。
16.5 上下文隔离
多 Agent 最大的工程价值之一是上下文隔离。
单 Agent 处理复杂任务时，上下文窗口会被各种中间结果填满------读的文件、搜索的结果、执行的命令输出。到后期，模型可能因为上下文过于拥挤而"迷失"。
多 Agent 方案中，每个子 Agent 启动时拥有干净的上下文：
typescript
// 主 Agent 上下文: 用户需求 + 高层计划 (干净)
// ↓ 启动子 Agent
// 子 Agent 上下文: 任务描述 + 该任务需要的文件 (干净)
// ↓ 子 Agent 完成，返回精简结果
// 主 Agent 上下文: 用户需求 + 高层计划 + 子 Agent 结论 (仍然干净)关键原则：子 Agent 的中间过程（读了哪些文件、搜了几次）不应污染主 Agent 的上下文。只有最终结论传递回来。
16.6 通信协议
Agent 之间如何传递信息？
共享状态（LangGraph）
所有 Agent 读写同一个 State 对象：
python
class SharedState(TypedDict):
messages: list # 所有 Agent 共享
research_results: str # 研究 Agent 写入
implementation_plan: str # 架构 Agent 写入
code_changes: list # 实现 Agent 写入
review_feedback: str # Review Agent 写入优点：简单直接。缺点：Agent 可能读到不相关的其他 Agent 输出。
消息传递（Claude Code）
主 Agent 通过 prompt 给子 Agent 传递任务，子 Agent 通过返回值传递结果。没有共享状态------纯消息传递。
typescript
// 主 Agent 发送
const result = await agent({
prompt: `任务: ${task}\n\n参考信息: ${context}`,
})
// 子 Agent 返回
return `研究结果: ${findings}\n\n建议: ${recommendations}`优点：隔离性强。缺点：传递大量数据时效率低（需要序列化为文本）。
通信模式对比
| 维度 | 共享状态（LangGraph） | 消息传递（Claude Code） |
|---|---|---|
| 耦合度 | 高（所有 Agent 读写同一 State） | 低（纯输入→输出） |
| 隔离性 | 弱（Agent 可能读到无关数据） | 强（每个 Agent 只看到自己的上下文） |
| 数据传递效率 | 高（内存共享） | 低（序列化为文本） |
| 调试难度 | 中（State 是可检查的） | 低（每个 Agent 独立可重放） |
| 适用场景 | 紧密协作的工作流 | 松散的任务分发 |
关键洞察：子 Agent 的中间过程不应污染主 Agent 的上下文。研究 Agent 读了 20 个文件，但主 Agent 只收到精简的结论------这就是上下文隔离的价值。
16.7 成本控制
多 Agent 的 API 调用量是单 Agent 的数倍。必须有成本控制机制：
typescript
class CostController {
private totalTokens = 0
private readonly budget: number
constructor(budgetTokens: number) {
this.budget = budgetTokens
}
canSpawn(): boolean {
return this.totalTokens < this.budget * 0.8 // 留 20% 余量
}
recordUsage(tokens: number): void {
this.totalTokens += tokens
if (this.totalTokens > this.budget) {
throw new BudgetExceededError(
`Token budget exhausted: ${this.totalTokens}/${this.budget}`
)
}
}
}实践建议：
- 设置每次任务的 token 上限
- 子 Agent 的数量设上限（如最多 5 个并发）
- 对深层递归设限制（Agent 不应无限嵌套启动子 Agent）
- 监控并报告每个子 Agent 的消耗
16.8 错误传播
子 Agent 失败时，主 Agent 需要优雅处理：
typescript
async function coordinateTask(task: Task): Promise<Result> {
try {
const research = await spawnAgent("research", task.description)
if (!research.success) {
// 策略 1: 换一个方法重试
const altResearch = await spawnAgent("research",
`${task.description}\n\n注意: 之前的尝试失败了: ${research.error}`)
if (!altResearch.success) {
// 策略 2: 降级处理
return { partial: true, message: "研究阶段部分完成" }
}
}
// 继续后续步骤...
} catch (error) {
// 策略 3: 通知用户
return { failed: true, message: "需要人工介入", error }
}
}原则：子 Agent 的失败不应导致整个任务崩溃。主 Agent 应该有降级策略。
16.9 何时使用多 Agent
多 Agent 不是银弹。使用条件：
| 适合多 Agent | 单 Agent 即可 |
|---|---|
| 任务涉及多个领域（前端+后端+数据库） | 任务在单一领域内 |
| 需要处理大量文件/信息 | 只涉及几个文件 |
| 可以清晰分解为独立子任务 | 任务步骤紧密耦合 |
| 对延迟不敏感 | 需要快速响应 |
| 预算充足 | 成本敏感 |
如果单 Agent 能搞定，就不要用多 Agent。多 Agent 引入的复杂度（通信、协调、错误处理）是有成本的。
16.10 本章小结
多 Agent 协调的核心要点：
- Coordinator 模式适合有明确主从关系的任务
- Pipeline 模式适合流程化、阶段性的工作
- Swarm 模式适合探索性、跨领域的任务
- 上下文隔离 是多 Agent 的核心工程价值
- 成本控制 必须前置设计------token 预算、并发限制、递归深度限制
- 错误处理 要有降级策略------子 Agent 失败不应崩溃全局
- 不要过度设计------单 Agent 够用就不要上多 Agent
下一章将探讨人机协作模式------Agent 不是要取代人类，而是要和人类高效配合。