Agent 可观测性：从调用到决策链

普通接口调用通常有清晰的请求和响应，而 Agent 会读取上下文、规划步骤、调用多个工具、修改计划并反复尝试。只记录模型文本，无法解释任务为何变慢、为何选错工具，也无法判断最终结果是由模型、数据还是权限问题造成。

先统一事件模型

每次任务应有稳定的任务 ID，每个模型调用、工具调用和验证动作都是一个事件。事件至少包含父事件、开始与结束时间、状态、输入摘要、输出摘要、错误类型和资源消耗。

父子关系比一串平铺日志更重要：它能还原哪个判断触发了哪个工具，以及一次重试替代了哪次失败。最终文件、消息或外部变更也必须链接回产生它的任务。

• task——用户目标、约束与最终状态。
• decision——候选动作、选择结果与审计说明。
• tool_call——参数、权限、耗时和返回状态。
• verification——检查对象、规则与通过结果。

从调用链升级为决策链

传统 Trace 擅长展示耗时，却不一定解释决策。Agent 还需要记录当时可用的工具、读取到的上下文版本、被排除的方案以及计划如何变化。

不必保存完整思维过程；可以记录面向审计的简短说明，例如“数据日期不一致，因此重新查询主数据源”。这既保留可解释性，也避免收集大量无用或敏感文本。

让指标能够指向问题

平均延迟和成功率不足以描述 Agent。更有用的指标包括每任务工具调用数、无效重试率、验证失败率、人工接管率、每个完成任务的成本，以及外部副作用回滚率。

诊断时先定位失败阶段，再查看该阶段的输入证据。若工具成功但验证失败，应检查返回内容；若规划反复改写，则检查上下文是否冲突；若结果正确但成本上升，则比较重复读取与无效调用。面板的价值是缩短定位路径。

• 模型问题——判断偏差、格式错误或输出不稳定。
• 工具问题——权限、超时、参数或返回结构异常。
• 流程问题——状态跳转、重试和验证策略不合理。

在完整性、成本与隐私间取舍

全量保存原始提示和工具返回，既昂贵也危险。生产环境可以全量保留结构化元数据，对正文按风险分级：错误任务保留脱敏样本，正常任务抽样，密钥与个人数据在进入日志前移除。

同时定义保留周期。实时诊断需要细粒度事件，长期趋势通常只需要聚合指标。若一次故障无法通过脱敏记录复现，可以在受控环境短期提高采样，而不应永久扩大数据收集范围。

• 关联——任务与子事件具备稳定父子关系。
• 分层——能区分模型、工具、验证与权限故障。
• 保护——敏感内容在写入日志前完成脱敏。

可观测性不是把过程全部保存，而是让每一次结果都能沿着证据向前追问。