Agent Observability 实战：从 Trace 到 Eval 的生产闭环

背景问题：Agent 线上故障很少是单点错误

传统 Web 服务出现问题时，排查路径通常比较直接：看 HTTP 状态码、接口耗时、数据库慢查询、异常堆栈和服务器指标。大模型应用，尤其是 Agent 系统，复杂度远高于此。

一次看似普通的用户请求，可能包含：

• 多轮对话历史拼接
• Prompt 模板渲染
• 检索召回与重排
• 多次模型调用
• 工具调用、失败重试和权限判断
• Guardrail 拦截
• 输出结构化解析
• 用户反馈与在线评估

最终答案错了，不一定是模型能力问题。可能是检索结果过期，可能是工具返回了半截数据，也可能是系统提示词被覆盖，还可能是某个重试逻辑让 Agent 走到了错误分支。

因此，LLM 线上治理不能只依赖普通日志。更合理的做法是建立一套 Agent Observability：用 Trace 还原执行过程，用 Eval 衡量输出质量，用 Dataset 固化失败样本，用 Alert 驱动持续改进。

核心原理：Trace、Span、Eval 三层分工

Trace：一次业务请求的完整执行链

在 Agent 场景中，Trace 不应该只等同于一次 HTTP 请求。它更适合表示一次完整的业务工作流，例如：

• 一次客服问答
• 一次代码修改任务
• 一次 RAG 检索问答
• 一次工具链自动执行
• 一次多 Agent 协作

Trace 的价值不在于「记录很多日志」，而在于建立父子关系：哪个步骤触发了哪个步骤、每个步骤用了什么输入、耗时多少、失败在哪里、最后输出由哪些证据支持。

一个可用的 Trace 元数据通常包括：

trace_id: trace_8f7a...
workflow_name: customer_support_agent
group_id: conversation_123
user_segment: paid_user
release_version: 2026.06.29
prompt_version: support-v17
model: gpt-4.1
sampling_policy: error_or_high_value

Span：把黑盒过程拆成可定位步骤

Span 是 Trace 内部的一个操作片段。Agent 系统常见 Span 包括：

Span 类型	说明
llm.generation	模型调用
retriever.search	向量检索或关键词检索
tool.call	外部工具调用
guardrail.check	安全、格式、权限或合规检查
parser.validate	结构化输出解析
memory.read / memory.write	长期记忆读写
eval.score	在线或离线评估结果

Span 不是越多越好。一个合理原则是：只要某个步骤可能单独失败、单独变慢、单独影响质量，就应该成为 Span。

Eval：把「看起来不错」变成可比较指标

Trace 解决「发生了什么」，Eval 解决「结果好不好」。

Eval 可以分成两类：

1. 离线评估：上线前在固定数据集上比较版本，适合做回归测试、模型切换、Prompt 改版、检索策略变更。
2. 在线评估：上线后对真实流量采样打分，适合监控安全、格式、相关性、幻觉、工具误用和用户体验退化。

评估器也不应该只有 LLM-as-a-Judge。生产环境更稳的做法是组合使用：

• 代码规则：JSON Schema、字段范围、权限边界
• 传统指标：精确匹配、字符串包含、BLEU/ROUGE 等
• RAG 指标：Context Precision、Context Recall、Faithfulness
• Agent 指标：Tool Call Accuracy、Tool Call F1、Agent Goal Accuracy
• 人工审核：用于高风险样本和评估器校准
• Pairwise 对比：用于判断新旧版本谁更好

工程落地：从埋点到闭环

第一步：统一 Trace Schema

不要让每个业务团队自由发挥字段名。否则后续无法聚合、无法查询，也无法跨工具迁移。

推荐先定义最小 Schema：

trace:
  id: string
  workflow_name: string
  group_id: string
  started_at: datetime
  ended_at: datetime
  status: success | error | timeout | blocked
  metadata:
    tenant_id: string
    user_segment: string
    release_version: string
    prompt_version: string
    model: string

span:
  id: string
  parent_id: string
  type: llm | retriever | tool | guardrail | parser | memory | eval
  name: string
  started_at: datetime
  ended_at: datetime
  status: success | error | timeout
  input_summary: string
  output_summary: string
  token_usage:
    input_tokens: integer
    output_tokens: integer
  cost_estimate: number
  error:
    code: string
    message: string

如果未来要接入 OpenTelemetry，字段设计要尽量贴近语义约定，不要把所有内容塞进一个 extra_json。

第二步：先埋关键路径，不要一开始全量捕获

生产环境最容易犯的错误是：第一版 Observability 就想记录所有 Prompt、所有输出、所有中间状态。

更稳妥的顺序是：

1. 先记录 Trace ID、Span 父子关系、耗时、状态、模型名、Prompt 版本、工具名
2. 再记录 token、成本、重试次数、超时原因
3. 再对错误样本保存输入输出摘要
4. 最后对低敏、可授权、可采样的请求保存完整上下文

这样做的好处是可以先建立可查询链路，不会一开始就被隐私、成本和存储打爆。

第三步：把失败 Trace 沉淀为 Dataset

Agent 质量改进的关键不是「线上发现问题后临时改 Prompt」，而是把问题转成可回归资产。

典型流程如下：

