LangGraph · v1.0

LangGraph：把 Agent 建成一张可存档的状态图

这份教程把 LangGraph 看成一件事：把 agent 建模成状态图——节点是步骤、边是控制流、一个共享 state 在节点间流动；它每步自动 checkpoint，于是持久化、人在环、故障恢复都成了同一机制的副产品。基于 LangGraph v1.0（2025-10 发布），写于 2026-06。读完约 2 小时。下文所有代码用来演示判断与机制，均未在本机执行（标 2026-06）。

·适合谁

  • 能读写 Python，看得懂 TypedDict 与 Annotated[...] 类型注解，调过至少一个 LLM SDK 或 LangChain。
  • 用 LangChain 串过链、或用裸 while 循环手写过 agent，但说不清何时这条链就不够用、必须换一种结构。
  • 正在做 agent 框架选型或代码评审，需要判断一段需求该停在 LCEL 链、还是必须上 LangGraph 状态图。

·不适合谁

  • 还没调用过任何 LLM API：先去 OpenAI 文本生成指南 或 Anthropic 快速开始 跑通一次裸调用，再回来。
  • 只想抄一段能跑的 agent 脚手架、不关心它为什么这么建：官方 quickstart 更快。
  • 需求确定就是「单 agent + 几个 tool、无状态、无人工介入」：一段裸 while 循环就够，上状态图是负收益；03 章 §3.3 给判据。

·读完之后你能做到什么

看到一个 agent 需求，你能判断它该停在 LCEL 链、还是必须上 LangGraph 状态图——并说清上图白拿了什么（持久化 / HITL / 恢复）、又付出了什么（状态与样板复杂度）。

更具体地，读完后你能：

  • 画出 StateGraph 的三要素——节点、边、共享 state，并说出 state 的并发更新靠 reducer 合并。
  • 讲清 checkpoint 为何让持久化、时间旅行、人在环、故障恢复变成同一机制的副产品，而不是四个独立功能。
  • 判断一段需求该停在 LCEL 链，还是必须上图——并说出分界两侧各自的代价。
  • 落地同一个 agent：既能用高层入口 create_agent 起步，也能在需要更多控制时下沉到手搭 StateGraph。

一句话本质

LangGraph 把 Agent 建模成一张状态图：节点是步骤、边是控制流、一个共享 state 在节点间流动；它每步自动 checkpoint——于是持久化、时间旅行、人在环、故障恢复都成了同一机制的免费副产品。

·现状速览（截至 2026-06）

LangGraph 是一个仍在快速演进的框架，分清哪些是定论、哪些还在动，比记住任何单个 API 都重要。下表把当前状态切成三层。

表 0.1 · LangGraph 现状三层（截至 2026-06，基于 v1.0）
层内容为什么这样判定
稳定（可放心建心智模型） StateGraph = 节点 + 边 + state；state 用 reducer 合并并发更新；checkpointer 每步存档的持久化模型。这是几年没动的地基。 核心抽象自 LangGraph 早期就定型；v1.0 把它定为正式 API。
在变（盯紧版本） v1.0 已发布；durable execution 提供 sync / async 两种 durability 模式；2025-10 起 LangChain 的 agent 直接跑在 LangGraph 执行引擎上、create_agent 是高层入口，要更多控制就下沉 StateGraph。详见 03 章 §3.1。 v1.0 发布于 2025-10；agent 底层换成 LangGraph runtime 是这一代最大结构变化。
已过时（别当默认） 把 LangGraph 当成「与 LangChain 二选一的另一个框架」——它其实是 LangChain agent 的执行底座，二者互补而非对立。 2025-10 起 LangChain agent 跑在 LangGraph 执行引擎上，「二选一」的旧框架已不成立。

来源：LangChain & LangGraph v1.0 发布博客（2025-10）、官方 durable execution 文档。

流畅感警告

这一页读起来会很顺，正因为顺，三种假象最容易出现：

「我读得很顺」——顺只证明句子通顺，不证明你能在陌生代码上判断该不该上图。

「我做题很快」——题做得快，常常是答案就在上一段，换个场景就卡住。

「我没卡壳」——没卡壳意味着没触到边界；真正的理解发生在被迫做判别、而不是被讲解抚平的时刻。

下面这道题用来戳破假象：两个节点并发往 state 的同一个字段写值，谁的写入生效、还是两个都生效？先在心里答，再展开。

展开答案（先答再展开）

取决于那个字段声明的 reducer。没声明 reducer 时，后写覆盖前写（甚至抛冲突错误）；声明了如 add 这类 reducer 时，两个写入被合并（例如追加进同一个列表）。并发更新的结果不是「图」决定的，而是「每个字段的 reducer」决定的——这正是 01 章 §1.2 要锚定的概念。

·概念地图

StateGraph 节点·边·state Node 一个步骤 Edge 普通 / 条件 分支与回边 State + reducer 共享并合并 checkpointer 每步存档 持久化 / HITL time-travel / 恢复 compile → 可执行 注册 连接 流经 编译 挂上后每步存档
图 0.1读这张图盯三件事： 一，StateGraph 居中——节点、边、state 都先挂到这一个图上，它是组装点。 二，左侧 State + reducer 才是「并发更新如何合并」的真正决定者，不是图本身。 三，右下 checkpointer 一框里列着四件事，正是要记住它们是同一存档机制的派生物，而非四个独立功能。

·学习路径建议

这是一份概念向教程（不含动手章），按目的挑路径：

  • 理解状态图模型：先读 01 概念 的 StateGraph / State+reducer / Node / Edge，再到 02 原理 看「为什么用图」与「state+reducer 机制」。这条线把模型立起来。
  • 做选型（LCEL vs 图 vs 框架）：先看本页「现状速览」三层表，再直接跳 03 对比选型——§3.1 vs LCEL、§3.2 vs 多智能体框架、§3.3 选型决策，对照你的场景走判据。
  • 落地带 checkpoint 的 agent：从 01 概念的 compile 与 checkpointer 入手，再到 02 原理的「checkpoint 持久化机制」「durable execution」「中断与人在环」，把存档与恢复这条线打通。

·目录

·学完之后

  • 多智能体协作（supervisor / handoff / 子图）——在你的心智模型上，把单张状态图扩展成多张图互相调度，state 在图之间如何汇聚成为新问题。
  • 部署与可观测（LangGraph Platform、LangSmith trace）——给「跑起来的图」加一层部署与观测，让每一步节点的输入输出与 checkpoint 可见，把抽象的图变成可运维的服务。
  • 评估（评测集、回归测试）——在心智模型上加一把尺子：同一张图在数据集上跑分，让「改对了没有」从感觉变成可量化的结论。