跟踪智能体

本页介绍了如何在智能体上启用 Cloud Trace，以及如何查看跟踪记录来分析查询响应时间及所执行的操作。

跟踪记录是智能体在响应每个查询时所发出的各个请求对应的时间轴。例如，下图显示了来自代理开发套件 (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以及跟踪记录上下文部分。

为智能体写入跟踪记录

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

ADK

如需为 AdkApp 启用 OpenTelemetry，请在将代理部署到 Vertex AI Agent Engine Runtime 时设置以下环境变量：

env_vars = {
  "GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY": "true",
  "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT": "true",
}

请注意以下几点：

• GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY 可启用代理轨迹和日志，但不包括提示和响应数据。

• OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT 可用于启用输入提示和输出回答的日志记录。

• 如需使用轨迹提取功能，您需要启用 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-2.0-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 控制台中，前往 Vertex AI Agent Engine 页面。
   

   前往 Agent Engine

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

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

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

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

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

配额和限制

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

价格

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