BigQuery Agent Analyticsを使用してADKで実装したエージェントの対話データを記録する

G-gen の佐々木です。当記事では、ADK で開発した AI エージェントに BigQuery Agent Analytics のプラグインを組み込むことで、エージェントのリクエストやレスポンス、ツール呼び出しなどのイベントを BigQuery に記録し、SQL で分析できるようにしていきます。

構成

当記事では、Agent Development Kit（ADK）で定義した AI エージェントを Agent Runtime（旧称 : Vertex AI Agent Engine）にデプロイし、エージェントの実行中に発生するイベント（LLM への入出力、ツール呼び出し、エージェントのライフサイクルなど）を BigQuery にストリーミング方式で記録できるようにします。

イベントの記録には、ADK が公式に提供する BigQuery Agent Analytics プラグイン（BigQueryAgentAnalyticsPlugin）を使用します。プラグインをエージェントに登録するだけで、BigQuery の Storage Write API を使用したイベントの記録と、イベント型ごとのビューの自動生成が行われます。

BigQuery に記録されたイベントにクエリを実行することで、トークン使用量の集計、ツール呼び出しの頻度分析、特定セッションのトレースなどを行うことができます。また、Conversational Analytics 機能を使用した自然言語での分析や、BigQuery ML や Looker / Data Studio（データポータル）による高度な分析、可視化も可能です。

BigQuery Agent Analytics を使用してエージェントのイベントを BigQuery にストリーミングする

当記事で使用するもの

Agent Development Kit（ADK）

Agent Development Kit（ADK）は、Google Cloud が提供する AI エージェント構築のためのオープンソース フレームワークであり、単純なタスクをこなすエージェントから複数のエージェントが協働する複雑なワークフローまで容易に実装できます。

ADK には、当記事で使用する BigQueryAgentAnalyticsPlugin のような、エージェントの振る舞いを拡張するためのプラグインが用意されており、エージェントのコードを大きく変更することなくロギング、トレーシングなどの機能を追加できます。

• 参考 : Agent Development Kit の概要
• 参考 : Plugins

Agent Runtime

Agent Runtime は AI エージェントの実行基盤を提供するフルマネージドサービスです。

Agent Runtime では、エージェントとのマルチターン会話を実現するための組み込みのセッション機能を利用することができるほか、エージェントの機能拡張に必要な様々な機能が提供されています。また、Agent Runtime のコンソールからチャット UI（Playground）で直接エージェントの動作確認を行うことができます。

Agent Runtime の詳細については、以下の記事をご一読ください。

blog.g-gen.co.jp

BigQuery

BigQuery は Google Cloud が提供するフルマネージドなサーバーレス データウェアハウスです。大量のデータを高速に分析できる SQL エンジンを備えており、Storage Write API を用いたストリーミング インサートによってリアルタイムにデータを書き込むこともできます。

当記事では、エージェントのイベントを格納する先として BigQuery を使用します。BigQuery Agent Analytics プラグインが内部で Storage Write API を利用してイベントを非同期にストリーミングするため、エージェントのパフォーマンスへの影響を抑えつつログを蓄積できます。

BigQuery の詳細については、以下の記事をご一読ください。

blog.g-gen.co.jp

• 参考 : BigQuery の概要
• 参考 : BigQuery Storage Write API の概要

BigQuery Agent Analytics について

概要

BigQuery Agent Analytics は、AI エージェントのインタラクション データをキャプチャ・分析・可視化するためのオープンソース ソリューションです。エージェントのリクエスト、レスポンス、ツール呼び出し、エラーなどのイベントを BigQuery テーブルに直接ストリーミングすることで、SQL や BigQuery ML での分析や、ダッシュボードでの可視化を可能にします。

当記事を執筆している2026年4月現在では、以下の2つのフレームワークに対応しています。

• Agent Development Kit（ADK）
• LangGraph（2026年4月現在ではプレビュー）

ADK では BigQueryAgentAnalyticsPlugin というプラグインが提供されており、これをエージェントに登録するだけで BigQuery に対するイベントのログストリーミングを有効化できます。プラグインには以下のような特徴があります。

• Storage Write API による高スループット・低遅延の非同期書き込み
• マルチモーダルのコンテンツ（テキスト / 画像 / 音声 / 動画）を記録可能（コンテンツの種類によっては Cloud Storage にオフロード）
• OpenTelemetry と統合された分散トレーシングにより trace_id、span_id による実行フローの可視化が可能
• ツールの呼び出し元（LOCAL / MCP / SUB_AGENT / A2A / TRANSFER_AGENT）を記録
• 新しいイベント型が追加された際に、既存テーブルに対して自動で列を追加

その他、詳細な仕様については、以下の公式ドキュメントを参照してください。

• 参考 : BigQuery Agent Analytics plugin for ADK
• 参考 : BigQuery エージェント分析を使用する