1. 在线 Trace 发现失败样本
2. 根据错误类型打标签，例如 retrieval_miss、tool_wrong_args、schema_invalid
3. 清理敏感信息
4. 抽取为 Dataset 样本
5. 写入期望行为或参考答案
6. 在下一次 Prompt、模型、RAG、工具链变更前自动跑离线评估

只有这样，线上事故才会变成系统能力，而不是一次性补丁。

第四步：把评估结果挂回 Trace

不要把 Eval 做成独立报表。更好的方式是让评估结果成为 Trace 的一部分。

例如：

{
  "eval": {
    "trace_id": "trace_8f7a...",
    "evaluator": "rag_faithfulness_v3",
    "score": 0.42,
    "label": "fail",
    "reason": "answer contains claims not supported by retrieved context",
    "evaluator_version": "2026.06.29"
  }
}

这样排查时可以直接从低分样本进入 Trace，看它的检索结果、工具参数、模型输出和版本信息。

第五步：控制采样与成本

线上评估不能简单全量跑。常见采样策略：

• 错误请求 100% 采样
• 高价值客户高采样
• 新版本灰度期间提高采样
• 低风险闲聊低采样
• 长上下文请求单独采样
• 工具调用失败或重试请求强制采样

成本看板至少要拆到：模型、业务线、Prompt 版本、工具链、用户分层。只看总 token 没有意义，因为无法定位哪个版本或场景导致成本异常。

适用场景

RAG 问答系统

RAG 系统最需要看到「答案是否由证据支持」。Trace 中至少要保留：query、召回文档 ID、重排分数、上下文片段摘要、最终回答、Faithfulness 或 Groundedness 评分。

工具调用型 Agent

工具调用型 Agent 最重要的是参数、权限和副作用。Trace 中必须记录工具名、参数摘要、权限检查结果、返回状态、重试次数和是否产生外部写入。

多 Agent 协作

多 Agent 系统容易出现责任不清。需要在 Trace 中区分 Agent 名称、角色、交接原因、handoff 输入输出，以及最终决策由哪个 Agent 负责。

高合规行业

金融、医疗、政务等场景不能只追求可观测，还要追求可审计。完整 Prompt 不一定能存，但至少要保存版本、证据、授权、脱敏后的输入摘要、输出摘要和评估结论。

常见误区

误区一：把 Observability 等同于日志平台

日志平台记录事件，Observability 要重建因果关系。没有 Trace ID、Span 层级、版本信息和评估结果，日志再多也只是碎片。

误区二：只监控延迟和错误率

LLM 应用最致命的问题往往不是 500 错误，而是「稳定地产生错误答案」。因此质量指标必须进入监控，包括相关性、事实性、格式合规、工具调用准确率和安全拒答率。

误区三：全量保存 Prompt 和输出

这会带来隐私、合规、存储成本和内部滥用风险。更推荐按数据等级保存摘要、哈希、结构化字段或脱敏样本。

误区四：上线后才补评估

评估要从开发阶段开始。线上 Trace 的价值在于补充真实分布，而不是替代离线回归集。

误区五：评估器没有版本管理

Prompt 会变，模型会变，评估器也会变。没有评估器版本，就无法解释为什么同一批样本本周得分和上周不同。

上线检查清单

Trace 与 Span

• 是否每次业务请求都有全局唯一 Trace ID
• 是否能从最终答案反查模型调用、工具调用和检索结果
• 是否记录模型名、Prompt 版本、发布版本和环境
• 是否区分错误、超时、拦截和用户取消
• 是否支持跨服务传播 Trace ID

数据与隐私

• 是否默认关闭高敏原文捕获
• 是否配置输入输出脱敏
• 是否有数据保留周期
• 是否限制 Trace 查看权限
• 是否可以按用户或租户删除相关数据

评估与告警

• 是否有离线回归数据集
• 是否有线上采样评估策略
• 是否区分规则评估、LLM Judge 和人工审核
• 是否给评估器本身做版本管理
• 是否能把低分 Trace 自动进入分析队列

成本与性能

• 是否记录输入 token、输出 token、总成本估算
• 是否按业务线、模型、Prompt 版本拆分成本
• 是否对长上下文请求单独监控
• 是否限制 Trace 采集对主链路的延迟影响
• 是否对评估任务设置并发和预算上限

小结

大模型应用进入生产后，真正困难的不是「能不能调用模型」，而是「当结果变差时，能不能解释为什么、复现现场、验证修复」。

一套可落地的 Agent Observability 应该具备四个闭环：

1. Trace 闭环：还原一次执行的完整过程
2. Eval 闭环：把质量问题变成可比较指标
3. Dataset 闭环：把线上失败沉淀为离线回归
4. Governance 闭环：用脱敏、权限、采样和保留策略控制风险

只有把这些能力连起来，团队才能从「看日志猜问题」升级为「基于证据改系统」。

参考资料

• OpenTelemetry GenAI Semantic Conventions
• OpenAI Agents SDK Tracing
• LangSmith Observability
• LangSmith Evaluation
• Arize Phoenix Tracing
• OpenInference
• Ragas Documentation
• From Agent Traces to Trust: Evidence Tracing and Execution Provenance in LLM Agents