诊断与可观测性

一次失败的 Agent 运行不是单一事件。它可能是页面发送了错误的上下文、模型挑了一个不存在的工具、动作存在但当前不可用、用户拒绝了确认、业务函数抛错，或者声明的结果始终没有出现。可观测性必须保留这些区别。

诊断回答“这一次运行看到了什么、做了什么”；可观测性回答“系统在许多运行之间表现如何”。两者共享请求 id 与事件形状，但保留期限和隐私要求不同。

三种记录，三种用途

记录	回答	通常包含
请求轨迹	这一次运行到底发送和收到了什么？	系统上下文、历史、工具 schema、模型响应、工具结果
遥测	花了多少，失败在哪里？	模型调用数、耗时、token 估算、重试与工具状态
审计	谁授权了这次操作，发生了什么？	用户、Agent、会话、能力、记录 id、结果、请求 id

请求轨迹最敏感，可能包含页面快照、用户消息和模型输出。它应进入有上限的开发缓冲，而不是默认进入生产日志。遥测应排除提示词和响应正文。审计要识别授权与执行，但不能复制业务参数或凭证。

用请求 id 串起来

在传输边界为每个请求分配稳定 id，并把它带到模型调用、工具执行、业务结果和审计事件中。这样，用户只需报告一个 id，不必粘贴聊天；运维也能把失败页面、网关和执行路径对上。

请求 id 不是业务幂等键。它关联观察记录，不保证支付、删除或库存变更只发生一次。持久业务操作仍需要自己的幂等规则。

分层检查一次运行

失败时，按以下顺序检查：

1. 页面投影。 目标区域是否活跃？记录是否有稳定 id？动作是否可见且可用？
2. 工具 schema。 模型是否收到了正确的动作名、说明和输入形状？
3. 模型响应。 它选择了已声明能力，还是编造了一个？
4. 执行结果。 调用是被拒绝、不可用、参数无效、执行失败，还是结果未验证？
5. 执行后状态。 记录或页面状态是否真的变化？
6. 传输与网关。 身份、限流、重试或上游故障是否介入？

这个顺序能避免一种常见误判：页面上根本没有声明动作，却通过提高模型预算来“修”。它也能避免把网关在请求到达页面前拒绝，误认为页面执行失败。

有用的计数器

至少按应用、模型别名、发布版本和结果分组记录：

• 模型调用数、耗时与 token 估算；
• 已用轮数和预算耗尽；
• 按能力 id 与状态分组的工具调用；
• ACTION_NOT_FOUND、ACTION_UNAVAILABLE、INVALID_PARAMS、EXECUTION_FAILED、EXPECTATION_FAILED 与确认拒绝；
• 重试次数和耗尽的重试预算；
• Surface 请求、越界范围、限流、重放拒绝和已撤销会话。

没有分母的计数很容易误读。工具调用成功数上升，可能只是流量增加；流量增长时成功率下降，才是值得处理的信号。

隐私与保留

最安全的轨迹是默认不采集的轨迹。开启后，应限制访问、限制保留的调用数、遮蔽已知敏感字段，并规定较短保留期。页面内容和模型输出都是不可信数据：诊断界面必须以文本呈现，不能把它们当作指令执行。

遥测端点需要验证与传输策略。一个公开接收页面快照的随机端点，是换了形式的数据库泄露。审计存储需要访问控制、与风险相称的防篡改能力，以及清楚的保留规则。

发布前检查

上线前验证：一次受控失败能产生用户可见的稳定错误码和请求 id；运维能在网关与工具事件中找到同一个 id；关闭诊断时，轨迹界面和数据采集都停止，而不只是隐藏按钮。

诊断本身不会让系统变安全。它让页面、模型和后端之间的边界足够可见，从而可以修复。参见 失败模型与错误码与 运行时限额、观测与错误码。