使用 AgentOps 进行智能体可观测性¶

仅需两行代码，AgentOps 就能为智能体提供会话回放、指标和监控功能。

为什么为 ADK 选择 AgentOps？¶

可观测性是开发和部署对话式 AI 智能体的关键方面。它允许开发者了解智能体的性能表现、与用户的交互方式，以及智能体如何使用外部工具和 API。

通过集成 AgentOps，开发者可以深入了解 ADK 智能体的行为、LLM 交互和工具使用情况。

Google ADK 包含自己的基于 OpenTelemetry 的追踪系统，主要旨在为开发者提供追踪智能体内基本执行流程的方式。AgentOps 通过提供专用且更全面的可观测性平台来增强这一功能：

统一追踪和回放分析： 整合来自 ADK 和 AI 堆栈其他组件的追踪数据。
丰富的可视化： 直观的仪表板，用于可视化智能体执行流程、LLM 调用和工具性能。
详细调试： 深入特定跨度，查看提示、完成、令牌计数和错误。
LLM 成本和延迟跟踪： 跟踪延迟、成本（通过令牌使用）并识别瓶颈。
简化设置： 仅需几行代码即可开始使用。

AgentOps 智能体可观测性仪表板

AgentOps 仪表板显示带有嵌套智能体、LLM 和工具跨度的 ADK 追踪。

AgentOps 仪表板显示多步骤 ADK 应用程序执行的追踪。你可以看到跨度的层次结构，包括主智能体工作流、各个子智能体、LLM 调用和工具执行。注意清晰的层次结构：主工作流智能体跨度包含各种子智能体操作、LLM 调用和工具执行的子跨度。

开始使用 AgentOps 和 ADK¶

将 AgentOps 集成到你的 ADK 应用程序中非常简单：

安装 AgentOps：
```
pip install -U agentops
```
创建 API 密钥 在此处创建用户 API 密钥：创建 API 密钥并配置你的环境：

将你的 API 密钥添加到环境变量中：
```
AGENTOPS_API_KEY=<YOUR_AGENTOPS_API_KEY>
```

初始化 AgentOps： 在 ADK 应用程序脚本的开头添加以下行（例如，运行 ADK Runner 的主 Python 文件）：

import agentops
agentops.init()

这将启动 AgentOps 会话并自动跟踪 ADK 智能体。

详细示例：

import agentops
import os
from dotenv import load_dotenv

# 加载环境变量（可选，如果你使用 .env 文件存储 API 密钥）
load_dotenv()

agentops.init(
    api_key=os.getenv("AGENTOPS_API_KEY"), # 你的 AgentOps API 密钥
    trace_name="my-adk-app-trace"  # 可选：为你的追踪指定名称
    # auto_start_session=True 是默认值。
    # 如果你想手动控制会话开始/结束，请设置为 False。
)

🚨 🔑 你可以在注册后在 AgentOps 仪表板上找到你的 AgentOps API 密钥。建议将其设置为环境变量（AGENTOPS_API_KEY）。

初始化后，AgentOps 将自动开始检测你的 ADK 智能体。

这就是捕获 ADK 智能体所有遥测数据所需的全部内容

AgentOps 如何检测 ADK¶

AgentOps 采用复杂的策略来提供无缝的可观测性，而不会与 ADK 的原生遥测发生冲突：

中和 ADK 的原生遥测： AgentOps 检测 ADK 并智能地修补 ADK 的内部 OpenTelemetry 追踪器（通常是 trace.get_tracer('gcp.vertex.agent')）。它用 NoOpTracer 替换它，确保 ADK 自己创建遥测跨度的尝试被有效静音。这防止重复追踪，并允许 AgentOps 成为可观测性数据的权威来源。
AgentOps 控制的跨度创建： AgentOps 通过包装关键的 ADK 方法来控制创建逻辑层次结构的跨度：
- 智能体执行跨度（例如，adk.agent.MySequentialAgent）： 当 ADK 智能体（如 BaseAgent、SequentialAgent 或 LlmAgent）启动其 run_async 方法时，AgentOps 为该智能体的执行启动父跨度。
- LLM 交互跨度（例如，adk.llm.gemini-pro）： 对于智能体对 LLM 的调用（通过 ADK 的 BaseLlmFlow._call_llm_async），AgentOps 创建专用的子跨度，通常以 LLM 模型命名。此跨度捕获请求详细信息（提示、模型参数），并在完成时（通过 ADK 的 _finalize_model_response_event）记录响应详细信息，如完成、令牌使用和完成原因。
- 工具使用跨度（例如，adk.tool.MyCustomTool）： 当智能体使用工具时（通过 ADK 的 functions.__call_tool_async），AgentOps 创建以工具命名的单个综合子跨度。此跨度包括工具的输入参数和返回的结果。
丰富的属性收集： AgentOps 重用 ADK 的内部数据提取逻辑。它修补 ADK 的特定遥测函数（例如，google.adk.telemetry.trace_tool_call、trace_call_llm）。这些函数的 AgentOps 包装器获取 ADK 收集的详细信息，并将其作为属性附加到当前活动的 AgentOps 跨度。

在 AgentOps 中可视化你的 ADK 智能体¶

当你使用 AgentOps 检测 ADK 应用程序时，你可以在 AgentOps 仪表板中获得智能体执行的清晰层次视图。

初始化： 当调用 agentops.init() 时（例如，agentops.init(trace_name="my_adk_application")），如果 init 参数 auto_start_session=True（默认为 true），则创建初始父跨度。此跨度（通常命名为类似 my_adk_application.session）将成为该追踪内所有操作的根。
ADK Runner 执行： 当 ADK Runner 执行顶级智能体时（例如，编排工作流的 SequentialAgent），AgentOps 在会话追踪下创建相应的智能体跨度。此跨度将反映你的顶级 ADK 智能体的名称（例如，adk.agent.YourMainWorkflowAgent）。
子智能体和 LLM/工具调用： 当这个主智能体执行其逻辑时，包括调用子智能体、LLM 或工具：
- 每个子智能体执行将作为嵌套子跨度出现在其父智能体下。
- 对大型语言模型的调用将生成进一步的嵌套子跨度（例如，adk.llm.<model_name>），捕获提示详细信息、响应和令牌使用。
- 工具调用也将产生不同的子跨度（例如，adk.tool.<your_tool_name>），显示其参数和结果。

这创建了跨度的瀑布，允许你查看 ADK 应用程序中每个步骤的顺序、持续时间和详细信息。所有相关属性，如 LLM 提示、完成、令牌计数、工具输入/输出和智能体名称，都被捕获并显示。

对于实际演示，你可以探索一个示例 Jupyter Notebook，该示例说明了使用 Google ADK 和 AgentOps 的人工审批工作流： GitHub 上的 Google ADK 人工审批示例。

此示例展示了如何在 AgentOps 中可视化具有工具使用的多步骤智能体流程。

优势¶

轻松设置： 最少的代码更改即可实现全面的 ADK 追踪。
深度可见性： 了解复杂 ADK 智能体流程的内部工作原理。
更快调试： 通过详细的追踪数据快速定位问题。
性能优化： 分析延迟和令牌使用。

通过集成 AgentOps，ADK 开发者可以显著增强构建、调试和维护强大 AI 智能体的能力。

使用 AgentOps 进行智能体可观测性¶

为什么为 ADK 选择 AgentOps？¶

开始使用 AgentOps 和 ADK¶

AgentOps 如何检测 ADK¶

在 AgentOps 中可视化你的 ADK 智能体¶

优势¶

更多信息¶

额外链接¶