当你的 Agent 系统正式上线，每天处理几千个真实用户的请求时，你最怕听到哪句话？
客服群里有人喊：“刚才有个客户反馈，说你们的 AI 助手乱改了他的订单！赶紧查一下！”

这时候你满头大汗地打开服务器。如果你没有做任何准备，你会发现服务器里只有一堆黑漆漆的无意义报错：Error: LLM API Timeout。
到底是哪个订单被改了？AI 当时脑子里在想什么？它调用了什么工具？你一无所知。这叫系统黑盒。

为了不让工程师天天背锅，工业界引入了极其重要的一环：可观测性（Observability）。
本篇我们就来讲讲，如何给你的 Agent 装上“监控摄像头”和“黑匣子”，让任何线上的灵异事件都能被完美重放。

---

1. 什么是可观测性？三大支柱

可观测性不是随便打几行 console.log("跑到这里了")，它是一套结构化的监控体系，包含三大支柱（三大法宝）：

① 指标（Metrics）：宏观的“仪表盘”

• 看什么：系统的整体健康状态（数字）。
• 常见指标：当前并发请求数、平均响应延迟（Latency）、每分钟 Token 消耗量、工具调用的报错率。
• 作用：用来报警。当大盘上的“Token 消耗曲线”突然像火箭一样垂直拉升时，不用看日志你就知道，肯定有个 Agent 陷入死循环了，赶紧拉闸！

② 日志（Logs）：微观的“监控录像”

• 看什么：系统发生的具体事件文本。
• 作用：在 AI 系统中，仅仅记录系统的报错是不够的，必须把 Prompt 的输入（Prompt） 和 大模型的输出（Completion） 原封不动地记下来。这是你日后复盘“AI 为什么会发疯”的唯一证据。

③ 追踪（Traces）：穿透迷雾的“红线”

• 看什么：请求在系统内的流转轨迹。
• 痛点：用户问了一个问题，系统先调了 RAG 检索，又调了重排模型，最后 Agent 思考了 3 轮，调用了 2 次工具。这中间经历了 10 个步骤。
• 解决：给这个用户的提问生成一个唯一的 Trace ID。这 10 个步骤产生的所有日志，都必须带上这个 Trace ID。
• 作用：当客户来投诉时，你只要拿着他的单号查出 Trace ID，就能像串糖葫芦一样，把这个请求从头到尾的所有日志一把全拉出来看。

---

2. Agent 时代的特殊追踪：Span 与可重放（Replay）

在传统的微服务追踪里，我们看的是“服务 A 调用了服务 B”。
在 Agent 系统里，我们看的是大模型的“思考轨迹”。这就引入了 Span（跨度） 的概念。

一个典型的 Agent Trace 结构如下：

• Trace (总任务): 用户提问“帮我查订单并退款”
  • Span 1 (RAG 检索): 耗时 500ms，检索出退款政策。
  • Span 2 (Agent 思考 1): 耗时 2s，决定调用 query_order 工具。
  • Span 3 (工具调用): 耗时 300ms，查到了订单状态。
  • Span 4 (Agent 思考 2): 耗时 2s，决定调用 refund 工具。

**可重放（Replay）**的魔力：
如果你把上述带有 Span 的结构化日志存入专业的 LLM 监控平台（如 LangSmith、Langfuse 或国产的大模型监控平台），平台会自动帮你把这些冷冰冰的日志渲染成漂亮的“对话树”。
点一下“Replay”按钮，你就能像看录像回放一样，一秒一秒地看着 Agent 当时是怎么思考、怎么踩坑的。

---

3. 失败复盘：不要让同一个坑绊倒两次

监控不是为了看热闹，而是为了解决问题。
当你通过可观测性工具抓到了一个失败案例（Bad Case）后，必须进行结构化的复盘。

在 AI 团队里，复盘一个幻觉 Bug 往往比复盘传统代码 Bug 更难。传统 Bug 改一行代码就修好了，AI 的 Bug 你改了 Prompt 可能会引发新的问题。

失败的根因（Root Cause）通常只有三类：

1. 输入问题（RAG 没查到）：资料库里根本没有退款政策，AI “巧妇难为无米之炊”开始瞎编。
2. 工具问题（API 报错）：退款接口挂了，Agent 没做好异常处理。
3. Prompt 问题（指令冲突）：系统提示词里既写了“满足客户一切需求”，又写了“严禁随意退款”，导致模型精神分裂。

---

4. 本篇产出：Agent 失败复盘模板（含时间线）

为了防止团队在排查线上事故时像无头苍蝇一样乱撞，请在内部 Wiki 里建立一个“AI 事故复盘区”，并强制使用以下模板进行记录：

# 线上 Agent 失败案例复盘报告

## 1. 基本信息
- **发生时间**：2024-05-25 14:30:00
- **Trace ID**：`trace-9988-abcd`
- **影响范围**：单个客户订单被错误取消
- **现象描述**：用户询问“我的订单发货了吗”，Agent 误将其理解为退款请求并调用了取消订单工具。

## 2. 案发现场还原 (Timeline)
*(通过追踪系统拉取的 Span 记录)*
- `14:30:01` [User] 输入：“我不想等了，这订单到底发没发货？”
- `14:30:02` [Agent Thought] 触发关键词“不想等了”，误判用户意图为“取消订单”。
- `14:30:03` [Tool Call] 调用 `cancel_order(order_id: 123)`。
- `14:30:04` [Agent Output] 回复用户：“已经为您取消订单。”

## 3. 根因分析 (Root Cause)
- **直接原因**：Prompt 中对“取消订单”的触发条件定义过于宽泛，没有强制要求 Agent 进行“二次确认”。
- **深层原因**：缺失 `Human-in-the-loop`（人类审批）机制，高危操作被轻易放行。

## 4. 修复与防范方案 (Action Items)
- **修复 1 (Prompt 层)**：修改 Agent 的系统提示词，明确规定：“在调用取消订单工具前，必须向用户发送【请确认是否取消：是/否】”。
- **修复 2 (工程层)**：在 `cancel_order` 工具底层强制加入白名单校验。
- **回归测试**：将此对话案例加入自动化评测的**“金标集 (Gold Standard)”**的【越权拦截测试】分类中，确保后续版本绝不再犯。

---

总结与复盘

• 没有可观测性的 Agent，就是一颗在暗处跳动的定时炸弹。
• 用 Metrics（指标） 来发现大面积异常，用 Traces（追踪） 锁定嫌疑犯，用 Logs（日志） 还原作案现场。
• 抓住一个 Bad Case 不要轻易放过，用结构化的复盘报告把它榨干，最后一定要把它变成评测阶段的“金标测试用例”，这才是 AI 系统越养越聪明的闭环。

下一步路线提示：
有了监控，我们终于能睡个安稳觉了。但是，到了月底一看账单，老板崩溃了：“这 AI 助手上线一个月，怎么光 API 调用费就花了几十万？比雇个人还贵！”
在企业里落地 AI，如果不算经济账，项目必死无疑。
下一篇，我们将化身“精算师”，进入极其现实的篇章：《成本与性能：缓存、批处理、模型路由与降级》。