1. 引言：从“能跑通”到“可信任”的转折点背景：AI Agent 已从单一 LLM 问答走向“规划—工具调用—反思—重试”的多步自主执行。痛点：传统监控只管“接口通不通、延迟高不高”，管不了“Agent 为什么这样推理、在哪一步走偏、是否产生幻觉”。核心论点：多步推理黑盒是 Agent 落地的最大障碍，可观测性是把黑盒变灰盒、进而可调试、可治理的关键能力。文章目标：讲清 Agent 可观测性的核心概念、技术方案、落地路径与工具选型。2. 为什么传统监控对 AI Agent 失效传统后端监控的三大支柱：Metrics、Logs、Traces，及其面向“确定性系统”的隐含假设。AI Agent 的非确定性特征：同一输入可能产生不同推理路径；推理链长且分叉，存在重试、回溯与并行调用；关键行为隐藏在提示词、中间步骤、工具返回与模型内部状态中。结论：Agent 可观测性必须重建一套以“推理轨迹”为中心的新范式。3. 多步推理黑盒：问题拆解与可观测性目标黑盒在哪一层：用户看不到模型内部概率，Agent 应用层也常丢失中间步骤。需要回答的核心问题：Agent 做了哪些步骤？顺序与依赖关系如何？每一步的输入、输出、耗时、Token 消耗与工具调用结果是什么？最终答案是由哪些中间结论推导而来？哪一步出现了幻觉、重复调用、错误工具选择或提前终止？可观测性目标：追踪：完整还原推理链；量化：成本、延迟、成功率、步数等关键指标；归因：定位失败根因与责任步骤；评估：对推理质量进行可度量、可回归的验证。4. 核心可观测性维度：Agent 的“新三支柱”推理轨迹（Traces）：把一次 Agent 任务划分为 Span 树，覆盖 LLM 调用、工具调用、检索、代码执行、子 Agent 等节点。质量与安全事件（Events）：记录幻觉、拒答、越权、敏感信息泄露、工具异常等语义化事件。评估结果（Evals）：在线/离线评分、用户反馈、A/B 对比，形成闭环。与传统 Metrics/Logs 的关系：不是替代，而是在其之上叠加语义层与推理层。5. 关键技术方案与实践全链路追踪设计：单次任务的 Trace 结构：根节点到叶子节点的层级建模；Span 属性设计：模型名、温度、提示词版本、Token 数、工具名、参数、返回状态；代码示例：OpenTelemetry 手动 Span 追踪# 从 OpenTelemetry 主包导入 trace API，提供 Tracer、Span 等基础能力fromopentelemetryimporttrace# 从 SDK 引入 TracerProvider：用于创建 Tracer 实例并管理 Span 的生成fromopentelemetry.sdk.traceimportTracerProvider# 引入 ConsoleSpanExporter 与 SimpleSpanProcessor：# 一个负责把 Span 打印到终端，一个负责在每个 Span 结束时同步导出，# 适合演示；生产环境可换成 BatchSpanProcessor + OTLP Exporter 异步批量上报fromopentelemetry.sdk.trace.exportimportConsoleSpanExporter,SimpleSpanProcessor# 初始化 TracerProvider：OpenTelemetry SDK 的核心对象，负责组织和管理 Tracerprovider=TracerProvider()# 为 Provider 添加导出处理器：# SimpleSpanProcessor 在 Span 结束时立即调用 ConsoleSpanExporter 输出，# 便于本地调试时直接观察链路数据；生产环境建议改为批量处理器降低开销provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))# 把刚创建的 Provider 注册为全局默认 Provider，# 后续通过 get_tracer 获取的 Tracer 都基于这个 Provider 工作trace.set_tracer_provider(provider)# 创建 Tracer：# - 第一个参数 "agent-observability" 是服务/组件名，用于在链路中区分来源；# - 第二个参数 "0.1.0" 是版本号，便于在做版本对比或线上回溯时定位代码版本；# 这两个值会作为资源属性附加到该 Tracer 产生的所有 Span 上tracer=trace.get_tracer("agent-observability","0.1.0")defrun_agent_step(name:str,model:str,temperature:float,prompt_version:str,token_count:int)-str:# start_as_current_span(name) 创建一个以 name 命名的 Span，# 并将其设置为当前上下文中的活动 Span；进入 with 块后开始计时，# 退出 with 块时自动结束 Span，异常退出时也会记录错误状态withtracer.start_as_current_span(name)asspan:# ===== Span 属性：把步骤元数据写成可检索的键值对 =====# set_attribute(key, value) 把结构化信息挂到当前 Span 上。# 它和日志最大的区别是：这些属性可以被过滤、聚合、排序和告警，# 是把“模型推理黑盒”拆解为可量化、可定位数据的关键手段。# gen_ai.system：标识底层 LLM 提供方或生态系统，# 例如 openai、anthropic、cohere，便于跨厂商对比质量与成本span.set_attribute("gen_ai.system","openai")# gen_ai.request.model：记录本次实际调用的模型名（如 gpt-4o、gpt-4o-mini），# 观测价值：当某个模型质量变差或成本异常时，可以快速按模型维度定位和过滤span.set_attribute("gen_ai.request.model",model)# gen_ai.request.temperature：记录生成温度参数，# 观测价值：温度越高，输出越不稳定；复现轨迹或归因结果漂移时必须核对该值span.set_attribute("gen_ai.request.temperature",temperature)# agent.prompt.version：记录提示词模板版本号，# 观测价值：同一输入在不同提示词版本下表现差异时，可精确归因到具体版本span.set_attribute("agent.prompt.version",prompt_version)# gen_ai.usage.prompt_tokens：记录本次请求消耗的提示词 Token 数，# 观测价值：结合步骤聚合，可识别提示词过长、重复调用造成的成本浪费span.set_attribute("gen_ai.usage.prompt_tokens",token_count)# 模拟一步推理：实际项目中这里应替换为真实的 LLM 调用、工具调用或检索逻辑result="中间结论示例"# 记录这一步的执行状态，比如 success / failed / timeout，# 观测价值：在控制台或后端平台按状态过滤，快速筛选出失败的推理步骤span.set_attribute("agent.step.status","success")# ===== Span 事件：记录时间轴上的关键瞬间 =====# add_event(name, attributes) 在 Span 时间轴上追加一个带时间戳的语义事件。# 它与 set_attribute 的区别：属性是全程有效的事实，事件强调“某时点发生了什么”。# 参数含义：# - "llm.call.completed"：事件名，表示一次 LLM 调用已经完成；# - {"output_length": len(result)}：事件携带的附加属性，用于记录输出长度等维度。# 观测价值：可精确定位某一步内部的关键节点耗时，# 例如“第 3 秒完成上游检索、第 8 秒完成生成”，便于分析长链路时定位瓶颈span.add_event("llm.call.completed",{"output_length":len(result)})returnresult上下文传播：跨服务、跨异步任务、跨子 Agent 的 trace 关联。依赖 W3C Trace Context，通过 HTTP 头traceparent、tracestate和消息头透传 Trace ID，让跨服务调用串成同一棵树；使用 OpenTelemetry Baggage 扩展用户 ID、会话 ID、Agent 任务 ID 等维度，实现跨子 Agent 的关联与统一过滤；在异步任务、重试和并行分支中，于子任务入口显式绑定父上下文，避免中途丢失 Span 层级。提示词与中间步骤的版本化：为提示词模板、模型名与温度参数、工具 JSON Schema、RAG 索引版本分别编号，组合成config_fingerprint写进 Span 属性；记录每步输入/输出的轻量快照，形成“版本 + 配置 + 输入”三元组，复现问题时优先核对三者是否匹配；把提示词和中间步骤版本接入 Git 与评测流水线，上线前生成变更摘要并关联回归结果，便于追踪质量波动。Token 级与步骤级成本监控：在 Span 上挂载prompt_tokens、completion_tokens与耗时属性，按步骤、工具、用户、模型、版本多维度聚合成本与延迟；对循环调用、重复检索和过长提示词设置阈值告警，例如“同一步骤重试超过 3 次”或“单轮提示词 Token 超限”；产出成本归因报表，定位高成本低价值步骤，支持按租户、业务线或 Agent 版本拆账与优化。推理链路可视化：把 Span 树渲染成时序瀑布图或甘特图，一眼看清每一步耗时、嵌套与并行关系；失败步骤高亮、重试路径虚线标注、LLM 调用与工具调用分层着色，降低定位噪声；在关键节点附上“中间结论摘要”，让读者不必展开原始 JSON 即可理解推理走向。重放与调试：利用 Trace 记录的输入快照与配置指纹还原现场，一键重跑相同输入，复现失败链路；在相同输入下对比不同提示词、模型或工具配置，观察结果差异并归因到具体变更；对历史 Trace 做离线重放或影子流量验证，评估新配置在新版本上线前的质量与成本影响。6. 主流工具与生态：从 SDK 到平台开源框架：OpenTelemetry 的 GenAI 语义约定（SemConv）与趋势；LangSmith、Langfuse、Phoenix、Helicone 等定位与能力对比。集成方式：无侵入 SDK 自动埋点 vs. 手动 Span 装饰器；与 LangChain、LlamaIndex、AutoGen 等 Agent 框架的适配。选型建议：按“即时调试需求、长期评估需求、数据隐私、自托管成本”给出决策矩阵。7. 实战案例：定位一次“多步推理翻车”事故故障排查流程图否