Agent 工具调用超时导致幂等性缺失，易引发重复下单风险

在企业内部推进 AI Agent 应用时，往往会碰到一个并非模型本身能力所致的难点：工具在真实环境中的不确定性。开发者习惯把工具当作普通的 API 函数，只要在 JSON Schema 中声明参数，模型能够正确传递，便认为一切已就绪。然而在生产环境里，“调用成功”与“实际执行成功”之间常常留下模糊的空白。

写操作超时的典型困境

最让人揪心的情形通常出现在写入类任务。假设 Agent 调用了 create_report_job("weekly")，目标是启动一次周报生成。理想流程为：Agent 发出指令 → Runner 调用工具 → 后端处理 → 返回成功回执 → Agent 向用户反馈完成。实际运行时，网络抖动、服务响应迟缓或中间件超时都会导致 Runner 在等待返回时抛出 Timeout 异常。此时需要决定是否进行重试。

如果直接让 Runner 再次发送请求，风险极高。因为超时并不等同于操作未完成。请求可能已抵达后端，并在数据库中完成写入，只是确认信息在返回途中丢失或因响应时间过长被视为超时。盲目重试会导致任务队列中出现两个相同的任务。对查询类操作影响不大，但在“下单”“扣费”“创建任务”等写入场景中，重复执行会产生数据冗余甚至资金损失。

放弃重试的隐患

相反，为了避免重复而完全不做重试，同样会面临任务彻底丢失的可能。若 Worker 在执行期间、数据库 commit 之前发生崩溃，整个请求会在后台消失，用户只会看到超时错误，业务流程因此被中断。

通过唯一标识实现幂等

在“重试可能导致重复，放弃重试可能导致丢失”的两难局面中，核心并非对超时时间的微调或采用指数退避等复杂策略，而是将“意图”与“结果”分离，并为每一次请求绑定唯一的身份标识。后端服务应依据 Idempotency-Key 来判断是否为同一意图，从而确保即使 Runner 多次重试，只要该标识保持不变，系统仍只会创建一个任务。官方文档指出，使用 Idempotency-Key 可以保证请求的幂等性（参见 https://developer.example.com/idempotency）。

实验验证

作者构建了一个基于 Python 与 SQLite 的本地实验，以排除模型和网络因素的干扰。实验模拟了两类极端崩溃：进程在数据库 commit 前突停，以及 commit 后但在返回前突停。结果显示，在没有唯一标识的情况下，重试会在 SQLite 中产生多条相同的 Job 记录；而加入基于 Idempotency-Key 的唯一约束后，无论崩溃多少次，最终数据库中只保留一条记录，达成幂等。

实践建议

在设计 AI Agent 与工具交互的接口时，应强制要求客户端提供由调用方生成的唯一请求 ID。这样，无论网络多么不稳，或服务响应多慢，都可以安全地启用重试机制，避免因重复创建导致的业务风险。此类幂等性设计不应视作可选项，而是实现可靠 AI Agent 的基础设施之一。