Session 23: persistence — state storage and task recovery

Agent 跑起来之后,状态持久化很容易被当成一个简单的技术问题:把对话历史和任务状态存进数据库,程序出问题后再读出来继续执行。

Originally in ChineseThis article was written in Chinese. The body below is the Chinese original; the English translation is not available yet.

但实际的 Agent 任务往往会持续几分钟甚至几小时,中间可能调用多个工具、访问外部系统、等待人工审批,还可能生成大量中间结果。程序崩溃后,恢复执行时究竟应该从哪里开始?已经成功执行的操作要不要重做?用户审批之前保存了哪些信息?这些才是 Agent Persistence 需要处理的核心问题。

一、Agent 到底需要保存哪些状态?

以 Research Agent 为例,整个任务可能经历以下过程:获取研究主题、搜索资料、分析证据、判断证据是否充分、补充搜索、生成报告,最后等待人工审核。

如果程序在生成报告之前崩溃,恢复后至少需要知道当前研究主题是什么、之前搜索过哪些资料、已经完成了哪些分析,以及为什么还需要继续搜索。

这意味着,Agent 的执行状态通常不只包含对话历史,还包括任务进度和中间结果。

状态类型 典型内容 是否需要持久化
对话历史 用户输入、模型回复、工具调用消息 根据业务需要,通常需要
任务状态 研究主题、当前阶段、任务是否完成 长任务通常需要
执行进度 已完成的步骤、待执行的步骤、重试次数 长任务通常需要
中间结果 搜索结果、证据列表、分析结果 根据恢复成本和数据量决定
外部操作记录 报告是否已发布、订单是否已创建 重要业务操作应独立记录
临时数据 可随时重新计算的中间变量 不一定需要

这里需要区分两类数据:一类是为了恢复 Agent 执行而保存的状态,另一类是业务本身需要长期保存的数据。

例如,Research Agent 搜索到的网页摘要可以作为中间结果保存在图状态中,也可以保存到独立的数据存储中;最终生成的研究报告则可能需要进入业务数据库,供后续查询、审核和发布。

所有数据都放进图状态并不合适。状态过大会增加序列化、存储和恢复的成本,尤其是对话历史不断增长、工具返回大量网页内容的情况。更合理的做法是让图状态保存必要的执行信息,大型材料和长期业务数据放到独立存储中,状态里保留引用或 ID。

二、Checkpoint:保存 Agent 的执行现场

在 LangGraph 中,Checkpointer 负责持久化图执行的状态。执行过程中,框架会在相应的执行边界保存 checkpoint,后续可以利用这些状态恢复执行。

先看一个简化的 Research Agent:

text
from typing import TypedDictfrom langgraph.graph import StateGraph, START, ENDfrom langgraph.checkpoint.memory import InMemorySaverclass ResearchState(TypedDict):    topic: str    search_results: list[str]    report: strdef search(state: ResearchState):    results = search_web(state["topic"])    return {"search_results": results}def analyze(state: ResearchState):    report = analyze_results(        state["topic"],        state["search_results"],    )    return {"report": report}builder = StateGraph(ResearchState)builder.add_node("search", search)builder.add_node("analyze", analyze)builder.add_edge(START, "search")builder.add_edge("search", "analyze")builder.add_edge("analyze", END)# 适用于本地开发的内存 Checkpointercheckpointer = InMemorySaver()graph = builder.compile(checkpointer=checkpointer)config = {    "configurable": {        "thread_id": "research-001"    }}result = graph.invoke(    {        "topic": "Agent 工程化实践",        "search_results": [],        "report": "",    },    config=config,)

这里的 ResearchState 定义了图执行过程中需要维护的状态,节点通过返回字典更新状态。checkpointer 负责保存执行过程中产生的状态快照,thread_id 用于标识这条执行线程。

需要注意,InMemorySaver 只适合演示或本地开发。它的数据存在当前进程的内存里,进程退出后就无法依靠它恢复。生产环境通常需要使用持久化存储后端,例如数据库支持的 Checkpointer。

另外,LangGraph 的 checkpoint 通常以 super-step 为单位保存。一个 super-step 可能包含多个并行执行的节点,因此不能简单理解成每执行完一个节点就必定单独保存一份完整状态。

