[LangGraph] checkpoint常用API

• getState：可以获取最后的检查点快照，如果传了checkpoint_id，那么就获取对应checkpoint_id的快照。
• 获取所有的检查点快照
  • list：不是graph上面的方法，而是checkpointer上面的方法
  • getStateHistory：是graph上面的方法

1. 获取最新状态

这是最常用的API，用来查看当前 thread 的 最后一个 checkpoint 的完整状态。

const config = {
  configurable: { 
    thread_id: "user_1001_chat" 
  }
};

const snapshot = await graph.getState(config);

它会返回一个StateSnapshot对象，里面包含：

• 当前 state（你的 zod schema 定义的全部字段）
• 当前的 messages（对话历史）
• 当前超步中的执行元数据
• 最后一个 checkpoint_id

你可以把它理解为：把该线程当前的世界状态全部给我。

2. 列出所有检查点

这个方法用于查看某条 thread 的完整 checkpoint 时间线：

const config = { configurable: { thread_id: "1" } };
const allCps = await checkpointer.list(config);

输出是一组检查点元数据，例如：

[
  {
    config: {
      configurable: {
        thread_id: "1",
        checkpoint_ns: "",
        checkpoint_id: "1f0d417a-160b-6010-8002-4989c8485d2c",
      },
    },
    checkpoint: {
      v: 4,
      id: "1f0d417a-160b-6010-8002-4989c8485d2c",
      ts: "2025-12-08T09:24:00.529Z",
      channel_values: { foo: "b", bar: ["a", "b"], __pregel_tasks: [[], []] },
      channel_versions: {
        __start__: 2,
        foo: 4,
        bar: 4,
        "branch:to:nodeA": 3,
        "branch:to:nodeB": 4,
      },
      versions_seen: {
        __input__: {},
        __start__: { __start__: 1 },
        nodeA: { "branch:to:nodeA": 2 },
        nodeB: { "branch:to:nodeB": 3 },
      },
    },
    metadata: { source: "loop", step: 2, parents: {} },
    pendingWrites: [],
    parentConfig: {
      configurable: {
        thread_id: "1",
        checkpoint_ns: "",
        checkpoint_id: "1f0d417a-1608-6900-8001-06b1113beafe",
      },
    },
  },
  // ...
]

1. checkpoint_id

这是当前 checkpoint 的唯一ID，用来确定“这是哪一个时间点”。

用途：

• time travel
• 版本回溯
• 恢复历史
• 分支执行

你可以把它理解为：存档编号

2. config

这是这个 checkpoint 执行时所使用的 config，包括：

• thread_id
• checkpoint_id
• checkpoint_ns（命名空间）

它决定了属于哪个 thread（对话），断电重启、恢复执行，都靠它。

3. metadata

执行时产生的元信息，例如：

• 执行到了哪一步（step）
• 来源（source）
• 父节点执行信息

例如：

metadata: { source: 'loop', step: 2, parents: {} }

含义就是：这个 checkpoint 是第 2 个步骤执行结束时产生的。

4. parentConfig

这个 checkpoint 的“上一个 checkpoint”。

换句话说：parentConfig → 这个 checkpoint 的父存档是谁

作用：

• 用来恢复整个执行链路
• 构建执行时间线
• time-travel 时知道上一点是谁
• 能显示完整历史链条

可以理解为：这是从哪个 checkpoint 演化来的。

5. pendingWrites

这表示“这个 checkpoint 在本次执行中有哪些写操作，将被写入 state”。

形式通常是三元组：

[nodeId, field, value]

意思是：

• 哪个节点
• 要写哪个字段
• 写什么值

示例：

['nodeA', 'foo', 'b']

翻译为：节点A，把 foo 写成 b

为什么叫 pending ？因为它记录发生过哪些写操作，但最后的结果体现在 channel_values 中。

6. channel_values

这就是“state 真正存储的值”，里面就是完整状态

也可以使用 graph.getStateHistory() 方法，例如：

const config = { configurable: { thread_id: "1" } };
graph.getStateHistory(config)

3. 获取指定检查点

如果你不想看最新状态，而是想看某个历史状态，就可以这样：

const config = {
  configurable: {
    thread_id: "user_1001_chat",
    checkpoint_id: "6c2c72c0-..."  // 历史 checkpoint id
  }
};

const snapshot = await graph.getState(config);

官方支持这种用法，用于：

• 时间旅行（Time Travel）
• 调试历史状态
• 对比不同 checkpoint 之间的差异

总结

检查点相关API能让开发者可以读取、回放、分叉、恢复任意执行点，它们是 langgraph 持久化机制的核心工具箱。

---

-EOF-