有一次凌晨被叫起来,原因是同一个客户收到了十一条一模一样的退款通知。

翻日志才看明白链条:第一次调用其实成功了,但网关在第三十秒超时,程序判定失败并重试了两次。三次调用都落库成功,模型收到三个「成功」的返回,于是各自补发了一条确认消息。通知服务那边又没有去重,十一条就这么发出去了。

没有一行代码是「写错」的。超时处理是对的,重试是对的,模型基于结果做确认也是对的。错的是这些正确的东西凑在一起时,没有人管住「同一个副作用被执行了三次」这件事。

这件事之后我把工具调用当成一个独立的可靠性问题来看,而不是「写个 try-catch」。这篇就是那次之后攒下来的一套东西。

先给一个可能有点反直觉的统计:我后来复盘了四百多次失败任务,真正属于「模型能力不够、想不出怎么做」的不到两成。剩下八成都能归到同一句话——某一次工具调用返回了它处理不了的东西,然后它开始编。超时被当成空结果,HTML 错误页被当成正文,业务拒绝被当成暂时故障重试三次。模型没有能力区分这些,除非你替它区分。

一、先把失败分类

不分类型地谈「容错」,最后一定写成一个大而全的 try-catch,把所有异常都吞成一句 failed。分类是后面所有策略的前提。

类别 典型表现 根因在谁 该在哪处理
模型侧参数错 字段名拼错、枚举值越界、必填项漏填、数字传成字符串 模型理解偏差 / 描述不清 schema 校验 + 结构化纠错反馈
环境侧超时与限流 429、502/503、连接重置、响应超过阈值 基础设施 程序层退避重试
业务侧拒绝 库存不足、状态不允许、无权限 业务规则 立即终止,转述原因
结果不可用 返回空、返回 HTML、字段缺失、乱码、编码错 上游服务 结果校验 + 降级
副作用重复 重复下单、重复发消息、重复扣款 设计缺陷 幂等键 + 去重

前三类大部分人都会想到,后两类才是真正难缠的。

结果不可用最阴险。HTTP 200,Content-Type 是 text/html,body 是公司统一登录页——这算成功还是失败?程序看到 200 就往下走,模型看到一大段 HTML 就从中找了几句话当作答案。类似的还有:上游把错误包装成 {"code": 0, "data": null};接口返回了正确结构但关键字段是空字符串;日志接口在服务降级时返回了一条「查询超时」的文本,被当成日志内容。

副作用重复最贵。它不会报错,不会告警,只会在事后被人发现。而且它往往由「正确的容错」引发:超时重试、失败重放、用户手动再点一次。每一次单独的决策都合理,加起来就是十一次通知。

「结果不可用」这一类值得单独给一段代码,因为它太容易被 200 骗过去:

1
2
3
4
5
6
7
8
9
10
11
def validate_result(resp, expect="json"):
if resp.status != 200:
return fail("HTTP_ERROR", resp.status)
ctype = resp.headers.get("content-type", "")
if expect == "json" and "json" not in ctype:
# 登录页、网关错误页、限流页都会走到这里
return fail("BAD_CONTENT_TYPE", ctype, retryable=False)
body = resp.json()
if body.get("data") is None and body.get("code") != 0:
return fail("EMPTY_PAYLOAD", body.get("message"))
return ok(body)

这三行检查能挡掉我遇到过的大多数「假成功」。它的价值不在于多严谨,而在于把「返回了但没用」从成功路径里摘出来,变成一个模型能看见的错误。否则模型拿到一段 HTML,除了硬着头皮解读,没有别的选择。

二、参数校验分三层,不要指望模型自觉

这是最容易偷懒的一层。很多人的做法是「schema 写清楚,模型会遵守」,然后把校验全交给 schema。

问题在于,schema 只在支持严格模式时才是硬约束。在不支持的环境里,schema 是建议,不是法律。模型会输出 "top_k": "5"(字符串)、"status": "PAID"(大小写)、"page": -1(负数),全都语法合法、语义错误。

