Published on

别再把 Agent 失败都算给模型：一次从粗错误码到失败链的排查

Authors
  • avatar
    Name
    hpoenixf
    Twitter

做 Agent 一段时间以后，我越来越不相信简单的一个错误码。

尤其是这种：PROVIDER_UNAVAILABLE

它看起来很明确：模型服务不可用。

于是大模型很自然地会做几件事：

  • 重试；
  • 换模型；
  • 调大 timeout；
  • 查 provider 状态；
  • 再跑一遍。

但后来我们遇到过一种很尴尬的情况：

模型请求其实已经正常结束了。

HTTP 是 200，流也走完了。

真正失败的地方，是后面的发布校验。

也就是说，我们一直在重试一个没有坏的东西。

这件事让我意识到，Agent 里“没拿到答案”只是结果，不是原因。

同一个现象，可能坏在：

请求根本没发出去
模型服务失败
流中途断了
结构化输出解析失败
工具调用失败
发布校验拒绝
持久化失败
内容没有真正交付

如果这些最后都被压成一句 PROVIDER_UNAVAILABLE，错误码虽然简单，排障反而会越来越盲。

这篇文章就是这次改造的复盘。

不是教系统自动找“根因”，而是先做一件更实际的事：

至少先把“最后确定卡在哪一站”说清楚。

最开始的问题，不是日志太少，而是日志没有关系

Agent 其实从来不缺日志。

模型调用有日志。

工具有日志。

发布有日志。

数据库有日志。

前端流也有日志。

问题是，这些日志经常是散的。

一次请求失败后，能看到很多事情发生过：

14:03:01 model request started
14:03:07 provider 200
14:03:08 candidate parsed
14:03:08 publication rejected
14:03:09 another model turn started
14:03:15 block committed
14:03:15 stream closed

光看时间线，很容易脑补出一个故事：

第一次回答被拒了，模型根据反馈修了一次，然后成功提交并交付。

这个故事听起来完全合理。

但真正去问证据，会发现里面至少有三个跳跃：

  1. 后一个模型回合真的看到了前一次拒绝反馈吗？
  2. 后面提交的 block 真的是在修前面被拒的那个 block 吗？
  3. block committed 之后，用户真的拿到了它吗？

时间上前后相邻，不代表它们有因果关系。

这就是我们后来真正想解决的问题：

不只是记录“发生了什么”，还要记录“哪些事实可以被连起来”。

第一个改动：先别急着找根因，先找最后一个确定阻塞点

一开始很容易把这个字段叫 rootCause 或者 primaryFailure。

后来没有这么做。

因为大多数时候，我们根本没有资格说“这是根因”。

例如：

provider 返回 200
→ JSON 解析成功
→ publication validation 拒绝
→ 最终没有内容交付

这时我们能确定的是：

当前这条链最后明确阻止完整交付的阶段，是 publication validation。

但为什么发布校验会拒绝？

可能是模型输出有问题。

可能是规则太严。

可能是上游给错数据。

也可能是某个版本之间的协议不一致。

这些都需要继续调查。

所以我们最后更愿意用：

terminalBlocker

而不是：

rootCause

这个命名差别其实挺重要。

terminalBlocker 只承诺一件事：

从当前已经确认的运行事实看，任务最后明确停在这里。

它不假装知道更深层的原因。

例如：

{
  "terminalBlocker": "publication_validation",
  "delivery": "none"
}

这个信息已经足够把排障范围缩小很多。

至少这一次，不应该第一反应去换模型 provider。

HTTP 200 以后，失败才刚刚开始有可能发生

做普通 API 时，很容易对 HTTP 状态形成肌肉记忆。

200，成功。

4xx，调用问题。

5xx，服务问题。

但 Agent 的 200 只能说明其中一段路走通了。

后面可能还有：

provider response
→ stream assemble
→ JSON parse
→ schema validation
→ runtime orchestration
→ tool execution
→ publication validation
→ publication commit
→ delivery

