AI Agent 可观测性设计：Trace、日志、指标、回放怎么串起来

很多团队做 Agent 调试时，手里只有两样东西：模型返回文本和几行控制台日志。

这在 Demo 阶段还能勉强工作，一到线上就会失效。因为线上故障很少是“模型一句话答错了”，更常见的是：

• 检索拿到了错的片段
• 规划循环了两轮后才超时
• 工具调用第一次成功、第二次因为幂等冲突失败
• 最终回答看着正常，但中途已经发生过降级

如果这些事件没有被串起来，你就无法回答一个最基本的问题：

$$ 这次失败到底是在哪里开始失控的？ $$

建议和 AI Agent 评估框架完全指南、AI Agent 并发与可靠性、Function Calling 工程实战 一起看。

一、日志、指标、Trace、回放分别负责什么

很多系统的问题就在于只做了其中一层。

二、最小可行的 Trace 结构

至少给每次 run 生成一个全局 run_id，然后把关键阶段挂在这条链上。

推荐字段：

三、一个典型失败案例：超时了，但你不知道卡在哪

某个客服 Agent 的线上异常表现是“平均时延正常，但用户偶发等待 20 秒以上”。

最初团队只看到了：

• 端到端时延高
• 最终输出为空

后来把 trace 打开后才发现：

1. 检索阶段耗时正常
2. 第一个工具调用正常
3. 第二个工具因为上游接口抖动超时
4. 系统进入重试
5. 重试后又触发了一次权限校验
6. 最后在降级前耗尽总预算

如果没有分阶段 trace，这类问题几乎只能靠猜。

四、Trace 应该怎么和状态机配合

Agent 的可观测性最好不要只围绕“函数调用”建模，而要围绕“状态迁移”建模。

一条最小状态链可以是：

RECEIVED -> BUILD_CONTEXT -> PLAN -> EXECUTE_TOOL -> VALIDATE -> RESPOND -> DONE

每次状态迁移都要记录：进入时间、退出时间、关键输入、关键输出、异常信号。

这样你做回放时，就不是在看一堆散乱日志，而是在看一次任务如何从一个状态进入下一个状态。

五、回放链路怎么做最划算

你不需要一开始就做复杂的可视化平台。最小方案可以是：

1. 保留输入和裁剪后的上下文快照
2. 保留规划结果与工具请求参数
3. 保留工具返回值摘要
4. 保留策略判定结果
5. 保留最终输出与关键指标

做到这 5 项，已经足够支撑大多数线上问题复盘。

六、上线前必须看的观测指标

• p95_e2e_latency
• tool_failure_rate
• schema_fail_rate
• degrade_rate
• replayable_run_rate

其中 replayable_run_rate 很容易被忽略，但非常重要。没有足够可回放样本，团队的优化就会退化成碰运气。

七、AI Agent 可观测性上线清单

• 每次 run 都有唯一 run_id
• 状态迁移有进入和退出打点
• 关键工具调用能关联到同一条 trace
• 失败 run 至少能复原上下文、规划和工具结果摘要
• 指标面板和单次 run 诊断链路能互相跳转

延伸阅读

• AI Agent 评估框架完全指南：从离线 Eval 到线上 Guardrail
• AI Agent 并发与可靠性
• AI Agent Session Replay 调试指南：如何复盘一次失败 Run 的每个决策
• Function Calling 工程实战