AI 工具调用如何处理超时重试：幂等键、部分结果与人工接管

AI 助手调用搜索、库存、工单或数据库工具时，最危险的信号不是明确的 4xx/5xx，而是“客户端超时、服务端状态未知”。这时直接把原请求再发一遍，可能重复扣库存、重复创建工单，甚至把一个已经成功的动作误判为失败。稳妥的做法是把每次工具调用绑定到稳定的 call_id 和业务幂等键，先确认是否产生副作用，再决定重试、补偿还是交给人工。

先把一次工具调用拆成可追踪状态

在小实验里，把模型发出的工具请求看成一个普通任务，不依赖某家 SDK 的重试器。记录四个值就够开始：模型侧的 call_id、业务侧的 idempotency_key、当前动作 action 和执行状态 state。OpenAI 的 Responses 流式参考也把 function call 作为有独立标识和状态的输出项；这个思路适合直接映射到自己的任务表。

初始化：给写操作准备幂等键和截止时间

幂等键不要只用时间戳。相同用户意图的重试必须得到同一个键，建议由会话标识、工具名和业务动作组成，再做固定长度编码。下面的伪代码故意把关键字段写全，便于在日志和任务表中对照：

type ToolAttempt struct {
    CallID           string
    IdempotencyKey   string
    Tool             string
    State            string
    Attempt          int
    DeadlineUnixMs   int64
    SideEffectSeen   bool
}

func newKey(sessionID, tool, action string) string {
    return sha256Hex(sessionID + ":" + tool + ":" + action)
}

同一个幂等键还需要服务端支持查询或去重，否则它只是一条漂亮的日志字段。对于“创建订单”“发放优惠券”“写入工单”这类写操作，服务端应保存键与最终结果的映射；重试到达时，返回原结果或明确的处理中状态。

最小实验：只对明确可重试的错误再试一次

先把错误分成三类：网络连接还没建立、服务端明确返回临时不可用、服务端已经接受但客户端等待超时。前两类可以在截止时间允许时有限重试，第三类必须先查询幂等键。下面的流程不追求复杂，它的价值在于把“重试”前的判定固定下来：

调用工具
  ├─ 明确成功       -> 保存结果，结束
  ├─ 明确可重试错误 -> 退避后最多再试一次
  ├─ 客户端超时     -> 查询幂等键
  │    ├─ 已成功     -> 读取原结果
  │    ├─ 处理中     -> 转异步等待
  │    └─ 不存在     -> 仅在写入尚未发生时重试
  └─ 部分结果/未知   -> 先核对副作用，必要时人工接管

示例中的“最多再试一次”不是性能定律，而是为了让实验结果容易复查。生产环境应同时受总截止时间、下游限流、工具成本和动作风险约束。

运行检查：把重试结果和副作用分开验收

一次测试至少准备四个响应：成功、连接失败、明确的临时错误、客户端超时后服务端成功。检查日志时不要只看最后一行“retry success”，还要确认业务表里只有一条写入记录，且两次请求的 Idempotency-Key 相同。

check attempts 

如果第二次请求返回“已处理”，它不是重复成功，而是第一次动作的结果被安全复用。这个区别要在指标里单独记录，例如 deduplicated=true，否则排障时会把正常去重看成下游重复执行。

部分结果出现后，为什么不能继续盲重试

工具可能先写入一条任务记录，再在返回摘要时超时；也可能返回了前 20 条搜索结果，却在分页或排序阶段断开。此时先保存已见结果和版本号，执行一次状态核对。如果写入动作存在中间状态，就让工具提供“查询任务”或“查询幂等键”的只读入口；没有这个入口时，自动重试的安全性无法证明。

人工接管也要有最小上下文：用户意图、工具名、幂等键、最后一次已知状态、已看到的部分结果、尝试次数和截止时间。不要把整段对话原样丢给人工，既增加阅读成本，也可能泄露不必要的敏感字段。

扩展实验：读操作和写操作使用不同策略

读操作通常可以在同一截止时间内换节点或短暂重试，但也要考虑结果是否允许变化；例如库存查询跨越了缓存刷新点，重试得到的新值不一定代表第一次请求的真实时刻。写操作则优先查询状态、复用原结果，只有能证明没有副作用时才允许重放。

• 读操作：记录查询版本或时间范围，限制总重试预算。
• 可去重写操作：固定幂等键，支持“已成功/处理中/不存在”查询。
• 不可安全重放的动作：超时或部分结果后直接进入 handoff，让人工或补偿流程继续。

常见问题

请求超时后立刻重试可以吗？

只有在动作明确是只读，或服务端用同一个幂等键保证去重时才适合。客户端超时本身不能证明服务端没有执行。

幂等键应该每次重试都换吗？

不应该。表示同一次业务意图的重试应复用同一个幂等键；新的用户意图才创建新键。

部分结果是不是等于成功了一半？

不是。部分结果只说明调用链上已有信息或副作用线索，仍需通过查询接口核对最终状态。

什么时候必须人工接管？

当写操作状态无法确认、补偿动作可能再次产生副作用，或重试预算耗尽时，应停止自动重放并交给人工。

收尾：让失败分支成为可验收的产品能力

一个可靠的 AI 工具调用器，不是把重试次数调大，而是能回答“这次动作到底发生没有”。把 call_id、幂等键、状态核对、部分结果和人工接管写进同一条可追踪链路，再用成功、超时、去重和副作用检查做回归，才有资格把自动化范围逐步放大。