LangGraph 设计与实现

深入 LangGraph 的源码与架构。

你按文档写完一个图，它跑起来了。然后问题开始出现：两个并行节点同时写同一个字段，最后留下的是哪一个？在人工审批处中断，几小时后恢复，状态从哪里捞回来？子图里的节点和父图重名会怎样？为什么明明加了循环，跑着跑着却抛出了 GraphRecursionError？

这些答案都不在文档里，在 Channel、Pregel 超步和 Checkpoint 三维寻址里。本专栏以 LangGraph 1.1.6 源码为解剖对象，把这三样东西拆开。

flowchart TB
  SG[StateGraph<br/>add_node · add_edge · 条件边] -->|compile| CG[CompiledStateGraph]
  CG --> P
  subgraph P [Pregel 执行引擎 · 一个超步]
    direction LR
    T1[tick 计划<br/>prepare_next_tasks] --> T2[执行任务]
    T2 --> T3[after_tick<br/>apply_writes · Reducer 合并 · 版本追踪]
  end
  P <--> CH[Channels<br/>状态的真正住处]
  P --> CK[Checkpoint<br/>三维寻址 · 时间旅行]
  CK --> HIL[interrupt<br/>人机协作 / 恢复]
  P -.动态并行.-> SEND[Send]
  P -.命名空间隔离.-> SUB[子图]

为什么要理解 Pregel。 LangGraph 的执行模型不是"依次调用节点"，而是借自 Google Pregel 的超步（superstep）模型：一个超步里所有任务并行跑，跑完统一 apply_writes。上面那些让人困惑的行为——并发写谁赢、循环为什么会停、恢复时从哪继续——全都是这个模型的直接推论。不理解它，你只能靠试。

读完你能做到什么

1. 预测并发写的结果。 Channel 是什么、Reducer 怎么合并、apply_writes 的更新算法与版本追踪机制（第4章 Channel、第6章 Pregel 引擎）。
2. 看懂一次 graph.invoke() 的完整旅程。 四层架构、Channel 的读写路径、PregelLoop 这个状态机的每一步，以及「没有活跃触发 Channel」与 recursion_limit 两个停止条件的区别（第2章 架构总览、第6章 Pregel 引擎）。
3. 把状态可靠地存下来、再捞回去。 Checkpoint 的数据结构与三维寻址、序列化体系、几种持久化模式，以及生产环境里真正要注意的地方（第8章 Checkpoint）。
4. 做出能中断、能恢复、能改主意的人机协作流程。 interrupt() 到底做了什么、interrupt_before/after 的差别、用 Command 恢复并改写状态（第9章 中断、第10章 Command）。
5. 组织大图。 子图嵌套与命名空间隔离、用 Send 做动态扇出（数量在运行时才知道的并行）（第11章 子图、第12章 Send）。
6. 调试与观测。 几种流式模式各自吐什么、Runtime 与 Store 提供了哪些可挂载点（第13章 流式输出、第14章 Runtime、第15章 Store）。

这个专栏的讲法

从 API 讲到算法。 add_node 有五重重载、compile() 到底把 StateGraph 变成了什么、prepare_next_tasks 的任务准备算法长什么样 —— 一路从你每天写的那几行，追到引擎内部真正执行的那几行。

各章带「设计决策分析」，不少章节还列出常见陷阱与误解。 图构建那章直接列出常见陷阱与最佳实践，Checkpoint 那章写明生产里的注意事项。这些是文档不会写、而你迟早会踩的部分。

最后落回工程。 预构建组件怎么用、多 Agent 编排有哪些成型模式（第16章 预构建、第17章 多 Agent 模式、第18章 设计模式）。

适合谁读

• 已经在用 LangGraph、但遇到"行为不符合直觉"的开发者。 这个专栏就是为解释那些行为写的。
• 从 LangChain 进阶到复杂工作流的工程师。 链是线性的，图是有状态的，两者的心智模型不同。
• 多 Agent 系统的架构师。 子图、Send、Checkpoint 是搭多 Agent 的三块地基。

不适合：只想照着教程搭一个 demo 的读者 —— 官方文档更快。这里讲的是它内部为什么这样运作。

目录

第一部分：开篇

• 前言
• 第1章 为什么需要理解 LangGraph

第二部分：图定义与状态

• 第2章 架构总览
• 第3章 StateGraph 图构建 API
• 第4章 Channel 状态管理与 Reducer

第三部分：执行引擎

• 第5章 图编译：从 StateGraph 到 CompiledStateGraph
• 第6章 Pregel 执行引擎
• 第7章 任务调度与并行执行

第四部分：持久化与控制流

• 第8章 Checkpoint 持久化
• 第9章 中断与人机协作
• 第10章 Command 与高级控制流

第五部分：高级特性

• 第11章 子图与嵌套
• 第12章 Send 与动态并行
• 第13章 流式输出与调试

第六部分：运行时与集成

• 第14章 Runtime 与 Context
• 第15章 Store 与长期记忆
• 第16章 预构建 Agent 组件

第七部分：总结

• 第17章 多 Agent 模式实战
• 第18章 设计模式与架构决策

源码版本

本专栏基于 LangGraph 1.1.6 和 langgraph-checkpoint 4.0.1 源码分析：

三个包在同一个 monorepo 里，c3ba590 就是 1.1.6 这个 tag 指向的提交——注意 langgraph-prebuilt 有自己独立的版本号（第 16 章讲的 ToolNode / create_react_agent / ToolRuntime 都住在这里）。

git clone https://github.com/langchain-ai/langgraph.git
cd langgraph && git checkout 1.1.6

核心代码在 libs/langgraph/langgraph/、libs/checkpoint/langgraph/checkpoint/ 和 libs/prebuilt/langgraph/prebuilt/ 目录下。

版权声明

本专栏内容为 杨艺韬 版权所有，保留一切权利。未经书面许可，不得全文或大段转载、改编、翻译，或用于任何商业用途（含以本专栏内容训练模型、生成衍生课程或商品）。

欢迎分享本专栏的链接。引用少量内容用于评论、教学或研究时，请署名 杨艺韬 并附上原文链接。