摘要AgentState与Checkpoint的关系可以概括为AgentState是 Agent 当前正在使用的、可随时读写的可变状态容器承载对话历史、中间结果等实时记忆而Checkpoint则是某一时刻AgentState的完整、不可变快照。前者是“活着的草稿纸”后者是“草稿纸的历史照片”。Checkpoint并非AgentState内部的某样东西而是对AgentState外部保存的状态记录用于实现时间旅行、故障恢复和持久化存储。简单说AgentState 是一个专门用来存储 Agent 当前完整记忆的盒子里面主要装的是多轮对话的消息列表、节点之间传递的中间计算结果。而Checkpoint是AgentState在某一时刻的快照。目录一、引言二、核心概念一句话定义1. AgentState —— 当前正在使用的“草稿纸”或“盒子”2. Checkpoint —— 草稿纸的“快照”三、形象比喻纠正你的直觉1. 草稿纸2. 为什么“盒子里的东西”是错的四、它们如何配合工作1. 运行时流程2. 回溯机制五、这跟“记忆丢失”有什么关系六、总结对照表结语一、引言在使用 LangGraph 构建 Agent 应用时AgentState和Checkpoint是两个极易混淆的核心概念。很多初学者包括我之前的理解会下意识地认为AgentState是一个盒子Checkpoint就是盒子里存放的一个个东西。这个比喻方向恰恰是反的。如果你也有同样的困惑别担心这篇文章将用一个简单直观的比喻彻底厘清两者的关系并告诉你它们是如何协同工作的。二、核心概念一句话定义1. AgentState —— 当前正在使用的“草稿纸”或“盒子”AgentState是一个可变的数据容器它承载了 Agent 在当前时刻的所有“记忆”包括对话历史消息列表中间计算结果任何自定义的状态字段它就像你正在写字的草稿纸你可以随时在上面增删改内容。2. Checkpoint —— 草稿纸的“快照”Checkpoint是一个不可变的状态快照它记录了某一时刻AgentState的完整副本。每当你执行完一个图节点或手动触发LangGraph 会自动拍下一张“照片”保存当时的整个状态。这张“照片”一旦生成就再也不会改变可以被永久存储内存、文件、数据库等。说白了Checkpoint就是AgentState在某一时刻的状态Checkpoint的中文意思就是快照是AgentState的快照。三、形象比喻纠正你的直觉1. 草稿纸概念比喻特点AgentState一张可以随时擦写的草稿纸内容动态变化Checkpoint每隔一段时间拍摄的照片定格某一瞬间的草稿纸内容你写作文时草稿纸上不断修改。每写完一段你拍张照片存进相册。相册里的照片不是草稿纸上的字而是草稿纸的历史影像。2. 为什么“盒子里的东西”是错的用户原话“AgentState 相当于一个盒子Checkpoint 就是一个个盒子里的东西。” ❌纠正后盒子 AgentState盒子本身里面的东西会变照片 Checkpoint记录盒子某时刻的照片不是盒子里的东西四、它们如何配合工作1. 运行时流程开始 → 初始化盒子(AgentState) → 执行节点A → 自动拍照(Checkpoint_1) ↓ 修改盒子内容 ↓ 执行节点B → 自动拍照(Checkpoint_2) ↓ 修改盒子内容 ↓ 执行节点C → 自动拍照(Checkpoint_3)每一步执行后LangGraph 都会自动将当前AgentState的完整副本保存为一个Checkpoint。2. 回溯机制如果节点C执行出错或者你想撤销某些修改你可以告诉框架“回到 Checkpoint_2 时的状态。”框架会做两件事清空当前盒子的所有内容从 Checkpoint_2 中读取保存的状态副本重新填入盒子此时你的AgentState就完美恢复到了拍摄 Checkpoint_2 时的模样。五、这跟“记忆丢失”有什么关系你之前可能担心 Agent 会忘记历史对话。实际上只要你不修改 AgentState记忆一直存在盒子里的东西没丢但如果你手动修剪 AgentState比如删除了早期几条消息那就是直接改变了当前记忆此时Checkpoint 就是你的后悔药即使你把盒子里的东西改得面目全非只要你之前拍过照就能随时翻出旧照片恢复。Checkpoint 是一种外置的、持久化的保险机制而 AgentState 是正在使用的易变记忆。没有 Checkpoint改坏了状态就只能重新开始有 Checkpoint你可以像游戏读档一样任意回溯。六、总结对照表维度AgentStateCheckpoint本质当前正在使用的数据容器某一时刻的状态快照可变性✅ 可读写节点不断更新❌ 不可变生成后只读生命周期跟随当前会话/图执行可持久化存储跨会话作用承载 Agent 的实时记忆提供回溯点、实现时间旅行、持久化恢复比喻草稿纸 / 盒子草稿纸的照片 / 盒子的照片存储位置内存通常可选内存/Redis/数据库结语现在你明白了吗AgentState 是你正在操作的那个“活状态”Checkpoint 是给这个活状态拍的历史照片。照片不是盒子里的东西而是盒子状态的记录。记住这个核心区别你就再也不会混淆 LangGraph 中这两个最重要的概念。下次在代码中看到configurable里的thread_id和checkpoint_id你就知道它们正是用来从相册中挑选某张照片然后把盒子恢复成当时的样子。如果你还有疑问欢迎在评论区留言讨论。或者自己动手写一个小例子打印每次 Checkpoint 的内容你会看得更清楚。本文由作者在理解 LangGraph 源码过程中的笔记整理而成。希望帮助后来者少走弯路。