AI Agent工具调用设置超时与幂等键的执行边界

AI Agent 调用外部工具时，超时和幂等键解决的是两类不同问题：超时限制等待时间，幂等键限制同一个业务意图产生多次副作用。生产实现不要把二者合成一个“失败就重试”开关，而要把截止时间、结果确定性和执行账本连起来。

划分读取操作与外部副作用

先给每个工具写一张小表：它是只读查询、可重复写入，还是不可逆写入。查询订单状态通常可以重试；创建订单、扣库存、发送通知则必须让服务端识别同一业务请求。只在客户端保存一个随机 UUID 不够，因为服务端若不持久化它，重试仍可能再次执行。

用统一截止时间控制工具调用

不要分别给模型循环、工具函数和 HTTP 客户端设置 30 秒，否则外层已经超时，内层仍可能继续占用连接。更稳妥的做法是由 Agent 入口生成一个绝对 deadline，适配器每次调用前计算剩余时间，剩余时间不足时直接返回 timeout。

type ToolResult = { status: "ok" | "timeout" | "unknown" | "failed"; data?: unknown };

async function callToolOnce(
  execute: (signal: AbortSignal) => Promise,
  deadlineMs: number,
): Promise {
  const remaining = deadlineMs - Date.now(); // 统一截止时间，避免层层叠加超时
  if (remaining  controller.abort(), remaining); // 到点中止本地等待
  try {
    return { status: "ok", data: await execute(controller.signal) };
  } catch (error) {
    if (controller.signal.aborted) return { status: "unknown" }; // 请求可能已到达服务端
    return { status: "failed", data: String(error) };
  } finally {
    clearTimeout(timer); // 清理定时器，避免 Agent 长循环泄漏资源
  }
}

这里的 unknown 很关键：客户端超时只说明没有在期限内收到结果，不能证明服务端没有执行。对外部副作用工具，unknown 应进入查询确认或补偿流程，而不是直接再次创建。

用幂等键账本保护写操作

幂等键建议由业务对象、动作和一次业务意图组成，例如 order:create:user-42:cart-981，而不是每次重试都重新生成。服务端收到请求后，把键、参数指纹、状态和结果摘要写入账本；第一次执行完成后，后续相同请求直接复用结果。

type Ledger = { fingerprint: string; state: "running" | "done"; result?: unknown };

async function idempotentWrite(key: string, input: unknown, run: () => Promise) {
  const fingerprint = stableJsonHash(input); // 参数指纹用于阻止同键改参数
  const old = await ledger.get(key);
  if (old && old.fingerprint !== fingerprint) throw new Error("idempotency_conflict");
  if (old?.state === "done") return old.result; // 重试直接复用第一次结果
  await ledger.putIfAbsent(key, { fingerprint, state: "running" }); // 需要原子占位
  const result = await run();
  await ledger.markDone(key, result); // 结果落账后再向 Agent 返回
  return result;
}

账本的 putIfAbsent 必须是原子操作；多实例 Agent 同时提交相同键时，只允许一个执行者获得占位。账本还要设置保留周期，周期取决于业务重复窗口，不能为了省空间立即删除。

按结果确定性决定是否重试

重试条件至少分三类：请求尚未发出，可以安全重试；服务明确返回可重试错误，可以按上限退避；请求已发出但客户端超时，结果未知，必须先查询状态。退避时间不能突破总 deadline，建议记录 attempt、elapsed_ms、idempotency_key 和最终状态。

AWS 的可靠性建议也强调先确认操作具备幂等性，再实施有限重试；Stripe 的幂等请求说明则指出，同一个键应与请求参数一起约束，参数冲突不能静默复用。它们共同说明一个边界：重试是传输策略，幂等是业务语义，不能相互替代。

用指标和故障演练收紧边界

上线前至少演练四种情况：工具尚未发出就超时、服务端已执行但响应丢失、Agent 进程在 running 状态重启、相同幂等键被不同参数再次提交。检查超时率、unknown 占比、幂等冲突数、重复副作用数和账本滞留时长；其中重复副作用应设为零容忍告警。

最终检查清单是：每个写工具都有幂等键；键与参数指纹绑定；账本占位原子化；总 deadline 能覆盖所有重试；unknown 有查询或人工恢复路径。做到这五点，Agent 才是“有限时间内可恢复”，而不是“超时后不断重复”。

常见问题

超时后马上换一个幂等键重试可以吗？

不建议。换键会把同一业务意图伪装成新请求，只有确认第一次没有执行且业务允许时才应创建新键。

幂等键放在模型提示词里安全吗？

不应依赖模型记忆。由编排层根据业务上下文生成，并在服务端校验参数指纹。

只读工具也需要幂等键吗？

通常不需要业务幂等键，但仍需要 deadline、最大重试次数和取消信号，避免查询风暴。