摘要

前两篇文章，我们已经完成了企业级 Agent 的工具调用、权限校验、风险分级、人工确认和审批流。

到这里，Agent 已经不只是一个“会聊天的机器人”，而是可以连接真实业务系统、调用工具、执行任务、进入审批流程的业务执行单元。

但一旦 Agent 上线，就会出现一个更现实的问题：

用户说“AI 执行错了”，开发者到底怎么排查？

在传统后端系统里，排查问题通常看接口日志、错误堆栈、数据库记录和监控指标。但 Agent 系统更复杂，因为一次请求可能包含：

• 多次模型调用；
• 多次工具选择；
• 多次工具执行；
• RAG 检索；
• 审批流；
• 人工参数修改；
• 失败重试；
• 多轮状态变化；
• Token 成本；
• Prompt 版本；
• 模型输出不确定性。

如果没有完整 Trace，Agent 系统上线后会非常难维护。

本文将围绕 Agent Trace、可观测性和调试面板展开，完整讲解如何记录、展示和分析一次 Agent 任务的全链路执行过程。

本文重点包括：

1. 为什么 Agent 必须有 Trace；
2. Agent Trace 与普通日志的区别；
3. 一次 Agent Run 应该记录哪些数据；
4. Trace、Span、Event 的数据模型；