1. Agent可观测性概述
大家好，我是你们这堂课的主讲人。今天咱们聊聊Agent可观测性。说实话，这个概念在AI Agent火起来之前，我更多是在微服务和分布式系统里折腾。但这两年做Agent项目，我发现——没有可观测性，你连Agent在「想什么」都不知道。
什么是可观测性
可观测性，英文叫Observability。说白了，就是你能从系统外部，通过它产出的数据，推断出内部到底发生了什么。
我习惯用一个比喻：你开车时看不到发动机内部，但通过仪表盘上的转速、水温、油压，你就能判断发动机状态。可观测性就是给Agent装上一套「仪表盘」。
具体到Agent场景，可观测性回答三个问题：
- 发生了什么？——Agent调用了哪个工具？
- 为什么发生？——LLM为什么选择了这个Action？
- 接下来会怎样？——当前状态是否会导致死循环？
核心观点：可观测性不是监控。监控告诉你「系统挂了」，可观测性告诉你「为什么挂」。差一个字，差一个维度。
为什么Agent需要可观测性
你想想看，传统软件是确定性的——输入A，输出B。但Agent不一样。它依赖LLM，LLM的输出有随机性。同一个Prompt，两次调用可能给出不同结果。
我在项目中遇到过这样一个坑：一个客服Agent，上线后突然开始给用户推荐竞品。排查了三天，最后发现是LLM在一次工具调用中，把「推荐本公司产品」理解成了「推荐市面上最好的产品」。如果没有完整的调用链日志，这种问题根本无从下手。
Agent需要可观测性的原因，我总结为三点：
- 黑盒问题——LLM的推理过程不可见，你只能看到输入输出。可观测性帮你「透视」中间状态。
- 连锁故障——一个错误的工具调用，可能引发后续10步全部跑偏。没有追踪，你找不到根因。
- 成本控制——Token就是钱。可观测性帮你定位「哪个Prompt浪费了最多Token」。
避坑指南：我曾经在一个项目里，Agent每轮对话都调用了一个外部API。上线后账单吓死人。后来加了指标监控才发现——那个API调用完全没必要，LLM自己就能回答。可观测性直接帮我们省了60%的API成本。
可观测性的三大支柱
聊到可观测性，绕不开这个经典框架。三大支柱分别是：日志（Logs）、指标（Metrics）、追踪（Traces）。它们各司其职，又互相补充。
1. 日志（Logs）
日志是最原始的数据。每一行日志记录一个具体事件。在Agent场景下，日志应该包含：
- 用户输入的原始Prompt
- LLM返回的完整Response
- 每次工具调用的请求和响应
- Agent内部状态的变化（比如当前Step、已收集的信息）
我习惯给每条日志加上session_id和step_id，这样后续关联起来非常方便。
{
"timestamp": "2025-01-15T10:30:00.123Z",
"level": "INFO",
"session_id": "sess_abc123",
"step_id": 3,
"event": "tool_call",
"tool": "search_web",
"query": "2025年AI Agent市场规模",
"response": "预计2025年达到...",
"latency_ms": 1200
}小技巧：日志要结构化。别写「Agent调用了搜索工具」这种自然语言，用JSON。后面做分析时，结构化日志能直接喂给ELK或Loki，省大事了。
2. 指标（Metrics）
指标是聚合后的数值。它不关心单个事件，关心的是「整体趋势」。Agent场景下，我重点关注这几类指标：
| 指标类别 | 具体指标 | 说明 |
|---|---|---|
| 性能 | 平均响应时间、P99延迟 | 用户等多久才能拿到结果 |
| 成本 | 每轮对话Token数、API调用次数 | 钱花在哪了 |
| 质量 | 任务完成率、重试次数 | Agent靠谱吗 |
| 异常 | LLM返回错误率、工具超时率 | 哪里出问题了 |
嗯，这里要注意：指标不能太多。我见过有人给Agent挂了50多个指标，最后没人看。挑最重要的5-8个，盯住就行。
3. 追踪（Traces）
追踪是三大支柱里最「性感」的一个。它把一次完整的Agent执行过程串起来，形成一个调用链。
举个例子：用户问「帮我查一下北京明天的天气，然后提醒我带伞」。Agent的追踪链可能是这样的：
- Step 1: LLM分析意图 → 决定调用天气API
- Step 2: 调用天气API → 获取数据
- Step 3: LLM生成回复 → 包含天气信息
- Step 4: 调用提醒服务 → 设置提醒
每一步都有开始时间、结束时间、输入、输出。如果某一步卡住了，追踪能精确告诉你卡在哪。
我个人习惯用OpenTelemetry来做追踪。它支持自动埋点，你只需要在Agent的每个关键步骤前后加上span即可。
from opentelemetry import trace
tracer = trace.get_tracer(__name__)
with tracer.start_as_current_span("agent_execution") as span:
span.set_attribute("session_id", session_id)
with tracer.start_as_current_span("llm_call") as llm_span:
llm_span.set_attribute("prompt_tokens", 150)
response = llm.invoke(prompt)
with tracer.start_as_current_span("tool_call") as tool_span:
tool_span.set_attribute("tool_name", "weather_api")
result = call_weather_api()我的经验：三大支柱不是孤立的。日志提供细节，指标提供趋势，追踪提供链路。调试Agent时，我通常先看指标——发现异常，然后点进追踪——找到具体哪一步出问题，最后看那一步的日志——定位根因。三步走，效率最高。
知识体系总览
下面这张图，是我自己梳理的Agent可观测性知识体系。你可以把它当作本章的「地图」：
这张图把三大支柱和它们的关键子项都串起来了。你调试Agent时，就按这个思路走——先看指标发现异常，再点进追踪定位步骤，最后翻日志找根因。这套流程，我在多个项目里验证过，确实好用。
好了，第一章就聊到这。可观测性不是锦上添花，是Agent上线的「安全带」。没有它，你就是在盲飞。下一章我们深入讲讲日志的具体落地——怎么埋点、怎么存储、怎么查询。到时候见。