設定追蹤

Cloud Trace 可追蹤每項查詢的操作時間軸，分析代理的效能。您可以使用追蹤記錄找出瓶頸，並瞭解與大型語言模型 (LLM) 或工具的互動情形。

本文說明如何為代理啟用 Trace，以及如何在 Google Cloud 控制台查看及分析追蹤記錄。

追蹤記錄是代理回覆每項查詢時的要求時間軸。舉例來說，下圖顯示 Agent Development Kit (ADK) 代理的追蹤記錄範例：

追蹤記錄是由個別跨度組成，代表單一工作單位，例如函式呼叫或與 LLM 的互動，第一個跨度代表整體要求。每個 Span 都會提供特定作業的詳細資料，例如作業名稱、開始和結束時間，以及要求中的任何相關屬性。舉例來說，下列 JSON 顯示代表呼叫大型語言模型 (LLM) 的單一 Span：

  {
    "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 日起，如果選擇加入「啟用提示輸入和回覆輸出內容記錄功能」，系統就會記錄 user.id (適用於 Agent Development Kit 2.1 版)。如果您在 5 月 22 日前選擇加入，記錄就不會包含 user.id。您必須重新部署代理程式並再次選擇加入，這項設定才會生效。

• 如要使用追蹤記錄擷取功能，請啟用 Telemetry API。詳情請參閱「Telemetry (OTLP) API 總覽」。

• 如要使用記錄擷取功能，請啟用 Cloud 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 的追蹤功能，請在enable_tracing=True開發 LangChain 代理時指定 LangchainAgent。例如：

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 專案」中的專案。

查看代理的追蹤記錄

如果是已部署的代理，您可以使用 Google Cloud 控制台查看代理的追蹤記錄：

1. 前往 Google Cloud 控制台的「Agent Platform Deployments」(Agent Platform 部署作業) 頁面。
   

   前往「Deployments」(部署作業) 頁面

   清單中會顯示所選專案中的 Agent Platform 執行個體。您可以使用「Filter」(篩選器) 欄位，依指定資料欄篩選清單。

2. 按一下 Agent Platform 執行個體的名稱。

3. 按一下「Traces」分頁標籤。

4. 您可以選取「工作階段檢視」或「Span 檢視」。

   點選工作階段或時距，即可查看追蹤記錄詳細資料，包括時距的有向無環圖 (DAG)、輸入和輸出內容，以及中繼資料屬性。

配額與限制

部分屬性值達到配額限制時，可能會遭到截斷。詳情請參閱「Cloud Trace 配額」。

定價

Cloud Trace 提供免費方案。詳情請參閱「Cloud Trace 定價」。