幂等键

幂等性指对同一操作发起多次调用产生的结果与调用一次完全相同，应为每个业务动作生成唯一幂等键并将结果持久化绑定到该键以防止重复执行

幂等键是客户端为每个操作生成的全局唯一键（通常是UUID），随请求发送给外部服务；服务端在处理前查询该键是否已存在，若存在则返回上一次结果，不再执行实际动作。

实现幂等的常见手段是客户端生成唯一的幂等键随请求发送，服务端记录该键对应结果，收到重复请求则返回缓存结果

实现幂等性的常见手段包括为每次写操作分配唯一的请求ID（idempotency key），或采用条件写入（compare-and-swap）仅当目标数据处于预期状态时才执行写入

幂等性指同一操作无论执行一次还是多次最终结果应相同，常见实现是为每次请求生成全局唯一请求ID（如UUID）供服务端去重

校验失败时应将具体错误反馈给模型让其修正，但重试必须设置次数、超时时间和成本控制，因为重试会增加延迟和资源消耗

幂等键（idempotency key）机制：为每个动作分配固定ID，重试时发送同一个ID，支付系统会拒绝重复请求。OpenAI文档也推荐此做法。

对 LLM 调用，5xx 与超时值得重试，而 400 类错误重试通常无意义；带副作用的请求重试可能造成重复计费，应结合幂等键或请求去重设计。

重试只适用于幂等请求或可安全重复的操作，对有副作用的调用应配合幂等键使用。

timeout应被视为'我不知道'而非'否'，解决方案是由代码生成幂等键随重试发送，使预订系统识别相同键并返回首次结果。

幂等键的关键设计点包括生成时机（应在首次请求前生成，而非每次重试时重新生成）、作用域（通常绑定到特定用户和操作类型）、有效期（常见如24小时）和存储（需要持久化，并考虑并发原子性）。

社区讨论中，共识度最高的做法是把去重责任下沉到API层，由Agent在每次请求中携带幂等键，服务端识别重复键并返回第一次的结果。

Stripe等支付平台的经典做法是使用幂等键，服务端识别重复键并返回第一次的结果，而不是执行两次操作。

Stripe的幂等实现允许在请求参数不一致时返回错误，防止键被误用。

对于资金、邮件和外部写入，始终需要幂等键，幂等键能防止重复但不能解决发送未经审批载荷的问题。

为Agent的每个改变状态的动作绑定唯一幂等键，重试时先检查该键，若动作已完成则直接返回缓存结果，可实现幂等保护。

审批必须绑定到精确动作（如这笔订单、这个金额、这个幂等键），一旦状态变化，需要重新获取审批。

幂等键的有效性取决于契约细节：作用范围、是否校验同键请求参数一致性、保留时长、并发同键请求处理方式；仅携带幂等键并不构成永久防重复保证。

对于没有幂等键的外部工具，失败后的第二次运行就是真实重放，目标系统会收到两次调用。

至多一次执行需要端到端的去重机制（如幂等键、调用日志、目标系统幂等支持），跨越决策层之外的重试、重启和网络分区场景。