我的做法是分三层,每层的职责不重叠:

第一层,schema 校验。 类型、必填、枚举、范围、格式。这一层应该是纯粹机械的,用 JSON Schema 校验器跑一遍就行,不写业务逻辑。不通过就构造一条结构化错误回灌给模型,不要抛异常中断——这是它可以自己修的一类错。

第二层,业务校验。 资源是否存在、当前状态是否允许这个操作、调用方有没有权限、数值是否超过业务上限。这一层必须在服务端做,因为它需要查数据。校验失败返回 isError 而不是异常,理由和上面一样:模型需要知道「为什么不行」才能换个做法。

第三层,危险操作确认。 凡是不可逆的写操作,必须有人确认。这一层不能放在模型手里——你没法通过 prompt 让一个概率模型可靠地「在危险操作前停下来问一句」,它有时会问,有时不会,而失败的那次就是事故。确认要在 Host 侧做成硬拦截:调用参数里带 confirmed: true 才放行,而这个字段只能由用户交互写入,模型无权设置。

三层的关系是漏斗,不是并联。第一层挡掉八成低级错,第二层挡掉剩下的语义错,第三层只管那几十个真正会造成损失的调用。

这里有个反向的权衡也要注意:校验太严会把模型逼进死循环。我一度把 top_k 限制成必须大于零且不超过十,模型传了 20,被拦;它改成 10,又被另一个规则拦(要求偶数);它改成 8,通过。中间那两轮完全是浪费。所以校验规则应该尽量贴近「真实的业务约束」,而不是「我觉得更合理的写法」——凡是能用默认值、能自动纠正的(比如把 20 截成 10 并标注「已按上限截断」),就别拦。拦住只应该发生在「继续下去会产生错误结果」的时候。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
def guard(call, ctx):
issues = schema_check(call) # 类型/枚举/必填,机械校验
if issues:
return tool_error("INVALID_ARGUMENT", issues, retryable=False,
hint="按 issues 里指出的字段修正后重试")

if not ctx.user.can(call.tool, call.args):
return tool_error("FORBIDDEN", "无权限", retryable=False)

if call.tool in DESTRUCTIVE and not ctx.confirmed_by_human:
return tool_error("NEEDS_CONFIRMATION",
"该操作不可逆,需要用户确认",
retryable=False,
hint="向用户说明将要发生什么,等待确认后再调用")
return None

注意 hint 那一行。校验不只是「拦住」,还要「告诉它怎么改」。只说 invalid argument 的错误,模型只能靠猜,而它猜的方式通常是换个写法再试一次,来回几轮。

三、重试:分清哪些值得重试

重试的第一原则:只重试可能自己好的错误。

网络抖动、连接重置、429 限流、502/503/504,这些过一会儿可能就恢复了。而 400、401、403、404、409、422 以及所有业务拒绝,重试一百次结果都一样,只是把一次失败变成一百次失败,顺便把账单乘以一百。

状态 可重试 理由
连接超时 / 重置 是 瞬时网络问题
429 是 限流,退避后大概率恢复
500 / 502 / 503 / 504 是 上游临时故障
400 参数错 否 需要改参数,属于模型该修的事
401 / 403 否 凭据或权限问题,重试没用
404 否 资源不存在
409 冲突 否 状态已变,要重新读状态
业务拒绝(余额不足等) 否 确定性结果

第二原则:退避要加抖动。固定间隔重试会让所有失败请求在同一时刻再次涌向已经过载的服务,把一个瞬时故障放大成雪崩。标准做法是指数退避加随机抖动,并且设上限。

1
2
3
4
5
6
7
8
9
10
11
RETRYABLE = {429, 500, 502, 503, 504}

def call_with_retry(fn, max_attempts=3, base=0.5, cap=8.0):
for i in range(max_attempts):
try:
return fn()
except ToolError as e:
if e.status not in RETRYABLE or i == max_attempts - 1:
raise
delay = min(cap, base * 2 ** i)
time.sleep(delay * (0.5 + random.random())) # 抖动

