BigQuery Agent Analyticsは、Googleが提供するADK(Agent Development Kit)  で開発したエージェントの実行イベントをほぼリアルタイムでBigQueryに蓄積できる公式の分析用のプラグインです。

エージェントの処理フローやツールの呼び出し状況を、特別なログ基盤を用意することなく、そのままBigQuery上で扱えるため、エージェント向けの分析基盤を短時間で構築できる点が特徴です。

特徴：

①既存のエージェントにすぐ組み込める

BigQuery Agent Analytics は、既存の ADK アプリケーションに 数行の設定を追加するだけで導入できます。

新たにログ収集用のサービスを立ちあげたり、非同期処理を自分で実装する必要はありません。

まずはログを取り始めたいという段階でも、導入のハードルはかなり低いと感じました。

②大量のイベントにも耐えられるストリーミング設計

内部ではBigQuery Storage Write API が使われており、エージェントのイベントを低レイテンシかつ効率的にBigQueryへ書き込むことが可能です。

③エージェント分析を前提に設計されたスキーマ

出力されるテーブルには「エージェント名」「セッションID」「イベント種別」「実行時間やエラー情報」といった情報が整理された形で保存されます。

「どのエージェントが」「どの流れで」「何をしたのか」を追いやすく、分析を前提としたスキーマ設計になっています。

④ログ内容を用途に応じて制御できる

デフォルトの出力を利用するだけでなく、「記録するイベントタイプを絞る」ことや、「特定の情報をマスキングする」といった制御も可能です。

実運用を想定すると、「何を保存し、何を保存しなのか」を調整できることは、セキュリティやコンプライアンスの面でも重要になるかと思います。

2025/12/12 に リリースされたAgent Development Kit (ADK) 1.21.0 では、さらにマルチモーダル コンテンツ (画像、音声など) もログに記録できるようになったようです！

ここからは、実際に BigQuery Agent Analytics を ADK のエージェントに組み込む方法を紹介します。

本記事では、すでに ADK を使ってエージェントが作成済みであることを前提とします。またADK1.21.0 バージョンを利用します。
エージェントのロジック自体には手を加えず、agent.py に設定を追加するだけでログを BigQuery に送信する流れを紹介します。

ステップ1：必要なクラスをインポート

from google.adk.plugins.bigquery_agent_analytics_plugin import BigQueryAgentAnalyticsPlugin

from google.adk.plugins.bigquery_agent_analytics_plugin import BigQueryLoggerConfig

ステップ2:プラグインの設定

bq_config = BigQueryLoggerConfig(

    enabled=True, # BigQuery Agent Analyticsを有効化、Falseにするとプラグインは動作しない

    gcs_bucket_name=GCS_BUCKET, # マルチモーダルコンテントを保存するためのGCSバケット

    log_multi_modal_content=True, #マルチモーダルコンテントの入力/出力をログ対象に含めるかどうか、Falseの場合テキスト以外は保存されない 

    max_content_length=500 * 1024, # BigQueryに直接書き込めるテキストログの最大サイズが500KBを指定

    batch_size=1, # BigQueryへの書き込み単位（イベント数）を指定、デフォルトの1は低レイテンシ（ほぼリアルタイム）

    shutdown_timeout=10.0 # アプリケーション終了時に未送信のログをBigQueryに送るために待つ最大時間（秒数）を指定

)

bq_logging_plugin = BigQueryAgentAnalyticsPlugin(

    project_id=PROJECT_ID,

    dataset_id=DATASET_ID,

    table_id="agent_events_v2", # デフォルトのテーブル名が`agent_events_v2`

    config=bq_config,

    location=LOCATION

)

ステップ3:エージェントにプラグインを組み込む

app = App(

    name="app_name", # ご自身のapp_nameを指定

    root_agent=root_agent,

    plugins=[bq_logging_plugin], #ここでエージェントにプラグインを組み込む

)

ステップ4:BigQueryにテーブルを作成
指定したテーブルがない場合、初回で自動でテーブルが作成されるということですが、自動で作成されたものはパーティションの設定がないため、下記のDDLでテーブルを作成することが推奨されています。

