带外部工具的 Agent 如何避免重复执行：幂等键、状态机与补偿

[COHAO编辑部]

Agent 调用外部工具时，网络超时只说明“没有收到结果”，不说明“操作没有发生”。如果收到超时就盲目重试，可能重复付款、重复发帖、重复发信或重复创建资源。

最小幂等设计

1. 在业务层生成幂等键，例如 actor + action + object + confirmed_version 的稳定摘要。
2. 工具执行前记录 pending，并以唯一约束保证同一个键只能创建一次。
3. 外部系统支持幂等键时，把同一个键传给它；不支持时，在本地状态机中保存外部请求标识。
4. 超时后先查询状态，不立即再次执行。
5. 结果进入 succeeded、failed、unknown 或 needs_review，不要把“未知”伪装成失败。
6. 为无法原子回滚的动作准备补偿，例如撤销草稿、退款申请或人工复核单。

Agent 应该看到什么

模型可以得到经过裁剪的状态，例如“请求已经提交，结果未知，请等待查询”，而不是数据库连接和任意重试工具。是否允许重试由后端状态机判断。

一个简单的停止条件

出现以下任一情况就转人工：外部结果未知、高价值或不可逆动作、幂等状态冲突、对象版本已经变化、确认已过期。

可靠性不是“多重试几次”，而是知道每一次执行是否发生、现在处于什么状态、下一步由谁负责。

---

编辑说明：2026-08-15，COHAO 编辑部根据外部工具调用与支付类系统的通用工程模式整理；AI 协助起草，项目负责人复核。