LangGraph三部曲至此走向终点。前两篇深入了底层架构和生产部署，但真正的多Agent应用程序到底怎么写？四个Agent如何协作完成内容创作？为什么messages列表莫名其妙丢失数据？为什么中断恢复失败？本文聚焦五个维度：编排模式、实战构建、子图嵌套、6个Reddit踩坑的源码级修复、测试策略。
这是 LangGraph 系列最实用的一篇。如果你已经在用 LangGraph 构建多 Agent 系统，或者正打算开始，本文提供的 6 个踩坑修复可以直接应用于你的代码。每个踩坑都配有复现、原因分析和修复方案。我们还提供完整的"内容创作团队"构建代码，可以作为你项目的起点。
| 系列篇 | 标题 | 核心内容 |
|---|---|---|
| #1 | 内部架构 | Pregel、Channels、Checkpoint、设计决策 |
| #2 | 生产部署 | FastAPI+SSE、多租户、Human-in-Loop |
| #3 (本文) | 实战指南 | 编排模式、踩坑修复、测试策略 |
四种成熟编排模式：Agent Supervisor（中央调度，适合明确分工的团队）、Network（点对点，适合自由通信）、Hierarchical（分层嵌套，适合大型团队）、Custom / Send（动态路由，适合 Map-Reduce）。LangGraph 本身没有"多Agent"概念——多Agent编排是在状态图上叠加的组织模式。
理解四种模式的选择依据：Supervisor 模式适用于 3-6 个职责明确的 Agent（如一个主管分配任务给多个专家）。Network 模式适用于需要自由讨论的场景（如辩论、头脑风暴），但 O(n²) 的消息复杂度限制了 Agent 数量。Hierarchical 模式通过子图嵌套支持大型团队（10+ Agent）。Send 模式最灵活，可以在运行时动态决定向哪个 Agent 发送什么数据，特别适合并行处理任务。
选择模式时考虑以下因素：Agent 数量（<5 用 Supervisor，5-10 用 Network/Hierarchical，>10 用 Hierarchical+Send）、通信模式（集中调度 vs 自由交流 vs 分层传递）、故障隔离需求（子图嵌套提供天然故障边界）。
构建"内容创作团队"：Research → Write → Review → Publish 四个Agent通过状态共享协作。关键设计：messages: Annotated[list, add_messages] 使用reducer合并而非覆盖；迭代计数器作为dead loop保护；Send 对象实现动态并行分发（Map-Reduce）。Pregel引擎的 recursion_limit=25 是最后兜底。
内容创作团队的工作流程：Research Agent 根据主题收集资料，将结果写入状态中的 research_notes 字段。Write Agent 读取 research_notes 撰写初稿，写入 draft 字段。Review Agent 审查 draft，如果发现问题则返回给 Write Agent 修改（通过条件边实现），如果通过则传递给 Publish Agent 格式化输出。这个循环通过 iteration 计数器确保最多重写 3 次。
Send 对象用于实现并行研究。当需要同时调研多个主题时，Research Agent 可以通过 Send("research_agent", {"topic": sub_topic}) 动态创建多个并行子任务。这些任务由 Pregel 引擎并行调度执行，结果通过 add_messages reducer 聚合到主消息列表。这种 Map-Reduce 模式显著提升了多主题调研的效率。
当Agent团队规模增长到10+，扁平化状态图变得不可维护。将一个完整的 StateGraph 编译后作为另一个图的子图节点，通过 channel_map 实现通道映射。子图继承父图checkpointer，中断恢复时子图内部状态自动恢复。嵌套 vs 展平决策：Agent < 5 展平，> 10 或存在子团队时嵌套。
子图的核心优势是状态隔离。子图内部的状态对外部不可见（除非通过 channel_map 显式映射），这意味着子图的内部变更不会意外影响到父图或其他子图。每个子图还可以有自己的 checkpointer 配置——例如，一个子图使用 Postgres 持久化，另一个使用内存存储。
子图嵌套的代价是性能开销。每次子图执行都需要 PregelLoop 的上下文切换和状态合并。对于简单的"获取数据 → 处理 → 返回"子图，每次调用约增加 5-10ms 的延迟。建议只在 Agent 数量超过 10 或存在明确子团队时才使用嵌套。对于小团队（<5 Agent），展平图更高效且易于调试。
坑1：路由器死循环 — 路由函数从未返回 END。加 iteration 计数器保护。
坑2：Reducer冲突导致状态覆盖 — 多节点写同一键无reducer。用 Annotated[list, add_messages] 或 operator.add。
坑3：中断恢复后状态丢失 — 未配置 checkpointer 或 durability 非 sync。设置 durability="sync"。
坑4：Agent间消息污染 — 所有Agent共享同一messages列表。使用命名空间前缀或独立通道。
坑5：中断恢复卡住 — as_node 必须匹配中断节点名。
坑6：大状态流式慢 — 使用 DeltaChannel 替代全量序列化。
坑1 的详细修复：路由器死循环是最常见的 LangGraph 问题。当条件边路由函数返回了已执行过的节点名而非 END 时，图会进入无限循环。修复方案是在状态中添加 iteration: int 字段，每次经过路由节点时 +1，在路由函数中检查 iteration >= max_iterations 时返回 END。
坑2 的详细修复：Reducer 冲突的根源是 LangGraph 默认使用 LastValue 通道——后写入的值会覆盖先写入的值。如果两个节点都写入 messages 字段且没有 reducer，前一个节点的输出会被后一个覆盖。修复方案是在状态 schema 中使用 Annotated[list, add_messages] 注解，这会将写入操作从"覆盖"改为"追加"。
单元测试：每个节点是纯函数，输入状态 → 输出更新。集成测试：用 InMemorySaver 和 test fixtures 隔离外部依赖。调试模式：langgraph.debug = True 或 stream_mode="debug"。利用 get_state() 查看中间状态、update_state() 注入调试数据。LangSmith CI 集成自动记录每次测试的运行轨迹，便于回归分析。
单元测试 LangGraph 节点非常简单：每个节点是一个纯函数，接收状态 dict 返回状态 dict。你只需要构造输入状态，调用节点函数，然后验证输出状态。不需要运行 Pregel 引擎。集成测试则需要编译图并使用 InMemorySaver 作为 checkpointer，验证完整的图执行流程。
调试模式是排查复杂问题的最强工具。启用 langgraph.debug = True 后，PregelLoop 会在每次 tick 时打印详细的执行信息——包括哪些节点被调度、每个节点的输入输出、通道版本变化。结合 breakpoint() 在节点函数中设置断点，你可以单步跟踪图的执行过程。
关键原则回顾：状态隔离优先 — 私有状态用独立通道，共享状态用reducer合并。始终设置迭代保护 — 路由逻辑中加入 iteration 计数器。checkpointer + durability="sync" — 中断恢复正确性的基石。DeltaChannel 大状态 — 状态超过1000条消息时切换。子图是有成本的 — 约10个Agent以上才值得嵌套。测试节点 = 测试纯函数。
决策树总结：1-3 个 Agent → Agent Supervisor 模式；4-10 个 Agent → 如果有子团队则用 Hierarchical（子图嵌套），否则用 Network（点对点）；需要动态并行分发 → Send/Custom 模式。性能排序：Send > Supervisor > Hierarchical > Network。
LangGraph 的核心理念可以概括为三句话：一切皆状态（StateGraph 管理所有共享数据）、一切皆节点（函数、Agent、工具都是图节点）、一切皆可恢复（检查点系统确保任意中断点都可以恢复执行）。掌握这三个理念，你就掌握了 LangGraph 的精髓。