このページは Cloud Translation API によって翻訳されました。

エージェントをトレースする

このページでは、エージェントで Cloud Trace を有効にしてトレースを確認し、クエリレスポンス時間と実行されたオペレーションを分析する方法について説明します。

トレースは、エージェントが各クエリに応答するリクエストのタイムラインです。たとえば、次のガントチャートは LangchainAgent からのサンプルトレースを示しています。

クエリのサンプルトレース

ガントチャートの最初の行はトレース用です。トレースは個々のスパンで構成されます。スパンは、関数呼び出しや LLM とのやり取りなどの単一の作業単位を表します。最初のスパンはリクエスト全体を表します。各スパンには、リクエスト内の特定のオペレーションに関する詳細（オペレーションの名前、開始時刻と終了時刻、関連する属性など）が示されます。たとえば、次の JSON は、大規模言語モデル（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 のドキュメントをご覧ください。

エージェントのトレースを書き込む

エージェントのトレースを書き込むには:

ADK

AdkApp のトレースを有効にするには、Agent Development Kit エージェントを開発するときに 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 ユーザー（roles/cloudtrace.user）IAM ロールを付与するよう管理者に依頼してください。
Google Cloud コンソールで [Trace エクスプローラ] に移動します。

Trace エクスプローラに移動
ページ上部で Google Cloud プロジェクト（PROJECT_ID に対応）を選択します。

詳細については、Cloud Trace のドキュメントをご覧ください。

割り当てと上限

一部の属性値は、割り当て上限に達すると切り捨てられることがあります。詳細については、Cloud Trace の割り当てをご覧ください。

料金

Cloud Trace には無料枠があります。詳細については、Cloud Trace の料金をご覧ください。