21. 可观测性：看清一次 Agent 为什么失败

Agent 失败经常不是最后一步失败

最终回复不好，原因可能在很早之前：

搜索结果差
网页没抓到正文
工具参数错
子 Agent 跑偏
模型上下文被噪声淹没

所以只看最后回答没有用。

DeerFlow 的 tracing 目录

相关源码：

backend/packages/harness/deerflow/tracing/

能看到：

factory.py
metadata.py

runtime 里也有 events store、stream bridge、runs store 等模块。

这些共同决定你能不能看清一次 run。

应该观察什么

一次 Agent 任务至少要看：

输入目标
模型调用
工具调用
工具返回
中间事件
最终输出
文件产物
错误堆栈

如果有 tracing 平台，还要看每一步耗时和 token 消耗。

常见排查顺序

不要直接改 prompt。

先按这个顺序排：

配置是否读到
模型是否调用成功
搜索是否返回可用资料
工具是否执行成功
中间事件是否正常
最终报告是否基于证据

这一篇你要记住

可观测性不是上线以后才需要。

只要你开始做复杂 Agent，tracing 和事件记录就是开发工具。

下一篇专门看一次任务为什么失败。

一次 run 应该留下什么

比较理想的记录包括：

run id
thread id
用户输入
模型调用
工具调用
工具返回
生成文件路径
错误堆栈
耗时和 token

没有这些信息，排错只能靠猜。

metadata 的价值

tracing/metadata.py 这类文件通常负责把运行上下文整理成可追踪信息。

metadata 不只是附加信息。

它能帮你回答：这次任务用的是哪个模型、哪个用户、哪个配置、哪个 run。

开发阶段就要开观测

不要等上线后才接 tracing。

复杂 Agent 的开发阶段，tracing 就是调试器。