Agent 工具执行：幂等、超时与断点恢复

Agent 的动作必须经过执行层；环境返回、任务状态与业务副作用需要分别记录。

图：Agent 的动作必须经过执行层；环境返回、任务状态与业务副作用需要分别记录。来源：Generative AI agent architecture，作者 Marxav，许可 CC BY-SA 4.0。

问题现场

Agent 已成功创建工单，网络却在响应返回前中断。模型只看到 timeout，于是再次创建工单。用户现在得到两个重复任务。超时表达的是客户端不知道结果，并不证明服务端没执行。

这类问题靠“重试三次”或“Prompt 要求不要重复”无法解决。执行层必须将用户意图、尝试次数和业务效果区分开。

任务有稳定 task_id，每个业务动作有 action_id，网络重试有 attempt_id。创建工单属于写操作，读取状态属于只读操作。服务端支持幂等键或按业务标识查询；若两者都不支持，就不能承诺可靠消除所有重复副作用。

任务状态至少包括待规划、待确认、待执行、执行中、结果未知、成功、失败、取消。模型消息历史帮助理解上下文，持久状态则决定下一步能否执行；仅把一段聊天存在数据库不足以构成可靠恢复。

对同一次已授权创建动作生成稳定幂等键，并记录用户、租户、参数摘要和结果。网络重试复用同一个键；用户明确发起另一笔创建才用新键。若每次调用都重新生成随机键，服务端会把它们视为不同动作。

同键不同参数必须报冲突，而不是默默沿用旧结果。确认也绑定参数摘要和有效范围：用户确认创建 A 工单后，模型改成 B，必须重新走适用的授权与确认流程。

第一次请求超时后先标记 unknown，尝试按幂等键或业务 ID 查状态。如果已成功，读取原结果；若确认未执行且仍允许操作，再重试；若无法确定，保持待核实或人工接管。不要把不确定状态直接转成“失败所以重做”。

数据库中的幂等记录与业务创建若在同一事务内提交，可以减少“业务成功但去重记录丢失”的窗口。跨系统写入则还需对端幂等或事务消息等设计。单机锁不能解决进程崩溃和多实例竞争。

规划节点输出后持久保存；工具调用前记录待执行意图，调用后记录结果。恢复时可重算纯计算节点，但带副作用的动作先查持久业务结果。框架 checkpoint 能保存执行状态，却不能自动给远程工具提供事务性。

同一任务可能从第 5 步恢复，但第 4 步使用的文件或权限已经改变。恢复时要校验资源版本、授权与截止时间，不能把旧检查无限期当作有效。

设置最大步数、总时长、token、工具次数和业务成本预算。若同一动作和参数反复出现且没有新信息，应停止并报告缺口。工具错误分为参数错误、权限错误、临时故障、确定失败和结果未知，不能都交给模型任意解释。

补偿不是数据库回滚。例如已发出的邮件无法真正撤回；取消工单也可能留下业务记录。只对有明确补偿语义的动作设计自动补偿，其余需要展示状态和人工处理。

至少注入四种故障：执行前断网、执行成功后丢响应、持久化结果前进程退出、两个 worker 同时恢复。验收看业务系统里实际工单数量和内容，不能只看 Agent 最终说“完成”。

还要测同键不同参数、确认后改参数、任务取消后迟到的回调、权限中途撤销。重试次数应受总 deadline 约束，并使用退避与抖动，避免故障时大量实例同时重试。

日志关联 task、action、attempt 和外部业务 ID。对敏感参数保存受控摘要或引用，兼顾可追踪与访问隔离。用于回放的环境应该是沙箱或只读，不能通过重放日志再次执行真实写操作。

“至少一次投递”描述调用可能重复；“幂等”要求重复同一意图不产生额外业务效果。“恰好一次”若没有指定边界容易误导：网络、执行、消息投递和业务效果是不同层次。面试应讲清保证覆盖哪些操作、保留多久、依赖什么条件。

幂等记录有过期时间时，超过保留窗口的迟到重试可能再次产生副作用，应定义最大重试周期及处理策略。用户取消也不证明远端已停止，仍需查询或补偿。

工具返回成功但最终任务未完成？ 工具成功只是步骤结果，任务还需验证目标状态，例如工单是否属于正确项目、字段是否齐全。

所有只读请求都能无限重试吗？ 不能；读取也占配额和资源，且数据会变化，要遵守时限与一致性需求。

90 秒回答： 我用稳定业务动作 ID 去重，将超时标为结果未知并先查状态；checkpoint 负责恢复位置，对端幂等负责副作用。恢复重新校验授权和版本，最后用外部业务状态判定完成，并通过丢响应和崩溃测试验证。