Agent 工具调用可靠性:超时、重试、幂等与人工确认怎么设计

Agent 会挑工具,不代表它知道工具已经做了什么。最危险的状态不是明确报错,而是调用超时后,模型自作主张"再试一次"。查询库存与扣减库存,返回相似的 JSON,却不能共享同一套重试策略。

我做了一个本地故障注入实验:模拟余额扣减和邮件入队,服务端事务已提交,随后故意丢弃回包。没有真实支付、邮件发送、用户事故或外部生产系统。问题只研究执行治理,不讨论 RAG 检索质量。

1. 回包丢失,推翻"超时就没成功"

环境:macOS arm64,Python 3.12.3、SQLite 3.45.3。2026-11-18 12:43:52(UTC+8)实测,12 项测试全部通过,总耗时约 12.33 ms;这是本地测试耗时,不是网络性能。每项保留逐步事件与源码 SHA-256。

具体算例:初始余额 1000 分,每次操作扣 100 分并新增一条邮件队列记录。注入点在 commit 之后、return 之前。实际异常原文:TimeoutError: remote committed; response lost。

路径 第一次回包 第二次执行 最终余额/邮件入队数
naive 丢失 再扣款、再入队 800 / 2
同 key 安全重放 丢失 返回既有结果 900 / 1
确认后改 amount 为 200 拒绝 不执行 1000 / 0
首次执行时确认已过期 拒绝 不执行 1000 / 0

这个实验推翻了待验证判断"客户端没拿到成功,就是服务端没成功"。观察到的事件明确是 approved → effect → response_lost → replay,而不是重新审批、重新扣款。客户端最多知道结果未知,不能把 unknown 偷换成 failed。

2. 幂等不是在 Agent 里放一个 set

重试通常产生 at-least-once 的请求交付:相同业务可能被发送多次。要让副作用只发生一次,服务端必须按稳定 operation_id 查既有结果,并拒绝同 key、不同参数;key 应在第一次发送前持久化,不能每次重试重新生成。

关键是副作用和结果记录处在同一原子提交边界。先扣款再写幂等记录,中间崩溃仍会重复;先记"成功"再扣款,中间崩溃又会丢操作。实验把模拟余额、邮件入队、结果和 nonce 消耗放在同一个 SQLite 事务里,注入部分效果后的异常验证全部回滚。

这不证明跨系统 exactly-once。这里邮件只是数据库中的 outbox 记录;真正的邮件服务不在此事务内。消费者还需下游幂等或对账,否则"入队一次"仍可能"发送两次"。不支持幂等且结果未知的第三方工具,应查询业务状态或交人工核对,不能自动补一次危险动作。

3. 把确认对象从"调用工具"缩到"这一笔操作"

confirm=true 不能证明人同意的是最新参数。确认应绑定租户、工具、收件人、金额、operation_id、有效期和一次性 nonce。这里金额限定为整数分,先过 schema,再对排序、无多余空格的 JSON 算 SHA-256。字典顺序改变不影响 hash;100 与 100.0 则不能被模糊地混用。真实接口还要显式约定默认值、Unicode、币种及版本,不能把一种 JSON 序列化当作通用规范化标准。

下方完整核心复制到一个 Python 文件即可执行,不安装包、不联网。approve 只是本地模拟可信人工确认入口,不是让模型给自己授权;生产环境要由认证的人类会话签发,保护确认账本,或验证签名令牌,并持续校验读取结果的权限。tenant 虽参与 hash,但演示只有一张余额表,不具备多租户隔离。

python 复制代码
import hashlib
import json
import sqlite3
import uuid


def digest(args):
    if set(args) != {"tenant", "tool", "to", "amount"}:
        raise ValueError("schema mismatch")
    if type(args["amount"]) is not int or args["amount"] <= 0:
        raise ValueError("amount must be positive integer cents")
    if args["tool"] != "charge_and_queue" or not all(
        isinstance(args[k], str) and args[k] for k in ("tenant", "to")
    ):
        raise ValueError("scope mismatch")
    raw = json.dumps(args, sort_keys=True, separators=(",", ":"),
                     ensure_ascii=False, allow_nan=False)
    return hashlib.sha256(raw.encode()).hexdigest()


