← 返回首页

Agent Framework checkpoint:8 处让恢复失效的地方

Agent Frameworkcheckpoint状态恢复

给一个工作流加了存档,跑通、输出正确、日志里还有「Created checkpoint」这一行,然后你放心地把它放到线上——这是 checkpoint 这一层最常见的误判。存档写成功和恢复可用是两件事,中间隔着六七个不会抛异常的环节。我实际在 Windows 11 上用一个隔离目录装了 Microsoft Agent Framework 1.25.0(PyPI 发布于 2026-11-07),又单独装了 1.26.0(截至发稿 PyPI 最新版,2026-11-12)做对照,用纯 executor 搭了三条链反复跑,本文所有数字都来自这两次本机实测,凡是没有实测到的地方我会写明「未验证」。

先说结论:存档确实能跨进程恢复,这一层是成立的;但让恢复失效的方式比让恢复成功的方式多得多,而且大部分失效不报错。另外声明一句,本文不含任何联盟推广链接,下面出现的版本号与异常原文都可以在官方包和官方文档里逐字核对。

// FLOW_01checkpoint 的写入与恢复路径(本文实测)6 NODES01STEP_01build(start_executor + checkpoint_storage)02STEP_02入口存档 iteration 003STEP_03执行 superstep 104STEP_04存档 iteration 105STEP_05执行 superstep 206STEP_06存档 iteration 2END_OF_FLOW
checkpoint 的写入与恢复路径(本文实测) · 依据本文步骤自绘示意图
PythonJsonOpenAI
文中涉及的技术标识 · 图标来自 Simple Icons(CC0)

先固定版本与实验环境

环境是 Windows 11 + CPython 3.13.12,agent-framework 1.25.0 与 1.26.0 装在两个互相隔离的目录里(1.26.0 用 no-deps 装核心包,其余依赖从 1.25.0 的目录复用),用 PYTHONPATH 切换。工作流全部由 WorkflowBuilder 构建,executor 是纯函数或类式 executor,不接任何模型,所以下面每个数字都可以在没有 API key 的机器上复现。

