跟踪智能体

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

跟踪记录是智能体在响应每个查询时所发出的各个请求对应的时间轴。例如，下面的甘特图显示了来自 LangchainAgent 的示例跟踪记录：

查询的示例跟踪记录

甘特图中的第一行用于表示跟踪记录。跟踪记录由各个 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": [],
  }

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

为智能体写入跟踪记录

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

ADK

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

  from vertexai.agent_engines import AdkApp
  from google.adk.agents import Agent

  agent = Agent(
      model=model,
      name=agent_name,
      tools=[get_exchange_rate],
  )

  app = AdkApp(
      agent=agent,          # Required.
      enable_tracing=True,  # Optional.
  )

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。

查看智能体的跟踪记录

您可以使用 Trace 探索器查看跟踪记录：

如需获得在 Google Cloud 控制台中查看跟踪记录数据或选择跟踪记录范围所需的权限，请让您的管理员为您授予项目的 Cloud Trace User (roles/cloudtrace.user) IAM 角色。
在 Google Cloud 控制台中，前往 Trace 探索器：

前往 Trace 探索器
选择页面顶部的 Google Cloud 项目（对应于 PROJECT_ID）。

如需了解详情，请参阅 Cloud Trace 文档。

配额和限制

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

价格

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