第三原则,也是最少人做的一条:重试要在程序层做完,不要把失败原样丢回给模型让它自己重试。原因有三个。模型没有时间感,它会立刻再调一次,等于没有退避;它每重试一次都要重发整个上下文,成本远高于程序层重试;它的重试策略不稳定,同一个错误有时重试有时不重试。

但有一个例外必须留给模型:换参数再试。那不是重试,是修正。程序分辨不出「这个参数该改成什么」,只有模型能。所以界线是:同样的参数重试由程序做,不同的参数由模型做。

并发场景还要多一层判断:部分失败怎么算。模型一次发出三个并行调用,两个成功一个超时。这时候如果把整个批次判为失败、全部重跑,那两个成功的会被执行两次——又回到了副作用重复。正确做法是逐调用判定:成功的照常回灌,失败的单独标出来,让模型拿着两个成功的结果去决定「那一个要不要重试」。批次级的成功失败是个假概念,工具调用没有事务。

四、超时、预算与取消传播

超时要有两层,缺一不可。

单次调用超时防止一个卡死的请求拖垮整轮。我一般给十到三十秒,长任务改成异步两段式(先提交拿 id,再轮询状态)。

整体任务预算防止「每一步都不慢,加起来跑了两小时」。这个预算要包含的不只是时间,还有轮数和 token。三者任一触顶就该收尾。

关键是预算要往下传。子调用的超时不能是一个固定值,而应该取「单次上限」和「剩余预算」的较小值。否则会出现这种情况:任务只剩五秒预算,某个子调用还按三十秒超时去等,等回来的时候整个任务已经超时了,成果全部作废。

取消传播是更容易漏的一环。用户按下中断,主循环停了,但已经发出去的子进程和 HTTP 请求还在跑。表现出来就是:界面显示已停止,后台还在往数据库写,或者终端里 Ctrl-C 之后那个 npm install 又跑了三分钟。

正确的做法是把取消当成一个信号,往下传到每一个还在执行的调用:协程取消、HTTP 客户端 abort、子进程杀掉整个进程组(只 kill 父进程不管用,shell 会留下孤儿进程)。这件事在一个「工具会启动子进程」的 Agent 里尤其重要,因为最常见的形态就是主循环退出了,后台还挂着一堆跑飞的命令。

还有一个细节:超时不要静默返回空结果。超时必须是一个明确的错误,带 code=TIMEOUT、retryable=true。返回 [] 或者 null 会让模型以为「查了,没有」,这是幻觉最常见的起点之一。

五、幂等与副作用

回到开头那十一条通知。修法不是「别重试」,而是让重试变得安全。

先把工具按副作用分级,这个分级决定了后面所有的策略:

级别 例子 策略
只读 查询、搜索、读文件 可随意重试,可并行
可逆写 创建草稿、修改配置、发一条可撤回的消息 可重试,需带幂等键
不可逆写 扣款、退款、发通知、删除数据、发布上线 幂等键 + 人工确认 + 审计

幂等键是最核心的机制。它应该由「任务 id + 工具名 + 归一化后的参数」算出来,而不是随机生成——随机生成的话,重试时键变了,去重就失效了。服务端维护一张短期的键表,同一个键第二次到达时直接返回第一次的结果,不再执行。

1
2
3
def idem_key(task_id, tool, args):
norm = json.dumps(args, sort_keys=True, ensure_ascii=False)
return hashlib.sha256(f"{task_id}|{tool}|{norm}".encode()).hexdigest()[:32]

sort_keys=True 这一句别省。不排序的话,{"a":1,"b":2} 和 {"b":2,"a":1} 会算出两个键,去重形同虚设。

干跑(dry-run)是第二道闸。所有不可逆写操作都应该支持一个 dry_run 参数:完整走一遍校验和预演,返回「将会发生什么」,但不真正执行。这样模型可以先演一遍给用户看,用户确认后再真跑。这个设计还有个附带好处——调试时不用造测试数据,直接干跑就能看到参数对不对。