BigQuery に記録されるイベントについて

BigQuery に記録されるイベントは、大きく以下の5つのカテゴリに分類されます。

カテゴリ	イベント型	内容
LLM interactions	LLM_REQUEST / LLM_RESPONSE / LLM_ERROR	LLM へのプロンプト、モデル出力、エラーに関するイベント トークン使用量、生成にかかった時間なども記録される
Tool usage	TOOL_STARTING / TOOL_COMPLETED / TOOL_ERROR	ツール呼び出しの開始、完了、エラーに関するイベント ツールの呼び出し元（tool_origin）も記録される
State Management	STATE_DELTA	エージェントの内部状態の変更に関するイベント
Agent lifecycle & Generic Events	INVOCATION_STARTING / INVOCATION_COMPLETED / AGENT_STARTING / AGENT_COMPLETED / USER_MESSAGE_RECEIVED	エージェントの起動、実行完了、ユーザー入力の受信などのイベント
Human-in-the-Loop (HITL) Events	HITL_CREDENTIAL_REQUEST / HITL_CONFIRMATION_REQUEST / HITL_INPUT_REQUEST / 各イベントの _COMPLETED	ユーザー認証情報の要求、ユーザーへの確認要求、ユーザーからの入力要求などの割り込みイベント

これらのイベントはすべて agent_events という1つのテーブルにまとめて格納されますが、プラグインによって自動で生成されるビュー（v_llm_request、v_llm_response、v_tool_completed など）を使用することで、イベント型ごとに分析が可能です。

イベントのスキーマや詳細な内容については、以下の公式ドキュメントを参照してください。

• 参考 : BigQuery Agent Analytics plugin for ADK - Event types and payloads

エージェントの開発

ディレクトリ構成

当記事では、コーヒーに関する質問に回答する「コーヒーエージェント」を ADK で構築し、BigQueryAgentAnalyticsPlugin を組み込みます。ユーザーからの質問は、Google 検索を行うサブエージェントをツールとして持つエージェントが処理します。

最終的なディレクトリ構成は以下の通りになります。coffee_agent ディレクトリで AI エージェントを実装していきます。

.
├── coffee_agent
│   ├── agent.py
│   ├── .env
│   └── __init__.py
├── pyproject.toml  # 自動で作成
└── uv.lock  # 自動で作成

プロジェクトの準備

エージェント開発用のディレクトリでプロジェクトを初期化します。BigQueryAgentAnalyticsPlugin は google-adk をインストールするだけで併せて利用できます。

# uv プロジェクト初期化
$ uv init --no-readme
  
# パッケージの追加
$ uv add "google-adk>=1.29.0"

エージェント用のパッケージディレクトリ（coffee_agent）を作成し、ADK がエージェントのパッケージとして認識できるように __init__.py を配置します。

# エージェントのパッケージディレクトリを作成
$ mkdir coffee_agent
  
# __init__.py を作成
$ cat <<EOF > coffee_agent/__init__.py
from . import agent
EOF

エージェントのソースコード（agent.py）

エージェントのソースコードでは、以下のように BigQueryAgentAnalyticsPlugin を組み込んだエージェントを実装します。

• BigQueryAgentAnalyticsPlugin のインスタンスを作成し、ログの記録先となる BigQuery プロジェクト・データセット・ロケーションを指定
• root_agent をラップする App オブジェクトを作成し、plugins 引数にプラグインを登録

ポイントとして、このエージェントを adk deploy コマンドで Agent Runtime にデプロイする際に、root_agent ではなく App オブジェクト（app）をデプロイ対象として指定する必要があります（後述）。この App オブジェクトに plugins を登録しておくことで、デプロイ後のエージェントでプラグインが有効化されます。

import os
  
from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.plugins.bigquery_agent_analytics_plugin import (
    BigQueryAgentAnalyticsPlugin,
    BigQueryLoggerConfig,
)
from google.adk.tools import google_search
from google.adk.tools.agent_tool import AgentTool
  
  
PROJECT_ID = os.environ["GOOGLE_CLOUD_PROJECT"]
DATASET_ID = os.environ.get("BQ_DATASET", "agent_analytics")
BQ_LOCATION = os.environ.get("BQ_LOCATION", "asia-northeast1")
  
# BigQuery Agent Analytics プラグイン
bq_analytics_plugin = BigQueryAgentAnalyticsPlugin(
    project_id=PROJECT_ID,
    dataset_id=DATASET_ID,
    location=BQ_LOCATION,
    config=BigQueryLoggerConfig(
        batch_size=1,
        batch_flush_interval=0.5,
        log_session_metadata=True,
    ),
)
  
