株式会社G-gen の技術ブログ

全808件

2026/04/17

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

G-gen の佐々木です。当記事では、ADK で開発した AI エージェントに BigQuery Agent Analytics のプラグインを組み込むことで、エージェントのリクエストやレスポンス、ツール呼び出しなどのイベントを BigQuery に記録し、SQL で分析できるようにしていきます。構成当記事で使用するもの Agent Development Kit（ADK） Agent Runtime BigQuery BigQuery Agent Analytics について概要 BigQuery に記録されるイベントについてエージェントの開発ディレクトリ構成プロジェクトの準備エージェントのソースコード（agent.py） Google Cloud 側の準備 BigQuery データセットの作成 Agent Runtime サービスアカウントへの IAM 付与ローカル認証 .env ファイルの作成ローカルでの動作確認（ADK Web） Agent Runtime へのデプロイデプロイの実施動作確認構成当記事では、 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