AI Agent 可观测性完全指南：遥测、追踪、指标与评估
译注： 本文翻译自 groundcover 技术博客。原文链接：AI Agent Observability: Key Concepts, Challenges & Best Practices。译文在保留原文核心观点的基础上进行了意译润色，并保留了所有原始配图。
AI 代理的一次运行，表面上看起来可能很成功，实际却在做着错误的事情。它可能用错误的参数调用了正确的工具，陷入了循环，或者走上了一条只有在真实流量下才会暴露的慢速路径。在这种情况下，单个请求就可能触发大量的模型调用和工具调用，导致延迟和成本飙升。
当这类问题发生时，传统的 APM 追踪能捕捉到错误和延迟，但它在基础设施边界处就止步了。仅记录模型输入输出的 prompt 日志，又会遗漏路由决策和上下文变化。在本文中，你将了解什么是 AI Agent 可观测性、应该追踪哪些信号和指标，以及如何在单代理和多代理系统中应用可观测性实践，包括 AI Agent 可观测性面临的独特挑战和规模化实施的最佳实践。
什么是 AI Agent 可观测性？
AI Agent 可观测性，指的是能够通过遥测数据看到代理在一次请求中做了什么 、为什么这样做 ，以及表现如何。它不再局限于 CPU、延迟和错误率，而是同时追踪 AI 特有的信号------如 token 用量、模型响应、工具调用、决策路径和输出质量------并将它们映射到常规的指标、日志和追踪之上。这让由模型、工具和记忆组成的智能体生态系统从外部变得可推理，而不是一个不透明的黑盒 LLM 调用。
在一个拥有良好 AI Agent 可观测性的系统中，每个用户请求都会呈现为一条相互关联的追踪。你可以打开一次运行，看到用户输入、代理的规划步骤、每一次 LLM 调用、每一次工具调用、中间结果和最终答案，以及每一步的耗时、token 计数和成本。这些追踪数据还可以输入到仪表板、告警和评估中，让你既能审查某次令人困惑的运行，也能跨大量运行来发现行为、可靠性和支出的模式。
AI Agent 可观测性的核心组件
AI Agent 可观测性由几个构建模块组成，帮助你逐步审查单次运行，同时在多次运行间衡量行为和成本。
- 分布式追踪（Distributed Traces）：分布式追踪是单次代理运行的端到端记录。它们将每个步骤连接成有序的时间线，让你可以跨路由、模型调用和下游工作追踪整个运行过程，而不必猜测时间花在了哪里。
- 结构化日志（Structured Logs）：结构化日志以一致的格式捕获步骤级细节，而非自由文本。对于代理来说，这包括工具调用的输入和输出、模型调用的请求元数据，以及系统产生的任何决策记录（如选定的路由或评分），确保这些细节始终绑定到特定的运行和步骤。
- 延迟、错误和用量指标：指标跨多次运行汇总行为。除了延迟和错误指标外，代理可观测性还追踪 AI 特有的用量信息，如 token 计数和模型计时信号，帮助解释性能下降和成本增加。
- 评估和反馈信号：评估是对输出质量、安全性和任务成功率的结构化测量。当每个评分都能追溯到产生该输出的确切运行和步骤时，其价值就会大大增加。
- 治理和策略结果：治理信号记录了哪些规则被检查以及结果如何。这包括安全过滤器、访问控制，以及解释为什么某个操作在一次运行中被允许、阻止或修改的策略决策。
- 语义约定和命名标准：语义约定为 span、事件、属性和指标定义共享名称，使来自不同框架和组件的遥测数据能够以一致的方式被查询。在代理系统中，这是当混合使用多个模型、工具和运行时后仍能保持追踪和仪表板可读性的关键。
有了这些组件，你就可以解释一次运行中发生了什么、衡量性能和成本，并将质量和策略结果追溯回产生它们的步骤。
为什么 AI Agent 可观测性在生产系统中至关重要
在生产环境中，你需要知道代理在每次请求中做了什么，以及这些行为的代价。AI Agent 可观测性就是将这些变成可见可控的能力。
为调试提供运行级别的证据
当出现问题时，你通常从一个错误的结果开始排查：一个错误的答案、一个中断的工作流，或一个困惑的用户。由于代理的非确定性，重放相同的输入可能不会遵循相同的路径。运行级别的追踪为你提供了该特定请求实际发生的具体记录，让你看到哪些步骤被执行了、调用了哪些工具、行为在哪里偏离了预期。
精确定位是哪一层出了问题
并非每个 LLM 问题都是模型问题。检索可能返回了错误的上下文，某个工具可能超时了，schema 可能变了，或者代理图将请求路由到了错误的分支。当路由、检索、模型调用和工具调用分别显示为独立的步骤时，你就能判断修复应该放在 prompt、数据源、工具 API 还是代理工作流中。
揭示那些看起来成功的失败
代理经常在跳过必要的工具调用、使用过时数据或错误应用规则时，仍然返回流畅的响应。这些运行表面看起来正常，只会在之后表现为业务问题。追踪、结构化日志和评估让这些静默失败变得可见------它们能显示哪些步骤被跳过了、哪些工具从未被调用、哪些检查在表面上"成功"的运行中被忽略了。
将成本和延迟峰值归因到具体原因
如果看到的只是更高的平均值，成本或响应时间的峰值很难采取行动。步骤级别的可见性让你看到哪些路径、模型或工具驱动了 token 用量、重试和慢速 span。这使得基于明确目标来调优 prompt、调整路由或改变工具使用成为可能，而不是盲目猜测或降级模型。
捕获未跟踪变更导致的回归
许多影响代理的变更永远不会表现为正式的部署：有人微调了 prompt、添加了新工具、更换了数据源或切换到新的模型版本。这些未跟踪的变更可能在不提高错误率的情况下降低质量。当评估和反馈与追踪关联时，你可以在这些变更发生后不久就发现成功率下降、新的失败模式或行为漂移。
支持审计和合规审查
如果代理读取敏感数据或触发其他系统中的操作，你需要清晰的记录来证明它访问了什么、尝试了什么、哪些被允许或阻止。可观测性数据就是你的审计追踪。它支持事后复盘，并在安全、风险或合规团队需要了解系统行为时提供具体证据。
跨代理边界追踪故障
多代理设置增加了系统中可能的路径数量。工作可能在规划器、专家和助手之间流转，链条早期的一个小错误可能级联成后续的浪费调用或错误操作。统一的追踪和跨代理的一致遥测让你能够端到端地跟随单个请求，看到第一个错误发生在哪里，以及它如何传播。
AI Agent 可观测性在生产中不是可选项。它是让你能够调试真实问题、管理成本、降低风险，并保持单代理和多代理系统可控的关键。
AI Agent 可观测性在现代架构中如何运作
现代 AI Agent 可观测性并不存在于孤岛中。它通过你已有的服务遥测流水线运行。代理、工具和模型发出结构化遥测，可观测性工具收集和存储这些数据，让你能够调试运行并随时间监控代理性能。
OpenTelemetry 与 AI Agent 可观测性标准
大多数新架构使用 OpenTelemetry 作为代理可观测性的传输协议和数据模式。代理框架不再发明自定义格式，而是发出带有 GenAI 专用字段（如提供商、模型名称、操作类型如 invoke_agent、token 计数和错误信息）的 OpenTelemetry span 和指标。
这为不同代理框架之间的可观测性提供了一致的追踪形态。一个 invoke_agent span 可以包含代理 ID、输入大小、输出大小和评估结果的属性。子 span 代表工具使用、检索步骤或嵌套的代理调用。基于同一遥测构建的指标涵盖每个模型或代理的延迟、错误率、token 用量和吞吐量。
通常有两种方式将代理连接到 OpenTelemetry。一些框架自带内置的 OpenTelemetry 支持，你只需设置一个端点就能获得每次代理调用和模型调用的 span。另一些则依赖显式插桩库，你需要将其导入应用程序来包装 LLM 调用、代理调用和工具函数。
两种方式的目标是一样的：发出标准化的遥测数据，使任何 OpenTelemetry 兼容的可观测性工具都能摄取和查询。
多代理和工具驱动系统中的可观测性
许多生产环境在设计上就是多代理的。一个规划代理将工作委托给专家代理，后者调用工具和服务。代理可观测性必须展示单个用户请求如何穿越整个链条，而不仅仅是单个代理做了什么。
核心技术是多代理追踪。每次代理调用显示为一个 span。每当一个代理调用另一个代理或工具时，追踪上下文就会被传递。打开一条追踪时，你会看到根代理 span 在顶部，然后是路由、规划、专家代理和工具使用的子 span。这个视图展示了在每个步骤中哪个代理承担了责任，以及控制权如何流回调用方。
工具驱动系统遵循相同的模式。每个工具调用变成一个 span，包含工具名称、延迟、状态以及选定的参数或响应元数据等字段。这使得工具使用成为同一可观测性叙事的一部分，而不是单独的日志流。查看一条追踪时，你可以看到调用了哪些工具、以什么顺序、耗时多久，以及它们的输出如何反馈到代理的决策中。
面向调试、成本控制和可靠性的可观测性
一旦遥测开始流动，同一组可观测性数据就能驱动三个主要运营循环：调试、成本控制和可靠性。
成本控制方面 ，你将相同的 span 聚合为指标。可以看到每个代理、每个模型和每个路由的 token 用量、特定工具的慢速 span，以及重试或循环对总体支出的影响。这让你能够基于数据回答哪些流程最昂贵 、上周和本周之间发生了什么变化等问题，然后调整 prompt、路由或工具使用来提升性能并降低成本。
可靠性方面，你在追踪之上叠加评估和策略检查。每次运行可以携带任务成功率、答案正确性、工具准确性和护栏结果等信号。随时间推移，你将这些作为时间序列来追踪，以检测代理可观测性工具中的行为漂移和可靠性问题。当新的 prompt、模型或工具版本损害了可靠性时，这种变化会表现为评估分数和错误模式的偏移------基于真实流量，而不仅仅是离线测试。
AI Agent 可观测性追踪的核心信号和指标
监控 AI 代理时，你追踪特定的信号组别：用量、性能、行为、质量和治理。以下是主要的几类：
- Token 和模型用量：你测量每次模型调用的输入和输出 token，以及模型和提供商信息。这显示了支出的来源、哪些代理或路由最昂贵，以及在更新 prompt、模型或路由后用量如何变化。
- 延迟和错误率：你追踪每次代理运行和每个步骤的端到端延迟，包括模型调用、工具调用和检索。你还记录每个步骤的错误计数和简单错误类型。这告诉你时间花在哪里、可靠性问题是出在模型、工具还是代理逻辑中。
- 代理路径和步骤指标：你记录代理走了多少步、运行了哪些节点或子代理、发生了多少次重试或循环，以及选择了哪个路由或策略分支。这些指标解释了为什么有的运行三步就完成了，而另一些需要二十步，帮助你发现不必要的循环或过度规划等模式。
- 工具使用和性能：你追踪每个工具被调用的频率、运行时长、失败频率，以及代理用错误或不完整参数调用它的频率。这展示了性能和可靠性对工具使用的依赖程度，并突出那些导致错误或引入显著延迟的工具。
- 评估和输出质量：你为运行附加评分，衡量任务成功率、正确性、对检索数据的忠实度，以及安全或策略合规性。随时间推移，这些指标显示代理性能是在改善还是退化，以及哪些模型、代理或路由倾向于产生薄弱或有风险的输出。
- 治理和数据访问信号：你记录哪些策略和护栏被运行、它们是否阻止或修改了操作，以及代理使用了哪些数据源。当你需要审计行为、解释为什么某个请求被阻止或展示某条安全规则触发的频率时，这些信号至关重要。
这些信号组合在一起，让你对 AI 代理的性能获得全方位的视图。
AI Agent 可观测性的独特挑战
在生产环境中监控 AI 代理时，会出现一些在传统服务中较少遇到的问题。以下是需要提前规划的关键可观测性挑战：
| 挑战 | 描述 | 解决方案 |
|---|---|---|
| 非确定性运行和路径变化 | 相同的输入可能遵循不同的路由和步骤，使回归难以比较和解释。 | 使用运行级分布式追踪（每个请求一条追踪）、标准化的代理 span，并附加评估分数来逐步比较"好"和"差"的运行。 |
| 长对话和隐藏的失败模式 | 问题在长工作流或长对话的后期才出现，即使每次 API 调用都"成功"。 | 为所有 span 标记对话或旅程 ID，并在真实流量上追踪端到端完成率、延迟和结果评估，而不仅仅是在测试中。 |
| 多步骤和多代理流中的级联错误 | 规划、检索或交接中的早期小错误通过多个代理和工具级联传播。 | 跨代理和工具传播追踪上下文，为每个代理和工具调用使用统一的 span，并在其上追踪旅程完成率和工具调用准确性。 |
| 超越状态码的质量衡量 | 语义失败（如错误、不安全或偏离策略的答案）永远不会表现为 HTTP 错误。 | 将评估视为遥测。将任务成功率、正确性、忠实度和安全评分附加到运行上，并将其作为带告警的指标聚合。 |
| 含敏感和大载荷的遥测 | Prompt、输出和检索的上下文可能非常大，且包含敏感数据。 | 选择性地记录内容。截断或遮蔽输入和输出字段、采样追踪，在不需要完整文本时依赖 token、延迟和评估指标。 |
| 框架碎片化和不一致的遥测 | 不同团队和技术栈为相似概念发出不同的日志格式和指标名称。 | 统一采用 OpenTelemetry GenAI 语义约定，从所有框架和服务发出具有共享属性的代理和模型 span。 |
| 频繁的未跟踪变更导致的漂移 | Prompt 编辑、工具更新、模型切换和数据变更在非正式部署的情况下改变行为。 | 在 span 上记录模型、prompt、工具和数据源标识符，并监控评估、成本和延迟趋势，设置与这些配置关联的漂移告警。 |
理解这些挑战有助于你设计适合 AI 代理的可观测性方案，而不是仅仅依赖为传统服务构建的模式。
规模化实施 AI Agent 可观测性的最佳实践
规模化场景下，AI Agent 可观测性必须成为你设计和交付代理的一部分，而不是事后添加的仪表板。要构建在真实流量和多种代理框架下仍然稳固的系统，需要遵循以下实践：
将每次代理运行为单条追踪
将每个用户请求视为一条追踪，其中规划、模型调用、工具调用和下游服务分别对应各自的 span。这给你一份完整的记录，当运行出现异常时可以打开查看，而不是面对散落的日志。使用一致的 span 名称和属性（代理名称、操作、模型、工具、路由），使追踪在不同代理间保持可读性和可比性。
使用共享的遥测约定
选择一个通用的代理遥测模式，并在不同技术栈中坚持使用。OpenTelemetry GenAI 语义约定已经定义了代理操作、模型、对话 ID、数据源和错误的属性，你不必自己发明。以这种格式发出 span 和指标使你更容易接入现有可观测性工具，并在混合使用不同代理框架时保持遥测的一致性。
添加 AI 特有的指标和评估
标准的基础设施指标不够用。你还需要每个模型和每个代理的 token 和成本指标、工具使用和失败模式，以及任务成功率、正确性、忠实度和安全性的评估评分。将评估视为可观测性的一部分，评分存储在追踪旁边，用于仪表板和告警，而不是作为单独的离线步骤。
将评估接入 CI/CD 和生产环境
不要等到生产环境才发现回归。在 CI/CD 中对关键场景运行自动化评估套件，阻止质量或安全性低于阈值的变更。然后在采样的生产流量上复用相同的评估逻辑，这样你就能在 prompt、模型、工具或数据变更后发现性能漂移，并直接从低分跳转到对应的追踪。
围绕代理结果构建仪表板和告警
仪表板应该回答代理是否在做好自己的工作，而不仅仅是服务是否在线。追踪任务完成率、评估分数、工具调用准确性、漂移指标和每请求成本，按代理、路由和模型分解。对这些信号设置告警，例如"此工作流的完成率下降了"、"schema 变更后工具调用准确性下降了"、"本周每请求成本翻倍了"，并将告警关联到示例追踪以加快调试。
将治理和安全视为遥测
策略检查和护栏应该像任何其他步骤一样出现在追踪中。记录哪些策略被运行、哪些阻止或修改了操作、代理访问了哪些数据源。同时，通过在遥测中截断或遮蔽 prompt 和输出来保护用户和数据，并将详细追踪的访问权限限制到真正需要它的角色。
为多代理和工具密集型流做设计
假设工作会跨越代理和工具边界。在所有代理调用和工具调用中传播追踪上下文，使单个请求从规划器到专家再到外部 API 都保持在单条追踪内。在每个 span 上包含代理名称、工具名称、参数（安全的情况下）、延迟和状态，这样当多代理工作流失败时你就能看到级联从哪里开始。
从聚焦的起点逐步扩展覆盖范围
不要试图在第一天就记录一切。从自动插桩和一小部分重要的代理或工作流开始，然后在你真正需要更多细节来调试或优化的地方添加自定义 span、属性和评估。这使遥测量保持在可控范围内，确保你构建的仪表板是你会真正使用的。
groundcover：追踪优先的 AI Agent 可观测性
到目前为止，你已经了解了 AI Agent 可观测性需要什么。groundcover 将这些需求转化为一种追踪优先的设置，而无需你为代理单独构建一套基础设施。
无需改动代码即可追踪每次 LLM 和代理调用
groundcover 在你的 Kubernetes 集群中运行一个 eBPF 传感器，自动将 LLM 流量转化为追踪。它检测来自你的服务对 OpenAI 或 Anthropic 等提供商的调用，并将 prompt、响应、延迟、token 用量和错误记录为 span。你不需要添加新的 SDK 或将每次调用都包装在追踪代码中。
对于代理工作负载，同一个传感器让你能看到响应背后的步骤，而不仅仅是单个 API 调用。你可以打开一条追踪，跟随代理的规划步骤、模型调用、工具调用和下游服务作为一次运行，这与前文所述的追踪优先最佳实践一致。
在技术栈中使用共享的 GenAI 遥测
当 groundcover 捕获 LLM 和代理调用时，它将它们编码为遵循 GenAI 导向 OpenTelemetry 约定的 span 和指标。每个 span 都标记了模型名称、提供商、操作和状态，以及计时和 token 用量。
由于遥测使用共享模式，你可以在普通的服务追踪和指标旁边查询 LLM 和代理 span，而不必在单独的 AI 专用可观测性工具之间来回切换。这让构建将代理性能、token 用量和服务级延迟整合在一处的仪表板变得更加容易。
将代理行为与 Kubernetes 和服务关联
groundcover 是作为全栈可观测性平台构建的，因此 LLM 可观测性位于它已经从你的应用程序和 Kubernetes 收集的追踪和指标之上。一个代理请求显示为一条追踪，从入口或 API 网关开始，流经运行代理的服务，到达 LLM 提供商，再进入任何内部工具或数据库。
每个 span 都丰富了 Kubernetes 元数据，如集群、命名空间、工作负载和 Pod。当你调试代理问题时，你可以看到问题出在 LLM 调用、慢速工具、压力下的 Pod 还是网络跳转------无需切换工具。
让 AI 遥测留在你自己的云中并受你掌控
代理可观测性通常涉及敏感的 prompt 和响应。groundcover 部署在你自己的云中，因此遥测和载荷留在你的环境内部，而不是在共享的 SaaS 后端。
你还可以控制存储多少内容。默认情况下，groundcover 可以捕获完整的请求和响应体用于调试，但你也可以配置遮蔽和截断规则来移除密钥、PII 或特定字段，同时保留计时、token 计数和错误详情。这让你在需要时使用详细追踪，而不暴露超出必要的数据。
让代理通过 groundcover MCP Server 查询遥测
groundcover 还通过 MCP Server 暴露其数据。这意味着你自己的代理可以作为其工作流的一部分直接从 groundcover 查询日志、指标和追踪。
你可以给一个客服代理或值班助手受控访问最近错误、慢速追踪或资源使用情况的权限------全部通过自然语言查询实现。代理使用你在 UI 中看到的相同可观测性数据，从而闭合 AI Agent 可观测性与 AI 辅助运营之间的环路。
结语
借助 AI Agent 可观测性，你可以解释代理做了什么、为什么这样做，以及每次运行如何影响延迟、成本和输出质量。通过将追踪、指标、日志、评估和治理数据视为一个统一的系统，你从对"代理出了问题"的模糊抱怨，转向具体的运行、步骤和修复。
groundcover 在你现有的 Kubernetes 和服务遥测之上为你提供了一种追踪优先的实现方式。通过追踪 LLM 和代理调用、标准化 GenAI 信号并将可观测性数据保留在你的云中，你可以在工作负载增长的同时及早调试问题，并保持性能、成本和可靠性在正轨上。