Agent 项目日志应该记录什么

先说结论。

Agent 日志不能只记录提示词和模型回答。一次任务可能经历路由、检索、工具调用、人工审批、重试和降级。日志的目标是重建这条链：任务为什么开始，依据什么做决定，实际执行了什么，最终由谁确认。

如果线上问题只能看到“模型返回 200”，就无法区分模型、数据、工具还是流程状态出了问题。

先建立贯穿全程的任务身份

每个任务至少要有 task_id，并把同一任务中的多次模型调用、工具调用和审批事件串起来。若任务由外部请求触发，还要保存 request_id、来源系统和去敏后的业务对象标识。

不要用用户姓名、邮件正文或客户名称充当关联键。它们既不稳定，也可能扩大敏感信息暴露。业务标识应可追溯但受访问控制。

判断日志是否够用，可以随机拿一条最终结果，检查能否反向找到它的触发入口和完整事件序列。

输入日志要记录来源与快照，不是无限复制原文

需要知道输入来自表单、邮件、知识库还是人工补充，以及读取时的版本和时间。关键字段可以保存受控快照，敏感正文则可保存引用、哈希或脱敏摘要。

为什么要记录版本？因为知识库文档和 CRM 字段会变化。没有快照或版本号，事后无法判断错误来自当时的数据，还是后来更新的内容。

边界是隐私和保留周期。日志不是第二套业务数据库，不应为了排障永久复制全部客户材料。

模型调用要能比较版本和成本

建议记录业务动作名、模型供应方与模型标识、提示模板版本、输入输出 token 或供应方提供的用量字段、延迟、重试、错误码和结构化校验结果。

不要只保存完整 Prompt。更重要的是它属于哪个业务版本，以及运行时拼入了哪些资料引用。对于动态提示，可记录模板 ID、变量摘要和内容哈希。

成本字段要以供应方实际返回和项目计费规则为准。价格会变化，日志保存用量比把价格写死更稳妥。

工具调用日志要记录“想做什么”和“做成没有”

工具事件至少包含工具名、调用目的、参数摘要、权限主体、开始与结束时间、结果状态、外部系统返回标识、是否重试和幂等键。

参数摘要不是把密钥和全部请求体写进去。访问令牌、身份证件、合同原文等应过滤；对关键写操作，可以保存字段差异和目标资源 ID。

还要区分计划与执行。Agent 提议删除文档，不等于删除已经发生。日志里应有 proposed、approved、executed、failed 等明确状态。

状态变化是 Agent 日志区别于聊天日志的地方

一个状态化流程会在“等待检索”“等待人工补充”“等待审批”“执行中”“降级人工”等状态间切换。每次变化要记录前状态、后状态、触发事件和流程版本。

当任务卡住时，团队最先要问的是“停在哪个状态、在等谁”。如果日志只有一串自然语言消息，这个问题很难回答。

状态定义不宜过细。每个状态都应对应不同的允许动作、责任角色或恢复策略，否则只是命名噪音。

人工审批要记录看到什么、改了什么

审批事件包括审批请求时间、审批人角色、输入与动作快照、批准结果、修改差异、退回原因、超时和最终执行结果。

只记“张三批准”仍然不够。要知道批准的是哪一版邮件、哪个收件人和哪些附件。关键字段变化后，原批准应失效。

人工修改是高价值评估数据，但使用前要去敏并明确用途，不能默认拿所有员工操作训练模型。

失败原因要分层，不要都写成 Agent 错误

可以至少分为：输入缺失、检索无结果、模型超时、输出格式错误、策略拒绝、工具权限不足、外部系统失败、审批超时、业务规则不满足和未知错误。

错误分类的价值在于对应不同处理人。数据问题交给知识库运营，权限问题交给系统管理员，提示与结构化输出问题交给应用团队。

“未知错误”可以保留，但每周应复盘占比高的未知项并补分类。否则它会成为所有难题的垃圾桶。

一套最小字段可以这样组织

| 事件组 | 关键字段 | | --- | --- | | 任务 | task_id、workflow_version、trigger、business_object_id、created_at | | 输入 | source_type、source_ref、source_version、input_hash、redaction_status | | 模型 | action_name、model_id、prompt_version、usage、latency、validation_status | | 工具 | tool_name、intent、actor、parameter_summary、idempotency_key、result | | 状态 | from_state、to_state、reason、event_time | | 审批 | approver_role、decision、snapshot_hash、changes、expired_at | | 结果 | final_status、output_ref、fallback_used、failure_category |

字段名称可以调整，但任务、输入、决策、动作、审批和结果六层不能缺。

常见误区会让日志既贵又没用

可以把日志查询能力也写进验收。值班人员应能按业务对象查最近任务，按失败类别聚合，定位某个流程版本的异常，并从审批事件跳到最终执行结果。若日志只能由开发者写 SQL 临时查，业务审核和日常运维仍然没有真正入口。

告警也不应只盯模型错误率。任务长期停在待审批、工具重复调用、单任务用量异常、敏感字段过滤失败，都可能比一次模型超时更值得立即处理。每种告警都要对应责任角色和降级动作。

第一，记录全部内容，却没有 task_id 串联。第二，只记录成功请求，不记录被拒绝、超时和降级。第三，日志包含密钥或敏感原文。第四，没有版本字段，无法比较变更前后。第五，日志存在，却没有查询视图和告警负责人。

另一个反例是为了“可观测”把每个思考文本都长期保存。自然语言推理并不等于可靠证据，真正需要的是输入来源、决策结果、工具动作和状态变化。

上线前做一次任务重放检查

1. 选一条成功任务和三条不同失败任务。
2. 从最终结果反查触发入口。
3. 核对每次状态变化和工具动作。
4. 确认审批绑定了确定快照。
5. 检查敏感字段是否被过滤。
6. 用流程版本定位当时运行的逻辑。
7. 验证故障能否分派给明确责任人。

下一步可以先定义一张事件表和六类事件，而不是先采购观测平台。日志结构不清楚，换任何平台都只会得到更多难以解释的数据。

发生了什么、真正变化与后续观察信号

发生了什么：Agent 任务从一次模型调用扩展为计划、工具、状态和人工审批链。真正变化是团队能从最终回答追到每个中间决定。后续观察信号有三项：

1. 信号一：同一故障是否能稳定归到同一责任层。
2. 信号二：一次任务能否在脱敏后被重放。
3. 信号三：升级后成本和失败分布的变化能否定位到具体版本。

低风险个人实验不必保存完整输入与长期轨迹，这是隐私和成本边界。生产任务则应先确保事件身份、版本与失败原因完整。下一步随机挑一条“用户说结果不对”的记录，要求另一位工程师只凭日志还原过程；无法回答的字段就是下一轮补充重点。

我的判断是，可重放、可归因和可分派三项能力，比单纯增加日志字段更能说明观测体系成熟。