可回滚是第三道。做不到真回滚,至少要做到「可补偿」:软删除而不是物理删除、发通知前先落一条待发记录、发布前保留上一版本。这些是普通后端的常识,放到 Agent 场景里更必要,因为调用方是一个会犯随机错误的模型,而不是一个你写死的流程。

确认本身也有质量高低。一句「是否继续」的弹窗,用户只能凭感觉点;一个好的确认应该把这次调用的关键事实摊开:要做什么(动作)、影响谁(对象)、影响多大(数量或金额)、能不能撤回。这四样正好对应工具参数里最重要的四个字段,所以确认框的内容应该由工具的结构化参数渲染,而不是由模型写一段话——模型写的那段话可能漏掉最关键的金额。

最后是重复执行的检测。除了幂等键,还要在任务层做一层:同一组参数在一个时间窗内出现超过 N 次,就应该怀疑是重试风暴或者死循环,而不是正常调用。这层检测和下面要讲的死循环检测可以共用一套逻辑。

六、结果回灌的瘦身与脱敏

工具结果会进上下文,而上下文会流向很多地方:日志、trace 平台、可能还有第三方模型。这意味着脱敏必须在回灌之前做,而不是在日志层做。日志层脱敏只保护了日志,上下文里的原文该泄露还是泄露。

两个动作,都是程序侧的,不要交给模型。

瘦身:截断要带标记。 一个两千行的日志,直接砍到两百行,模型不知道被砍过,会以为看到的是全部。正确的做法是保留头尾,中间明确标注省略了多少:

1
2
3
4
5
6
7
8
def clip(text, head=80, tail=40):
lines = text.splitlines()
if len(lines) <= head + tail:
return text
omitted = len(lines) - head - tail
return "\n".join(
lines[:head] + [f"...(中间省略 {omitted} 行,如需查看请用 offset 参数)..."] + lines[-tail:]
)

那句「如需查看请用 offset」很重要。它不只是告知,还给了模型一条出路,否则它要么假装看到了,要么开始编。

脱敏:用规则,不用模型。 密钥、token、手机号、邮箱、身份证、内网地址,这些模式是确定的,正则比模型可靠得多。

类型 匹配 替换
API Key sk-[A-Za-z0-9]{16,} sk-***
Bearer Token Bearer\s+\S+ Bearer ***
手机号 1[3-9]\d{9} 138****0000
邮箱 [\w.+-]+@[\w-]+\.[\w.]+ u***@example.com
身份证 18 位,末位可为 X 保留前六后四
连接串密码 ://[^:]+:[^@]+@ ://user:***@

有一个例外要处理:如果任务本身要求把原值展示给用户(比如「帮我看下这个 token 是不是配错了」),脱敏会让模型没法完成任务。这时候正确的做法是让原文不进模型,由渲染层直接从工具的结构化结果里取,而不是把原文塞进上下文再指望它别乱说。

七、死循环与「幻觉完成」

死循环的表现很好认:同一轮里反复调同一个工具,参数几乎一样,结果也几乎一样。

检测的关键在「几乎」这两个字。如果按参数原文做哈希,模型把 "query": "退款" 改成 "query": "退款 "(多个空格)就绕过了。所以要先归一化:去首尾空白、折叠连续空格、key 排序、数值统一格式,然后再哈希。

判定阈值我给三个:

  • 同参数连续 N 次(N 取 3):直接打断。
  • 连续 k 轮无新增信息:结果集合和上一轮完全相同,或者连续几轮全是同类错误。
  • 总轮数触顶:兜底,防止一种「每轮都略有不同但始终不收敛」的慢速循环。

打断的方式比打断本身更重要。直接终止进程体验很差,用户看到的是一个没有解释的失败。更好的做法是往上下文里注入一条系统消息:「检测到重复调用同一工具,请停止重试,说明当前已知信息与卡点」,给它一次自己收尾的机会;如果下一轮还是重复,再强制结束。

