设置跟踪

借助 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 Observability 文档中的收集和查看多模态提示和回答。

为智能体写入跟踪记录

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

ADK

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

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 控制台中，前往 Agent Platform Deployment页面。
   

   转到部署

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

2. 点击 Agent Platform 实例的名称。

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

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

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

配额和限制

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

价格

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