智能体活动指标¶

Supported in ADKPython v1.32.0Kotlin v0.1.0

智能体开发套件（ADK）提供内置的、与厂商无关的指标收集功能，帮助你了解智能体的性能、成本和使用模式。日志提供了关于发生了什么的详细叙述，而指标则提供聚合的定量数据，用于回答事情发生的频率和速度。

指标理念¶

ADK 的指标方法设计为轻量级、标准化，并且完全与你选择的监控后端无关。

OpenTelemetry 语义约定： ADK 实现了 OpenTelemetry (OTel) GenAI 语义约定。这确保了指标以标准、可预测的属性和指标名称进行记录。
OTLP 传输格式： ADK 使用标准的 OTLP 格式发出数据，确保你的指标能够无缝集成到任何 OTel 兼容的后端（如 Prometheus、Datadog、SigNoz、Google Cloud Monitoring）。
成本和性能优先： 在对大量数据进行分析时，指标的成本和性能显著优于日志或追踪。ADK 跟踪 LLM 应用程序最关键的信号：令牌消耗、请求延迟和工具执行可靠性。
厂商中立导出： ADK 不会将你锁定在特定的指标流水线中。你可以实例化标准的 OTel 计量提供者，并将数据导出到你的基础设施所需的任何位置。

指标方案¶

启用指标后，ADK 会根据 OpenTelemetry GenAI 语义约定自动对智能体的生命周期、工作流步骤和工具执行进行检测。以下是发出的核心指标：

指标名称	类型	描述	关键属性（维度）
`gen_ai.invoke_agent.duration`	Histogram（秒）	智能体处理提示并返回响应所花费的总时间。	`gen_ai.agent.name`, `error.type`
`gen_ai.invoke_workflow.duration`	Histogram（秒）	运行工作流所花费的时间。	`gen_ai.operation.name`, `gen_ai.workflow.name`, `gen_ai.workflow.nested`（仅嵌套工作流）, `error.type`
`gen_ai.execute_tool.duration`	Histogram（秒）	智能体调用的单个工具的执行延迟。用于发现缓慢的外部 API。	`gen_ai.agent.name`, `gen_ai.tool.name`, `gen_ai.tool.type`, `error.type`
`gen_ai.invoke_agent.inference_calls`	Histogram（计数）	单次智能体调用期间执行的推理（模型）调用次数。	`gen_ai.agent.name`
`gen_ai.invoke_agent.tool_calls`	Histogram（计数）	单次智能体调用期间执行的工具调用次数。	`gen_ai.agent.name`
`gen_ai.client.operation.duration`	Histogram（秒）	单次模型 `generate_content` 调用的延迟。	`gen_ai.agent.name`, `gen_ai.operation.name`, `gen_ai.provider.name`, `gen_ai.request.model`, `gen_ai.response.model`, `error.type`
`gen_ai.client.token.usage`	Histogram（令牌）	每次模型调用的令牌消耗，按 `gen_ai.token.type` 分为输入和输出。	`gen_ai.agent.name`, `gen_ai.operation.name`, `gen_ai.provider.name`, `gen_ai.request.model`, `gen_ai.response.model`, `gen_ai.token.type`

实验性指标¶

ADK 在 adk.experimental.* 命名空间下发出额外的遥测数据，涵盖 span 属性以及以下指标。其中尚无任何内容属于 OpenTelemetry 语义约定，因此名称、属性和含义在不同版本之间仍可能发生变化。你可以自由探索，但随着名称逐步稳定，基于它们构建的长期方案可能需要更新。

以下指标将令牌消耗和调用次数聚合到单次智能体调用或单次工作流的粒度上，这比 gen_ai.client.* 所度量的单次模型调用粒度更高，因此你无需自行汇总模型调用即可查看一轮对话的总开销。

默认关闭。要启用，请设置环境变量：

export ADK_EXPERIMENTAL_TELEMETRY=true

你也可以按请求粒度选择启用，该设置优先于环境变量：

from google.adk.agents.run_config import RunConfig
from google.adk.telemetry import TelemetryConfig

run_config = RunConfig(
    telemetry=TelemetryConfig(adk_experimental_telemetry_opt_in=True)
)

如果两者都未设置，则不会记录以下任何指标。

