深色模式
Agent 可观测与调试
摘要：Agent 比单轮 LLM 调用难调试一个数量级——它有循环、有分支、有工具、有状态。本文给出 Agent 可观测性的四层覆盖（trace/span、token 与成本、工具调用链、评估回流），讲清 OpenTelemetry 接入、LangSmith 类平台与常见调试手段。通用 LLM 可观测见
../observability/llmops-overview。
核心概念：要观测什么
| 层 | 观测对象 | 关键指标 |
|---|---|---|
| 执行流 | 每一步 reasoning / action / observation | 步数、分支、终止原因 |
| 调用链 | 每次 LLM、每次工具调用 | 延迟、错误率、重试 |
| 成本 | token 消耗、调用次数、并发 | 单任务成本、日总额 |
| 质量 | 成功率、人工评分、评估集 | 任务成功率、回归 |
Agent 的 trace 是「树」不是「线」
单轮 LLM 调用是一条 span；Agent 是多步、可分支、可并行的树。可观测系统必须能展示这种嵌套结构，否则无法定位「哪一步跑偏」。
架构与原理
主流做法：用 OpenTelemetry 把每一步作为 span 打点（含 input/output 摘要、token、耗时、工具名），汇聚到可观测后端；框架层（LangGraph + LangSmith）已内置 trace。评估样本回流到评测集，形成「生产—评测」闭环。
生产实践：手动打点（OTel）
即使不用特定平台，也可用 OTel 标准打点，便于跨语言聚合。
python
# otel_agent.py —— 用 OpenTelemetry 追踪 Agent 步数 [未实测]
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, BatchSpanProcessor
trace.set_tracer_provider(TracerProvider())
trace.get_tracer_provider().add_span_processor(BatchSpanProcessor(ConsoleSpanExporter()))
tracer = trace.get_tracer("agent")
def step(name, fn, **kw):
with tracer.start_as_current_span(f"agent.step.{name}") as sp:
sp.set_attribute("agent.tool", name)
out = fn(**kw)
sp.set_attribute("agent.output_len", len(str(out)))
return out
# 每个 ReAct 步骤都用 step() 包裹，即可得到嵌套 trace1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
不要把完整 PII 写进 trace
trace 常含用户输入与工具返回，可能是 PII 或机密。对策：trace 默认只存摘要/哈希，原始内容按需脱敏或仅存引用 ID；按 tenant 做访问隔离。
操作步骤 / 配置
LangSmith（LangGraph 生态）接入示意：
bash
export LANGCHAIN_TRACING_V2=true
export LANGCHAIN_API_KEY="..." # [版本相关]
export LANGCHAIN_PROJECT="prod-agents"1
2
3
2
3
yaml
# Prometheus 抓取 Agent 指标（示意）
scrape_configs:
- job_name: agent-runtime
static_configs:
- targets: ["agent-svc:8080"]1
2
3
4
5
2
3
4
5
验证
- trace 完整性：跑一个多步任务，确认 trace 树能展示每一步的 input/output 与耗时。
- 指标可读：Prometheus 中应能查到
agent_step_total、agent_token_total、agent_cost_usd。 - 告警可用：设置「单任务成本 > 阈值」「步数 > 上限」「工具错误率突增」告警。
回滚 / 清理
- 可观测配置（exporter、采样率）可灰度；高采样率仅在排障期开启，避免存储爆炸。
- 调试产生的 trace/日志含任务数据，按保留期清理并落实脱敏。
故障排查
- trace 断链：跨进程/异步未传递 context。对策：用 OTel context propagation（W3C traceparent）。
- 看不到工具调用：打点只在 LLM 层，未包裹工具执行。对策：工具层也包 span。
- 成本指标失真：只统计 LLM token 漏算工具/embedding。对策：统一在边界汇总。
安全与合规
- 数据泄露：trace/日志含 PII。对策：脱敏 + 访问控制 + 短保留期。
- 提示注入：调试面板若渲染工具返回可能触发注入。对策：渲染层做转义与隔离。
- 越权访问：可观测平台本身能看到全部交互，需严格 RBAC。
- 成本失控：高采样率 + 长保留期会放大存储成本。对策：采样 + 生命周期管理。
成本 / 性能
可观测本身有成本：OTel 打点开销极小（微秒级），但 trace 存储随采样率线性增长。建议：生产默认采样 10–20%，排障期临时拉满；trace 只存摘要，原始内容存对象存储并按需拉取。以日 10 万任务、每任务 5 步、每步 trace 1KB 估算，全采样约 500MB/日，采样 20% 约 100MB/日 [版本相关，取决于后端单价]。性能上，异步批量导出（BatchSpanProcessor）几乎不增加请求延迟。