AI Agent / 系统课时
配置检查点保存线程状态
配置检查点保存线程状态
多轮智能体不能只依赖当前函数调用里的 Python 变量,否则一次执行结束后就无法可靠恢复上下文。本节给图接入 checkpointer,用 thread_id 把同一会话的状态快照串起来,并通过两次调用验证第二次执行能够从上一份线程状态继续。
学习目标
- 在
compile时配置 checkpointer,并用thread_id标识线程。 - 理解检查点如何保存图状态并支持后续调用继续执行。
- 区分线程级持久化、普通内存变量与真正的持久化存储。
检查点保存的是什么
LangGraph 的 checkpointer 保存的是图管理的状态快照,而不是整个 Python 进程。调用图时,thread_id 充当这条状态历史的主键;后续使用相同 thread_id,图可以读取该线程最近的检查点,再把本次输入作为新的状态更新继续执行。
在顺序图里,可以把它理解为节点执行后形成新的快照;更准确地说,检查点发生在图的超步边界。并行节点可能属于同一个超步,因此不要把“一个节点必然对应一个独立检查点”当成通用规则。

配置 InMemorySaver 并验证恢复
InMemorySaver 适合本地实验和测试。下面的图只有一个自增节点,但足以验证线程状态:第一次把 count 从 0 增加到 1;第二次只提交新的 note,同一个线程会继续使用检查点中的 count=1,因此结果变成 2。
from typing import TypedDict
from langgraph.checkpoint.memory import InMemorySaver
from langgraph.graph import END, START, StateGraph
class ThreadState(TypedDict, total=False):
count: int
note: str
def increment(state: ThreadState) -> dict:
return {"count": state.get("count", 0) + 1}
builder = StateGraph(ThreadState)
builder.add_node("increment", increment)
builder.add_edge(START, "increment")
builder.add_edge("increment", END)
checkpointer = InMemorySaver()
graph = builder.compile(checkpointer=checkpointer)
config = {"configurable": {"thread_id": "demo-thread"}}
first = graph.invoke({"count": 0, "note": "first"}, config)
second = graph.invoke({"note": "second"}, config)
snapshot = graph.get_state(config)
print(f"first: count={first['count']}, note={first['note']}")
print(f"second: count={second['count']}, note={second['note']}")
print(
f"snapshot: count={snapshot.values['count']}, "
f"note={snapshot.values['note']}"
)预期输出
first: count=1, note=first
second: count=2, note=second
snapshot: count=2, note=second第二次调用没有重新传入 count,仍能得到 2,说明图从同一 thread_id 的已有状态继续执行。graph.get_state(config) 读取该线程的当前状态快照,可用于调试、恢复判断和状态检查。
持久化不等于普通内存变量
普通模块变量、函数局部变量或某个对象字段,如果没有进入图状态,就不会自动出现在检查点里。checkpointer 管理的是可按线程检索、恢复和继续执行的图状态,这也是它与“把值留在一个 Python 变量里”的核心区别。
但 InMemorySaver 本身仍然把检查点放在当前进程内存中。进程重启后这些数据会消失,因此它不能提供生产级耐久性。
正确使用 thread_id
同一段多轮会话应稳定复用同一个 thread_id;彼此独立的用户会话或任务则必须使用不同 ID。若每次请求都生成新 ID,就等于主动切断历史状态;若多个用户误用同一个 ID,则可能把原本隔离的线程状态混在一起。
检查点解决的是“这条线程执行到了哪里、当前图状态是什么”。它不是任意业务数据的通用数据库,也不应替代长期用户画像或跨线程共享数据。先把需要恢复的执行状态明确放进图 state,再选择与环境匹配的 checkpointer,才能真正得到可恢复的多轮工作流。