八个 invoke_workflow 行还需要遥测 schema v2，该版本在 Vertex AI Agent Engine 上默认开启，在其他环境中默认关闭。在其他环境中请设置 ADK_TELEMETRY_SCHEMA_VERSION_OPT_IN=2，否则这些行将保持为空。invoke_agent 行不受影响，基于 Workflow 引擎构建的应用在任一版本下都会记录逐节点数据点。

指标名称	类型	描述	关键属性（维度）
`adk.experimental.invoke_agent.input_tokens`	Histogram（令牌）	单次智能体调用期间的输入（提示）令牌总和，包括服务端工具结果和缓存的提示令牌。	`gen_ai.agent.name`
`adk.experimental.invoke_agent.output_tokens`	Histogram（令牌）	单次智能体调用期间的输出（补全）令牌总和，包括推理令牌和用于发出工具调用的令牌。	`gen_ai.agent.name`
`adk.experimental.invoke_agent.total_tokens`	Histogram（令牌）	单次智能体调用的输入加输出令牌总和。	`gen_ai.agent.name`
`adk.experimental.invoke_agent.cache_read.input_tokens`	Histogram（令牌）	单次智能体调用期间由提供商管理的缓存提供的输入令牌总和。	`gen_ai.agent.name`
`adk.experimental.invoke_agent.reasoning.output_tokens`	Histogram（令牌）	单次智能体调用期间用于推理（思维链/扩展思考）的输出令牌总和。	`gen_ai.agent.name`
`adk.experimental.invoke_agent.tool.input_tokens`	Histogram（令牌）	单次请求内模型将服务端工具结果（如代码执行或搜索接地）反馈给自身的输入令牌。客户端函数工具为零。	`gen_ai.agent.name`
`adk.experimental.invoke_workflow.input_tokens`	Histogram（令牌）	上述 `input_tokens` 在一次工作流调用中所有运行的智能体之间的总和。	`adk.experimental.root_agent.name`, `gen_ai.workflow.name`, `gen_ai.workflow.nested`（仅嵌套工作流）
`adk.experimental.invoke_workflow.output_tokens`	Histogram（令牌）	上述 `output_tokens` 在一次工作流调用中所有运行的智能体之间的总和。	`adk.experimental.root_agent.name`, `gen_ai.workflow.name`, `gen_ai.workflow.nested`（仅嵌套工作流）
`adk.experimental.invoke_workflow.total_tokens`	Histogram（令牌）	上述 `total_tokens` 在一次工作流调用中所有运行的智能体之间的总和。	`adk.experimental.root_agent.name`, `gen_ai.workflow.name`, `gen_ai.workflow.nested`（仅嵌套工作流）
`adk.experimental.invoke_workflow.cache_read.input_tokens`	Histogram（令牌）	上述 `cache_read.input_tokens` 在一次工作流调用中所有运行的智能体之间的总和。	`adk.experimental.root_agent.name`, `gen_ai.workflow.name`, `gen_ai.workflow.nested`（仅嵌套工作流）
`adk.experimental.invoke_workflow.reasoning.output_tokens`	Histogram（令牌）	上述 `reasoning.output_tokens` 在一次工作流调用中所有运行的智能体之间的总和。	`adk.experimental.root_agent.name`, `gen_ai.workflow.name`, `gen_ai.workflow.nested`（仅嵌套工作流）
`adk.experimental.invoke_workflow.tool.input_tokens`	Histogram（令牌）	上述 `tool.input_tokens` 在一次工作流调用中所有运行的智能体之间的总和。	`adk.experimental.root_agent.name`, `gen_ai.workflow.name`, `gen_ai.workflow.nested`（仅嵌套工作流）
`adk.experimental.invoke_workflow.inference_calls`	Histogram（计数）	一次工作流调用中执行的推理（模型）调用次数。	`adk.experimental.root_agent.name`, `gen_ai.workflow.name`, `gen_ai.workflow.nested`（仅嵌套工作流）
`adk.experimental.invoke_workflow.tool_calls`	Histogram（计数）	一次工作流调用中执行的工具调用次数。	`adk.experimental.root_agent.name`, `gen_ai.workflow.name`, `gen_ai.workflow.nested`（仅嵌套工作流）

警告

嵌套工作流会记录自身的数据点，其总量也会被计入包围它的每个工作流中，因此跨所有数据点汇总 invoke_workflow 指标会导致重复计算。

