AI Agent 工具超时后怎样保留可恢复状态

AI Agent 工具调用超时后，应保存“这次调用做了什么、远端是否可能已经执行、下次应该查什么”，而不只是把聊天记录写到文件。对于有副作用的工具，超时先记为 unknown，恢复时优先查询同一业务操作；没有可靠证据时停止自动重试。

要改变的是工具适配层的状态约定，不是给模型再加一句“失败就继续”。下面给出一套自定义恢复协议，不是某个框架新发布的功能。以 smolagents 为例，其官方入口为 https://huggingface.co/docs/smolagents/index；本文的字段和恢复函数并非该库的内置 API。

把超时从失败状态里拆出来

假设工具负责创建一份测试报告。服务端可能已经接受任务，但客户端没有在限时内收到回执。此时“等待失败”与“报告创建失败”是两件事。若把二者都记成 failed，并让 Agent 自动重新调用，就可能创建重复报告。

Python 的 asyncio.wait_for 超时会取消所等待的对象并抛出 TimeoutError，但取消过程本身也可能耗时。这说明本地等待和取消有明确语义，不说明远端业务已回滚。HTTP 连接断开、协程取消与远端提交状态之间，仍需要业务协议补上证据。

本例建议至少保留四种状态：planned 表示仅有调用意图；pending 表示已进入可能发送的边界；unknown 表示结果未决；succeeded 表示已有可靠成功回执。确定的拒绝可以单独记为 rejected，但不要用超时推断它。状态改变必须保留依据，而不是由模型凭回答文字猜测。

在调用前保存最小恢复记录

给每一次业务意图生成稳定的 operation_id，并保存调用输入的引用 input_ref。同一操作因超时进入恢复时，不换业务标识、不偷偷改参数。工具版本 tool_version 也一起保存，防止恢复程序用新版字段解释旧输入。

下面是一次超时后的记录示意，严格 JSON 不含注释；这些字段由业务系统定义：

{
  "schema_version": 1,
  "run_id": "run-demo",
  "operation_id": "op-report-001",
  "tool_name": "create_report",
  "tool_version": "v1",
  "input_ref": "inputs/report-001.json",
  "state": "unknown",
  "attempt": 1,
  "remote_job_id": null,
  "result_ref": null,
  "resume_action": "query_or_review"
}

remote_job_id 为空表示没有拿到远端任务号，不表示远端没有任务。result_ref 是可复用结果或回执的受控引用，resume_action 是恢复标记，不是已执行动作。attempt 记录本地尝试次数；它不能代替稳定的业务标识。

在真正发请求前，把意图和输入落到可靠存储；跨过发送边界前先持久化 pending。这样即使进程在发出请求后、记录超时前崩溃，下次仍能找到未决项。单机文件可用临时文件加原子替换降低半写风险，但不能把文件重命名宣称为跨系统事务或完整断电保证；多进程服务通常需要事务、唯一约束和持久化配置。

超时只改变观察状态，不抹掉未决调用

超时时把本地记录更新为 unknown，保留原输入、业务标识和已经获得的远端任务号。不要在 finally 中清空整条记录，也不要覆盖为“已取消”后丢弃查询线索。若写 unknown 本身失败，恢复端仍应把遗留 pending 当成待核实项，而不是重新发送的许可。

收到成功响应时，要先可靠保存回执和结果引用，再允许依赖它的 Agent 步骤继续。另一个崩溃窗口是“远端成功、回执尚未落盘”，本地数据库不能单独消灭这个窗口。适配层需要用业务标识查询远端，或依赖远端明确承诺的幂等协议；无法确认就保留未知状态。

恢复入口也必须有并发约束。同一个操作只允许一个有效恢复认领者修改，采用事务条件更新和版本号等手段避免旧进程覆盖新结果。租约到期只能说明本地认领可以重新协调，不证明旧远端执行已经停止。对于会持续写入的旧工作进程，还需要业务系统实际支持的隔离或 fencing 约束。

把恢复选择写成确定性策略

恢复调度器读取未决记录，使用 operation_id 或 remote_job_id 查询权威结果。模型可以解释信息，但不能凭“应该失败了”决定重复创建报告。下面的 Python 函数只返回恢复动作，不访问网络、不写存储，也不声称是完整 Agent：

def recovery_action(record, remote_status):
    # 本函数只选择动作，不调用远端、不执行重试；并发认领需在事务中另行完成。
    if record["state"] == "succeeded":
        return "reuse_result"

    # 状态查询必须针对同一业务操作，且查询来源具有权威性。
    if remote_status == "completed":
        return "persist_receipt"
    if remote_status == "running":
        return "poll_later"

    # 超时和查不到记录都不足以证明远端没有执行，默认进入人工确认。
    return "review_required"

persist_receipt 的下一步是获取并保存可验证的远端回执及结果引用，再更新 succeeded；不是看到一个字符串就把任务跳过。poll_later 需要持久化下次查询时间和总体截止预算，不能忙循环。review_required 必须真实阻止自动重发，向操作者说明缺少哪种证据。

本例刻意不自动重试。“未找到”可能来自查询延迟、标识不匹配或服务尚未建立可查记录。如果业务接口确实支持相同幂等键重放，还需要核实键的作用域、保留时长、相同输入约束与并发语义，才能增加受限重试分支。只给 HTTP 请求附加一个自命名请求头，不会自动获得幂等保证。

迁移旧调用链时先检查这些场景

原来只有 try/except 的调用层，可以先增加未决记录，再接入恢复调度器，最后把“任何异常直接重试”收窄为有业务证据的分支。以下是应在自己测试环境中构造的场景与预期，不是本文的实测结果：

保存 memory 就能恢复吗

不能直接画等号。smolagents 的 memory 包含任务、动作、观察和错误，replay 用于查看既往步骤；官方 save 方法说明的是导出 Agent 相关代码与配置。它们不能单独证明远端副作用已经完成，也不能替代业务恢复记录。

超时后可以让用户直接再试一次吗

只有明确知道风险并得到相应授权时才考虑。默认应展示“结果未确认”，保留原操作查询入口；不要把一个无条件重试按钮伪装成无风险的继续。

保存整段工具输出够不够

还要保留结果与哪次输入、哪个版本相对应。只保存自然语言摘要很容易丢失远端任务号或错误边界。敏感输入与回执应限制访问，在恢复记录里尽量存受控引用，而不是凭据全文。

官方资料

smolagents memory：https://huggingface.co/docs/smolagents/tutorials/memory

smolagents 方法定义：https://huggingface.co/docs/smolagents/reference/agents

Python 等待与取消语义：https://docs.python.org/3/library/asyncio-task.html