告别智能体「盲盒」，一次线上事故之后，我们决定给每个推理步骤都打上“调试桩”
事情的起因，其实非常普通。某个工作日下午，一个已经跑了两个月、看起来“还算稳定”的 Agent 服务，突然在生产环境出现了零星失败。失败比例不高，大概 1% 左右，但问题在于——这些失败没有任何规律。
有时是工具没调用
有时是调用了，但结果没被用
有时 Agent 给了一个逻辑完全不通的最终结论
更糟糕的是，当你试图复现时，它又表现得一切正常。我们能拿到的，只有一堆对话日志。那一刻你会意识到一个残酷的事实：这个 Agent 在“干什么”，我们其实并不知道。它像一个包装精美、行为不可预测的黑盒。而这，正是智能体系统在工程上最危险的状态。
一、从“它答错了”，到“我们不知道它为什么会这么做”
在最初的排查阶段，我们做的事情，和大多数团队一模一样：
翻对话记录
对照 Prompt
看模型版本是否变更
猜是不是“模型抽风”
但很快就发现，这条路是走不通的。原因很简单：对话日志不是调试信息，它只是“结果的叙述”。你看得到 Agent 说了什么，却看不到：
它是基于什么判断选择了这个工具
中间是否考虑过其他路径
是规划阶段出了问题，还是执行阶段偏航
是模型判断错误，还是系统调度错误
这就像在调一个分布式系统，却只保留了 HTTP Response，没有任何 trace。在 Demo 阶段，这种方式还能凑合；一旦进生产，它就会变成一种工程灾难。
二、一个关键转变：我们不再把 Agent 当“会聊天的模型”
真正的转折点，是我们内部一次非常工程化的讨论。有人问了一个听起来有点“反直觉”的问题：如果我们今天不用 LLM，而是用一堆普通函数拼成一个系统，我们会允许它这样不可观测吗？答案显然是否定的。于是我们开始重新定义这套系统：
Agent 不是一个对话对象，而是一条“带概率性的推理流水线”。
只要是流水线，在工程上就一定有几个基本要求：
每一步是否被执行过
每一步输入输出是什么
为什么从这一步走到下一步
哪里失败了，失败时系统处于什么状态
如果这些问题回答不了，那它就不是一个可上线的系统。
三、第一次尝试“打桩”：从粗暴日志到结构化事件
一开始，我们的做法其实非常朴素，甚至有点“土”。我们没有立刻上复杂的观测框架，而是先做了一件事：强制把 Agent 的执行过程拆成显式阶段。
例如：
输入解析
任务理解 / 规划
决策选择
工具调用
结果评估
状态更新
然后规定一条硬规则：每一个阶段结束，必须产出一个结构化事件。不是自然语言，不是随手 print，而是明确 schema 的工程事件。
{ "trace_id": "req-123", "stage": "decision"," agent": "PlannerAgent", "input": {...}, "output": {...}, "chosen_action": "search_docs", "reason_code": "need_external_knowledge", "timestamp": "2025-01-05T10:32:11Z" }这一步看起来很琐碎，但它带来的改变是立竿见影的。
四、当你第一次“看见”Agent 的推理路径
有一次线上失败，我们终于不再是“猜”。通过 trace，我们看到完整路径是这样的：
Planning 阶段给出了一个合理的任务拆分
Decision 阶段选择了正确的工具
Tool 调用返回了空结果
Observation 阶段没有识别这是一个异常
系统继续往下执行，最终生成了一个“看起来像是成功”的错误答案
这不是模型幻觉，也不是 Prompt 写错。这是一个非常标准的工程问题：异常没有被显式建模。如果没有这些调试桩，这条结论是永远不可能被确认的。你只能不停地换 Prompt，换模型，祈祷“下次好一点”。
五、后来我们系统性做的三件事
在那之后，我们对 Agent 系统做了三层改造。
推理与决策必须“留痕”
不要求模型解释自己，而是解释：
当前目标是什么
可选动作有哪些
最终选了哪一个
哪怕理由是概率性的，也要在系统层留下记录。选择本身，就是最重要的调试信号。
工具调用彻底结构化
我们明确禁止两件事：
用自然语言描述工具参数
用自然语言解释工具结果
所有工具调用都必须是：
严格 Schema
明确成功 / 失败状态
明确是否可重试
这一步极大地降低了“看起来调用了，实际上没用”的隐性失败。
引入真正的全链路追踪
当 Agent 数量和步骤多起来后，我们直接复用了成熟方案：
每个请求一个
trace_id每个 Agent 一个
span每一步记录延迟、Token、成功率
直接接 OpenTelemetry，丢给现有的监控系统。不要为 Agent 发明一套新的工程哲学。
六、一个被严重低估的能力：可回放
后来我们发现，最有价值的不是实时监控，而是回放能力。当你可以：
固定输入
固定中间状态
重跑一次完整推理流程
你就拥有了：
可复现的线上事故
可量化的优化效果
可做回归测试的 Agent
这一步，直接把 Agent 从“玄学系统”，拉回到了工程世界。
Agent 可以是概率的，但系统不能是
现在回头看，那次事故其实是件好事。它逼着我们承认一个事实：LLM 的推理可以不可预测，但 Agent 系统的行为路径必须是可追踪的。推理可以是黑盒，但决策链路不能。模型可以犯错，但系统必须知道错在哪里。否则，你永远只是在：和一个包装精美的盲盒共事。真正成熟的智能体系统，不是“每次都很聪明”，而是每一次失败，都能被完整解释、稳定复现、明确归因。这不是降低对智能的期待，这是把智能，真正带进工程世界。