比死循环更隐蔽的是「幻觉完成」:模型声称任务完成,但实际上什么都没做。

典型形态是:它说「已经帮你把配置改好了」,而这一轮的工具调用记录里没有任何写操作。或者它说「测试全部通过」,但根本没有跑测试的命令。这类问题在长任务快结束时特别容易出现,因为那时候上下文里已经堆满了「正在做」的描述,模型倾向于顺着这个叙事给一个圆满的结尾。

对抗它的办法只有一个:用确定性的检查验证声明。它说改了文件,就看 git diff 有没有变化;它说跑了测试,就看有没有对应的命令记录和退出码;它说创建了订单,就再查一次订单是否存在。凡是能用程序验证的完成声明,都不要采信模型的自我报告。这一条和第一篇里讲的 Harness 是同一个原则:能用确定性程序检测的事,不要交给模型判断。

八、可观测性:出事之后靠什么复盘

开头那个事故,我能在一个小时内定位,靠的是每一轮都记了足够细的字段。如果没有,只能看到「用户投诉收到十一条通知」这一个事实。

每轮至少要落这些:

字段 示例 用来回答什么问题
task_id / turn t-8f2a / 7 这次调用属于哪个任务的第几轮
tool orders.refund 哪个工具错误率高
args_digest sha256 前 8 位 去重、复现,且不落敏感原文
args_summary order_id=SO20…, amount=19900 人眼看得出调了什么
status ok / error:INVALID_ARGUMENT / timeout 失败类型分布
duration_ms 1240 哪个工具慢,慢在哪一段
retry_count 1 稳定性,是否在靠重试撑成功率
tokens_in / tokens_out 51200 / 320 成本归因到具体工具
result_bytes 3200 结果膨胀,是否有工具在灌水
idem_key 3f9c… 关联重复执行

几个取舍值得说:

args_digest 和 args_summary 要同时有。前者用于机器去重和精确复现,后者用于人眼快速判断。只存摘要,排查时看不出调了什么;只存原文,敏感信息就进了日志。

tokens_in 要按轮记,不要只记任务总量。任务总量只能告诉你「这次很贵」,按轮记才能告诉你「贵在读文件那三步」,这才是能优化的信息。

retry_count 是一个被低估的指标。如果某个工具的平均重试次数在上升,说明它已经在靠重试维持成功率,稳定性其实在恶化——只是还没到报错的程度。

还有一个跨系统的问题:你的日志和工具服务端的日志怎么对上。答案是在调用时把 task_id 和 turn 透传下去,放进请求头或者参数,让服务端也记一份。否则出了问题,一边只有「第 7 轮调了退款」,另一边只有「收到一笔退款请求」,中间靠时间戳对齐,误差能有几秒,而几秒里可能有几十个请求。

采样策略也值得定一下。全量存每一轮的完整上下文很贵,但只存摘要又复不了现。我的做法是成功轮存字段级摘要,失败轮存完整上下文(含工具入参出参的原文,脱敏后)。失败是少数,存全量的成本可控;而复盘需要的恰恰只有失败那一侧。

九、降级与体面失败

工具全挂的时候,最差的输出是「抱歉,我无法完成这个任务」。它把用户扔在了原地。

好的失败输出应该有三段:

  1. 我做到了哪一步,带证据。改了哪几个文件、查到了哪些信息、哪些步骤已经验证过。
  2. 卡在哪,说清是哪个工具、什么错误、是否可重试。不要只说「出错了」。
  3. 接下来可以怎么办。是重试、换一条路径,还是需要人工接手;如果人工接手,需要什么信息。

举个具体的:发布流程跑到第三步,部署工具超时三次。合格的输出是「代码已合并到 release 分支(commit abc1234),构建产物已上传,卡在部署这一步:部署接口连续三次超时。建议确认集群状态后重新执行部署,产物不需要重传」。不合格的输出是「发布失败,请重试」。