gen_ai.workflow.nested 属性仅在嵌套工作流上设置，因此排除该属性后仅保留最外层工作流，该数据点覆盖整个对话轮次。工作流指标不携带智能体维度，因为跨越整个工作流的值无法归属于单个智能体。它们携带两个名称：gen_ai.workflow.name 与 gen_ai.invoke_workflow.duration 关联，而 adk.experimental.root_agent.name 标识应用，当对话轮次从子智能体进入时二者会不同。

指标导出设置¶

在 ADK Web 中导出指标¶

如果你使用 adk web 或 adk api_server CLI 命令运行智能体，可以配置指标导出。

OTLP 导出¶

要将指标导出到 OTLP 兼容的后端，请设置标准的 OTel 环境变量：

export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT="http://your-collector:4318/v1/metrics"
adk web path/to/your/agents_dir

注意： 如果你希望将追踪和日志也发送到同一端点，还可以设置通用的 OTEL_EXPORTER_OTLP_ENDPOINT 环境变量。

GCP 导出¶

要启用指标导出到 Google Cloud Monitoring，请使用 --otel_to_cloud 标志：

adk web --otel_to_cloud path/to/your/agents_dir

编程方式导出指标¶

你也可以在应用程序代码中以编程方式配置指标导出。

OTLP 导出设置¶

要以编程方式启用指标并将其导出到 OpenTelemetry Collector（或 OTLP 兼容的后端）：

from google.adk.telemetry.setup import maybe_set_otel_providers
import os

os.environ["OTEL_EXPORTER_OTLP_METRICS_ENDPOINT"] = "http://your-collector:4318/v1/metrics"
os.environ["OTEL_SERVICE_NAME"] = "your-adk-agent"
os.environ["OTEL_RESOURCE_ATTRIBUTES"] = "key1=value1,key2=value2"
maybe_set_otel_providers()

GCP 导出设置¶

要以编程方式将指标导出到 Google Cloud Monitoring，请使用 OpenTelemetry Google Cloud 导出器。以下是一个 Python 示例：

from google.adk.telemetry.google_cloud import get_gcp_exporters
from google.adk.telemetry.setup import maybe_set_otel_providers
import os

gcp_exporters = get_gcp_exporters(
  enable_cloud_metrics = True,
)
os.environ["OTEL_SERVICE_NAME"] = "your-adk-agent"
os.environ["OTEL_RESOURCE_ATTRIBUTES"] = "key1=value1,key2=value2"
maybe_set_otel_providers([gcp_exporters])

Kotlin 编程设置¶

在 Kotlin 中，ADK 使用标准的 GlobalOpenTelemetry 管理指标。使用 MeterProvider 配置 OpenTelemetry SDK 即可启用指标收集。

OTLP 导出设置¶

要启用指标并将其导出到 OpenTelemetry Collector，请使用适当的指标导出器配置 OpenTelemetry SDK：

// 1. Configure OpenTelemetry (Traces)
// ADK Kotlin uses GlobalOpenTelemetry to resolve its tracer on the JVM.
val spanExporter = OtlpGrpcSpanExporter.builder().setEndpoint("http://localhost:4317").build()

val resource =
    Resource.getDefault()
        .merge(
            Resource.create(
                Attributes.of(AttributeKey.stringKey("service.name"), "my-kotlin-agent"),
            ),
        )

val tracerProvider =
    SdkTracerProvider.builder()
        .addSpanProcessor(BatchSpanProcessor.builder(spanExporter).build())
        .setResource(resource)
        .build()

OpenTelemetrySdk.builder().setTracerProvider(tracerProvider).buildAndRegisterGlobal()

// 2. Optional: Configure ADK Telemetry behavior
// Enable capturing full message content in traces (use with caution in production)
TelemetryConfig.captureMessageContent = true

// 3. Initialize Agent and Runner with LoggingPlugin for console output
val agent = LlmAgent(name = "my_agent", model = Gemini(name = "gemini-flash-latest"))

val runner =
    InMemoryRunner(
        App(appName = "my_agent", rootAgent = agent, plugins = listOf(LoggingPlugin())),
    )

// The runner will now automatically emit traces via GlobalOpenTelemetry
// and log activity to the console via the LoggingPlugin.
runner.run(
    userId = "user123",
    sessionId = "session456",
    newMessage = Content.fromText(Role.USER, "Hello!"),
)