如何诊断 AI Agent 错误？端到端追踪与告警的实用清单

Agent 错误可能源于模型、知识检索、工具参数、权限或外部 API。如果没有统一的追踪机制，团队只能靠猜测来修改提示词。而通过端到端的事件记录，他们可以定位到第一个异常步骤并验证修复效果。

为什么传统日志不够用

单个 Agent 任务可能涉及规划、检索、模型调用、工具调用、重试、审批和结果聚合。最终答案不正确，并不一定意味着模型本身出错。它也可能由过时的知识片段、生成的参数错误、权限拒绝或外部 API 超时引起。可观测性必须将所有这些步骤连接在同一个追踪链路中。

每个事件需要记录什么

• 统一的追踪 ID、任务 ID 和步骤 ID。
• Agent、提示词、模型、技能和知识库的版本信息。
• 开始时间、耗时、状态、重试次数及依赖步骤。
• 脱敏后的输入输出摘要，以及指向原始对象的引用。
• 工具参数摘要、返回状态及最终的外部状态。
• 任何人工审批的结果、审批人及时间。

默认情况下，不要将完整的提示词、响应、凭证或个人信息写入日志。根据风险等级，应采用脱敏、摘要、哈希处理或受控的对象存储。

将指标分为五类进行细分

平均值会掩盖尾部问题。指标应按任务类型、版本、工具和租户进行细分，同时需监控高百分位延迟。

告警必须直接指导行动

“错误率上升”无法说明影响范围或修复路径。有效的告警应明确指出受影响的具体工具和任务，说明问题发生的时间，并关联责任人、操作手册和恢复标准。仅在已验证的备用路径可用时才自动切换。对于写操作，还必须防止重复执行。

问题排查的标准流程

1. 确认用户看到的最终状态及对应的追踪 ID。
2. 定位第一个出现异常的步骤，而不是只看最后的报错信息。
3. 核实该时刻的版本、输入摘要、检索到的证据及工具响应。
4. 判断原因是偶发的数据问题、依赖服务故障还是版本回退。
5. 应用修复后，重放原始的失败样本，并将其加入回归测试集。

常见误区

• 仅记录模型调用，忽略知识、权限和工具。
• 存储所有原始文本，从而增加隐私风险。
• 收集大量指标，但未定义阈值、责任人或应对措施。
• 上线后才添加追踪功能，导致无法重建历史故障。

常见问题解答

可观测性与 APM 有什么区别？

APM 侧重于服务和 API。Agent 可观测性还需关联提示词、检索、工具决策、质量、成本和审批。两者应互为补充。

是否需要存储完整的输入和输出？

不需要。根据业务风险，可采用脱敏、摘要、哈希、采样或受控引用，同时设置访问控制和保留期限。

应该优先实施什么？

首先标准化追踪 ID 和任务成功的定义。然后逐步添加步骤事件、质量评估和可操作的告警。

下一步该做什么

从在一个关键的 SmaugBrain 工作流中标准化追踪和版本字段开始。选择一个历史失败案例进行完整重放，以确认日志既能精准定位问题，又不会泄露敏感信息。