class Server:
    def __init__(self):
        self.db = sqlite3.connect(":memory:")
        self.db.executescript("""
          CREATE TABLE wallet(balance INTEGER); INSERT INTO wallet VALUES(1000);
          CREATE TABLE mail(body TEXT);
          CREATE TABLE ops(id TEXT PRIMARY KEY, hash TEXT, result TEXT);
          CREATE TABLE grants(nonce TEXT PRIMARY KEY, op TEXT, hash TEXT,
                              expires REAL, used INTEGER DEFAULT 0);
        """)
        self.events = []
        self.approvals = 0

    def log(self, event, **fields):
        self.events.append(dict(step=len(self.events) + 1, event=event, **fields))

    def approve(self, op, args, now, ttl=30):
        token = uuid.uuid4().hex
        with self.db:
            self.db.execute("INSERT INTO grants VALUES(?,?,?,?,0)",
                            (token, op, digest(args), now + ttl))
        self.approvals += 1
        self.log("approved", op=op, hash=digest(args), expires=now + ttl)
        return token

    def snapshot(self):
        return (self.db.execute("SELECT balance FROM wallet").fetchone()[0],
                self.db.execute("SELECT count(*) FROM mail").fetchone()[0])

    def effect(self, args):
        n = self.db.execute("UPDATE wallet SET balance=balance-? WHERE balance>=?",
                            (args["amount"], args["amount"])).rowcount
        if not n:
            raise ValueError("insufficient balance")
        self.db.execute("INSERT INTO mail VALUES(?)", (args["to"],))
        return {"balance": self.snapshot()[0], "queued": True}

    def call(self, op, args, token=None, now=0, drop=False, safe=True):
        h = digest(args)
        try:
            self.db.execute("BEGIN IMMEDIATE")
            row = self.db.execute("SELECT hash,result FROM ops WHERE id=?", (op,)).fetchone()
            if safe:
                g = self.db.execute("SELECT op,hash,expires,used FROM grants WHERE nonce=?",
                                    (token,)).fetchone()
                if not g or g[:2] != (op, h):
                    raise ValueError("confirmation scope mismatch")
                if row:
                    if row[0] != h:
                        raise ValueError("idempotency parameter mismatch")
                    result = json.loads(row[1])
                    self.log("replay", op=op)
                else:
                    if now >= g[2] or g[3]:
                        raise ValueError("confirmation expired or nonce consumed")
                    result = self.effect(args)
                    self.db.execute("INSERT INTO ops VALUES(?,?,?)", (op, h, json.dumps(result)))
                    self.db.execute("UPDATE grants SET used=1 WHERE nonce=?", (token,))
                    self.log("effect", op=op, result=result)
            else:
                result = self.effect(args)
                self.log("naive_effect", op=op, result=result)
            self.db.commit()
        except Exception as exc:
            self.db.rollback()
            self.log("rejected", op=op, error=str(exc))
            raise
        if drop:
            self.log("response_lost", op=op)
            raise TimeoutError("remote committed; response lost")
        return result


if __name__ == "__main__":
    args = dict(tenant="demo", tool="charge_and_queue", to="demo@example.invalid", amount=100)
    for safe in (False, True):
        s = Server()
        token = s.approve("op-1", args, now=0) if safe else None
        try:
            s.call("op-1", args, token, drop=True, safe=safe)
        except TimeoutError as e:
            print(type(e).__name__ + ":", e)
        s.call("op-1", args, token, now=1, safe=safe)
        print("safe=", safe, "balance, queued=", s.snapshot())

运行 python3 core.py,实际输出分别是 (800, 2) 和 (900, 1)。本地扩展测试中的"确认后改 amount"会得到 confirmation scope mismatch;同 key 换参数即使重新取得确认,也会得到 idempotency parameter mismatch。

nonce 限制的是新副作用,不是查询已经完成的同一操作。实验在 30 秒确认过期后,第 60 秒仍允许同 key、同 hash 重放既有结果,审批次数保持 1;若此前从未执行,恰在第 30 秒首次执行就拒绝。这个设计不允许换 key 再扣一次,也不意味过期令牌可绕过身份撤销。结果重放必须受结果访问授权约束。