所以后来我们把失败按阶段记录。

不是为了造一套特别漂亮的分类标准，而是为了避免这种情况：

output schema 不合法
→ 记成 provider unavailable

业务 deadline 到期
→ 记成 provider timeout

用户主动取消
→ 记成 provider timeout

publication validation 拒绝
→ 还是 provider unavailable

一旦都落到 provider，上游就成了垃圾桶。

最典型的是 timeout。

以前一个 deadline 很难知道是谁的 deadline。

后来我们补了一个很小的事实：

timeoutOwner =
  provider
  | business
  | user
  | unknown

它由真正执行 abort 的那一层记录。

不是让模型推断。

也不是看到“差不多超时了”，再根据时间邻近猜。

这个字段本身一点都不聪明，但排障价值很高。

因为“provider 自己超时”和“我们的业务总时限到了”，修法完全不同。

一条诊断记录，不需要保存答案正文

做到这里以后还有一个顾虑：

如果为了排障，把用户问题、模型正文、工具结果全部复制进诊断系统，最后很可能得到另一个更麻烦的系统。

所以我们后来刻意把诊断和内容分开。

诊断记录大概只需要这种东西：

{
  "runId": "...",
  "timeline": [
    {
      "stage": "provider_dispatch",
      "status": "ok"
    },
    {
      "stage": "response_parse",
      "status": "ok"
    },
    {
      "stage": "publication_validation",
      "status": "rejected",
      "reasonCodes": ["..."]
    }
  ],
  "summary": {
    "terminalBlocker": "publication_validation",
    "delivery": "none"
  }
}

它回答的是：

  • 哪一阶段成功；
  • 哪一阶段失败；
  • 哪些原因码是允许记录的；
  • 最终有没有交付；
  • 哪些事实仍然未知。

它不需要知道正文是什么。

这也是我后来比较认同的一条原则：

可诊断，不等于把所有原始数据都存下来。

很多排障问题靠身份、阶段和状态已经足够定位。

正文只有在非常受限的临时调查窗口里才可能有必要，而且它应该和长期诊断记录分开。

第二个误判：A 被拒了，后来 C 成功了，不代表 A 被修好了

这一类问题比粗错误码更容易骗人。

假设时间线是：

A rejected
→ 模型继续运行
→ C committed

人很容易读成：

A rejected
→ 模型修复 A
→ 修复后的结果成功提交

但中间缺了一条最关键的关系：

C 到底是不是 A 的后继修订？

如果没有这个关系，C 可能只是另一个独立内容块。

也可能模型直接放弃 A，转去回答别的部分。

甚至可能 C 在 A 被拒之前就已经存在，只是提交发生得晚。

所以：

A rejected → C committed

只能证明顺序。

不能证明修复。

后来我们要求，想说“A 被修复”，至少要有明确对象关系。

概念上类似：

A revision 1 rejected
→ feedback consumed by model turn 3
→ A revision 2 proposed
→ A revision 2 validated
→ A revision 2 committed
→ A revision 2 delivered

这里每一步都不是另一件事的同义词。

特别是：

后一个模型回合发生了，不等于它看过反馈。

如果我们真的想证明反馈进入了下一轮模型输入，就得有明确的消费关系。

例如：

{
  "actionId": "...",
  "proposedByModelTurnId": "turn-2",
  "consumedByModelTurnId": "turn-3"
}

更严格一点，还会检查后一轮真正使用的 transcript，是否绑定了前面的那份反馈。

这样做听起来有点较真。

但如果没有它，所谓“self-repair 成功率”很容易只是根据时间顺序脑补出来的数字。

“模型看到了反馈”也不等于“模型理解了反馈”

这又是一个需要克制的地方。

就算我们证明：

前一次拒绝反馈确实进入了下一轮模型请求。

也只能说明：

模型有机会看到它。

不能继续推导：

模型理解了原因。

更不能直接推导：

后一个答案就是根据反馈正确修出来的。

这和前一篇里讲“输入完整不等于回答正确”很像。