# Web 検索用サブエージェント
search_agent = Agent(
    name="search_agent",
    model="gemini-2.5-flash",
    description="Google検索でコーヒーに関する情報を調べるエージェント",
    instruction="ユーザーの質問に対してGoogle検索を使って情報を収集し、日本語で回答してください。",
    tools=[google_search],
)
  
# ルートエージェント
root_agent = Agent(
    name="coffee_agent",
    model="gemini-2.5-flash",
    description="コーヒーに関する情報を収集するエージェント",
    instruction="""あなたはコーヒーの専門家アシスタントです。
ユーザーからの質問に対して、search_agentを活用しながらコーヒーに関する正確で有益な情報を提供してください。
  
対応できるトピックの例:
- コーヒー豆の産地・品種・特徴
- 抽出方法（ドリップ、エスプレッソ、フレンチプレスなど）
- 焙煎度合いと味わいの違い
- カフェやコーヒーショップの情報
- コーヒーの健康効果や歴史
- ラテアートやバリスタの技術
  
回答は日本語で、わかりやすく丁寧に行ってください。""",
    tools=[AgentTool(agent=search_agent)],
)
  
# Agent Runtime デプロイ用 App (プラグインを登録)
app = App(
    name="coffee_agent",
    root_agent=root_agent,
    plugins=[bq_analytics_plugin],
)

また、BigQueryLoggerConfig では動作確認をしやすくするために、batch_size=1 / batch_flush_interval=0.5 を指定してイベントが即座に BigQuery へ書き込まれるようにしています。

BigQueryLoggerConfig では、このほかにもイベントの記録挙動を細かく制御できます。代表的なものを以下に挙げます。

パラメータ	デフォルト	説明
table_id	"agent_events"	イベントを格納する BigQuery テーブル ID
event_allowlist / event_denylist	None	記録する / 除外するイベント型のリスト
content_formatter	None	イベントの記録前にフォーマットを行うために使用する関数（参考）
gcs_bucket_name	None	マルチモーダル コンテンツをオフロードする Cloud Storage バケット
create_views	True	イベント型ごとのビューを作成するか
view_prefix	"v"	自動生成するビュー名のプレフィックス

• 参考 : BigQuery Agent Analytics plugin for ADK - Configuration options

Google Cloud 側の準備

BigQuery データセットの作成

プラグインがイベント記録用のテーブル（agent_events）とビュー（v_llm_request など）を自動で作成するため、あらかじめ格納先のデータセットのみ用意します。データセットのリージョンは、後述する Agent Runtime の稼働リージョンと一致させます。

# データセット ID とロケーションを環境変数にセット
$ PROJECT_ID=<プロジェクトID>
$ DATASET_ID=agent_analytics
$ BQ_LOCATION=asia-northeast1
  
# データセットの作成
$ bq --location=$BQ_LOCATION mk \
    --dataset \
    --description="BigQuery Agent Analytics for ADK" \
    $PROJECT_ID:$DATASET_ID

Agent Runtime サービスアカウントへの IAM 付与

Agent Runtime にデプロイしたエージェントから BigQuery に書き込みを行うために、Agent Runtime のサービスアカウント（service-<プロジェクト番号>@gcp-sa-aiplatform-re.iam.gserviceaccount.com）に対して以下のロールを付与します。

ロール	スコープ	用途
BigQuery ジョブユーザー（roles/bigquery.jobUser）	プロジェクト	BigQuery ジョブ（クエリ・書き込み）の実行
BigQuery データ編集者（roles/bigquery.dataEditor）	データセット	テーブル・ビューの作成、データの書き込み

最小権限の原則に従い、roles/bigquery.dataEditor はエージェント分析用のデータセットに対してのみ付与します。データセット単位の IAM は SQL の GRANT 文を使って付与します。

# プロジェクト番号の取得
$ PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')
  
# Agent Runtime 実行サービスアカウント
$ RE_SA="service-${PROJECT_NUMBER}@gcp-sa-aiplatform-re.iam.gserviceaccount.com"
  
# bigquery.jobUser はプロジェクトレベルで付与
$ gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member="serviceAccount:${RE_SA}" \
    --role="roles/bigquery.jobUser"
  