4. 重试按结果语义分型,不按异常名字一刀切

情形 动作
只读调用遇临时错误 在剩余预算内重试,接受快照可能变化
参数、权限、确认 scope 错误 停止并修正,不能原样反复试
限流或可恢复故障 尊重 Retry-After,指数退避加抖动
副作用超时且有服务端幂等契约 固定 key、固定参数重放或查状态
副作用超时且无幂等保证 标记 unknown,业务对账或人工核查

"只读"还要由实现验证,不能只信工具描述;查询仍会消耗配额、留下访问日志。每个请求使用单调时钟的总 deadline:连接、响应、退避都消耗同一预算。测试用 1 秒预算模拟 0.1、0.2、0.4 秒退避,再等 0.8 秒会越界,因此停止;这些是确定性模型输入,不是实测网络延迟。生产请求也必须设置不超过剩余预算的超时,不能只检查 sleep。

取消客户端等待,只能撤销本地继续等待的意图。实验提交后记录 client_cancelled,余额仍为 900 分。没有服务端取消协议、状态查询与补偿机制,就不能说"用户取消所以没执行";补偿也应是另一笔受确认和幂等保护的业务操作。

5. 本地 claim 与结果审计,各守一条边界

8 个线程通过独立连接竞争 SQLite 中的同一任务,执行条件更新 UPDATE ... WHERE state='pending',实际只有 1 个 rowcount=1。这个 CAS 防止同一时刻本地重复领取,不能证明远端只执行一次:领取者提交远端后崩溃,租约过期的新领取者仍可能再发请求,必须复用原 operation_id。租约续期、fencing token 和陈旧 worker 拒绝是另外的协议,本实验不宣称覆盖。

12 项测试还包括规范化顺序、错误金额类型、nonce 换操作拒绝、过期重放、取消后已提交状态和部分副作用回滚。最小审计记录应串联 attempt_id、operation_id、参数 hash、确认主体及有效期、发送/提交/超时/重放事件和结果摘要。不要记录密钥;unknown 要作为独立状态保留,而不是被下一次成功覆盖。

本地扩展测试中的事件是进程内采集后落 JSON,便于复算,不是崩溃安全的生产审计账本。真正上线应将状态机和审计持久化,并定义幂等记录保留期:记录清理后旧 key 能否重用,会直接影响可靠性边界。Agent 可以建议下一步,但不能自行扩大确认 scope、换参数重试,或把工具提示里的"成功"当作业务已落地的证据。

上面的完整核心可保存为 core.py,运行 python3 core.py 复现两条重试路径;12 项扩展断言和逐步事件是本次作者保留的本地核查证据,不宣称有可下载的线上附件。本次没有调用外部模型,只验证上述局部协议,不以测试全绿替代端到端安全评审。

相关推荐
阿里云云原生14 分钟前
Velox 的 2026 年终总结:面向 Agent 的执行层演进!
agent
双鱼大猫1 小时前
opencode 吃掉 100G 空间:Agent 会话数据要分级清理
人工智能·agent·ai编程
学无止境小袁同学1 小时前
OpenAI Agents SDK 模板操作手册(可直接操作)
大模型·openai·agent·sdk·大模型应用
__underline__1 小时前
冷门Python知识点007篇:list[int]不是类,为什么能当基类?
后端·python
Dmz丶1 小时前
前端转 AI 100 天 Day 49:文档切分——RAG 效果的隐形开关
python
莪_幻尘2 小时前
AI 编程的下一场战争,不在模型,在协议
agent·ai编程·mcp
青少儿编程课堂2 小时前
第十八届蓝桥杯青少组图形化真题 + 全国青少年信息素养大赛 + 电子学会图形化考级:校园泡泡堂大挑战解析
c++·python·算法·bfs·信息学竞赛
mengrennwpu3 小时前
Kynvio: 新一代办公助手
llm·agent
Starry-sky(jing)3 小时前
Hermes Agent 升级 v0.23.2:先辨更新渠道,再看 CLI 退出残留修复
人工智能·python·ai agent