Agent 可观测性怎么做：日志、轨迹、成本和失败复盘

Agent 一旦开始调用工具、读取知识库、保存记忆、执行多步任务，就不能只看最终回答。你需要知道它为什么这么做、调用了哪些工具、拿到了什么结果、花了多少钱、哪里失败了。Agent 可观测性的目标，就是让这些过程可追踪、可复盘、可改进。

这篇是草稿，可以和 Agent 生产上线检查表、Agent 工具调用怎么设计 一起使用。

适合谁

适合准备把 Agent 用于真实用户、客户项目或内部工作流的人。你可能已经有 demo，但出错时只能看最终结果，不知道中间发生了什么。

也适合做交付维护的人。没有日志和轨迹，客户反馈“它答错了”时，你很难定位是检索错、模型错、工具错还是权限错。

不适合谁

不适合只做一次性个人实验的人。个人实验可以简化日志，但只要给别人用，就需要最基本的记录。

如果系统处理敏感信息，日志设计要更谨慎。不能为了排查方便保存所有原文。

记录用户请求

记录用户请求有助于复盘，但要考虑隐私。可以记录脱敏后的请求、请求类型、时间、用户角色和任务 ID。

不要长期保存不必要的敏感内容。日志保存时间和访问权限要写清楚。

记录检索和记忆

如果 Agent 使用 RAG，要记录检索到哪些文档片段、来源、分数和权限过滤结果。如果使用记忆，要记录读取了哪些记忆、是否写入新记忆。

这样可以判断回答错是因为资料没找到，还是模型没有正确使用资料。

记录工具调用

工具调用要记录工具名、参数、返回结果、耗时、错误和确认人。写入工具和外部执行工具尤其要清楚。

如果 Agent 执行了高风险动作，日志要能追踪是谁触发、谁确认、结果是什么。

记录成本和延迟

Agent 可能多次调用模型和工具。记录每次调用的模型、输入长度、输出长度、耗时和大致成本，才能判断系统是否可持续。

没有成本记录，原型上线后很容易费用失控。

记录用户反馈

用户反馈可以分成回答错误、资料过期、权限问题、工具失败、体验慢、无法理解。不同反馈对应不同优化方向。

不要只收集“满意/不满意”。要能定位原因。

常见错误

常见错误是只记录最终回答，不记录中间过程。Agent 出错时，你需要知道它读了哪些资料、调用了哪些工具、用了什么模型、哪里超时、谁确认了动作。没有轨迹，就无法复盘。

交付记录里要写清日志字段、保存时间、访问权限、脱敏规则、成本统计和报警负责人。可观测性本身也需要维护，不是加一个日志开关就结束。

风险提醒

日志本身也可能成为风险源。它可能包含用户隐私、客户资料、模型输出、工具参数和内部文档片段。

可观测性不是无限记录，而是记录足够排查的信息，同时控制访问、脱敏和保存时间。

具体步骤

第一步，为每次 Agent 任务生成唯一 ID。

第二步，记录用户请求、检索、记忆、模型调用和工具调用。

第三步，记录成本、延迟、错误和人工确认点。

第四步，设计用户反馈分类。

第五步，定期复盘失败案例。需要日志检查表或人工协助，可以从 工具导航 进入。

发布前复核点

发布前要补一张日志字段表，说明任务 ID、用户角色、检索来源、工具调用、模型名称、成本、延迟、错误和人工确认分别如何记录。没有字段表，读者很难落地。

还要补隐私说明。日志不是越多越好，尤其是客户资料、内部文档和用户输入都可能敏感。文章发布前要检查是否明确写了脱敏、访问权限和保存时间。

给客户解释时，可以把可观测性说成“Agent 的黑匣子记录”。没有记录，Agent 出错后只能猜；有记录，才能知道问题出在用户输入、知识库、模型、工具还是权限。这个解释能帮助客户理解为什么日志和监控不是额外花活，而是生产上线的必要部分。

免责声明

本文是 Agent 可观测性设计草稿，不构成日志平台或隐私合规建议。不同系统和行业要求不同，正式发布前需要人工复核。涉及敏感数据时，请由专业人员评估。