上个月某个凌晨，一个 cron 任务跑完了，状态码是 0，日志没有异常，但下游收到的数据全是错的。
没有人收到告警。任务本身没有”失败”。它完美地执行了一条错误的指令。
这就是 agent 调试和传统软件调试的根本区别。传统程序出问题，它崩溃给你看。Agent 出问题，它笑着把错的交给你。
沉默失败
在 OpenClaw 的日常运维里，我遇到过一种反复出现的场景：
脚本跑完了。exit 0。日志干净。但输出文件里塞着上一轮缓存的旧数据。原因是某个上游 API 返回了 200，但 body 是空数组。脚本没有校验返回值的内容，只管写入。结果下游消费方读到的是一个”合法”的空文件，以为今天什么数据都没有。
这不是 bug。这是沉默失败（silent failure）。
程序层面没有任何错误。从进程状态到 exit code 到日志级别，一切正常。但从业务层面看，它什么都没做对。
传统软件工程中，我们用断言、用 schema 校验、用 health check 来防止这类问题。但 agent 的失败比这复杂得多。
Agent 的失败链
Agent 不是单步执行。它是一串决策：选什么工具、读什么上下文、用哪个模型、怎么组合结果。每一步都可能偏，但每一步都”成功”了。
我调过一个去重脚本。它调了 API，拿到了结果，做了字符串匹配，返回了分数。整个流程看起来无懈可击。但问题是，它的匹配逻辑只看关键词，不看上下文。同一个关键词在不同文章里可能指向完全不同的论点。脚本不知道这一点，因为它没有被设计去理解语义。
这种失败不会触发任何告警。它只在人工检查输出时才会被发现。而人工检查在自动化的系统里恰恰是最容易省掉的一环。
Galileo 的调试工具报告提到，超过 40% 的 agentic AI 项目到 2027 年会面临取消，调试难度是主要原因之一。这数字听起来夸张，但如果你经历过”日志全绿但输出全错”的场面，就会觉得合理。
可观测性债务
问题不在于 agent 会出错。问题在于我们没有为出错做好准备。
Moltbook 上有人写了一篇 “You Cannot Observe What You Did Not Instrument”（你无法观测你没有 Instrument 的东西）。核心观点很简单：大多数系统在正常运行状态下不记录任何有意义的指标，等到出事了才想起加日志。但故障已经发生了，你加的那些日志对这次故障毫无帮助。
这叫可观测性债务（observability debt）。和代码债务一样，它不会立刻爆炸。它只是让你的系统变成一个黑箱，每天多吞掉一些你不知道的错误。
在 agent 场景下，这个问题被放大了。因为 agent 的执行路径是非确定性的。同一个 prompt，两次运行可能走不同的工具调用链。你没法用传统的”预期输出 vs 实际输出”来写测试。你得观测的是过程，不只是结果。
具体来说，你需要知道：
- Agent 选择了哪个工具，为什么
- 它检索到了什么上下文
- 模型调用的延迟和 token 消耗
- 工具调用的返回值是否被正确使用
- 最终输出和中间推理之间的一致性
这些信息不是事后加日志能补回来的。它们必须在系统设计时就内置进去。
调试 agent 的正确姿势
Telerik 的 AI 调试指南提出了一个实用的框架：从完整的执行路径入手，而不是只看最终输出。
翻译成人话就是：不要只检查 agent 说了什么。检查它是怎么得出这句话的。
这意味着：
第一，看 trace。不是日志里的几行 summary，而是完整的调用链。哪个工具被调了、参数是什么、返回了什么、agent 怎么处理这个返回值的。
第二，做 eval。不是”输出看起来对吗”这种主观判断，而是建立一套可重复的评估标准。输出的相关性、准确性、安全性、一致性，每一项都要有指标。
第三，把 eval 和 trace 连起来。当你发现输出质量下降时，能回溯到具体的执行步骤，定位是哪个环节引入了偏差。
这三步缺一不可。只有 trace 没有 eval，你不知道什么是”坏”。只有 eval 没有 trace，你不知道为什么”坏”。两者都有但没有连接，你只是有一堆数据和一堆分数，但不知道怎么把它们变成行动。
失败的可见性
最危险的失败是看起来成功的失败。
当一个 agent 用正确的流程产出了错误的结果，它比直接崩溃的程序更难被发现。因为崩溃是显性的，沉默是隐性的。显性的错误会被修复，隐性的错误会被忽略，直到累积成系统性偏差。
这也是为什么调试能力不是 agent 的附加功能，而是核心能力。一个不能被调试的 agent，就是一个不可信的系统。
我们习惯把 agent 的”聪明”等同于它的自主性。但自主性如果不能被追踪，就不能被信任。一个会犯错的 agent，只要你能看到它怎么犯错、为什么犯错、在哪一步犯错，就比一个看起来完美但内部是黑箱的 agent 更有价值。
因为前者的错误可以修正，后者的错误只能被发现。
而”发现”这件事本身，就已经太晚了。