智能体观测、执行轨迹回放与失败分析

学习目标

• 能设计智能体执行轨迹的最小字段。
• 能用轨迹回放定位失败来自计划、工具、权限还是模型判断。
• 能把失败案例沉淀为回归测试和运行规则。

核心概念

智能体的可观测性比普通单次大语言模型调用更重要。一次运行可能包含多轮模型调用、多个工具、权限检查、重试、预算判断和人工接管。只看最终答案，无法判断中间哪一环出了问题。

执行轨迹（Trace）应记录 run、step、tool_call、observation、decision、error 和 cost。为了安全，记录可以保存输入输出摘要或脱敏版本，不一定保存全部原文。关键是让工程师能复现路径，判断系统当时基于什么信息做了什么动作。

失败分析要按链路分层：目标是否清楚、计划是否可执行、工具是否返回正确数据、权限是否拦截合理、模型是否误读 observation、预算是否过紧、交接是否可用。只有定位清楚，修复才不会变成盲目加提示词。

示例与拆解

一个执行轨迹事件可以这样设计：

复制
1{
2  "run_id": "run_001",
3  "step_index": 3,
4  "event": "tool_call_completed",
5  "tool_name": "lookup_policy",
6  "input_summary": "查询 refund_policy",
7  "output_summary": "政策要求开课前 7 天内可退",
8  "status": "completed",
9  "latency_ms": 420,
10  "cost_usd": 0,
11  "error": null
12}

当最终结果错误时，你可以按 run_id 展开事件序列，确认错误是从哪个 observation 开始偏离。

常见误区

• 误区一：只记录提示词和最终回答。智能体的关键错误常发生在工具选择和状态迁移。
• 误区二：日志越全越好。敏感数据应脱敏，长文本应摘要，权限字段应严格控制。
• 误区三：回放只是展示。回放结果应该进入失败库，形成回归用例。

小练习

拿一个你设计的智能体任务，写出 5 类执行轨迹事件：run_started、plan_created、tool_call_requested、tool_call_completed、run_stopped。为每类事件列出必填字段。

实操检查点

准备一份失败分析表，把一次失败归因到具体层级。

复制
1失败现象：智能体给出错误退款建议
2失败层级：工具数据
3证据：lookup_policy 返回旧版本政策
4修复动作：政策工具增加 version 字段和发布时间过滤
5回归用例：同一订单再次运行，应触发 needs_human

检查标准：每个失败案例都能产出一个明确修复动作和一个可重复的回归用例。

随堂测验

完成本章测验时，重点判断执行轨迹是否足以支持复盘，而不是只看日志数量。

本章总结

智能体可观测性的目标是让复杂执行过程可复现、可解释、可修复。轨迹、回放和失败库共同构成持续改进的基础。

下一步学习指引

完成这条路线后，可以进入项目“受控智能体执行器”，把执行循环、权限、预算和执行轨迹做成一个完整可演示系统。