# bigquery.dataEditor はデータセットレベルで付与
$ bq query --use_legacy_sql=false \
"GRANT \`roles/bigquery.dataEditor\`
 ON SCHEMA \`${PROJECT_ID}\`.${DATASET_ID}
 TO 'serviceAccount:${RE_SA}'"

当記事では実施しませんが、マルチモーダル コンテンツを Cloud Storage にオフロードする場合は、対象バケットに対して Storage オブジェクト作成者（roles/storage.objectCreator）および Storage オブジェクト閲覧者（roles/storage.objectViewer）も付与します。

• 参考 : BigQuery Agent Analytics plugin for ADK - Prerequisites

ローカル認証

ローカルから adk web や adk deploy を実行する際の Google Cloud CLI の認証を行っておきます。

# 認証
$ gcloud auth login
$ gcloud auth application-default login
  
# プロジェクトの設定
$ gcloud config set project $PROJECT_ID

.env ファイルの作成

エージェントの実行時に Gemini Enterprise Agent Platform（旧称 : Vertex AI、以下 Agent Platform と記載）を利用するための環境変数を、coffee_agent ディレクトリ配下の .env ファイルに設定します。ADK は adk web や adk deploy の実行時にこのファイルを自動で読み込みます。

# coffee_agent/.env を作成
$ cat <<EOF > coffee_agent/.env
GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=$PROJECT_ID
GOOGLE_CLOUD_LOCATION=asia-northeast1
EOF

• GOOGLE_GENAI_USE_VERTEXAI: 1 を指定することで、Gemini API ではなく Agent Platform 経由で Gemini モデルを利用します
• GOOGLE_CLOUD_PROJECT: エージェントをデプロイする Google Cloud プロジェクト ID。agent.py で BigQuery 出力先プロジェクトとしても参照されます
• GOOGLE_CLOUD_LOCATION: Agent Runtime およびモデルを利用するリージョン

ローカルでの動作確認（ADK Web）

Agent Runtime へのデプロイ前に、ローカルで ADK Web UI を起動してエージェントの動作と BigQuery へのログ記録を確認します。

agent.py に app = App(...) を定義しておくと、root_agent ではなく app が自動検出され、plugins で指定されているプラグインを有効化した状態でエージェントが起動します。

# ADK Web UI の起動
$ uv run adk web

ブラウザで http://localhost:8000 を開き、チャット UI からエージェントに質問を送ってみます。

ADK Web UI からエージェントにメッセージを送信する

BigQuery コンソールで、agent_events テーブルが自動作成され、イベントが記録されていることを確認します。

SELECT timestamp, event_type, agent, content
FROM `<プロジェクトID>.agent_analytics.agent_events`
ORDER BY timestamp DESC
LIMIT 20;

エージェントの各種イベントが BigQuery テーブルに記録されている

USER_MESSAGE_RECEIVED、LLM_REQUEST、LLM_RESPONSE、AGENT_COMPLETED といったイベントが時系列で記録されていれば、プラグインが正しく動作しています。

また、agent_events テーブルとあわせて、イベント型ごとのビュー（v_llm_request、v_llm_response、v_tool_completed など）も自動で作成されており、こちらもデータセット内で確認できます。

イベント型ごとのビューが自動作成されている

• 参考 : ADK CLI documentation - web

Agent Runtime へのデプロイ

デプロイの実施

Agent Runtime にエージェントをデプロイします。プラグインを含めてデプロイするには、--adk_app_object オプションで App オブジェクトの変数名（ここでは app）を指定する必要があります。このオプションを指定しない場合、デフォルトでは root_agent がデプロイ対象となり、プラグインが適用されません。

# Agent Runtime にエージェントをデプロイ
$ uv run adk deploy agent_engine \
    --project=$PROJECT_ID \
    --region=asia-northeast1 \
    --display_name="Coffee Agent with BQ Analytics" \
    --adk_app_object=app \
    coffee_agent

• 参考 : ADK CLI documentation - deploy

動作確認

デプロイが完了したら、Agent Runtime のコンソール画面（https://console.cloud.google.com/vertex-ai/agents/agent-engines）でデプロイしたエージェントを選択し、チャット UI（Playground）で動作確認を行います。

コンソールのチャット UI で、コーヒーに関する質問を送信してみます。

Agent Runtime のコンソールからエージェントにメッセージを送信する

ローカル実行時と同様に、BigQuery の agent_events テーブルにイベントが記録されていることを確認します。

Agent Runtime にデプロイしたエージェントのイベントが記録されている

自動作成された v_llm_response ビューを使用して、LLM のトークン使用量を集計してみます。以下は全体の平均トークン数を確認するクエリです。

SELECT
  AVG(usage_total_tokens)      AS avg_tokens,
  AVG(usage_prompt_tokens)     AS avg_prompt,
  AVG(usage_completion_tokens) AS avg_completion
FROM `<プロジェクトID>.agent_analytics.v_llm_response`;

v_llm_response ビューから平均トークン数を集計する

公式ドキュメントにいくつかのクエリサンプルが紹介されているので、こちらも参照してください。

• 参考 : BigQuery Agent Analytics plugin for ADK - Advanced analysis queries

佐々木 駿太 (記事一覧)

G-gen 最北端、北海道在住のクラウドソリューション部エンジニア

2022年6月に G-gen にジョイン。Google Cloud Partner Top Engineer に選出（2024 / 2025 Fellow / 2026）。好きな Google Cloud プロダクトは Cloud Run。

趣味はコーヒー、小説（SF、ミステリ）、カラオケなど。

Follow @sasashun0805