Agent 重试了一次,订单就下了两遍:工具调用的幂等设计

举报
yd_232401777 发表于 2026/10/31 07:41:26 2026/10/31
【摘要】 大模型调用工具超时,框架重试一次,这是再正常不过的容错逻辑。但如果那个工具是「创建订单」,重试就意味着用户被扣了两次钱。问题的根源不是重试,而是把「超时」当成了「失败」——超时只说明你不知道结果,不说明事情没发生。这篇讲清楚三种状态、工具该怎么分级、幂等键该由谁生成,以及为什么模型自己生成幂等键一定不可靠。

前言

做过分布式系统的人对幂等不陌生。但把同一套经验搬到 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}"}
    ...

两个细节值得强调:

  1. 错误要结构化返回,带 error 码和 hint,模型才能自我纠正。抛一个 Python traceback 上去,模型只会道歉或者瞎猜。
  2. hint 里给出合法范围,比"参数错误"有用得多。这是让 Agent 具备自愈能力的最低成本手段。

五、并行工具调用的顺序陷阱

模型可以一次返回多个工具调用,框架通常会并发执行。但模型对"这些调用之间有没有依赖"的判断并不可靠。

用户:把 A 订单的商品换成 B,然后重新算价

模型一次返回:
  cancel_item(order="A", item="X")
  add_item(order="A", item="B")
  recalc_price(order="A")

三个调用如果并发执行,recalc_price 很可能在商品还没换完时就算完了,得到错误的金额。

三个应对层次:

  1. 工具描述里写清依赖:recalc_price 的描述中写明"必须在商品变更完成后调用"。成本最低,但不保证。
  2. 拆成两轮:让模型先调变更类工具,拿到结果后再调计算类。多一次模型调用,但确定性高。
  3. 在工具内部串行: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),
    })

做了什么

给一批写操作类工具(下单、退款、发通知)做了改造:

  1. 工具注册时显式声明 side_effect,非幂等工具自动走幂等键
  2. 幂等键统一用协议层的 tool_call_id,不再让模型生成 request_id
  3. 幂等记录落 Redis,TTL 24 小时,键前缀区分工具名
  4. 所有工具的业务错误改成结构化返回(error + hint),不再抛裸异常
  5. 超时单独归类为 UNKNOWN_STATE,提示模型先查状态而不是重试
  6. 订单表加了 (user_id, sku, created_at 分钟窗口) 唯一约束作为第二道防线

改造后一个可观测的变化:模型的自愈成功率高了不少。以前工具报错就是一句 traceback,模型只会说"抱歉请稍后再试";现在报错带合法范围,模型能自己改参数重试。

一些体会

幂等不是为了防重复点击,是为了防"我们自己"重试。 用户手抖点两次是低频事件,框架超时重试是高频事件。后者才是主要风险,而它恰恰最容易被忽略——因为重试是框架自动做的,业务代码看不见。

让模型生成幂等键,是一种自我安慰。 模型无法保证"重试时用同一个值",因为它不知道这是重试。这个字段加进去,只会让人误以为问题解决了。

"超时"必须和数据里的"失败"分开表达。 在工具返回值里把 UNKNOWN_STATE 和 FAILED 分成两个错误码,是为了让模型和人都能做出不同反应。混在一起的后果就是无脑重试。

第三道防线(人工确认)不要省。 金额以上、不可逆的操作,让 Agent 生成"待确认"的操作单,由人点一下。这不是技术不成熟的表现,而是对副作用的基本尊重。

【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。