第31章 0.2.x 到 1.x 迁移指南
31.1 版本演进与核心变化
LangGraph 的版本演进经历了四个主要阶段。2024 年初发布 0.1 版本，提供基于 StateGraph 的基础图编排能力；2024 年下半年发布 0.2 版本，引入 Pregel 计算模型作为底层执行引擎，并加入持久化检查点（Checkpointer）与中断恢复能力；2025 年底发布 1.0 RC（Release Candidate，候选发布版），完成 API 稳定化与核心接口收敛；2026 年 1 月发布 1.0 正式版，标志着核心 API 进入语义化版本（Semantic Versioning）的稳定期。本手册基于 1.2.x 版本编写，该版本在 1.0 基础上完善了 Store 接口、多智能体命名规范与 CLI 部署工具链。
1.x 版本相对 0.2.x 引入了以下核心变化。
interrupt() 原语：取代 0.2 版本中通过 NodeInterrupt 异常与 breakpoint 静态断点实现的中断机制。新的 interrupt() 函数在节点内部以普通函数调用方式触发中断，接收一个 value 参数作为中断时向外暴露的信息，resume 时通过 Command(resume=...) 传入恢复值。原有的 interrupt_before 与 interrupt_after 编译参数在 1.x 中仍被兼容，作为基于节点名的静态中断快捷方式保留。
Command 原语：成为统一的路由跳转、状态更新与 resume 机制。在 0.2 版本中，条件边返回字符串表示路由目标，状态更新通过节点返回值隐式合并；在 1.x 中，节点可返回 Command(goto=..., update=..., resume=...) 对象，在一次返回中同时指定跳转目标、状态增量更新与恢复值，取代了部分需要分离条件边与状态写入的分支写法。
create_react_agent 迁移：langgraph.prebuilt.create_react_agent 在 1.x 中保留但标记为 deprecated（弃用），官方提示迁移到 langchain.agents.create_agent。两者行为等价，新入口与 LangChain 生态的 Agent 构造函数保持一致，便于统一工具绑定与输出解析配置。
流式输出格式 v2：stream_mode 输出格式升级为三元组结构 {type, ns, data}，取代 v1 的 (mode, chunk) 元组。新格式中 type 表示事件类型，ns 表示命名空间路径（用于区分子图来源），data 携带具体负载。v1 格式可通过在 stream/astream 调用时传入 version="v1" 参数保持兼容。
Checkpoint 结构调整：checkpoint_ns 字段语义在 1.x 中被明确化，用于标识检查点所属的子图命名空间；pending_sends 字段正式纳入 Checkpoint 结构，用于记录并行扇出阶段尚未完成的发送任务。
Store 接口稳定：langgraph.store.base.BaseStore 成为正式公开 API，定义 put、get、search、delete 四个标准方法，取代 0.2 中实验性的存储接口。
多智能体命名统一：1.x 正式定义四种多智能体模式的官方命名——Supervisor（监督者模式）、Router（路由模式）、Handoffs（交接模式）、Swarm（蜂群模式），对应的实现示例纳入官方文档。
部署路径更新：LangGraph Platform 与 LangGraph CLI 正式发布，取代 LangServe 作为推荐部署路径。LangGraph Server 提供标准化的 REST API 与流式端点，支持自托管部署。
31.2 迁移步骤
建议按照以下六个步骤完成从 0.2.x 到 1.x 的迁移。
第一步，升级依赖并运行测试。将依赖声明中 langgraph 的版本约束更新为 langgraph>=1.0.0,<2.0.0，同时确保 langchain-core 版本满足 1.x 的 peer dependency（对等依赖）要求。升级后执行现有测试套件，确认基础功能未出现回归。
第二步，替换手写 breakpoint。搜索代码中所有 NodeInterrupt 异常抛出点与 interrupt_before/interrupt_after 的静态断点配置，评估是否需要迁移为节点内的 interrupt() 调用。对于仅需在节点边界中断的简单场景，interrupt_before/interrupt_after 可保留使用。
第三步，合并条件边与状态更新。检查条件边函数中仅做路由判断、状态更新分散在多个节点的写法，评估是否可通过返回 Command 对象将路由与状态写入合并，减少中间节点数量。
第四步，适配流式消费端。若使用 stream() 或 astream() 消费流式输出，需确认消费端代码是否解析 v1 的 (mode, chunk) 元组。若需快速兼容，可在调用时传入 version="v1"；长期建议迁移到 v2 的 {type, ns, data} 结构，以支持子图事件区分与更细粒度的事件类型判断。
第五步，检查 Checkpointer 数据兼容性。1.x 与 0.2.x 的 checkpoint 数据结构不完全兼容，0.2 版本持久化的检查点数据在 1.x 中可能无法正确加载。生产环境建议在升级窗口清空旧 checkpoint 数据并重新启动运行实例；若需保留历史数据，应编写迁移脚本将旧结构转换为新结构。对于 PostgresSaver，需重新执行 setup() 方法建表或运行官方提供的迁移 SQL 脚本。
第六步，切换部署路径。若原项目使用 LangServe 部署，建议迁移到 LangGraph Server（自托管 FastAPI 应用或 LangGraph CLI 构建的服务）。LangGraph Server 原生支持 thread_id 级别的状态路由、流式端点与中断恢复 API。
31.3 不兼容变更与常见错误
以下表格列出常见 API 在 0.2.x 与 1.x 中的对照写法。
| API 类别 | 0.2.x 写法 | 1.x 写法 |
|---|---|---|
| 节点中断 | raise NodeInterrupt("需要确认") | value = interrupt("需要确认") |
| 恢复执行 | 传入 None 或通过 update 注入 | Command(resume=user_input) |
| 条件路由+更新 | 条件边返回字符串，状态在节点中 update | return Command(goto="next_node", update={"key": val}) |
| ReAct Agent | create_react_agent(model, tools) | create_agent(model, tools)（langchain.agents） |
| 流式事件格式 | for mode, chunk in graph.stream(..., version="v1") | for ev in graph.stream(...): ev["type"], ev["ns"], ev["data"] |
| Checkpoint 命名空间 | checkpoint_ns 语义不稳定 | checkpoint_ns 显式标识子图路径 |
| 存储接口 | langgraph.store 实验性 API | langgraph.store.base.BaseStore 正式 API |
| 部署 | LangServe add_routes | LangGraph Server / langgraph dev / langgraph up |
迁移过程中三类错误出现频率较高。
其一，旧代码的 interrupt 用法在 1.x 报错。0.2 版本中部分项目通过直接导入 interrupt 函数并以装饰器方式使用，该用法在 1.x 中已被移除，必须改为节点内部的函数调用形式。
其二，v1 stream 解析代码在 v2 下失效。1.x 默认 stream_mode 输出为 v2 格式，直接对事件解包为 (mode, chunk) 会抛出 ValueError: too many values to unpack，需调整解构逻辑或显式指定 version="v1"。
其三，PostgresSaver 旧表结构导致持久化失败。0.2 版本创建的 checkpoint 表缺少 pending_sends 等字段，直接运行 1.x 代码会在写入时抛出数据库列不存在的异常，需调用 saver.setup() 重新建表或执行 ALTER TABLE 迁移脚本补齐字段。