知识点思维导图
34 个知识节点
Agent（13） - Multi-Agent 与 LangGraph：模式、状态、并行和故障边界
读完后，你应能完成以下任务：
- 绘制“Agent（13） - Multi-Agent 与 LangGraph：模式、状态、并行和故障边界 / 先证明单 Agent 不够”的关键对象与数据流，解释“多 Agent 会增加模型调用、状态同步、权限传递、调试和失败组合。”，并用源码位置、日志或 Trace 标注证据。
- 为“Agent（13） - Multi-Agent 与 LangGraph：模式、状态、并行和故障边界 / 四种常用模式”设计正常与异常输入，验证“还可以使用 Skills：仍是单 Agent，只按需加载专业提示和知识。”，输出首个偏差位置与回归测试结果。
- 实现“Agent（13） - Multi-Agent 与 LangGraph：模式、状态、并行和故障边界 / 状态必须是数据契约”的最小代码或配置，检验“大对象放外部存储，通过稳定 ID 引用。”，输出命令、结果与 Diff，并说明不适用边界。
更新日期：2026/08/11
核心知识清单
- Subagents、Router、Handoff 与 Supervisor
- Custom Workflow 与显式状态机
- fan-out、fan-in 与并发上限
- Conditional Edge、循环与停止条件
- Checkpointer、恢复与部分失败
- 工具权限隔离与副作用审批
- Multi-Agent Trace 与分层评测
一、先证明单 Agent 不够
多 Agent 会增加模型调用、状态同步、权限传递、调试和失败组合。复杂任务不自动等于多 Agent；单 Agent 配合动态工具和明确工作流往往更便宜。
只有出现以下边界时才拆：
- 单个 Agent 工具过多，持续选错工具。
- 不同领域需要大量专用上下文，全部塞入一个 Prompt 会互相干扰。
- 子任务可以独立并行，且结果能用稳定契约汇总。
- 不同团队需要独立维护能力和版本。
- 子任务需要不同权限，必须隔离工具和数据访问。
“产品经理 Agent + 架构师 Agent + 程序员 Agent”只是角色命名，不是边界证明。
二、四种常用模式
| 模式 | 控制权 | 适合 | 代价 |
|---|---|---|---|
| Subagents | 主 Agent 始终协调 | 多跳任务、上下文隔离、集中审批 | 子 Agent 结果要回主 Agent，多一次汇总调用 |
| Router | 路由器分发给一个或多个专家 | 分类明确、可并行的独立问题 | 路由错就全错，通常无连续多跳 |
| Handoffs | 当前 Agent 把控制权交给另一 Agent | 多轮客服、阶段切换、直接与用户交互 | 状态和权限交接复杂 |
| Custom Workflow | 图节点显式编排 | 有确定步骤、循环、回退、人工审批 | 开发维护成本最高，但最可控 |
还可以使用 Skills：仍是单 Agent，只按需加载专业提示和知识。当需求只是“减少上下文污染”时，Skills 往往比多 Agent 简单。
三、状态必须是数据契约
不要在共享 State 里无限追加完整消息、网页正文和模型思考过程。节点之间传结构化证据、来源、摘要和错误即可；大对象放外部存储，通过稳定 ID 引用。
四、用 LangGraph 表达循环与停止
示例省略了节点实现，重点是：循环、失败、上限和结束路径都由代码控制，不让模型用自然语言决定任意跳转。
五、并行不是无限 fan-out
Router 可把独立子问题并行分发，但需要同时限制：
- 最大子任务数和最大并发数。
- 每个子任务超时、重试和 Token 预算。
- 相同子任务的幂等键，避免重试产生重复副作用。
- 部分失败时是返回部分结果、降级单路，还是整体失败。
- 汇总前的结果 Schema 校验和引用去重。
并行 10 个 Agent 不会把一项串行任务加速 10 倍，反而可能触发模型限流、工具连接池耗尽和成本失控。
六、工具与权限隔离
每个 Agent 只拿完成任务所需的工具。读代码的 Agent 不应拥有部署权限；生成付款建议的 Agent 不应直接执行付款。Handoff 或 Subagent 调用时传递的是经过裁剪的上下文和授权声明，不是主 Agent 的全部凭证。
有副作用的工具统一经过审批层：
Agent 提议 → 参数 Schema 校验 → 权限检查 → 用户/规则审批 → 幂等执行 → 审计记录
模型输出永远只是“执行建议”，不能因为来自某个“专家 Agent”就跳过校验。
七、可观测与评测
每次运行至少记录：
- 路由决策、选择理由和候选 Agent。
- 每个节点输入摘要、输出 Schema、耗时、Token 和费用。
- 并行 fan-out 数量、超时、重试和取消。
- Agent 之间传递的上下文字段，不记录密钥和无关隐私。
- 最终任务成功率、路由准确率、工具成功率和人工接管率。
评测要与单 Agent 基线对比。若多 Agent 没有提高任务成功率或延迟，反而增加调用和故障点，就应退回更简单架构。
八、常见故障
- 死循环：缺少迭代上限、全局截止时间或终止状态。
- 状态爆炸：每个 Agent 都复制完整历史和所有证据。
- 路由漂移：路由 Prompt 更新后分发分布变化，却没有标注集回归。
- 部分失败悬挂：一个并行子任务超时，其他任务没有取消或汇总策略。
- 权限扩散：子 Agent 默认继承主 Agent 全部工具。
- 结论互相冲突：汇总器只拼接结果，没有比较证据来源和时效。
九、总结
- 先证明单 Agent 不够：多 Agent 会增加模型调用、状态同步、权限传递、调试和失败组合。
- 四种常用模式：| 模式 | 控制权 | 适合 | 代价 |
- 状态必须是数据契约：大对象放外部存储，通过稳定 ID 引用。
- 并行不是无限 fan-out：相同子任务的幂等键，避免重试产生重复副作用。
- 工具与权限隔离：Handoff 或 Subagent 调用时传递的是经过裁剪的上下文和授权声明，不是主 Agent 的全部凭证。
- 可观测与评测：路由决策、选择理由和候选 Agent。
十、动手实践：Multi-Agent、Checkpoint 与 HIL
这个实验把 Multi-Agent 最容易被忽略的工程边界放进同一条状态流：Supervisor 路由、专家最小权限、结果归并、写操作中断、Checkpoint、人工审批后恢复。
10.1 在线运行
零依赖，Python 3.10+ 可运行。它是 LangGraph 机制模拟，不依赖模型或外部工具；真实接入时可把状态换成 TypedDict，用 Checkpointer 保存线程，用 interrupt() 暂停，用 Command(resume=...) 恢复。
10.2 重点观察
- Supervisor 只负责路由，不继承专家的全部工具。
- 读取任务可以直接完成，删除长期记忆属于副作用，必须先暂停。
- Checkpoint 只保存受控状态，不保存密钥或模型思考过程。
- 恢复时使用同一
thread_id，审批结果进入审计事件。
10.3 可运行源码：Multi-Agent 与 LangGraph：模式、状态、并行和故障边界
main.py
学完自测
选择所有正确答案；提交后逐项核对判断依据。