Agent 重试一次 API,同一笔订单退了两次款
超时、有节制的重试和每个操作固定一个幂等键,约 80 行 TypeScript,今天就能用到项目里。
要点速览
- 有副作用的 API 只有支持幂等时,重试才安全。
- 幂等键每个业务操作只生成一次,所有重试复用同一个键,并且只附加在 POST 请求上。
- 重试需要预算:如果每一层都各自重试,数据库负载可能放大 243 倍。
一笔订单退了两次款,财务团队第二天早上才发现。设想一位刚到客户现场第二周的前线部署工程师(FDE)。团队部署的客服 Agent 有一个名为 createRefund 的工具,它调用客户内部的退款 API。某天下午网络不稳定,第一次请求没有收到响应,Agent 又试了一次,钱就退出去了两遍。
问题不在模型,而在包装 fetch 的那十几行代码。大家都觉得写这几行是杂活。对 FDE 来说,API 调用层是 Agent 接触客户真实资金、库存和数据的地方,这段代码必须一次写对。
这一层需要三样东西:超时、有节制的重试和幂等键。下文逐一讲解,最后把它们合成一个完整的 TypeScript 函数,可以直接复制,按自己的项目修改。
为什么简单重试很危险
Amazon Builders’ Library 说得很直接:有副作用的 API,除非支持幂等,否则重试并不安全。退款请求超时后,客户端无法判断服务器是否已经处理。可能数据包根本没送到,也可能钱已经转出,只是响应在返回途中丢了。
幂等键解决的正是这种不确定性。Stripe 的文档写道,发生连接错误时,可以放心重发请求,不必担心创建第二个对象或把一次更新执行两遍。
机制很简单。对每个键,Stripe 会保存第一次请求的状态码和响应体,无论成功还是失败,之后每次重复请求都返回同样的结果。
“无论失败”这几个字很关键。按 Stripe 的说法,如果第一次尝试返回 500,用同一个键重试拿到的还是那个 500。因此,用旧键重试主要适用于失败发生在传输途中的情况,比如超时或连接断开,也就是客户端根本没收到任何结果的时候。
超时该设多长?
默认值通常远超 Agent 的需要。OpenAI 的 Node SDK 默认超时为 10 分钟,对耗时较长的模型调用来说合理,但查询订单的 API 绝不该等这么久。
Amazon 给出了一种有依据的选法。先确定能接受多大比例的“误判”超时,即多等一会儿本可成功的请求,再取下游服务对应的延迟百分位数,例如 p99.9。
如果退款 API 的 p99.9 是 1.2 秒,把超时设在 1.2 秒左右,就意味着接受约 0.1% 的请求被不必要地中断。
在 Node 中不需要用 setTimeout 自己拼。AbortSignal.timeout() 返回一个到时自动中止的信号,触发时以名为 TimeoutError 的 DOMException 中止。这样代码就能区分超时和用户主动取消,这两种情况需要不同的处理。
重试几次才够?
OpenAI 的 SDK 是不错的参考设计。根据其 README,它会自动重试两次,使用较短的指数退避,默认重试 408、409、429 错误、所有 500 及以上的错误以及连接错误。它不重试 400 或 401,因为重发同样的请求不会改变结果。
只有退避还不够,还要加抖动。Amazon 对抖动的解释是:在等待时间里加一点随机性,让重试在时间上分散开。没有抖动,一千个同时失败的 Agent 会话会在同一时刻重试,再次把服务压垮。
最大的危险是多层叠加重试。Amazon 举过一个例子:一个五层系统中每层都独立重试,数据库负载被放大 243 倍。
反推一下,243 是 3 的 5 次方,相当于每层最多尝试三次。Amazon 的解决办法是用令牌桶在本地限制重试:令牌用完就停止重试,把错误向上抛。
TypeScript 完整实现
下面的 callApi 函数把三者结合在一起。注意生成键的那一行:它放在循环之外。
import { randomUUID } from "node:crypto";
type Method = "GET" | "POST" | "DELETE";
interface CallOptions {
method: Method;
url: string;
body?: unknown;
timeoutMs: number; // 取自下游 API 的 p99.9
maxRetries?: number; // 默认为 2
idempotencyKey?: string; // 如果操作已有键,就传进来
signal?: AbortSignal; // 来自 Agent 或用户的取消信号
}
// 令牌桶:最多 10 次重试,每秒补充 1 个令牌
class RetryBudget {
private tokens = 10;
constructor() {
setInterval(() => (this.tokens = Math.min(10, this.tokens + 1)), 1000).unref();
}
take(): boolean {
if (this.tokens <= 0) return false;
this.tokens--;
return true;
}
}
const budget = new RetryBudget();
// 带键的请求:不重试 5xx,服务器已保存结果,会返回同样的错误
const isRetryableStatus = (s: number, hasKey: boolean) =>
s === 408 || s === 409 || s === 429 || (!hasKey && s >= 500);
const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
const backoff = (attempt: number) =>
Math.random() * Math.min(5000, 200 * 2 ** attempt); // 抖动
export async function callApi(opts: CallOptions): Promise<Response> {
const maxRetries = opts.maxRetries ?? 2;
// 整个操作只生成一次;只有 POST 带键
const key =
opts.method === "POST" ? opts.idempotencyKey ?? randomUUID() : undefined;
for (let attempt = 0; ; attempt++) {
// 每次调用有独立的超时,并与调用方的取消信号合并
const timeout = AbortSignal.timeout(opts.timeoutMs);
const signal = opts.signal ? AbortSignal.any([opts.signal, timeout]) : timeout;
try {
const res = await fetch(opts.url, {
method: opts.method,
headers: {
"Content-Type": "application/json",
...(key ? { "Idempotency-Key": key } : {}), // 请求头名称取决于具体 API
},
body: opts.body ? JSON.stringify(opts.body) : undefined,
signal,
});
const canRetry =
isRetryableStatus(res.status, key !== undefined) &&
attempt < maxRetries &&
budget.take();
if (!canRetry) return res;
await res.body?.cancel(); // 重试前丢弃响应体,释放连接
} catch (err) {
// 调用方主动取消:立即停止,不重试
if (opts.signal?.aborted || attempt >= maxRetries || !budget.take()) throw err;
// 其余情况是 TimeoutError 或网络错误:用同一个键重发
}
await sleep(backoff(attempt));
if (opts.signal?.aborted) throw opts.signal.reason;
}
}
回到那笔退款。第一次调用超时,catch 块收到 TimeoutError,函数随机等待一段时间后用同一个键重发。如果服务器已经处理过上一次请求,就返回保存的结果,不会再退第二次款。
修改这个函数时,有两个小细节值得保留。调用方的取消信号通过 AbortSignal.any() 与超时合并,Agent 中途被停止时,函数会立即退出,而不是继续重试。另外,为重试而放弃的响应会取消其响应体,连接不会一直挂在连接池里。
这里的重试条件有一点比 OpenAI 的 SDK 更窄:带键的请求不重试 500 及以上的错误。原因就在前面讲的机制。对于像 Stripe 这样按键保存首次结果的 API,500 之后用同一个键重发,只会拿回同一个 500,白白消耗预算。
GET 和 DELETE 不带键,所以照常重试 5xx。如果客户的 API 处理键的方式不同,放宽这个条件前先问清楚。
当 409 表示与另一个并发请求冲突时,仍然值得重试。Stripe 指出,参数校验失败或请求与正在处理的请求冲突时,它不会保存结果,所以这些情况下重发是安全的。
现场常见错误
最常见的错误是在循环内生成键。每次重试都带着新键,服务器把它当成新操作,幂等实际上就失效了。
Agent 还会带来一个更隐蔽的变体:模型在后面的步骤里再次调用同一个工具,而调用层为这次调用生成了新键。如果编排器可能重跑某个步骤,就从该步骤的 ID 派生键,通过 idempotencyKey 传入。
第二个错误是用不同的参数复用同一个键。Stripe 会把新参数和原始请求比对,不一致就返回错误。它还可能在 24 小时后删除键,所以第二天重跑的任务不能依赖旧键。
第三个错误是给每个请求都加键。Stripe 说明 GET 和 DELETE 本身就是幂等的,给它们带键没有作用。键里也不应放邮箱或账号:Stripe 建议使用 UUID V4 或熵足够的随机字符串,最长 255 个字符,不含敏感数据。
最后一个错误最难发现:在 SDK 之上再叠加重试。如果你的工具封装了一个本身已会重试两次的客户端,Agent 的编排器又在外面重试,放大倍数在没人察觉时就已经成倍增长。只选一层负责重试,其他层全部关闭重试。
把这项技能写进简历
阅读 FDE 岗位描述时,留意与客户系统集成或生产环境可靠性相关的要求:这类代码正好可以放进你的经历里讲。
简历上不要只写“开发了调用 API 的 Agent”。要写清楚超时按哪个百分位数设定、由哪一层负责重试、如何用幂等阻止重复操作。
面试中被问到“如果创建订单的请求超时,你的 Agent 会怎么做?”,正好可以把上面的循环画出来。面试官会记住那个明白超时不等于失败、而是结果未知的候选人。
这篇文章对你有帮助吗?
感谢你的反馈!