Agent 重试了一次,订单就下了两遍:工具调用的幂等设计
前言
做过分布式系统的人对幂等不陌生。但把同一套经验搬到 Agent 上时,很容易漏掉一个事实:
工具调用的发起方是模型,而模型不知道"刚才那次到底成没成"。
传统服务里,调用方和被调方是我们自己的代码,可以约定重试策略。Agent 里,中间多了一层概率模型——它会因为超时、因为输出被截断、因为上下文里没看到结果,而重复发起同一个工具调用。
最典型的翻车现场:
用户:帮我下一单 2 杯美式 Agent → create_order(sku="AMERICANO", qty=2) ← 超时 5 秒 框架自动重试 Agent → create_order(sku="AMERICANO", qty=2) ← 成功 用户收到两笔订单,两笔扣款
这一篇拆这个问题。
一、先纠正一个概念:超时有三种结局,不是两种
大部分人心里只有两种结果:成功、失败。所以"失败了就重试"看起来很自然。
但网络调用的真实状态是三种:
| 状态 | 含义 | 能重试吗 |
|---|---|---|
| 成功 | 拿到了明确成功响应 | 不用重试 |
| 确定失败 | 拿到了明确失败响应(4xx 参数错、业务拒绝) | 可以,但要先修参数 |
| 未知 | 超时、连接被重置、响应读到一半断开 | 不能直接重试 |
第三种才是事故来源。超时的那一刻,请求可能已经到了服务端、已经执行完、只是响应没回来。此时重试 = 执行两次。
判断方法:如果重试前你不知道"上一次到底执行了没有",这次重试就是危险的。
所以工程上正确的动作不是"超时重试",而是:
超时 → 查询状态(按幂等键)→ 确认未执行才重试
这就引出了幂等键。
二、给工具分级:不是所有工具都需要幂等
一上来给所有工具加幂等键是过度设计。先按副作用分级:
| 等级 | 例子 | 重试安全 | 是否需要幂等键 |
|---|---|---|---|
| 只读 | 查订单、查库存、搜索 | 安全 | 不需要 |
| 幂等写 | 更新状态为"已发货"、设置字段值 | 安全(结果收敛) | 不需要 |
| 非幂等写 | 创建订单、发消息、扣款、发邮件 | 不安全 | 必须 |
关键区别:执行一次的最终状态,和执行两次的最终状态是否相同。
set status = shipped执行两次,结果还是 shipped → 幂等append log执行两次,多一条 → 非幂等amount -= 100执行两次,扣了 200 → 非幂等
第二类里还有一个隐蔽的子类:看起来幂等实际不幂等。
-- 看起来是"设置",实际是"累加" UPDATE account SET balance = balance - 100 WHERE id = ?
写成 SET balance = 500 才幂等,但业务上通常不能这么写(并发会覆盖别人)。这类只能用幂等键或乐观锁。
分级要在工具注册时声明,不能靠模型判断。 模型不知道自己调用的工具有没有副作用,它只看到描述文本。
三、幂等键该由谁生成
这是最容易做错的一环。常见的三个选择:
3.1 让模型生成(❌ 不可靠)
在工具 schema 里加一个 request_id 字段,让模型自己填:
{
"name": "create_order",
"parameters": {
"sku": {"type": "string"},
"qty": {"type": "integer"},
"request_id": {"type": "string", "description": "幂等键,请生成唯一值"}
}
}
问题很直接:模型每次重试都会生成一个新的。它没有"上次用过什么"的记忆,重试时上下文可能已经被截断。结果幂等键形同虚设,反而给了你一种"我做了幂等"的错觉。
更糟的是,模型可能生成重复的值(比如固定填 "order_1"),把两次不同的合法请求判成同一次。
3.2 由框架用 tool_call_id 生成(✅ 推荐)
模型返回的每个工具调用都自带一个唯一 ID,这是协议层面的字段,不是你编的:
{
"role": "assistant",
"tool_calls": [
{
"id": "call_a7f3d2e1", // ← 这个
"function": {"name": "create_order", "arguments": "{\"sku\":\"AMERICANO\",\"qty\":2}"}
}
]
}
同一个 tool_call_id 天然对应"模型的一次意图"。框架重试时复用同一个 id,幂等就成立了:
def execute_tool(tc):
key = f"{tc['id']}" # tool_call_id 就是幂等键
cached = idem_store.get(key)
if cached:
return cached # 重放上次结果,不再执行
result = real_call(tc)
idem_store.put(key, result)
return result
但要注意一个陷阱:如果模型因为上下文丢失重新发起了一个语义相同的调用,它会拿到新的 tool_call_id,幂等键就不同了,还是会重复执行。
这种情况需要业务层的第二道防线——比如订单表上 (user_id, sku, 时间窗口) 的唯一约束,或者"最近 5 分钟内同用户同商品的重复请求直接合并"。幂等键解决的是"同一次意图的重试",解决不了"两次独立但语义重复的意图"。
3.3 三层防护的实际组合
| 层 | 手段 | 挡住什么 |
|---|---|---|
| 协议层 | tool_call_id 作幂等键 | 框架重试、网络重试 |
| 业务层 | 唯一约束 / 时间窗口去重 | 模型重新发起的重复意图 |
| 人工层 | 高风险操作二次确认 | 语义正确但不该自动执行的请求 |
三层都要有,只做一层一定会漏。
四、参数幻觉:校验要写在工具里,不要写在提示词里
幂等解决"执行几次",另一类问题解决"执行得对不对"。模型生成的参数有三类典型错误:
| 形态 | 例子 | 危害 |
|---|---|---|
| 实体不存在 | order_id = "SO-2026-9999"(编的) | 查询为空、或匹配到错误记录 |
| 类型/范围错 | qty = -1、price = "一百" | 业务异常、脏数据 |
| 语义越界 | 退款金额大于订单金额 | 资金损失 |
第一类的根因是模型在"补全格式"而不是"引用事实"。它见过大量 SO-2026-xxxx 形式的字符串,于是在缺失时会生成一个看起来合理的。
用提示词治这个病效果很差。"请只使用上下文中出现过的订单号"这句话,模型大部分时候会遵守,但恰恰在上下文很长、订单号被挤出窗口时失效——而那正是最需要它遵守的时候。
可靠的做法是在工具层做引用校验:
def create_refund(order_id: str, amount: float):
order = db.get_order(order_id)
if order is None:
# 明确告诉模型"这个 ID 不存在",而不是抛异常让它猜
return {"ok": False, "error": "ORDER_NOT_FOUND",
"hint": f"未找到订单 {order_id},请从上下文中的订单列表选择"}
if amount > order.paid_amount:
return {"ok": False, "error": "AMOUNT_EXCEEDS_PAID",
"hint": f"最多可退 {order.paid_amount}"}
...
两个细节值得强调:
- 错误要结构化返回,带
error码和hint,模型才能自我纠正。抛一个 Python traceback 上去,模型只会道歉或者瞎猜。 hint里给出合法范围,比"参数错误"有用得多。这是让 Agent 具备自愈能力的最低成本手段。
五、并行工具调用的顺序陷阱
模型可以一次返回多个工具调用,框架通常会并发执行。但模型对"这些调用之间有没有依赖"的判断并不可靠。
用户:把 A 订单的商品换成 B,然后重新算价 模型一次返回: cancel_item(order="A", item="X") add_item(order="A", item="B") recalc_price(order="A")
三个调用如果并发执行,recalc_price 很可能在商品还没换完时就算完了,得到错误的金额。
三个应对层次:
- 工具描述里写清依赖:
recalc_price的描述中写明"必须在商品变更完成后调用"。成本最低,但不保证。 - 拆成两轮:让模型先调变更类工具,拿到结果后再调计算类。多一次模型调用,但确定性高。
- 在工具内部串行:
recalc_price内部加锁或校验版本号,检测到"商品正在变更"就返回重试提示。
实践中 1 + 3 组合最划算:描述降低概率,工具内部保证正确性。纯靠描述的方案,一定会遇到模型不听话的那次。
六、补偿:实在幂等不了怎么办
有些操作天生不可幂等——发短信、调用第三方支付。这时用 Saga 思路:为每个前向操作准备一个补偿操作。
steps = [
{"do": "reserve_inventory", "undo": "release_inventory"},
{"do": "create_payment", "undo": "refund_payment"},
{"do": "create_shipment", "undo": "cancel_shipment"},
]
任何一步失败,按逆序执行已成功步骤的 undo。
关键约束:补偿操作本身必须幂等。 否则"补偿失败再重试"会制造新问题。refund_payment 要用支付流水号做幂等键,同一笔退款多次请求只退一次。
还有一类补偿做不了:外部副作用无法撤销(已经发出去的短信、已经推到用户手机的通知)。这类只能靠"执行前二次确认"来预防,而不是靠事后补偿。
七、一个带幂等与校验的工具执行器
把上面的点落成代码:
import time
import json
class ToolError(Exception):
def __init__(self, code, hint=""):
self.code = code
self.hint = hint
super().__init__(code)
class ToolExecutor:
"""
side_effect:
"none" 只读
"idempotent" 幂等写
"non_idempotent" 非幂等写,必须走幂等键
"""
def __init__(self, ttl=24 * 3600):
self._tools = {}
self._idem = {} # key -> (result, expire_at)
self._ttl = ttl
def register(self, name, fn, side_effect="none", timeout=10):
self._tools[name] = {"fn": fn, "side_effect": side_effect, "timeout": timeout}
def _gc(self):
now = time.time()
self._idem = {k: v for k, v in self._idem.items() if v[1] > now}
def call(self, name, args: dict, tool_call_id: str):
spec = self._tools.get(name)
if not spec:
raise ToolError("TOOL_NOT_FOUND", f"可用工具:{list(self._tools)}")
non_idem = spec["side_effect"] == "non_idempotent"
# 只对非幂等工具查幂等记录
if non_idem:
self._gc()
hit = self._idem.get(tool_call_id)
if hit:
return {"ok": True, "replayed": True, "data": hit[0]}
try:
result = spec["fn"](**args)
except ToolError as e:
# 业务性失败:可以直接返回给模型,不需要重试
return {"ok": False, "error": e.code, "hint": e.hint}
except TimeoutError:
# ⚠️ 未知状态:不能当失败重试
return {"ok": False, "error": "UNKNOWN_STATE",
"hint": "调用超时,结果未知。请勿直接重试,先查询状态确认"}
except Exception as e:
return {"ok": False, "error": "INTERNAL", "hint": str(e)[:200]}
if non_idem:
self._idem[tool_call_id] = (result, time.time() + self._ttl)
return {"ok": True, "data": result}
调用侧直接拿 tool_call_id:
for tc in response.tool_calls:
name = tc["function"]["name"]
args = json.loads(tc["function"]["arguments"])
out = executor.call(name, args, tool_call_id=tc["id"])
messages.append({
"role": "tool",
"tool_call_id": tc["id"],
"content": json.dumps(out, ensure_ascii=False),
})
做了什么
给一批写操作类工具(下单、退款、发通知)做了改造:
- 工具注册时显式声明
side_effect,非幂等工具自动走幂等键 - 幂等键统一用协议层的
tool_call_id,不再让模型生成request_id - 幂等记录落 Redis,TTL 24 小时,键前缀区分工具名
- 所有工具的业务错误改成结构化返回(
error+hint),不再抛裸异常 - 超时单独归类为
UNKNOWN_STATE,提示模型先查状态而不是重试 - 订单表加了
(user_id, sku, created_at 分钟窗口)唯一约束作为第二道防线
改造后一个可观测的变化:模型的自愈成功率高了不少。以前工具报错就是一句 traceback,模型只会说"抱歉请稍后再试";现在报错带合法范围,模型能自己改参数重试。
一些体会
幂等不是为了防重复点击,是为了防"我们自己"重试。 用户手抖点两次是低频事件,框架超时重试是高频事件。后者才是主要风险,而它恰恰最容易被忽略——因为重试是框架自动做的,业务代码看不见。
让模型生成幂等键,是一种自我安慰。 模型无法保证"重试时用同一个值",因为它不知道这是重试。这个字段加进去,只会让人误以为问题解决了。
"超时"必须和数据里的"失败"分开表达。 在工具返回值里把 UNKNOWN_STATE 和 FAILED 分成两个错误码,是为了让模型和人都能做出不同反应。混在一起的后果就是无脑重试。
第三道防线(人工确认)不要省。 金额以上、不可逆的操作,让 Agent 生成"待确认"的操作单,由人点一下。这不是技术不成熟的表现,而是对副作用的基本尊重。
- 点赞
- 收藏
- 关注作者
评论(0)