Agent可观测性与质量保障#

1. Agent Trace 设计#

每步记录思考过程、动作、工具参数、结果、延迟和 Token 消耗：

Step 1: { thought: "需要查询用户订单", action: "call_tool", 
          tool: "query_order", params: {user_id: 123},
          result: {order_id: 456, status: "shipped"},
          latency_ms: 230, tokens: {input: 150, output: 45} }
Step 2: { thought: "已获取订单信息，生成回答", action: "final_answer",
          result: "您的订单456已发货...",
          latency_ms: 180, tokens: {input: 280, output: 60} }

与传统微服务链路追踪的区别：传统 Trace 记录服务间调用；Agent Trace 还要记录 LLM 的思考过程和决策逻辑，每步都有不确定性。

标准化埋点：OpenTelemetry GenAI 语义约定

为了不被某一家平台绑定，Trace 可以按 OTel GenAI 语义约定打点，再导出到 Langfuse / LangSmith / Phoenix 等后端：

注意：这套约定目前（2026-09）所有属性仍是 Development 状态，已从主仓库拆到独立仓库 open-telemetry/semantic-conventions-genai 维护，属性名还在变（例如早期的 gen_ai.system 已改为 gen_ai.provider.name）。接入时锁定版本，升级前看 changelog。

2. 核心 Metrics#

3. 可观测性工具链#

4. 质量保障流水线#

离线评测（回归测试集）
  → 影子流量对比（新旧版本跑同一批请求，比对结果）
  → 灰度发布（5% → 25% → 100%）
  → A/B 实验（线上随机分流，统计显著性检验）
  → 持续监控（Metrics 告警 + 人工抽检）

5. Demo 为什么上不了生产#

Agent可观测性要解决的核心问题是”Agent在生产环境出了问题怎么查”。我把它分三个维度：Trace、Metrics和质量保障。Trace设计上，Agent每一步都要记录思考过程Thought、执行动作Action、工具调用和返回结果、耗时和token消耗，形成完整的执行链路可以回放排查。核心Metrics关注六个指标：任务成功率要大于80%，平均迭代次数不超过5次代表Agent效率，工具调用准确率要90%以上，P99延迟不超过10秒保证用户体验，token消耗控制在预算内，幻觉率低于5%。工具链方面可以用Langfuse、LangSmith、Phoenix这类平台做全链路追踪和打分，埋点尽量按OpenTelemetry的GenAI语义约定来，避免被单一平台绑定。质量保障是重点：上线前跑离线回归测试集，用影子流量对比新旧版本，灰度发布从5%逐步放量到100%，线上持续A/B实验和人工抽检。很多Agent项目Demo效果很好但上不了生产，本质就是缺了错误处理、超时控制、可观测性、成本控制和安全防护这五个维度。

追问方向：

• Agent 的 Trace 怎么设计？和传统微服务链路追踪有什么区别？ → Agent Trace 多了 Thought/Action 语义信息和 token 消耗维度，传统 Trace 只有 RPC 调用链。实现上常把 OTel Span 的创建、属性写入、异常记录封装成一个工具函数，每步记录思考/动作/工具/耗时/token，属性名按 OTel GenAI 语义约定（invoke_agent / execute_tool / gen_ai.usage.*）
• 怎么判断 Agent 是”真的好”而不只是”会演示”？ → 跑离线评测集（覆盖 factual/adversarial/unanswerable 等边界），看 Faithfulness 和拒答率。Demo 通常只测 happy path，评测要覆盖失败场景
• 灰度发布怎么做？新旧版本结果不一致怎么判断哪个好？ → 灰度 5%→25%→100%，用影子流量新旧版本跑同一批请求对比 Metrics。判断标准：Faithfulness 不降 + Recall 不降 + 延迟不涨 + 成本不涨
• 线上 Agent 突然变差了怎么排查？ → 按链路逐段查：检索端（Recall 下降?）→ 生成端（模型更新?）→ 工具端（API 异常?）。在 Trace 平台上可定位到具体哪一步出问题

易错点：

• ❌ “任务成功率是唯一指标” → 还要看效率（迭代次数）、成本（token）、延迟（P99）
• ❌ “上线前测好了就行” → 模型更新、数据漂移会导致线上退化，需要持续监控
• ❌ “灰度就是慢慢放量” → 还需要对比实验，判断新版本是否真的更好

工程实践要点：

• 埋点样板代码要封装：Span 的创建、属性写入、异常记录、结束写成一个工具函数，业务代码只传名字、属性和执行体，否则埋点会被漏掉或写得不一致。
• 消融评测：按组件逐个叠加（如纯向量 → +BM25 → +Rerank → +反思），每个变体跑同一评测集、多轮取均值或中位数，才能看清每个组件的增量。
• 流式输出下的后置校验：token 一旦推给客户端就改不了，生成后的反思/校验只能打分或提示，不能改写已发出的内容；要改写就得在流结束后重新生成，或在流式前做判断。
• 置信度分流：高置信直接返回、低置信走补充检索或其他降级路径，省下的是多数请求的额外 LLM 调用。结合项目时可以讲：分流比例是多少、用什么数据验证分流没伤质量。