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。

python
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']}"
)

预期输出

text
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,才能真正得到可恢复的多轮工作流。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

配置检查点保存线程状态

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通