agent-observability

name	agent-observability
description	当你要为生产级 Agent 建立可观测性（追踪、监控、日志、成本追踪、问题诊断）、或把生产轨迹回流为评估资产时使用；当 Agent 出问题无法定位、成本失控、需要 A/B 测试和提示词版本管理时使用。不适用于评估指标体系设计（见 eval-metrics）。

Agent 可观测性（Observability）

角色与读者

面向生产级 Agent 的开发者与运维者。本 Skill 服务的目标：通过日志、指标、追踪数据推断系统内部发生了什么——因为 Agent 系统里同样的输入可能产生不同输出，多轮推理路径复杂，模型"思考"过程对外不透明。核心认识：可观测性借自分布式系统——你没法直接打开系统内部看，只能通过外部信号诊断。

核心原则（配正例/反例）

1. 数据基础是追踪（Trace），沿用 span 树模型

   • 一次任务一条 trace，每个 LLM 调用/工具调用/检索是一个 span（记录输入输出、起止时间、token 消耗、错误信息），span 间父子关系构成执行树。
   • 标准协议：OpenTelemetry（通用分布式追踪）+ OpenInference（LLM 特有语义约定：如何记录提示词、模型参数、token 用量）。采集与分析解耦，避免被单一平台锁定。

2. 四个价值：诊断 / 优化 / 成本 / 后训练数据

   • 问题诊断：完整轨迹让开发者回放全过程而非靠猜。
   • 持续优化基础：看到哪些任务多轮迭代、哪些工具成功率最低、哪些检索查询总返回空。
   • 成本管理：Agent 运行成本在不同任务可能差一两个数量级，追踪识别异常高成本案例。
   • 轨迹数据为模型后训练提供基础。

3. 监控仪表盘三块：成本追踪 + 性能监控 + 质量审计

   • 成本：今日/本月花费、异常任务（如循环调用 search 14 次耗 $2.1）。
   • 性能：P50/P95/P99 延迟、工具成功率。
   • 质量：任务成功率、幻觉触发率、安全违规、用户满意度。

4. 闭环：生产轨迹 → 评估资产

   • 从生产轨迹筛选失败/可疑案例 → 脱敏（去用户隐私/密钥）→ 沉淀为评估集新用例和回归测试。
   • 这样评估集不是一次性静态集合，而是随产品演化、持续贴近真实用户分布的活资产。今天线上暴露的失败模式，明天成为守住底线的回归用例。

5. 平台能力：A/B 测试 + 提示词版本管理 + 协作开发

   • A/B 测试：一部分用户流量路由到新版本，自动对比指标，支持快速回滚/渐进扩量。
   • 提示词版本管理：每个版本关联运行时性能数据。
   • 异步批量采集：确保追踪本身不影响 Agent 响应延迟。

执行流程（SOP 检查清单）

1. 用 OpenTelemetry + OpenInference 标准协议埋点（每个 LLM 调用/工具调用/检索一个 span）。
2. 搭监控仪表盘（成本/性能/质量三块）。
3. 建"生产轨迹→评估资产"闭环（筛选失败案例→脱敏→沉淀回归用例）。
4. 接 A/B 测试 + 提示词版本管理。
5. 用异步批量采集避免影响延迟。

禁止清单（写清合法例外）

• 禁止采集与分析耦合在单一平台（被锁定）。例外：用标准协议（OpenTelemetry/OpenInference），同一份追踪数据可对接不同后端。
• 禁止追踪本身影响 Agent 响应延迟。例外：异步批量采集。
• 禁止把生产轨迹直接当评估用例（未脱敏）。例外：去除用户隐私/密钥等敏感字段。
• 禁止把可观测性当一次性工具（应为持续改进的基础设施）。例外：持续从真实数据发现问题、识别优化点。

参考资料

• 本书第 7.8 节《Agent 的可观测性》（Trace/span 树、OpenTelemetry/OpenInference、LangSmith、闭环）。
• 笔记 07-Agent的评估.md 第 7.7 节。
• OpenTelemetry / OpenInference 规范；LangSmith / Langfuse / Arize Phoenix。