智能体可观测性与故障归因

评测回答“系统好不好”，可观测性回答“刚才发生了什么、为什么失败”。智能体包含概率模型、动态工具和外部环境，只记录最终文本无法定位问题。

最小 Trace

一次任务至少记录：

task_id、trace_id、用户与租户作用域；
模型、Prompt、工具和工作流版本；
每轮模型输入的摘要或安全引用；
模型响应类型：文本、工具调用、拒答或错误；
工具名称、规范化参数、结果状态和耗时；
状态变化、Checkpoint 和人工审批；
Token、费用、首字延迟和端到端延迟；
最终环境状态与验收结果；
错误类型、重试、恢复和人工接管。

生产日志不应默认保存完整敏感输入。可以使用事件 ID、哈希、脱敏摘要和受控审计存储。

事件模型

建议把运行轨迹表示为有序事件，而不是拼接成一段日志：

task_started
model_requested
model_responded
tool_requested
tool_authorized
tool_completed / tool_failed
state_updated
approval_requested
checkpoint_saved
task_completed / task_failed

事件应包含稳定序号和时间戳，便于断线续传、去重、回放和分析乱序。

故障分类

层级	典型问题	诊断方式
目标理解	误解用户意图或验收标准	检查任务契约与首轮计划
规划	步骤缺失、依赖顺序错误	对比参考计划或状态机
上下文	关键约束被裁剪、旧信息污染	检查实际模型输入
工具选择	选错工具或没有调用必要工具	检查候选集与 Tool Call
参数生成	类型、范围、实体绑定错误	Schema 与业务校验
工具执行	网络、权限、业务或状态冲突	工具错误码和环境日志
结果使用	忽略或误读工具返回	检查后续 Observation
终止判断	过早结束或无限循环	检查预算、进展和终态
输出	格式错误、无依据、未满足验收	Schema、事实和状态断言

回放与复现

为了复现失败，应固定：

模型和参数；
Prompt、工具 Schema 和代码版本；
初始数据库、文件或沙箱快照；
Mock API 返回；
时间、随机性与外部依赖；
用户输入和审批决策。

真实外部环境无法完全固定时，应区分模型非确定性与环境波动。

Badcase 闭环

收集失败轨迹
→ 按根因而不是表象聚类
→ 构造最小复现
→ 增加回归 Case
→ 修改 Prompt / Tool / Harness / 数据
→ 与基线重复运行
→ 灰度发布并继续观测

失败修复不能只看一次成功，应比较多次运行的成功率、尾延迟和成本变化。