Checkpoint 中保存的内容取决于图的 State 设计。State 可以包含消息历史、任务进度、工具返回结果和中间分析结果等。它并不会自动替业务系统保存所有数据,也不会自动记录所有外部操作的完整执行情况。

三、Checkpoint、会话存储和业务数据库有什么区别?

这三个概念经常被放在一起讨论,因为它们都涉及数据持久化,但职责并不相同。

存储类型 主要职责 示例
Checkpoint 保存图执行状态,支持恢复和中断续跑 当前研究阶段、消息历史、待审批数据
会话存储 管理应用层的会话信息 用户的会话列表、会话标题、归属用户
业务数据库 保存需要可靠管理的业务数据 研究报告、发布记录、订单、操作日志
长期记忆存储 跨会话保存可复用的信息 用户偏好、长期研究方向、已确认的知识

例如,用户打开英语学习平台后,可以看到自己之前创建的多个学习会话。这些会话的名称、创建时间和归属关系属于应用层的会话管理数据。

当用户进入其中一个会话时,系统可能通过对应的 thread_id 找到 LangGraph 保存的执行状态,恢复之前的对话和任务进度。

所以,会话恢复可以建立在 Checkpoint 之上,但会话管理本身不必完全依赖 Checkpoint。

长期记忆又是另一回事。LangGraph 的 Checkpointer 主要面向特定执行线程的状态快照;LangGraph Store 则可以用于跨线程、跨会话保存和查询长期信息。不能把所有历史对话、用户画像和业务资料都混成一份越来越大的 checkpoint。

四、程序崩溃之后,Agent 如何恢复?

假设 Research Agent 的执行顺序是:

  1. 搜索资料。
  2. 分析证据。
  3. 生成研究报告。
  4. 保存报告。
  5. 返回任务完成结果。

如果程序在第二步之后崩溃,恢复机制可以利用已经持久化的状态继续执行后续工作,避免每次都从研究主题开始。

在 LangGraph 中,只要使用支持持久化的 Checkpointer,并且恢复时指定同一个 thread_id,就可以读取该执行线程的历史状态。对于已经中断的图,可以按相应的恢复方式继续执行;对于已经结束的图,也可以在同一线程上发起后续调用,具体行为取决于调用方式和图的控制流程。

这里有几个需要明确的边界。

第一,Checkpoint 记录的是图状态,不是整个服务器的运行现场。 它不会保存 Python 进程的所有局部变量、线程栈或任意外部连接。节点恢复时,依然需要重新执行必要的代码。

第二,恢复不意味着所有历史节点都会从头执行。 持久化机制可以利用已经完成的执行步骤和状态,继续推进图。但如果节点尚未完成,或者恢复机制要求重新执行该节点,那么节点内部的代码仍然可能再次运行。

第三,Checkpoint 不等于事务回滚。 如果节点已经向数据库写入记录,或者已经通过外部 API 发布内容,恢复图状态不会自动撤销这些动作。

最后一点尤其重要。它直接关系到下一节讨论的副作用一致性问题。

五、节点存在不可重复的操作,怎么办?

考虑一个发布研究报告的节点:

text
def publish_report(state):    result = wechat_api.publish(        state["report"]    )    return {        "publish_result": result,        "published": True,    }

假设外部发布接口已经成功发布文章,但程序在节点结果可靠保存到 Checkpoint 之前崩溃了。

恢复执行时,系统可能仍然认为这个节点没有完成,于是再次调用发布接口。如果接口不具备去重能力,就可能发布两篇相同的文章。

这里存在两个独立的动作:

  • 外部系统执行发布操作。
  • Agent 将操作结果写入自己的状态存储。

这两个动作通常不属于同一个原子事务。因此,即使使用了 Checkpointer,也无法仅凭它保证外部操作只发生一次。

5.1 使用幂等键

如果外部接口支持幂等键,可以为每一次业务操作生成一个稳定的 ID,并在重试时复用同一个 ID。

text
def publish_report(state):    operation_id = state["operation_id"]    result = wechat_api.publish(        report=state["report"],        idempotency_key=operation_id,    )    return {        "publish_result": result,        "published": True,    }

这里假设外部 API 确实支持 idempotency_key。同一个操作 ID 被重复提交时,外部服务应根据自身的幂等规则避免重复执行。

