Agent 跑了三天显示 completed，怎么证明它真做完了？从 OpenAI Agents API 的会话与恢复文档，拆出长任务的五层完成记录

Agent 跑了三天，状态栏终于亮起绿色的completed。你敢直接把结果交给下游吗？

这个问题正在变得越来越实际。按照 OpenAI 官方文档的描述，Agents API 是用于构建持久云端 Agent 的托管框架：平台管理会话、编排、上下文压缩和恢复，应用侧提供工具并选择执行环境。文档呈现的已经不再是一次问答，而是一段可以持续推进、调用工具、保存工作的执行过程。换句话说，Agent 能“连续工作”的能力是平台给的，但“证明完成”的责任仍然在你手里。

一、completed 只说明运行走到了终点

先把最容易被忽略的一句话摆在前面：官方文档明确提醒，turn 显示为completed，并不保证其中每个工具都执行成功；会话处于空闲状态，也不等于任务成功。会话文档要求开发者继续检查输出和工具结果。

为什么会这样？因为一次工作循环（turn）是平台的执行单位，它关心的是“这一轮跑完了吗”，而不是“你的业务目标达成了吗”。turn 可能完成、失败或被取消——这三态描述的是执行过程，不是业务结果。日志显示浏览器访问了某个页面，不代表读到了正确版本；记录显示文件写入成功，不代表格式符合投稿要求；子 Agent 都正常返回，也不代表汇总时没有遗漏冲突结论。

一个真实任务至少包含五层完成状态，从下往上依次是：

1. 运行层：turn 的状态（completed / failed / cancelled）；
2. 工具层：每次工具调用是否成功、返回了什么；
3. 产物层：生成的文件、消息、提交是否存在且可读；
4. 内容层：产物内容是否基于正确的输入版本、是否符合格式与一致性要求；
5. 验收层：业务标准是否满足，例如“日报包含全部三个数据源且数字对得上”。

可观测性负责留下前四层的证据，验收标准负责判断证据是否足够。少了第五层，completed只是一个漂亮的绿色图标。

二、任务身份：业务幂等不能靠 API 幂等代替

长任务跨天、跨设备，第一件事是给任务一个稳定的身份。比如一个日报任务可以命名为：

daily:2026-10-18

当天手动补跑或断线恢复时，只要处理的仍是同一个逻辑任务，就复用这个身份；如果是显式要求重新生成，则创建新的修订版本，而不是悄悄覆盖原结果。

Agents API 的会话文档也建议为每一次逻辑消息提交创建幂等键：请求因超时或响应丢失而自动重试时，应复用相同的会话 ID、消息和幂等键；新的逻辑提交则使用新的键。这项机制解决的是请求层的重复提交问题。

但要注意边界：API 幂等不能替你判断“生成今天的日报”和“重新生成今天的日报”是不是同一件事。业务系统仍需定义自己的任务身份和修订规则。两层幂等各管一段，混为一谈迟早出事。

三、业务时间与观察时间：输入版本要钉死

长期任务经常跨过数据变化的边界。Agent 上午读取一篇文章，下午恢复时原文已经更新；原计划七点生成日报，电脑十点才从休眠中恢复。任务日期没变，实际处理的资料却可能已经不同。

因此完成记录至少要区分两种时间：

• 业务时间：结果属于哪一天、哪一个计划任务；
• 观察时间：系统实际在什么时候读取了什么资料。

配套的做法是把输入版本钉死：记录每份资料的 URL、版本号、抓取时间或内容哈希。恢复运行时先比对当前输入与记录中的版本，不一致就显式决策——要么用旧版本补完，要么声明这是新修订。这样三天后产出的报告，才能回答“你引用的是哪个时刻的世界”。

四、恢复时只补做未完成的工作

长任务中断后，最直觉的做法是重新运行。但失败的 turn 仍可能已经修改文件或调用了外部工具——直接重跑，反而可能扩大问题。

Agents API 的错误恢复文档建议：在重试前取回会话、turn 和已保存的 items，检查已经发生的动作；遇到暂时性错误，再按照间隔和次数限制，只继续未完成的工作。

可以把恢复顺序压缩成五步：

1. 查询最终状态，不根据断线现象猜测结果；
2. 核对已经完成的工具调用和外部副作用；
3. 找到已有产物并验证内容版本；
4. 只补做缺失步骤；
5. 达到重试上限后转人工处理。

对于三天级别的任务，“失败就重跑”是危险默认值；上面这套顺序才是。

五、用行为变更日志让完成记录可被复核

完成记录不仅要回答“这次做完了没有”，还要让下游团队能复核“为什么这次和上次不一样”。参考《AI 更新日志问题：为什么你的提示词更新正在破坏其他团队的工作》提出的框架，一次行为变更至少应记录五项：

1. 版本和日期：SemVer 字符串、时间戳、可读发布名；
2. 变更内容：Prompt 差异、模型 from/to、工具 schema 或检索器变化——“改进了提示词”不是一个条目，而是一个道歉；
3. 变更原因：工单、评估结果、客户投诉或供应商弃用通知；
4. 行为差异：黄金数据集变更前后通过率，附 3–5 个样本输入的新旧输出并排对比；
5. 迁移指南：下游必须做、建议做或可以忽略的事，明确写出“无需操作”的情况。

配套纪律有两点：一是让评估门禁（eval gate）为变更日志背书——每次 Prompt PR 跑黄金数据集，差异发布到 PR 中并机械地决定版本号；二是不要把latest作为推荐默认值，让浮动版本变得显式且费力，否则每次发布都有一批使用者给你发报警。

适用范围与局限

这套五层记录 + 断点恢复清单，适用于跑数小时到数天、调用外部工具、可能中断恢复的 Agent 任务；对秒级问答类调用属于过度设计。同时要诚实地说：它解决的是“可核查”，不解决“正确”——黄金数据集覆盖不到的用例、验收标准写漏的格式问题，依然要靠人和持续运营去补。

Agent 跑得越久，completed这个词就越廉价。真正的完成证明，是一份别人能按图索骥、逐层复核的记录。

参考资料

以下链接为本文使用的公开资料。事实依据与检索摘录保存在本地记录中；资料内容与适用范围以原始页面为准。

• Agent 已经能连续工作几天，但你怎么证明它真的完成了？-腾讯云开发者社区-腾讯云
• AI 更新日志问题：为什么你的提示词更新正在破坏其他团队的工作