10. 如何防止有副作用的操作重复执行

假设 Agent 调用工具发送一封邮件。服务端已经接受请求，本地进程却在保存结果之前退出。恢复后，日志里只有“调用开始”，没有“调用完成”。

此时直接重试，收件人可能收到两封邮件。

幂等解决的是什么

幂等表示同一个操作执行一次或多次，外部可观察结果相同。读取文件天然接近幂等；发送消息、创建订单和追加记录一般不是。

运行时可以为有副作用的调用生成幂等键。服务端看到相同键时返回第一次结果，而不是再次执行。

幂等键必须与具体参数绑定。若参数变化却复用旧键，运行时可能错误返回旧结果。

三类工具采用不同恢复方式

不能因为所有工具都使用同一个调用协议，就对它们使用同一种重试策略。

先记录意图，再执行动作

工具执行前，运行时先持久化参数摘要、权限结论和幂等键；外部调用完成后再保存外部标识和结果。这个顺序缩小了“外部已执行、本地没有任何记录”的窗口。

它仍不能消除所有不确定性。网络超时可能发生在服务端完成之后、响应到达之前，所以服务端幂等支持或状态查询仍然重要。

模型不应决定是否安全重试

模型可以根据错误说明提出重试，但最终判断需要工具元数据：

• 操作是否有副作用。
• 服务端是否支持幂等键。
• 当前状态是否可查询。
• 已经重试多少次。
• 用户授权是否仍然有效。

这些是确定性信息，不应只通过自然语言提示交给模型判断。

故障实验怎样做

在工具返回成功后、写入 tool.completed 前强制终止进程。恢复时检查：

1. 是否复用相同幂等键。
2. 是否先查询外部状态。
3. 是否避免再次请求用户批准同一动作。
4. 参数变化时是否生成新操作。
5. 无法确认时是否进入 unknown，而不是自行重试。

“最多重试三次”只能限制重复次数，不能防止重复副作用。可靠恢复依赖动作语义、持久化顺序和外部接口共同支持。

请求指纹防止错误复用

幂等键对应一次逻辑动作，请求指纹对应这次动作的规范化参数。服务端或运行时再次收到同一键时，先比较指纹；一致则返回原结果，不一致则拒绝冲突，而不是把旧结果返回给新参数。

指纹计算前要固定字段顺序、路径形式和默认值。否则语义相同的两个请求可能得到不同指纹，或语义不同的请求因省略字段而被误判为相同。

幂等记录也需要生命周期

去重记录不能无限保留，也不能在任务仍可能恢复时过早删除。保留期至少覆盖客户端最大重试窗口、队列延迟和人工恢复时间。过期后再次使用同一键，应形成新动作还是拒绝，需要在工具契约中明确。

验收不只检查没有重复资源，还要检查并发提交相同键时只有一个执行者、失败结果是否可重试、参数冲突是否被拒绝，以及查询接口能否返回第一次执行的外部标识。

幂等键保护同一意图

幂等键与请求指纹共同定义一个逻辑操作。相同键配不同收件人或正文必须拒绝；相同参数但不同业务意图也不应意外合并。

记录状态至少包括 reserved、executing、succeeded、failed_retryable 和 failed_final。重复请求根据状态复用结果、等待执行或安全重试，而不是只检查键是否存在。

本地事务不能覆盖远端副作用

远端服务接受邮件后、本地成功记录提交前，进程仍可能终止。这是跨系统的不确定结果窗口。运行时把幂等键传给远端、重试前查询业务状态，或使用明确的补偿动作；补偿事件不能删除原始事件。

实验在意图落盘、远端接收和本地结果提交的前后分别终止进程。每个断点重复恢复，外部系统最终只能有一个逻辑对象，轨迹可以有多次尝试，但只能采纳一个结果。