CREATE TABLE `project-id.dataset_id.agent_events_v2`

(

  timestamp TIMESTAMP NOT NULL OPTIONS(description="The UTC time at which the event was logged."),

  event_type STRING OPTIONS(description="Indicates the type of event being logged (e.g., 'LLM_REQUEST', 'TOOL_COMPLETED')."),

  agent STRING OPTIONS(description="The name of the ADK agent or author associated with the event."),

  session_id STRING OPTIONS(description="A unique identifier to group events within a single conversation or user session."),

  invocation_id STRING OPTIONS(description="A unique identifier for each individual agent execution or turn within a session."),

  user_id STRING OPTIONS(description="The identifier of the user associated with the current session."),

  trace_id STRING OPTIONS(description="OpenTelemetry trace ID for distributed tracing."),

  span_id STRING OPTIONS(description="OpenTelemetry span ID for this specific operation."),

  parent_span_id STRING OPTIONS(description="OpenTelemetry parent span ID to reconstruct hierarchy."),

  content JSON OPTIONS(description="The event-specific data (payload) stored as JSON."),

  content_parts ARRAY<STRUCT<

    mime_type STRING,

    uri STRING,

    object_ref STRUCT< uri STRING, version STRING, authorizer STRING, details JSON >,

    text STRING,

    part_index INT64,

    part_attributes STRING,

    storage_mode STRING

  >> OPTIONS(description="Detailed content parts for multi-modal data."),

  attributes JSON OPTIONS(description="Arbitrary key-value pairs for additional metadata."),

  latency_ms JSON OPTIONS(description="Latency measurements (e.g., total_ms)."),

  status STRING OPTIONS(description="The outcome of the event, typically 'OK' or 'ERROR'."),

  error_message STRING OPTIONS(description="Populated if an error occurs."),

  is_truncated BOOLEAN OPTIONS(description="Flag indicates if content was truncated.")

)

PARTITION BY DATE(timestamp)

CLUSTER BY event_type, agent, user_id;

ステップ5:Google Cloud Storageにバケットを作成する

指定したバケット名でバケットを作成します。

試してみたところ、バケットは自動で作成されないようです。バケットの作成を忘れている場合、データが保存されません。

ステップ6:AIエージェントを通常通り利用する
上記の設定後、エージェントの実行に伴うイベントデータがBigQuery にストリーミングされるようになります。

では次に、どのようなデータが取得できているのかを確認していきます。

かなり色々なデータが取得できるので、特に重要なスキーマ項目を中心に紹介したいと思います。

【全体】

出力されるデータは1レコード=1イベントの形式で保存されます。

下記の4つの識別子を利用して、エージェントの動きを分析できます。

・session_id ：ユーザーとの 1 つの会話

・invocation_id ： 1 回のユーザー入力に対するエージェント1回の実行（sessionの中に複数存在）

・trace_id ：1回のエージェント実行処理を構成する内部処理全体を横断する識別子

・span_id：trace 内の個々の処理単位

【event_type】

エージェントの 1 回の処理が 複数のイベントに分解されて記録されます。

これにより、「いつ・どこで・何が起きたのか」を後から正確に追跡できます。

・USER_MESSAGE_RECEIVED：ユーザーからの入力メッセージを受信

・INVOCATION_STARTING：1 回のエージェント実行（invocation）が開始

・AGENT_STARTING：エージェントの処理（思考・判断）が開始

・LLM_REQUEST：LLM（大規模言語モデル）にリクエストを送信

・LLM_RESPONSE：LLM からの応答を受信

・TOOL_STARTING：エージェントが外部ツール（検索／API／DB 等）を呼び出すための処理を開始

・TOOL_COMPLETED：ツール呼び出しが終了

・AGENT_COMPLETED：エージェントの処理（思考・ツール利用・判断）が完了

・INVOCATION_COMPLETED：1 回のエージェント実行（invocation）が完了

画像は実際にBigQueryに保存されていたログです。

【マルチモーダルデータ】

GCSに保存された画像や音声データは下記の形式で、`content_parts`のカラムに登録されているようです。

また実際に作成したバケットに画像ファイルが保存されていることも確認できました！