系统能证明的事实，最好停在系统真正能观察的位置。

例如：

反馈进入 request：可以证明
后一版本和 A 有 revision 关系：可以证明
后一版本通过校验：可以证明
后一版本已提交：可以证明
后一版本已发送：可以证明到对应层级
模型是否真正理解：不能从这些事实直接推出

这种边界有点烦，但很重要。

否则诊断系统会从“记录事实”，慢慢长成“替模型解释心理活动”。

第三个误判：commit 不等于 delivered

这个问题在做流式 Agent 时特别容易发生。

一个答案 block 成功写入数据库，通常是很强的成功信号。

但它仍然不是“用户已经收到”。

至少有几个阶段：

validated
→ committed
→ projected / emitted
→ client received
→ rendered

具体产品可能没有这么多层，但意思一样。

所以如果我们只有：

publication committed

最好只说：

内容已提交。

不要写：

内容已交付。

更不要写：

用户已经看到了。

如果服务端还有真实发送记录，可以进一步说：

服务端已发送。

如果客户端还有 ACK、sequence 或渲染回执，再继续往后证明。

这是我这几篇复盘里反复碰到的一个共同问题：

系统总喜欢把“下一步很可能发生”写成“下一步已经发生”。

诊断系统尤其不能这么做。

因为它本来就是用来纠正这种乐观推断的。

后来我们把一次失败看成一条“有界调查链”

最后形成的东西，其实没有最开始想象得那么复杂。

对一次失败，我们希望能回答：

1. 请求有没有真正派发？
2. provider 有没有返回？
3. 返回有没有通过解析？
4. Runtime 有没有正确执行？
5. 工具有没有实际完成？
6. 发布有没有通过？
7. 内容有没有提交？
8. 内容有没有进入交付链？
9. 哪些关系是明确证明的？
10. 哪些地方只能写 unknown？

最终 summary 只需要保留少量信息：

{
  "terminalBlocker": "publication_validation",
  "contributingFailures": [
    "provider_dispatch:http_permanent"
  ],
  "delivery": "none",
  "classificationConfidence": "partial"
}

这里 partial 也很重要。

如果逐块交付身份还没有接通，就不要因为总计数看起来一致，写成 confirmed。

比如：

summary: delivered = 3
receipt count = 3

数字一样，不代表三个 summary 对象和三个 receipt 是一一对应的。

也可能：

A B C expected
A B B receipts

总数还是 3。

所以真正要确认交付，最终还是得落到对象身份和修订身份。

这和前一篇的数据完整性其实是同一个问题：

aggregate count 很有用，但它不能替代 identity。

诊断不能为了诊断，把业务链路搞坏

做到这里还有一个很现实的问题。

日志和 tracing 经常被当成“旁路”。

于是很容易写成：

await writeDiagnosticEvent()
await executeTool()

或者：

const result = await executeTool()
await writeDiagnosticEvent()
return result

如果诊断存储变慢，它就开始挡住真正的业务执行。

这次 review 里，我们确实发现另一条 lifecycle 日志路径存在这种风险：等待日志 start 可能拖住工具派发，等待 settle 可能拖住 wrapper 返回。

这不代表线上已经发生了数据库锁竞争。

但它至少说明：

“这是观测代码，所以不会影响业务”不是事实，只是一种愿望。

对于真正的 side-channel 诊断，应该专门验证一件事：

diagnostics off
diagnostics on
diagnostic sink slow
diagnostic sink failed

这几种情况下，业务终态是不是一致。

只有测过，才有资格说“非干扰”。

而且要限定范围。

某一条 diagnostics projection 被证明非干扰，不等于整个项目所有日志 writer 都自动获得这个性质。

这也是我后来很警惕的一类措辞：

observability is non-blocking

最好改成：

这条具体路径，在这些测试条件下没有改变业务 trace。

后一句虽然没那么漂亮，但更接近事实。

有些 unknown，比错误归因更有价值

