AI Agent 实战教程 18：日志、Trace 与可观测性

Agent 可观测性决定了系统能不能被维护。没有日志和 trace，Agent 出错时只能靠猜。尤其是多步骤任务中，模型判断、工具调用、状态变化、用户确认和错误恢复都会影响最终结果。

可观测性不是简单打印 console，而是让开发者能复盘 Agent 的完整执行链路。

需要记录什么

一次 Agent 任务至少应记录用户请求、模型计划、工具调用、工具参数、工具结果、状态变化、用户确认、错误信息和最终输出。

敏感信息必须脱敏，例如 token、密码、个人信息、内部密钥。日志系统既要可调试，也要安全。

Trace 结构

Trace 可以把任务表示成时间线或树。根节点是用户目标，子节点是计划步骤、工具调用和状态转移。

例如创建教程的 trace 包括查询文章、创建 tutorial、绑定文章、验证结果。每个节点记录输入、输出、耗时和状态。

这种结构比纯文本日志更适合排查复杂问题。

模型输入输出

是否记录完整 prompt 需要谨慎。完整 prompt 有助于调试，但可能包含敏感数据。生产系统可以记录摘要、哈希、脱敏内容或仅在调试模式记录。

模型输出也要记录关键决策，例如为什么选择某个工具，为什么认为任务完成。

工具调用日志

工具调用日志是最重要的部分。每次调用应记录工具名、参数、风险等级、执行结果、错误类型和耗时。

如果 Agent 报告成功但用户发现结果不对，工具日志能快速判断是模型误判、工具失败，还是后端接口返回异常。

状态变化

长任务需要记录状态变化。例如 pending 到 running，running 到 waiting_approval，waiting_approval 到 completed。

状态日志可以帮助判断任务卡在哪里。是等待授权，还是等待用户确认，还是某个工具一直失败。

指标监控

除了日志，还可以统计指标：任务成功率、平均执行时间、工具失败率、用户确认率、重试次数、模型调用成本。

这些指标能帮助发现系统性问题。例如某个工具失败率突然升高，可能是外部 API 变更。

小结

可观测性让 Agent 从“黑盒自动化”变成可解释的工程系统。日志、trace、状态记录和指标监控，是 Agent 进入生产环境的基础设施。

实战案例：追踪一次失败的工具调用

假设 Agent 调用 upload-link 后返回了一个看似成功的 URL，但页面图片无法显示。没有 trace 时，只能猜是前端、CDN 还是上传接口问题。

有了可观测性，就可以看到：Agent 选择了 material upload-link 工具，传入了外部 SVG URL，工具返回了 cdn.portal.levenx.com 地址，随后验证阶段 curl 返回 404。这样就能定位到上传接口返回了不可访问的旧 CDN URL，而不是标签更新错误。

这类 trace 对 Agent 非常关键。它不仅帮助开发者修 bug，也帮助用户理解 Agent 为什么需要重试、为什么需要修改流程。

从日志到告警

可观测性不应只停留在事后查看日志。生产系统还需要告警。例如某个工具连续失败、某类权限错误突然增加、平均执行时间显著升高、用户确认后仍执行失败，都应该触发告警。

这些告警可以帮助团队在用户反馈前发现问题。对于 Agent 系统，工具链和外部 API 变化很常见，自动化监控能显著降低维护成本。

成本与性能指标

Agent 可观测性还应包含成本指标。每次任务消耗多少 token、调用多少次模型、执行多少个工具、耗时多久，都应该被记录。

这些数据能帮助团队优化工作流。例如某个步骤总是重复检索，可能需要缓存；某个模型调用成本过高，可能可以换成小模型；某个工具耗时过长，可能需要异步化。