AI 系统的可观测性，不只是 Token 账单

传统服务出问题时，我们习惯查看状态码、延迟和错误堆栈。AI 应用出问题时，这些指标仍然重要，却经常不足以回答最关键的问题：

模型为什么做出了这个选择？

答案不在某一条日志里，而在从用户目标、上下文组装、模型决策、工具执行到最终结果的整条链路中。

先区分四种失败

把所有失败都记成“模型效果不好”，团队就无法采取具体行动。至少应该区分：

1. 输入失败

用户目标不完整，或系统没有拿到完成任务所需的上下文。此时升级模型通常没有帮助。

2. 推理失败

上下文正确，但模型选择了错误路径、遗漏约束或过早得出结论。

3. 工具失败

模型选择正确，实际执行却因为权限、网络、参数或外部状态失败。

4. 交付失败

内部工作已经完成，但最终回答没有把结果、限制和下一步说清楚。

这四类问题需要不同的修复者：产品、提示设计、平台工程或交互设计。可观测性的第一份价值，是让问题回到正确的人手里。

一次运行需要共同的 Trace

每个用户请求都应该有稳定的 trace_id，贯穿模型调用和工具执行：

type AgentEvent = {
  traceId: string
  spanId: string
  parentSpanId?: string
  type: 'model' | 'tool' | 'handoff' | 'result'
  startedAt: string
  durationMs?: number
  status: 'running' | 'ok' | 'error'
}

工具调用是模型决策的外部表现。只记录工具返回值而不记录调用原因，会失去决策上下文；只保存提示词而不保存工具结果，又无法判断执行是否符合预期。

需要注意的是，观测并不意味着无限制收集。原始提示词可能包含个人信息、凭据或业务数据。更稳妥的做法是：

• 默认记录结构化元数据；
• 对正文做字段级脱敏；
• 为调试样本设置短保留期；
• 允许用户和业务明确选择不进入训练或分析；
• 不在日志中保存密钥与完整身份信息。

质量指标必须贴近任务

Token、延迟和模型错误率是平台指标，但它们不能代表用户是否得到结果。

一个代码修复 Agent 更有意义的指标可能是：

“有效工具调用”比单纯调用次数更有价值。一次准确的搜索可能替代十次猜测式读取。

把评估变成日常反馈

离线 benchmark 能比较模型版本，却不能覆盖你的真实工作流。更可持续的评估集来自生产中的高价值样本：

1. 收集明确成功与明确失败的运行；
2. 删除隐私信息，保留决策结构；
3. 为失败标注类型，而不是只打一个总分；
4. 在提示、模型或工具变化时重新运行；
5. 同时比较结果质量、成本和延迟。

评估集不需要一开始就很大。二十个边界清楚、能稳定复现的案例，通常比两千个来源模糊的样本更能指导工程。

面向人的可观测性

最后一层观测不在仪表盘，而在产品界面。

当 Agent 正在读取文件、等待授权或执行部署时，用户需要知道它处于什么阶段。好的状态更新不是倾倒内部思维，而是给出：

• 当前正在完成什么；
• 已经确认了什么；
• 是否需要用户采取行动；
• 哪些风险仍未关闭。

这类可见性会直接改变用户对系统可靠性的判断。一个需要几十秒完成的任务，如果过程清楚，往往比十秒后突然返回不透明结果更让人放心。

可解释，不等于暴露全部过程

AI 系统不需要把每一个内部 token 展示给用户，也不应该把敏感上下文原样写入日志。真正需要的是一条足够清楚的因果链：

用户目标
  → 使用了哪些上下文
  → 选择了什么工具
  → 工具返回了什么状态
  → 最终交付了什么结果

当这条链路可以被查询、比较和复现时，团队才有能力把“偶尔很聪明”变成“长期可信赖”。