向后兼容 - Docs by LangChain

软件需要在生产环境中变更。新需求、错误修复和重构最终都会落地到你的图代码中。因为 LangGraph 使用最新部署的图来处理已为现有线程持久化的状态，所以你发布的每一个更改实际上都是相对于现有检查点的向后兼容 API 变更。与将运行固定到启动时代码版本的工作流引擎不同，LangGraph 会立即将最新的图应用到所有线程，包括新线程和从检查点恢复的线程。这很方便：错误修复可以直接传播到正在进行的对话和智能体中。但这也意味着你必须考虑每个更改如何与在旧版本代码下启动的运行进行交互。需要关注三类兼容性问题，大致按照你会遇到的顺序排列：

技术兼容性：最常见；新代码必须仍然能够加载并针对现有状态执行。
业务兼容性：不太常见；即使代码已更改，现有运行也应继续遵循旧的业务逻辑。
非确定性：仅适用于 Functional API。

有关运行时默认支持哪些图拓扑和状态更改的简短摘要，请参阅图迁移。本页面的其余部分涵盖了当更改超出支持范围时你可以应用的模式。

技术兼容性

技术兼容性相当于微服务中的 API 破坏性变更。这里的”API”是你的图代码与检查点器为现有线程持久化的数据之间的约定。当线程恢复时，LangGraph 反序列化保存的状态，按名称将其分发到节点，并期望节点返回符合状态模式的值。常见的技术破坏：

重命名或删除节点，而线程正暂停在该节点或即将进入该节点，例如在 interrupt 处或通过仍路由到旧名称的检查点条件边。恢复时，LangGraph 找不到保存名称对应的节点，运行将失败。恢复运行的起点是执行停止的节点的开头，因此缺失的节点将没有恢复的地方。
重命名或删除状态键，而旧检查点仍然包含该键或下游节点仍在读取该键。
收紧状态字段，例如将 Optional 字段变为必需、缩窄类型或添加没有默认值的新必需字段。现有检查点将不满足新模式。

边拓扑本身不持久化在检查点中。在仍然存在的节点之间添加、删除或重新路由边对正在进行的线程是安全的。根据图迁移摘要，唯一可能破坏被中断线程的拓扑更改是重命名或删除节点。

检测正在进行的线程

在你删除节点、重命名状态键或进行其他旧线程无法容忍的更改之前，你需要知道是否有任何线程当前停留在你即将弃用的代码版本上。LangGraph 本身不维护线程状态的搜索索引，因此答案取决于你的图在哪里运行。 如果你部署到 LangSmith。 使用 Agent Server 的线程搜索按状态过滤。status 字段接受 idle、busy、interrupted 和 error，因此你可以批量查询 interrupted 或 busy 线程，可选地使用元数据过滤器缩小范围。参见按线程状态过滤和列出线程。 LangGraph 运行的任何地方。 使用 LangSmith 追踪监控生产环境中哪些节点正在被进入和退出。这是确认某个节点或状态字段在任何活跃代码路径中不再可达的最可靠信号。 当你已有 thread_id 时。 直接检查该单个线程：

graph.get_state(config) 返回最新的检查点，包括线程暂停在哪个节点以及任何待处理的中断。
graph.get_state_history(config) 返回线程的完整时间顺序检查点列表。

如有疑问，请保留已弃用的节点或字段，直到 Agent Server 线程列表和追踪都显示不再有活动为止。

业务兼容性

有时候更改在技术上是有效的（每个现有检查点仍然加载，每个节点仍然解析），但新图的含义与旧的不同。新行为对新线程是正确的，你不希望将其追溯应用到在旧逻辑下启动的线程。例如，假设你的图运行 intake → triage → respond，而你决定在 triage 和 respond 之间插入一个新的 policy_check 步骤：

已经通过 triage 的线程应继续直接到 respond（旧流程）。
新线程应运行完整的新流程。

推荐的模式是在线程启动时在状态上记录相关的行为版本，然后通过条件边进行分支：

from typing import NotRequired
from typing_extensions import TypedDict

from langgraph.graph import END, START, StateGraph


class State(TypedDict):
    request: str
    flow_version: NotRequired[int]
    response: NotRequired[str]


def intake(state: State) -> dict:
    # 为新线程标记当前流程版本。绕过 `intake` 恢复的
    # 现有线程保留已保存的值。
    return {"flow_version": state.get("flow_version", 2)}


def triage(state: State) -> dict: ...
def policy_check(state: State) -> dict: ...
def respond(state: State) -> dict: ...


def after_triage(state: State) -> str:
    if state.get("flow_version", 1) >= 2:
        return "policy_check"
    return "respond"


builder = StateGraph(State)
builder.add_node("intake", intake)
builder.add_node("triage", triage)
builder.add_node("policy_check", policy_check)
builder.add_node("respond", respond)
builder.add_edge(START, "intake")
builder.add_edge("intake", "triage")
builder.add_conditional_edges("triage", after_triage, ["policy_check", "respond"])
builder.add_edge("policy_check", "respond")
builder.add_edge("respond", END)

graph = builder.compile()

在 triage 之后恢复的旧线程从其保存的状态中读取 flow_version（或回退到 v1 默认值）并跳过 policy_check。新线程从 intake 开始，被标记为 flow_version=2，并运行新路径。一旦所有 v1 线程完成，你就可以删除版本标记和条件边。此模式仅在你在线程开始时设置版本才有效，即在任何需要版本控制的分支之前。稍后设置意味着现有线程在需要时不会设置该值。

非确定性

此类别仅适用于 Functional API。Graph API 在恢复时从节点边界重新进入，因此节点代码不会像 Temporal 风格的工作流那样从函数开头”重放”。相比之下，Functional API 在运行恢复时从头重放 @entrypoint 的主体，使用缓存的 @task 结果来跳过已完成的工作。两种更改会破坏此模型：

添加、删除或重新排序在恢复点之前的 @task 调用或 interrupt 调用。LangGraph 通过重放中的位置将缓存结果和恢复值匹配到调用，因此移动该位置可能导致错误的缓存值被重放到不同的调用上。
在 @task 之外引入非确定性操作，例如 time.time()、random.random() 或内联在入口点主体中的网络调用。在重放时，这些操作产生的值与首次运行时不同，可能会改变控制流。

有关更深入的讨论和示例，请参阅 Functional API 指南中的确定性和常见陷阱。如果你需要对具有正在进行运行的 @entrypoint 进行非平凡的代码更改，最安全的选项是：

在部署更改之前让正在进行的运行排空。
将任何新逻辑包装在新的 @task 中，以便其结果独立进行检查点。
在 langgraph.json 中以新的图名称注册新的入口点用于新行为，并将新线程路由到它。

将这些文档连接到 Claude、VSCode 等工具，通过 MCP 获取实时答案。

在 GitHub 上编辑此页面或提交 issue。

Documentation Index

​技术兼容性

​推荐模式

​检测正在进行的线程

​业务兼容性

​非确定性

技术兼容性

推荐模式

检测正在进行的线程

业务兼容性

非确定性