一次看似完整的 AI Agent 运行日志，可能从第一条工具调用开始就不可信。问题不在于模型没有输出结果，而在于日志没有记录它到底看到了哪些工具。Dev.to AI 上一篇关于 Agent 可观测性的文章，用一个很具体的调试案例提出了一个容易被忽略的细节：在相信 Trace 之前，先把工具目录固定下来并计算哈希。
文章描述的场景并不复杂：一个 Agent 在四次工具调用后输出了 done，JSONL 日志表面完整。但其中出现了一个名为 run_tests 的调用，而本地运行环境从未注册过这个工具。真实暴露给模型的工具只有 pytest、read_file 和 grep。运行时仍然接受了这个并不存在的调用，并返回了一行错误信息。模型随后道歉，改调 pytest，最终助手消息仍显示 green。
表面上看，任务完成了；实际上，这次运行浪费了大量调试时间。真正的问题不是模型胡乱调用，而是日志里没有记录模型当时拿到的工具目录。缺少这一份 catalog，后续所有回放、对比和审计都可能建立在错误的契约之上。
Agent Trace 缺的不只是调用记录
目前多数 Agent 日志会保存工具名、参数和输出，却经常跳过模型实际接收到的工具列表。这样一来，回放系统只能拿日志中的调用和当前环境里的工具做对比，而不是和当时模型看到的工具集合做对比。
文章指出，这类缺失会让三类事件被误判为模型失败：
- 模型调用了未注册工具名；
- 工具目录发生变化导致调用行为漂移；
- 工具结果与调用 ID 无法对应。
这些本质上都是 catalog 事件，而不是单纯的模型问题。如果日志不记录工具目录，调试者很容易把系统性配置问题误读为模型能力问题。尤其是在 Agent 自动化调试、自动修代码、自动测试等场景里，这种误判会显著增加排查成本。
先冻结目录，再记录调用
文章给出的做法很直接：在第一次向模型发起补全请求之前，先冻结工具目录。对工具名排序，形成稳定顺序，再对规范化后的内容计算一次 SHA-256 哈希。之后每一次工具调用都可以通过 catalog_sha256 关联到同一份工具集合。
这样一来，不同运行之间是否可比，就有了明确依据。两次运行如果 catalog_sha256 不同，就不能简单对比它们的行为；如果要分析差异，也应该先比较工具目录，而不是先比较提示词。
但仅有工具名哈希还不够。名称哈希可以快速发现模型是否调用了不存在的工具，却无法发现同名工具的字段发生变化。例如，read_file 原本只需要 path 参数，后来增加了一个 offset 字段。此时工具名没有变，名称哈希也不会变，但调用契约已经发生漂移。
因此，文章建议同时对每个工具的 JSON Schema 做哈希。为了得到稳定结果，序列化时需要排序键、去掉多余空白，再对 UTF-8 字节计算 SHA-256。名称哈希用于识别未注册工具，Schema 哈希用于识别字段级变化，两者结合起来，调试循环才能区分是工具不存在，还是工具定义发生了改变。
从可读日志走向可审计日志
文章还提供了一个本地示例脚本，用于演示这种日志结构。示例中会写入一条 catalog 事件，记录运行 ID、开始时间、工具名列表、目录哈希以及每个工具的 Schema 哈希。后续的 tool_call 事件会带上 catalog_sha256，并标记调用对象是否为已知工具；tool_result 事件则检查结果是否与调用 ID 匹配。
在这个示例里，未注册的 run_tests 会被标记为 UNKNOWN_TOOL；一个从未发出的调用 ID 返回结果时，会被标记为 ID_MISMATCH；目录中没有被使用过的工具，也会通过 catalog_unused 事件单独记录。
这种设计的意义不只是让日志更详细，而是让 Agent 行为具备审计基础。对于 AI 编程 Agent、自动化运维 Agent 和企业内部工具型 Agent 来说，日志不仅要能复盘成功路径，也要能解释失败路径。未知工具调用、工具目录变化、结果与调用不匹配，都应该成为一等事件，而不是被淹没在普通输出里。
随着 Agent 越来越多地进入真实生产流程，Trace 的价值正在从观察模型变成验证系统。模型输出只是结果的一部分，运行时暴露给它的工具集合、调用契约和结果关联方式，共同决定了一次执行是否可以被复现、回放和审计。工具目录哈希看似只是一个工程细节，却可能是判断 Agent 日志是否可信的第一步。
原创文章，作者：点点，如若转载，请注明出处：https://www.dian8dian.com/ai-agent-ri-zhi-li-de-you-ling-gong-ju-wei-shen-me-trace-ke