幂等键必须在重试过程中保持不变。如果每次恢复都生成一个新的 ID,外部系统就可能把它们识别为不同操作。

5.2 使用业务操作记录

如果外部服务不支持幂等键,可以在业务数据库中建立操作记录,例如:

operation_id 操作类型 状态
pub-001 发布研究报告 pending
pub-002 保存研究报告 succeeded
pub-003 推送审核通知 failed

程序在执行操作前,先检查对应的业务记录;执行完成后,保存外部返回的结果。

但这还不够。如果外部操作已经成功,程序却在更新业务记录前崩溃,那么记录仍可能停留在 pending。因此,恢复时还需要查询外部系统的真实执行状态,或者利用外部幂等能力处理不确定的请求。

如果外部系统既不支持幂等,也无法查询操作结果,那么在某些故障情况下,程序无法仅凭本地记录确定操作究竟有没有成功。对于发布、支付等关键业务,这时可能需要人工核验。

5.3 拆分节点,明确执行边界

把所有操作都塞进一个节点,会让故障恢复更难判断。可以把流程拆成准备、执行和确认三个阶段:

text
准备发布数据
    ↓
记录待执行操作
    ↓
调用外部发布接口
    ↓
确认发布结果
    ↓
记录操作成功

这样可以明确每个阶段的职责,也更容易在日志和业务数据库中追踪问题。

不过,拆分节点本身并不能消除外部调用与本地记录之间的原子性问题。实际实现仍然需要幂等键、状态查询、事务设计或人工核验等手段。

还有一个经常被忽略的区别:Checkpoint 恢复、节点重试和业务操作幂等,解决的是三个不同层面的问题。

  • Checkpoint 恢复:从已保存的执行状态继续。
  • 节点重试:遇到暂时性故障时重新尝试执行。
  • 业务操作幂等:重复执行同一业务请求时,避免产生重复的业务效果。

三者需要配合使用,不能互相替代。

六、Human-in-the-Loop:人工审批之后如何继续执行?

Agent 在执行过程中,经常需要等待人工确认。例如,Research Agent 已经生成报告,但在发布前需要用户检查内容。

此时,图的执行状态需要被持久化。人工确认可能几分钟后到达,也可能隔几个小时才到达,因此不能依赖当前 Python 函数一直停在内存中等待。

LangGraph 提供了 interrupt 和 Command(resume=...) 这套机制,可以把图暂停下来,等待外部输入,再恢复执行。

text
from langgraph.types import interrupt, Commanddef approval_node(state):    decision = interrupt({        "report": state["report"],        "question": "是否发布这份报告?",    })    return {        "approved": decision["approved"]    }

编译图时需要配置支持持久化的 Checkpointer,并在调用时提供 thread_id。当节点执行到 interrupt 时,图暂停并保存恢复所需的状态。

之后,前端可以展示待审批的报告,用户点击批准或拒绝,再通过同一个执行线程提交恢复数据:

text
config = {    "configurable": {        "thread_id": "research-001"    }}# 恢复执行,传入用户审批结果graph.invoke(    Command(        resume={"approved": True}    ),    config=config,)

这里的关键是,恢复时要使用原来的 thread_id,并传入 Command(resume=...)。框架会根据保存的执行状态恢复中断流程,用户不需要自行拼装整个历史 State。

真实应用中,还需要在应用层验证当前用户是否有权审批这项任务,确认任务是否仍处于待审批状态,并防止同一审批请求被重复提交。不能只因为请求带着正确的 thread_id,就默认用户拥有对应的操作权限。

一个需要特别注意的细节

使用 interrupt 时,恢复执行可能会从包含该中断的节点开头重新执行。因此,不应该把可能产生重复副作用的操作放在 interrupt 之前,除非这些操作已经有幂等保护。

例如:

text
def approval_node(state):    create_external_order(state["order"])    decision = interrupt("是否确认订单?")    return {"approved": decision}

这段代码存在风险:第一次运行创建订单后暂停,恢复时节点可能重新执行,导致再次创建订单。

更稳妥的流程是先准备待审批数据,在中断点等待用户确认;恢复后再执行创建订单的操作。即使创建订单本身可能因为崩溃而被重试,仍然要通过幂等键和业务操作记录保护。