一个必须先说清的边界:文档站讲 checkpoint 的那一页给的是跨语言并列示例(C#、Python、Go 各一套 API),Python 侧的入口是 WorkflowBuilder(start_executor=..., checkpoint_storage=...)。我按这个入口写,没有遇到任何问题;但 11-08 那篇已经确认过,同一个文档站的部分页面列的方法在 1.25.0 里并不存在,所以凡是文档与包对不上的地方,本文一律以包里的实际行为为准。

存档数量 = superstep 数 + 1,第 0 个是入口存档

单节点工作流跑一次,存了 2 个存档(iteration 0 与 1);两节点链跑一次,存了 3 个(0、1、2);三节点链跑一次,存了 4 个(0、1、2、3)。规律很稳定:iteration 从 0 到 superstep 数,两端各多一个边界。

第 0 个不是「第一个节点跑完」,而是入口存档:它的 messages 里键名是 internal: 加首节点 id(实测是 internal:step_a 这种形态),装的是本次 run 的输入消息,迭代号 0、previous_checkpoint_id 为 None。最后一个存档的 messages 是空字典——此时没有待投递的消息了,只剩各 executor 的状态。

顺带记一条:存档里的 state 键只有四个,_workflow_run_kwargs、_resolved_workflow_run_kwargs、_routed_workflow_run_kwargs 与 _executor_state。最后那个是每个 executor id 对应的状态字典,没实现 on_checkpoint_save 的 executor 在这里是空字典。

恢复的边界是「第 N 个 superstep 之后」

这条决定了恢复到底是重放还是续跑。三节点链 a1 → b1 → c1,一次完整 run 的调用序列是 a1、b1、c1。从 iteration 1 的存档恢复,调用序列变成 b1、c1——a1 没有被再执行;从 iteration 2 恢复,只有 c1 被执行;从 iteration 0(入口存档)恢复,三个节点全部重跑。

换句话说,run(checkpoint_id=X) 的语义是「X 这个存档之后的部分重新开始」,X 里面已经存下的消息会被直接当作下一批输入投递出去。上面三次恢复的最终输出完全一致,都是同一条 c1:v|a1|b1,所以恢复正确性本身是可以验证的——但只有在你把「恢复点之后会执行什么」当成显式契约的时候。

从最后一个存档恢复:零调用、空输出、不报错

这是最容易踩的一个坑,因为它在正常路径上几乎一定会发生。上面那三次恢复里,如果我传的是 iteration 3(也就是跑完之后的那个存档),run() 会正常返回,get_outputs() 是空列表,executor 调用次数是 0,没有任何异常。

从使用者的角度看,这非常像「恢复成功,只是没有新输出」。真实含义是「你从这个存档恢复时,工作流的全部 superstep 都已经完成了」。如果恢复逻辑写在重试链路里,条件写成「只要有存档就恢复」,那么一个已经跑完的任务会被判成「恢复完成、结果为空」,然后空结果被当成正常结果落库。

判断方法只有一条:恢复前先比较目标存档的 iteration 与本次图的总 superstep 数,或者只从「明确不是末位」的存档恢复。get_latest() 返回的恰恰是末位存档,它是最不该直接拿来恢复的那一个。

存档写失败不会让工作流失败

这是本文最贵的一条,也是它不该只出现在日志里的原因。给 executor 加一个 on_checkpoint_save,让它返回一个自定义类的实例(我这里是一个 Order(oid, qty)),然后跑一次:run() 正常返回输出 ['step1'],一切看起来都成功,但存档目录里一个文件都没有——存档数是 0,不是减少,是完全没有。

日志里能看到的原文是这样的:

WARNING | agent_framework._workflows._runner | Failed to create checkpoint at iteration 0: Failed to decode pickled checkpoint data: Checkpoint deserialization blocked for type 'ckptmodel:Order'. ... Note that this does not fail the workflow run. The next successfully-created checkpoint will be parented to the last successful checkpoint

注意两件事:级别是 WARNING 不是 ERROR,logger 名是 agent_framework._workflows._runner;以及它自己写明了「does not fail the workflow run」。包里的实现也一致——_runner.py 里整个存档动作包在 except Exception 里,捕获后只打一条 warning,然后继续跑。所以只要你的日志级别把 agent_framework 压到 ERROR,这条信息就是不可见的,而工作流依然是成功的。

根因在解码侧:FileCheckpointStorage 的文档字符串写明,反序列化默认限制在内置安全类型(primitives、datetime、uuid 等)、所有 agent_framework 与 agent_framework_orchestrations 内部类型、以及 OpenAI SDK 的 openai.types。存档文件本身是 JSON,但复杂对象是以 __pickled__ 加 base64 的形式嵌在 JSON 里的(我打开过文件,11 个顶层键,messages 里就是这种形态),所以取值时走的是受限 unpickler。放行一个应用自定义类有两条路:构造 storage 时传 allowed_checkpoint_types=["模块名:类名"],或者调用 agent_framework.register_checkpoint_type(类) 全局注册。

实测对照很干脆:默认 storage 跑同一个 executor,存档数 1(只有入口存档写得下去,因为它当时的状态里那个列表还是空的);传了 allowed_checkpoint_types=['ckptmodel:Order'] 之后存档数 2,并且 load() 出来的 _executor_state 里能读回 Order(X1,1)。

白名单参数写错格式也不报错

接着上一条做个反例:把参数写成 allowed_checkpoint_types=['Order'](只有类名,没有 模块名:类名),构造 storage 时不抛异常,不警告,跑起来的结果和完全不传一模一样——存档数 1,自定义状态照旧丢失。

也就是说这个参数是「静默无效」型的:格式对了才生效,格式错了不告诉你。在 1.26.0 上行为相同。落地时唯一可靠的判据不是「参数写了没」,而是「跑完之后 list_checkpoint_ids() 的数量对不对」——按前面那条规律,两节点链应该是 3,不是 3 就说明有存档没写进去。

图指纹只认结构,不认代码

每个存档都带一个 graph_signature_hash。改图会怎样,实测很清楚:把 a1 的下游从 b1 换成 c1,恢复立刻抛

WorkflowCheckpointException: Workflow graph has changed since the checkpoint was created. Please rebuild the original workflow before resuming.

改动 executor 的 id(把 x 换成 y)、改类名,同样触发这条异常。但把 workflow 的名字从 s8 改成 renamed,恢复照样成功。

真正值得记的是第三种情况:只改 executor 的函数体,指纹一模一样。我把 worker 从 v1(追加 |v1)改成 v2(追加 |v2-changed-body),两版算出来的 hash 完全相同(都是 324fa621effcaf94 开头),恢复没有任何阻拦,而恢复时投递给下游的消息是 v1 时代的产物,最终输出还是 tail:x|v1。

翻一下 _workflow.py 里的 _compute_graph_signature 就明白了:它收集的是 start_executor、每个 executor 的 模块名.类名、edge group 的 source/target/condition,然后排序序列化算 sha256。函数体、默认参数、业务逻辑都不在里面。 所以「改了代码但没改结构」这种情况下,旧存档会被安静地接受,新代码拿着旧数据继续跑——这正好是最容易出数据错配的场景。要防它,只能靠自己的版本号:把逻辑版本写进 workflow 名字或者存档目录路径,改逻辑就换目录。

list_checkpoints 的顺序不是 superstep 顺序

三节点链跑完,list_checkpoints(workflow_name=...) 返回的 iteration 序列我实测到过两种:[1, 2, 0] 和 [2, 1, 0],两次都不是 [0, 1, 2]。原因在实现里:文件后端是 for file_path in self.storage_path.glob("*.json"),直接按文件系统返回顺序遍历,没有任何排序。

这一点直接冲击官方示例的写法。文档里的恢复示例是「假设我们要从第 6 个存档恢复」,然后取 checkpoints[5]——在文件后端上,「第 6 个」这个位置和「第 6 个 superstep」不是一回事。要按迭代走,必须自己 sorted(..., key=lambda c: c.iteration_count);实测 get_latest() 是可靠的,它按 timestamp 取最新、同一时间戳再用 lineage 链(previous_checkpoint_id)解冲突,返回值是 iteration 2 而不是迭代号最大的猜测值。

同一个实现还有个副作用:列表是「逐文件解码,失败只 warning」——某个存档文件解码失败时,它会被静默从列表里丢掉(warning 原文是 Failed to read checkpoint file ...),而 load(那个 id) 会老老实实抛异常。所以「列表里没有」不代表「不存在」。

每个存档是完整快照:能删父存档,也没有回收机制

我先删掉 iteration 1 的存档,再从 iteration 2 恢复——结果正确,只有 c1 被执行。删掉入口存档(iteration 0)之后重新跑一次全新 run,也正常完成。这说明存档里存的是完整状态,不是增量补丁,恢复不依赖父链。

好消息是旧存档可以删;坏消息是没有任何东西替你删。CheckpointStorage 这一层的接口只有 save、load、get_latest、list_checkpoints、list_checkpoint_ids、delete 六个,没有 TTL、没有保留条数、没有清扫参数(官方文档那一页也没有讲保留策略)。实测代价:一次两节点 run 产生 3 个存档,做两次恢复后目录里变成 6 个(+100%);换成 20 KB 左右的消息载荷跑 20 次,目录里 60 个文件、合计约 1,097 KB,list_checkpoints() 一次 18 ms 左右——而它每次都要把每个文件完整解码一遍,list_checkpoint_ids() 也是委托给它做的,耗时 19 ms,两者几乎一样。存档量线性涨,列表成本也跟着线性涨。

时间戳是 UTC,文件时间是本地时间

存档里的 timestamp 带时区偏移,实测值是 2026-11-14T22:12:49.750179+00:00;同一个文件的 mtime 用本地时间读出来是 2026-11-15T06:12:49(机器时区 +0800)。两者差 8 小时,指的是同一瞬间。

如果你把「存档时间」拿去和业务侧的本地时间字段比较(比如「只恢复今天产生的存档」),这 8 小时会直接把跨零点的任务判到昨天。要么统一转 UTC,要么统一用 mtime,不要混着用。

跨进程恢复成立,前提是图能重建出一致的指纹

这是 checkpoint 这一层真正要兑现的承诺,所以我单独跑了两个进程:进程 A(PID 20032)写入存档并打印 iteration 1 的 id,进程 B(PID 16244)用这个 id 恢复。B 读出的 graph_signature_hash 与 A 完全相同(a48f53cff8c2b80a 开头),恢复后只执行了 stage2,输出与 A 那次完整 run 一致。

因此图指纹是跨进程稳定的,不含内存地址之类的东西;只要 executor 的 id、类名与模块路径不变、边的结构不变,另一个进程能重建出同一个指纹。反过来说,三层重构会一次性废掉所有历史存档:改类名、改模块(比如把 executor 从 app.nodes 挪到 app.workflow.nodes)、改 executor id。C# 侧文档对这一点讲得很细(agent 的 id 必须稳定),Python 侧的实现是同一个道理,只是异常报文只告诉你「图变了」,不告诉你变在哪。

与 LangGraph 那一层的分工

站内 10-19 那篇讲的是 LangGraph 的 checkpointer 层,那篇回答的是「持久化接上之后哪些行为会变」;这一篇回答的是「存档文件到底记了什么、恢复从哪一格开始」。两者不要混着记:LangGraph 侧的接线是 thread 概念驱动的,而这一层没有 thread,恢复要靠调用方把 checkpoint_id 显式传进 run(),传错或不传都不会有默认值兜底。

如果你手上有 11-04 那篇里并发等待型的慢任务,checkpoint 也帮不上——它不解决调度,只解决「从哪一格继续」。真正该考虑开它的,是单次 superstep 很贵(调模型、调外部写接口)、失败重跑代价高的链路。至于「崩溃时到底丢了哪一段」,站内 10-29 那篇按 durability 模式逐档拆过,可以对照着看。

Troubleshooting:四个原文报错与处理

报错一:WorkflowCheckpointException: Workflow graph has changed since the checkpoint was created. Please rebuild the original workflow before resuming.

触发条件:改边、改 executor id、改 executor 类名(模块路径也会算进去)。处理:要么重建出与存档时完全一致的结构,要么放弃旧存档。注意它不告诉你差在哪个节点,只能自己按上面三样逐项对照。

报错二:WorkflowCheckpointException: No checkpoint found with ID not-a-real-id

触发条件:run(checkpoint_id=...) 传了不存在或已被 delete 的 id。处理:先 list_checkpoint_ids(workflow_name=...) 确认;注意传错 workflow 名字不会报这个异常,而是返回空列表,让你以为「本来就没有存档」。

报错三:TypeError: FileCheckpointStorage.list_checkpoint_ids() missing 1 required keyword-only argument: 'workflow_name'

触发条件:三个查询接口的 workflow_name 都是仅关键字参数,位置传参或不传都直接 TypeError。处理:统一写 list_checkpoints(workflow_name=wf.name)。附带一条:同一个类型错误也会出现在 list_checkpoints() 与 get_latest() 上,报错文案只差方法名。

报错四:Checkpoint deserialization blocked for type 'ckptmodel:Order'. To allow this type, either include its 'module:qualname' key in the 'allowed_types' set passed to 'decode_checkpoint_value', or add it to 'allowed_checkpoint_types' on your checkpoint storage (for example, 'FileCheckpointStorage.allowed_checkpoint_types').

触发条件:executor 状态里有未放行的自定义类型。它不是异常,是 WARNING 日志,工作流照常成功,存档静默缺失。处理:按报文里的 module:qualname 形态传 allowed_checkpoint_types,然后回到「存档数量 = superstep 数 + 1」这条硬判据上复核。

FAQ

Q:存档文件能不能直接看、直接改?

能看——顶层是 JSON,11 个键(workflow_name、graph_signature_hash、checkpoint_id、previous_checkpoint_id、timestamp、messages、state、pending_request_info_events、iteration_count、metadata、version)。但复杂对象是 __pickled__ 加 base64 嵌在里面的,改了就解不开。更重要的是安全边界:官方文档明确写了存档存储属于信任边界,不要从不可信或可能被篡改的来源加载。这一层用的是受限 unpickler,但它挡的是「类型不在白名单」,不是「文件被替换过」。

Q:InMemory 和 File 后端能不能混用?

接口一样(同一个 CheckpointStorage 协议),但行为有差别:InMemory 的列表就是插入顺序,File 的列表是文件系统顺序。我实测在 InMemory 上给两个不同名字的工作流建存档,两边各 3 个、互不串台,查询同样必须带 workflow_name。跨进程恢复只能用 File(或 Cosmos 那类外部存储),InMemory 出了进程就没了。

Q:恢复会不会重复执行已经成功的节点?

取决于你从哪个存档恢复。从 iteration 1 恢复时,第 1 个 superstep 之前的节点不会重跑;但从入口存档(iteration 0)恢复等于全量重放。所以「恢复」不是幂等保证,幂等要自己在 executor 里做。删掉父存档不影响子存档恢复这件事说明存档是完整快照,但这跟「重复执行」是两件事——它是靠跳过已完成的 superstep 实现的,不是靠去重。

Q:升级到 1.26.0 之后这些行为变了吗?

我逐条复跑了:存档数量规律、从末尾存档恢复的空转、白名单拦截后的静默缺失(存档数仍是 0)、图指纹不认代码、列表不排序(这次顺序是 [2, 1, 0])、delete 的幂等返回(先 True 后 False),全部一致。同构图在两版上算出的指纹也相同。所以本文的结论按「1.25.0 与 1.26.0 都成立」来读是安全的;再往后的版本我没有验证。

什么时候值得开 checkpoint

把上面这些拼起来,判断标准其实只有三条:单个 superstep 足够贵(值得为它付存档成本)、失败重跑有外部副作用(重复调用会出事)、以及你能接受「恢复点由调用方指定」这件事。反面的三种情况不要开:任务总时长只有几秒、executor 状态里有大量自定义对象却没配白名单(你会得到一堆看不见的失败)、以及把 get_latest() 直接当恢复点用(那是末位存档,恢复等于空转)。

最后一句话总结这一层的性格:它把「从哪一格继续」这件事交给了你,并且在你自己搞错的时候,倾向于安静地什么都不做。11-08 那篇讲的是节点之间接线层的六个静默失效,这一篇是同一类问题的存档层版本——两者的共同点不是 API 难用,而是失效的默认表现是成功。

👉 立即参与小米 MiMo 开放平台:国内领先的 AI 大模型开放平台,高性价比推理服务

👉 立即参与阿里云 AI:汇集爆款 AI 产品,热门模型专属权益优惠券助力企业创新加速

📌 本文由 AI 辅助生成并经人工审核发布 | TechPassive — AI 驱动的内容测试站点,专注于效率工具与 SaaS 真实评测

🔗 精选推荐工具

使用以下链接支持我们持续产出高质量内容(点击可直接前往购买):

作为亚马逊联盟会员,符合条件的购买会为我们带来佣金,不会增加你的购买成本。

☁️ DigitalOcean 云服务器 ⚡ Vultr 高性能 VPS 🤖 QoderWork 中国版(推荐有奖) ☁️ 阿里云爆款 AI 产品 📚 WordPress 实用书单 🧠 AI / 大模型书单 🏗️ 系统设计/云架构书单 🐳 Docker/K8s 书单 🐧 Linux 系统管理书单 🐍 Python 编程书单 🗄️ 数据库/PostgreSQL 书单 🚀 DevOps/SRE 书单 🤖 小米 MiMo 开放平台
← 返回首页