降级本身有两种常见模式,选哪种取决于任务能不能容忍旧数据。缓存兜底:检索类工具挂掉时,返回上一次的结果并显式标注「数据来自 12 分钟前的缓存,可能不是最新」,让模型在回答里带上这个限定。只读降级:写工具挂掉但读工具正常,就把任务收缩到「能查的都查清楚,改动留给人工」,这比强行重试写操作安全得多。两种模式的共同点是把降级状态显式写进上下文,而不是让模型自己猜为什么结果变少了。

降级还有一条原则:部分成功也要如实报,不要因为一步失败把前面的成果全部丢掉。Agent 的很多任务是不可分割的长流程,但用户真正需要知道的是「现在处在哪个状态」,而不是一个二元的成功失败。

最后一条,也是最容易被违反的一条:工具不可用时,宁可说不可用,不要用训练数据编一个答案。这在查询类工具上尤其常见——搜索接口挂了,模型基于自己的记忆给了一个看起来很像的结论,用户完全无从分辨。程序侧能做的兜底是:如果本轮所有检索类工具都失败,就在系统消息里明确写一句「当前无可用检索结果,不要基于记忆作答」,把这条约束放到离生成最近的位置。

常见的坑

  • 所有异常都标成可重试。业务拒绝重试三次,用户多等三十秒,结果还是一样。
  • 重试不带幂等键。超时重试写出三条一样的记录,而且是静默的。
  • 幂等键用随机值。看起来做了去重,实际每次都算新键,一点用没有。
  • 超时返回空数组。模型理解成「查了没有」,直接开始编。
  • 只截断不告知。模型以为看到的是全部,据此给出自信的错误结论。
  • 在日志层脱敏,上下文里还是原文。真正泄露的路径是上下文,不是日志。
  • 用模型判断任务是否完成。它会顺着上下文里的叙事给自己一个圆满结局。
  • 打断只停主循环。后台子进程继续跑,继续写库。
  • 参数哈希不归一化。加个空格就绕过死循环检测。
  • 预算只在最外层设。子调用按固定超时跑,整体早就超了还在等。

检查清单

  • 失败按五类分开处理,不要统一吞成 failed。
  • 参数校验三层齐全:schema、业务、人工确认,且确认由 Host 硬拦截。
  • 只对超时、429、5xx 重试,退避带抖动,次数有上限。
  • 所有写操作带幂等键,键由「任务 + 工具 + 归一化参数」算出。
  • 不可逆操作支持 dry-run,且至少有补偿方案。
  • 单次超时和整体预算都有,预算往下传,取消信号能传到子进程。
  • 工具结果回灌前做截断(带省略标记)和脱敏(正则,不靠模型)。
  • 死循环检测归一化参数,连续三次即打断,并给模型一次收尾机会。
  • 完成声明用确定性检查验证,不采信模型的自我报告。
  • 每轮记录轮次、工具、参数摘要、耗时、状态、token、重试次数。
  • 失败输出包含「做到哪一步、卡在哪、下一步怎么办」三段。

工具调用的健壮性,本质上是在给一个概率模型配一套确定性的护栏。模型负责判断「该做什么」,护栏负责保证「做了之后不会留下烂摊子」。这两件事不能互相替代:护栏再厚,也补不上模型选错工具;模型再强,也想不到「这次超时其实已经成功了」。

写到这里,这个系列从术语、上下文、模型、工具、协议一路走到了失败处理。回头看,所有的主题其实是同一件事的不同侧面:模型的能力是给定的,围绕它的工程决定了这份能力能不能稳定地交付出去。

护栏搭好之后,剩下的是循环本身:一轮轮怎么推进、什么时候该停、跑长了上下文怎么不炸、模型自称做完了该不该信。下一篇从一次「跑了几十轮、汇报说已修好、diff 却是空的」的失败开始,拆 Agent 的主循环。

系列大纲与全部篇目见:Agent 原理与开发。

延伸阅读