这一轮改造里一个挺反直觉的结果是：

诊断系统增加以后，unknown 反而变多了。

例如：

delivery = unknown
repairOutcome = unknown
usage = unknown
cost = unknown

以前这些地方可能会被默认填成：

0
false
failed

或者根据上下文猜一个最像的状态。

现在更愿意保留 unknown。

因为：

没采集到成本，不代表成本是 0。

没看到交付收据，不代表一定没交付。

后续有成功内容，不代表前一次修复成功。

没有 provider availability 的肯定证据，也不能随便叫 provider unavailable。

诊断系统真正有价值的地方，不是让所有问题都有答案。

而是把：

知道
不知道
推测

这三件事分开。

如果一个诊断系统最后几乎没有 unknown，我反而会有点怀疑它是不是替我们脑补了太多。

三个我现在会特别警惕的“顺手推断”

这次做完以后，我给自己留下了三个非常简单的检查。

1. HTTP 200 → 成功？

不一定。

它最多证明 provider 那一跳按对应协议完成。

后面仍然可能解析失败、工具失败、发布失败、交付失败。

2. 后面成功了 → 前面的问题修好了？

不一定。

要看是不是同一个对象、同一个修订链，以及反馈是否真的进入下一轮。

时间顺序不是因果关系。

3. commit 了 → 用户收到了？

不一定。

commit、server emit、client receive、render，是不同事实。

有什么证据，就说到哪一层。

这三条其实没什么高深的。

但 Agent 链路一长，人特别容易把它们连成一个顺滑故事。

而诊断系统的工作，恰恰是阻止我们讲得太顺。

这次做完以后，什么算已经证明，什么还没有

在受控 fixture 和 provider-free 验证里，我们已经能验证一些比较确定的机制：

  • 失败可以按阶段分类，而不是全部归到 provider；
  • terminalBlocker 可以由确定性事实归约；
  • timeout 可以保留 owner，而不是统一写成 provider timeout；
  • 后一模型回合是否消费前一反馈，可以通过明确身份关系验证；
  • commit 和 delivery 可以分开记录；
  • 诊断 projection 可以只保存安全元数据，不保存正文；
  • 部分诊断路径在受控测试里可以做到 sink 失败不改业务终态。

但也还有几件事情不能说完成：

  • 另一条 native tool lifecycle 日志路径的完整非干扰集成验证还没补齐；
  • summary 和逐 block、逐 revision 的真实交付 identity 还没有完全闭环；
  • PostgreSQL 真机重启和迁移场景没有在这轮环境里完整验证；
  • 真实 provider、真实 Langfuse endpoint 没有在这组验证中运行；
  • 真实 usage / cost delta 没有数据；
  • 所谓“修复恢复率”还不能从 fixture 关系直接推出。

这些东西我不想放进正文做成一大张验收表。

但对外分享时还是应该明确写出来。

因为“诊断机制写完了”和“整套生产诊断已经验证完了”，差得很远。

写在最后

以前遇到 Agent 不回答，我经常先看模型。

现在顺序有点变了。

我会先问：

请求到底发出去了吗？
provider 到底成功了吗？
解析过了吗？
工具执行了吗？
发布为什么被拒？
提交了吗？
发出去了吗？
我们是在看事实，还是在根据顺序讲故事？

模型当然会失败。

但 Runtime、协议、工具、发布和交付同样会失败。

如果最后所有问题都叫“模型不行”，不仅模型背了锅，工程上也失去了修复方向。

所以这次诊断改造最后留下来的原则，我觉得可以压成一句：

不要急着自动找根因，先把每一跳真实发生了什么记录清楚。

terminalBlocker 不是根因分析。

timeline 也不是因果证明。

commit 不是 delivered。

反馈进入上下文，也不是模型理解了反馈。

听起来都是在给结论加限制。

但实际排障时，这些限制反而很省时间。

因为一个准确的“不知道”，通常比一个错误但完整的故事更接近真正的下一步。

View on GitHub