人工审批也不只是一个简单的暂停按钮。它涉及审批数据保存、用户身份与权限验证、任务状态管理、超时处理,以及审批结果与外部操作之间的一致性。

七、状态恢复还需要考虑哪些工程问题?

7.1 多用户之间的状态隔离

thread_id 用于标识执行线程,但它本身不是权限控制机制。应用不能允许用户随意传入一个 thread_id,就读取其他用户的研究报告或恢复别人的待审批任务。

生产系统需要把用户身份、会话归属和权限验证放在应用层处理,并确保每次读取、恢复和审批都经过授权检查。

7.2 Checkpoint 过期与数据清理

长期运行的 Agent 可能产生大量 checkpoint。如果每次执行都保存完整状态,尤其是状态中包含长对话、大型工具返回结果和中间报告时,存储成本会不断增加。

可以根据业务需求制定保留策略,例如保留活跃任务的完整状态、对已完成任务进行归档、删除过期的临时数据,并对重要业务结果独立保存。

删除旧 checkpoint 之前,需要确认任务是否还可能恢复、是否存在等待审批的中断,以及业务审计是否要求保留相关记录。

7.3 状态版本变化

Agent 的 State 定义、节点逻辑和工具接口可能随着代码升级而变化。以前保存的 checkpoint 可能缺少新版本需要的字段,或者包含新版本已经不再使用的数据。

因此,长期运行的生产系统需要考虑状态结构的兼容性。例如,为新增字段提供默认值、为状态迁移编写转换逻辑,或者在部署时确保旧任务仍能由兼容版本继续处理。

7.4 长任务恢复与队列系统

Checkpoint 负责保存图执行状态,但它本身并不等同于任务队列。

如果有大量研究任务需要后台运行,通常还需要队列和 Worker 来管理任务分发、并发、超时和重试。Checkpointer 保存执行进度;队列负责调度任务;业务数据库记录业务结果和操作状态。

例如:

text
用户提交研究任务
       ↓
任务队列
       ↓
Agent Worker
       ↓
LangGraph + Checkpointer
       ↓
业务数据库 / 外部工具

Worker 崩溃后,队列系统负责重新调度任务;Agent 再根据持久化状态恢复执行。具体的队列确认、任务租约和重试策略需要与图的恢复机制协调,避免多个 Worker 同时恢复并执行同一任务。

八、LangGraph 和周边方案分别解决什么问题?

在 LangGraph 体系中,可以把相关能力理解为几个相互配合的部分。

能力 主要解决的问题
Checkpointer 保存图状态,支持执行恢复
thread_id 标识需要读取或恢复的执行线程
interrupt / Command(resume=...) 暂停图执行并接收后续人工输入
LangGraph Store 保存可跨线程、跨会话复用的长期信息
数据库事务与幂等设计 保护业务写入和外部副作用
队列与 Worker 管理长任务调度、并发和重新投递
日志与追踪 定位崩溃前执行到了哪一步、失败原因是什么

在技术选型上,LangGraph 的持久化接口可以对接不同存储后端。开发阶段可以使用内存实现;生产环境则应根据部署架构、数据规模和可靠性要求选择持久化后端。

Redis、关系型数据库、消息队列等基础设施也经常出现在 Agent 系统中,但它们的职责并不完全相同。不能因为系统用了 Redis 或 MySQL,就认为 Agent 已经具备完整的恢复能力;关键仍然是明确状态模型、故障恢复流程和外部操作的一致性策略。

九、最后梳理一下

Agent Persistence 的核心是让执行状态在进程退出之后仍然可用,使长任务能够恢复、人工审批能够续跑,并且避免每次都从头开始。

Checkpoint 保存图执行状态,thread_id 帮助定位执行线程,interrupt 和 Command(resume=...) 支持人工介入后的恢复。应用还需要独立管理会话信息、长期记忆和业务数据。

生产环境里最需要谨慎处理的,是外部副作用。Checkpoint 不会自动撤销已经完成的业务操作,也不能单独保证外部 API 只调用一次。对于发布文章、创建订单、发送通知等操作,需要结合幂等键、业务操作记录、执行状态查询和必要的人工核验。

最后可以记住一个判断:状态恢复解决的是 Agent 从哪里继续执行;业务一致性解决的是恢复之后,哪些操作可以重做、哪些操作必须避免重复。

On this page