第 29 章 可观测性设计

如果团队看不见 Agent 当时看到了什么、做了什么、为什么这么做，就无法真正调试它。可观测性不是附带日志，而是 Agent 工程闭环的前提。

29.1 日志

至少要记录任务入口、关键状态变化、工具调用摘要、错误类型和终止原因。日志不是为了还原所有细节，而是为了让团队知道系统在哪一步开始偏离。

29.2 Trace

多步任务尤其需要链路视图。一次任务可能包含多轮模型调用、多次工具调用和多个状态转换，没有 trace，团队很难重建执行路径。

29.3 指标

比起传统接口系统，Agent 更需要观察：

• 成功率。
• 延迟分布。
• 工具失败率。
• 人工介入率。
• 每任务成本。

29.4 本章小结

可观测性让 Agent 从“黑盒体验”变成“可调试系统”。没有它，Prompt、RAG、Memory、Workflow 和 Tool Use 的所有优化，最终都会退化成凭印象调参。