读完第十二章和 Extra09 后的一些思考：Agent 不报错却答错了，该怎么查

[TanZeyu]

最近读完第十二章和 Extra09，有一些想法想跟大家聊聊。第十二章讲的是怎么用基准测试给智能体打分，Extra09 里作者手写 Trace、一步步定位 tool failed 的过程，我读得特别有共鸣。不过读完以后我一直在想另一个问题：Agent 真正上线以后，最让人头疼的往往不是明显的报错，而是它没报错，结果却不对。比如编造了工具没返回过的数字、搜索失败了却照样给出一个像样的回答、在同一步反复打转。

下面是我们平时排查这类问题时摸索出来的几个做法，都可以直接用在 HelloAgents 的项目里。

1. 先看记录，再改提示词

Extra09 第四章提到过一个很常见的习惯：Agent 一出错就去改提示词。问题是，大部分时候原因根本不在提示词，而是工具返回了空数据、上下文里缺了关键信息，或者参数传错了。改提示词等于在没看病历的情况下开药。

所以第一步永远是打开那次运行的完整记录，看每一步的输入、输出和工具返回值。确认问题出在哪一层，再决定改什么。

2. 工具失败要说出来，不要返回空

这是最容易被忽略、也最常见的一个坑。很多工具写成下面这样：

def search(query: str) -> str:
    try:
        return call_search_api(query)
    except Exception:
        return ""   # 失败了返回空字符串

模型拿到空字符串，并不知道是"没有结果"还是"调用失败了"，往往会自己补一个答案。Extra09 第二章说的"错误在链路里被压扁了"就是这个情况。更好的写法是把失败原因明确告诉模型：

def search(query: str) -> str:
    try:
        result = call_search_api(query)
        return result if result else "搜索成功，但没有找到相关结果。"
    except Exception as e:
        return f"搜索失败：{type(e).__name__}: {e}。请告知用户无法完成搜索，不要自行推测。"

改动很小，但能挡掉一大类"安静的错误"。

3. 记录要能串起来看

Extra09 第六章总结过几条原则：结构化、上下文完整、不清洗失败。我们想补充一点：每条记录都要带上同一次运行的 ID，并且记下父子关系（哪次模型调用触发了哪次工具调用）。这样出问题时你看到的是一棵完整的调用树，而不是一堆散落的日志。

这套格式现在有行业标准，叫 OpenTelemetry，里面的 trace 代表一次完整运行，span 代表其中的一个步骤。如果不想自己设计格式，可以直接按这个标准来记。

4. 记录多了，让模型帮你筛

上线以后一天可能跑几百上千次，人是看不过来的。一个实用的做法是写一条检查规则，让另一个大模型去过一遍所有记录，比如：

请检查这次运行的最终回答。
如果回答里出现的具体数字或事实，在本次所有工具返回的内容中都找不到依据，判为"有问题"。
如果回答明确说明了无法获取信息，判为"不适用"。
只判断依据是否来自工具，不评价语气和长短。

写规则时有几个经验：一条规则只查一件事；把"有问题"和"没问题"的边界写清楚；跟当前问题无关的情况标成"不适用"，否则统计结果会失真。另外，检查用的模型最好和被检查的模型不是同一家，不然容易互相放水。

5. 把踩过的坑存下来

找到问题、修好以后，把这次的输入和当时工具返回的数据一起存成一个测试用例。以后改提示词或换模型之前先跑一遍，确认之前修好的问题没有再出现。

这里要注意：搜索结果、新闻这类外部数据每天都在变，测试时要用当时记录下来的工具返回值，而不是重新去查，否则前后结果没法比较。

---

上面这些，自己动手完全可以实现，Extra09 的作者就是这么做的。不过要是每个项目都从头搭一遍，确实挺费时间。

我们团队在做的开源项目 TraceRoot 就是想把这一整套流程自动化：按 OpenTelemetry 记录运行轨迹，用大模型按你写的规则自动筛查问题，再结合源码和 Git 提交记录定位到出错的代码行，给出修复建议。调试用的模型可以接 DeepSeek、Kimi、GLM 这些国产模型，也可以用 Docker 一键部署在自己的服务器上。项目是开源免费的，云服务也有免费额度。如果大家感兴趣，我们很乐意手把手教大家接到自己的 HelloAgents 项目里。

项目地址：https://github.com/traceroot-ai/traceroot

我们现在还是一个刚起步的开源社区项目，特别需要大家的意见。用的时候遇到任何问题、觉得哪里不好用，都欢迎直接在这里或者 GitHub 上告诉我们，每一条反馈对我们都很重要。

当然，做这件事的工具不止我们一家，像 Langfuse、Arize Phoenix 也都是开源的，大家可以多试几个，挑最适合自己项目的。

也很想听听大家平时是怎么排查 Agent 问题的，踩过哪些坑。如果感兴趣的人多，我们也可以写一篇完整的实战教程，投稿到 Extra-Chapter。