langchain-ai/langgraph: 显式状态机与可恢复运行时¶
LangGraph 解决的不是“组件如何组合”，而是状态如何跨轮次流转并实现断点续跑。当 Agent 任务涉及多步循环、外部副作用或人工干预（Human-in-the-loop）时，简单的 Chain 结构会因无法保存中间状态而崩溃。
1. 核心架构模型：Pregel 循环¶
LangGraph 的底层受到 Google Pregel 图计算模型的启发，其核心是一套带状态的节点调度系统。
- State Schema (状态契约)：显式定义系统持有的“共同现实”。它不仅包含消息历史，还包含业务指标、控制标记（Flags）与中间计算结果。
- Nodes & Edges (执行节点与边)：节点负责局部逻辑（读取 State -> 产生 Update），边负责路由决策（决定下一跳）。
- Channels & Reducers (状态合并)：解决并行节点更新冲突。Reducer 负责定义“当多个节点同时修改同一个状态字段时，该如何合并”。
2. 治理心智：Checkpoint 与中断¶
这是 LangGraph 区别于传统 AI 框架的护城河：
- Checkpoint (检查点)：在节点执行间隙，自动将全量 State 持久化。工程直觉：任务中途崩溃不再需要从头推理，而是从最近的 Checkpoint 直接 Resume。
- Interrupt (显式中断)：在执行敏感动作（如“向外部转账”）前，强制中断执行流并进入等待状态，直到人工确认后再携带状态重入循环。
- Time Travel (状态回溯)：允许开发者查看甚至修改历史状态，这在 Agent 调试与纠偏中具有极高的诊断价值。
3. 与 LangChain 的边界¶
- LangChain：擅长单向、确定性的“链式编排”。一旦进入“循环”或“复杂条件分支”，Chain 的状态管理就会变得极其脏乱。
- LangGraph：擅长处理非线性、循环、带状态的任务。它将执行流程显式化为图，让状态转移变得可观测、可审计。
4. 常见误区与失效模式¶
- 状态黑盒化：将所有信息塞进一个
messages数组，而不是拆解成结构化 State。这会导致模型在长任务中因 Token 稀释而丢失关键控制信息。 - 节点粒度失控：节点设计过大，内部包含了复杂的子循环，导致 Checkpoint 无法覆盖到真实的细粒度故障点。
- 副作用重复执行：在非幂等操作（如写库）之后未及时落盘 Checkpoint，导致 Resume 时重复执行副作用。
5. 排查顺序：从状态到路由¶
- 核对 State 更新：节点返回的 Update 是否正确合并进了全局 State？Reducer 是否导致了数据覆盖？
- 查 Checkpoint 记录：持久化层是否写入成功？恢复时加载的是否为预期的版本？
- 分析边逻辑 (Edges)：路由判断是否因为状态字段缺失而打向了错误的节点（或陷入死循环）？
- 监测人工干预：Interrupt 是否触发？外部输入的 Resume 信号是否正确携带了补全的状态？
结论： LangGraph 是 Agent 的“操作系统”级运行时。它强迫开发者承认：Agent 任务是长周期的状态机，必须通过显式的 Checkpoint 与治理插槽来对冲生成式模型的不确定性。