设置跟踪

借助 Cloud Trace，您可以跟踪每个查询的操作时间轴，从而分析智能体的性能。您可以使用跟踪记录来找出瓶颈，并了解与大语言模型 (LLM) 或工具的互动情况。

本文档介绍了如何为智能体启用 Trace，以及如何 在 Google Cloud 控制台中查看和分析跟踪记录。

跟踪记录 是智能体在响应每个查询时所发出的各个请求对应的时间轴。例如，下图显示了来自智能体开发套件 (ADK) 智能体的示例跟踪记录：

跟踪记录由各个 span 组成，每个 span 表示一个工作单元（例如函数调用或与 LLM 的互动），其中第一个 span 表示整体 请求。每个 span 都提供有关特定操作的详细信息，例如操作的名称、开始和结束时间，以及请求中的任何相关属性。例如，以下 JSON 内容展示了一个 span，该 span 表示对大语言模型 (LLM) 的一个调用操作：

  {
    "name": "llm",
    "context": {
        "trace_id": "ed7b336d-e71a-46f0-a334-5f2e87cb6cfc",
        "span_id": "ad67332a-38bd-428e-9f62-538ba2fa90d4"
    },
    "span_kind": "LLM",
    "parent_id": "f89ebb7c-10f6-4bf8-8a74-57324d2556ef",
    "start_time": "2023-09-07T12:54:47.597121-06:00",
    "end_time": "2023-09-07T12:54:49.321811-06:00",
    "status_code": "OK",
    "status_message": "",
    "attributes": {
        "llm.input_messages": [
            {
                "message.role": "system",
                "message.content": "You are an expert Q&A system that is trusted around the world.\nAlways answer the query using the provided context information, and not prior knowledge.\nSome rules to follow:\n1. Never directly reference the given context in your answer.\n2. Avoid statements like 'Based on the context, ...' or 'The context information ...' or anything along those lines."
            },
            {
                "message.role": "user",
                "message.content": "Hello?"
            }
        ],
        "output.value": "assistant: Yes I am here",
        "output.mime_type": "text/plain"
    },
    "events": [],
  }

注意：跟踪记录和 span 的格式取决于您选择的插桩选项。示例 span 尚处于实验阶段，随时可能会发生变化，因此其格式目前可能不稳定。如需了解详情，请参阅 OpenTelemetry 中正在开发的生成式 AI 系统的语义惯例。

如需了解详情，请参阅 Cloud Trace 文档中的 跟踪记录和 span以及 跟踪记录上下文部分。

准备工作

在收集和写入跟踪记录之前，您必须启用特定 API 并安装依赖项。如需了解详情，请参阅 Google Cloud 可观测性文档中的收集和查看多模态 提示和回答 。

为智能体写入跟踪记录

如需为智能体写入跟踪记录，请执行以下操作：

ADK

如需为 AdkApp 启用 OpenTelemetry，请在将智能体部署到智能体运行时时设置以下 环境变量：

env_vars = {
  "GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY": "true",
  "OTEL_SEMCONV_STABILITY_OPT_IN": "gen_ai_latest_experimental",
  "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT": "EVENT_ONLY",
}

请注意以下几点：

• GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY 会启用智能体跟踪记录、 日志和指标（请参阅查看智能体的指标），但不包括提示和回答数据。

• OTEL_SEMCONV_STABILITY_OPT_IN 可启用最新的生成式 AI 语义惯例。

• OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT 可启用输入提示、输出回答和用户 ID（user.id 字段）的日志记录。通过跟踪随时间推移的使用情况和互动情况，捕获这些详细信息有助于智能体的可观测性和异常检测。

  注意：请确保您已根据要求征得最终用户同意，履行相关告知义务，并已制定数据 处理政策，以便收集此信息。
  重要提示：如果您选择 “启用提示输入和回答输出的日志记录”，则系统会从 2026 年 5 月 22 日起（使用智能体开发套件 2.1 版）记录 user.id。如果您在 5 月 22 日之前选择启用，则日志记录不包含 user.id。您需要重新部署智能体并再次选择启用，此设置才会生效。

• 如需使用跟踪记录提取，您需要启用 Telemetry API。如需了解详情，请参阅 Telemetry (OTLP) API 概览。

• 如需使用日志提取，您需要启用 Logging API。如需了解详情，请参阅 Cloud Logging API 概览。

注意： 如果您之前设置了 enable_tracing 标志，我们建议 您改用环境变量。例如，将 GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true 设置为 enable_tracing=true，并将 GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=false 设置为 enable_tracing=false。

LangchainAgent

如需为 LangchainAgent 启用跟踪记录，请在开发 LangChain 智能体时指定 enable_tracing=True。例如：

from vertexai.agent_engines import LangchainAgent

agent = LangchainAgent(
    model=model,                # Required.
    tools=[get_exchange_rate],  # Optional.
    enable_tracing=True,        # [New] Optional.
)

LanggraphAgent

如需为 LanggraphAgent 启用跟踪记录，请在开发 LangGraph 智能体时指定 enable_tracing=True。例如：

from vertexai.agent_engines import LanggraphAgent

agent = LanggraphAgent(
    model=model,                # Required.
    tools=[get_exchange_rate],  # Optional.
    enable_tracing=True,        # [New] Optional.
)

LlamaIndex

预览

此功能受服务专用条款的“通用服务条款”部分中的“非正式版产品条款”的约束。 非正式版功能“按原样”提供，可能只能获得有限的支持。 如需了解详情，请参阅 发布阶段说明。

如需为 LlamaIndexQueryPipelineAgent 启用跟踪记录，请在 开发 LlamaIndex 智能体时指定 enable_tracing=True。 例如：

from vertexai.preview import reasoning_engines

  def runnable_with_tools_builder(model, runnable_kwargs=None, **kwargs):
      from llama_index.core.query_pipeline import QueryPipeline
      from llama_index.core.tools import FunctionTool
      from llama_index.core.agent import ReActAgent

      llama_index_tools = []
      for tool in runnable_kwargs.get("tools"):
          llama_index_tools.append(FunctionTool.from_defaults(tool))
      agent = ReActAgent.from_tools(llama_index_tools, llm=model, verbose=True)
      return QueryPipeline(modules = {"agent": agent})

  agent = reasoning_engines.LlamaIndexQueryPipelineAgent(
      model="gemini-3.5-flash",
      runnable_kwargs={"tools": [get_exchange_rate]},
      runnable_builder=runnable_with_tools_builder,
      enable_tracing=True,        # Optional
  )

自定义

如需为 自定义智能体启用跟踪记录， 请访问使用 OpenTelemetry 进行跟踪 了解详情。

这会将跟踪记录导出到 设置项目 Google Cloud 部分设置的项目下的 Cloud Trace。

查看智能体的跟踪记录

对于已部署的智能体，您可以使用 Google Cloud 控制台查看智能体的跟踪记录：

1. 在 Google Cloud 控制台中，前往智能体平台部署页面。
   

   转到部署

   属于所选项目的智能体平台实例会显示在列表中。您可以使用过滤条件 字段，按指定的列过滤列表。

2. 点击智能体平台实例的名称。

3. 点击跟踪记录 标签页。

4. 您可以选择会话视图 或 span 视图 。

   点击会话或 span 可检查跟踪记录详情，包括其 span、输入和输出以及元数据属性的有向无环图 (DAG)。

配额和限制

某些属性值在达到配额限制时可能会被截断。如需了解详情，请参阅 Cloud Trace 配额。

价格

Cloud Trace 提供免费层级。如需了解详情，请参阅 Cloud Trace 价格。