{

  "event_type": "LLM_REQUEST",

  "content_parts": [

    {

      "part_index": 2,

      "mime_type": "image/png",

      "storage_mode": "GCS_REFERENCE",

      "text": "[MEDIA OFFLOADED]",

      "object_ref": {

        "uri": "gs://***/***.png",

        "authorizer": "*****",

        "details": {"gcs_metadata": {"content_type": "image/png"}}

      }

    }

  ]

}

では実際の分析例を紹介していきます。

今回はroot_agentがいくつかのsub_agentを持っています。

①LLMのトークン使用量を把握する

LLMのトークン使用料量event_type：LLM_RESPONSEのデータのcontentにあります。

下記のSQLで入力（prompt）、出力（completion）、合計（total）それぞれのLLMのトークン使用量が確認できます。

SELECT

  agent,

  SUM(CAST(JSON_VALUE(content, '$.usage.prompt') AS INT64))     AS sum_prompt_tokens,

  SUM(CAST(JSON_VALUE(content, '$.usage.completion') AS INT64)) AS sum_completion_tokens,

  SUM(CAST(JSON_VALUE(content, '$.usage.total') AS INT64))      AS sum_total_tokens

FROM `project_id.dataset_id.agent_events_v2`

WHERE event_type = 'LLM_RESPONSE'

GROUP BY agent

ORDER BY sum_total_tokens DESC;

実行結果は下記です。

単純にpromptとcompletionの合計がtotalになってるわけではないようなので注意が必要です。

上記は合計で表示していますが、SQLを変更すれば平均なども簡単に集計できます。

各エージェントがどれくらいトークンを消費しているか簡単に確認することができました！

②レイテンシの分析

event_type が LLM_RESPONSE と TOOL_COMPLETED のデータでは、latency_ms カラムにレイテンシが記録されているので、レイテンシの分析が可能です。

(1) LLM_RESPONSEを利用する場合（ルートエージェントとサブエージェントを対象に分析）

SELECT

  agent,

  COUNT(*) AS execution_count,

  AVG(SAFE_CAST(JSON_VALUE(latency_ms, '$.total_ms') AS INT64)) AS avg_latency_ms,

  MAX(SAFE_CAST(JSON_VALUE(latency_ms, '$.total_ms') AS INT64)) AS max_latency_ms

FROM `project_id.dataset_id.agent_events_v2`

WHERE event_type = 'LLM_RESPONSE'

GROUP BY agent

ORDER BY avg_latency_ms DESC;

SQLの実行結果は下記です。

(2) TOOL_COMPLETEDを利用する場合（toolとして利用しているエージェントを対象に分析）

SELECT

  JSON_VALUE(content, '$.tool') AS tool_name,

  COUNT(*) AS execution_count,

  AVG(SAFE_CAST(JSON_VALUE(latency_ms, '$.total_ms') AS INT64)) AS avg_latency_ms,

  MAX(SAFE_CAST(JSON_VALUE(latency_ms, '$.total_ms') AS INT64)) AS max_latency_ms

FROM `project_id.dataset_id.agent_events_v2`

WHERE event_type = 'TOOL_COMPLETED'

  AND JSON_VALUE(content, '$.tool') IS NOT NULL

GROUP BY tool_name

ORDER BY avg_latency_ms DESC;

SQLの実行結果は下記です。

これを利用すれば、各サブエージェント、各ツールがどれくらい利用されているか、どれくらい応答までに時間がかかっているかなど簡単に分析することができそうです！

本記事では、BigQuery Agent Analytics の概要と、実際に BigQuery Agent Analytics を利用したエージェントの分析例を紹介しました。

BigQuery Agent Analytics を活用することで、LLM の応答時間やトークン消費量、各 tool の呼び出し回数、平均・最大レイテンシといった指標を、BigQuery 上で簡単に分析できることが分かりました。

これらの指標は、エージェント全体のボトルネックを把握し、改善の優先度を判断する上で非常に重要です。

設定も比較的簡単に行えるため、エージェントを運用している方は、ぜひ一度 BigQuery Agent Analytics を試してみてはいかがでしょうか。