Skip to content

用于 ADK 的 Google Cloud Trace 可观测性

Supported in ADKPythonTypeScriptGo

利用 ADK，你已经能够通过此处讨论的功能强大的 Web 开发 UI 在本地检查和观察智能体交互。但是，对于云端部署，你将需要一个集中式的仪表板来观察真实的流量。

Cloud Trace 是 Google Cloud Observability 的一个组件。它是一个强大的工具，专门专注于追踪功能，用于监控、调试和改进应用程序的性能。对于智能体开发工具包 (ADK) 应用程序，Cloud Trace 实现了全面的追踪，帮助你了解请求如何流经智能体的交互，并识别 AI 智能体中的性能瓶颈或错误。

Cloud Trace 构建在 OpenTelemetry 之上，这是一个开源标准，支持多种语言和摄取方法来生成追踪数据。这与 ADK 应用程序的可观测性实践一致，ADK 也利用了兼容 OpenTelemetry 的仪表化功能，从而允许你：

  • 追踪智能体交互：Cloud Trace 会持续收集并分析你项目中的追踪数据，使你能够快速诊断 ADK 应用程序中的延迟问题和错误。
  • 调试问题：通过分析详细的追踪信息，快速诊断延迟问题和错误。这对于理解在不同服务之间或在特定智能体操作（如工具调用）期间表现为通信延迟增加的问题至关重要。
  • 深入分析与可视化：Trace Explorer 是分析追踪数据的主要工具，提供诸如跨度时长热图和瀑布图之类的视觉辅助工具，以便轻松识别智能体执行路径中的瓶颈和错误来源。

以下示例将假设智能体目录结构如下：

working_dir/
├── weather_agent/
│   ├── agent.py
│   └── __init__.py
└── deploy_agent_engine.py
└── deploy_fast_api_app.py
└── agent_runner.py

# weather_agent/agent.py

import os
from google.adk.agents import Agent

os.environ.setdefault("GOOGLE_CLOUD_PROJECT", "{你的项目ID}")
os.environ.setdefault("GOOGLE_CLOUD_LOCATION", "global")
os.environ.setdefault("GOOGLE_GENAI_USE_VERTEXAI", "True")

# 定义一个工具函数
def get_weather(city: str) -> dict:
    """检索指定城市的当前天气报告。

    参数：
        city (str): 要检索天气报告的城市名称。

    返回：
        dict: 状态和结果或错误消息。
    """
    if city.lower() == "new york":
        return {
            "status": "success",
            "report": (
                "纽约的天气是晴天，温度为 25 摄氏度"
                " (77 华氏度)。"
            ),
        }
    else:
        return {
            "status": "error",
            "error_message": f"无法获取 '{city}' 的天气信息。",
        }

# 创建一个带有工具的智能体
root_agent = Agent(
    name="weather_agent",
    model="gemini-2.5-flash",
    description="使用天气工具直接回答问题的智能体。",
    instruction="你必须使用可用的工具来寻找答案。",
    tools=[get_weather],
)

Cloud Trace 设置

使用 ADK CLI

在使用 ADK CLI 部署或运行智能体时，你可以通过添加标志来启用云端追踪。

使用 adk deploy 命令部署智能体时： 

adk deploy agent_engine \
    --project=$GOOGLE_CLOUD_PROJECT \
    --region=$GOOGLE_CLOUD_LOCATION \
    --trace_to_cloud \
    $AGENT_PATH

运行使用 ADK Go 启动器构建的智能体时： 

adkgo web -otel_to_cloud

编程式设置

使用 ADK App 抽象

如果你正在使用 AdkApp 抽象，可以通过添加 enable_tracing=True 来启用云端追踪：

from google.adk.apps import AdkApp

adk_app = AdkApp(
    agent=root_agent,
    enable_tracing=True,
)

使用遥测模块

对于完全定制的智能体运行时，你可以使用内置的遥测模块启用云端追踪。

from google.adk import telemetry
from google.adk.telemetry import google_cloud

# 获取 GCP 导出器配置
hooks = google_cloud.get_gcp_exporters(enable_cloud_tracing=True)

# 初始化并设置全局 OTel 提供程序
telemetry.maybe_set_otel_providers(otel_hooks_to_setup=[hooks])

import { getGcpExporters, maybeSetOtelProviders } from '@google/adk';

// 获取 GCP 导出器配置
const gcpExporters = await getGcpExporters({
  enableTracing: true,
});

// 初始化并设置全局 OTel 提供程序
maybeSetOtelProviders([gcpExporters]);

// ... 你的智能体代码 ...

import (
    "context"
    "log"
    "time"

    "google.golang.org/adk/telemetry"
)

func main() {
    ctx := context.Background()

    // 初始化遥测并启用云端导出。
    // 默认情况下，从 GOOGLE_CLOUD_PROJECT 环境变量读取 GCP 项目 ID。
    // 你也可以使用 telemetry.WithGcpResourceProject("my-project") 显式指定。
    telemetryProviders, err := telemetry.New(ctx,
        telemetry.WithOtelToCloud(true),
        // telemetry.WithGcpResourceProject("your-project-id"),
    )
    if err != nil {
        log.Fatalf("无法初始化遥测: %v", err)
    }
    defer func() {
        shutdownCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
        defer cancel()
        if err := telemetryProviders.Shutdown(shutdownCtx); err != nil {
            log.Printf("无法关闭遥测: %v", err)
        }
    }()

    // 注册为全局 OTel 提供程序
    telemetryProviders.SetGlobalOtelProviders()

    // ... 你的智能体代码 ...
}

检查 Cloud Traces

完成设置后，每当你与智能体互动时，它都会自动将追踪数据发送到 Cloud Trace。你可以访问 Google Cloud 控制台 中的 Trace Explorer 来检查这些追踪信息。

cloud-trace

你将看到由 ADK 智能体生成的各种追踪信息，跨度名称诸如 invoke_agent、generate_content、call_llm 和 execute_tool。

cloud-trace

如果你点击其中一个追踪记录，你将看到详细过程的瀑布图，类似于本地 ADK Web UI 中的追踪视图。

cloud-trace

资源