【Google ADK】BigQueryを使って自然言語でデータ分析するAIエージェントを作ってみた

はじめに

こんにちは。
最近業務でADKでBigQueryを連携させたAIエージェントを構築し、便利だったので、みなさんに共有しようと思います。

ADKは、Googleが提供するオープンソースのAIエージェント開発フレームワークです。Pythonでは google-adk として提供されており、2026-03-31時点の最新安定版は1.28.0です。BigQuery連携には公式のBigQueryToolsetが用意されており、テーブル探索、テーブル情報取得、SQL実行、自然言語によるデータ問い合わせなどをエージェントに渡せます。

今回は、BigQueryの公開データセットbigquery-public-data.thelook_ecommerceを題材に、自然言語でBigQueryを読める最小構成のエージェントを作ります。the Look eCommerceはGoogle CloudのLookerサンプルでも使われている公開BigQueryデータセットです。

この記事でやること

この記事でやることは3つです。

• ADKをインストールする。
• BigQueryToolsetを組み込んだエージェントを作る。
• adk run で起動し、thelook_ecommerce に自然言語で質問する。

今回は公開データセットをそのまま使うため、自前のBigQueryテーブル作成やデータロードは行いません。BigQueryの公開データセットは、プロジェクトを作成または選択すれば利用できます。

今回使用予定のデータセットはこちら。

前提条件

事前に次の状態を用意しておきます。

• Google Cloudプロジェクトを選択または作成済みであること。
• 課金が有効であること。BigQueryの公開データセットは無料枠で試しやすいですが、今回はVertex AIのGeminiを使うため、プロジェクト側で課金とVertex AI APIの有効化が必要です。
• Cloud Shellを使えること。Cloud Shellでは gcloud などのツールがあらかじめ利用可能です。

1. Cloud Shell でプロジェクトと API を準備する

まずはGoogle Cloudコンソールにアクセスし、Cloud Shellを開きます。

Cloud Shellはブラウザから使えるGoogle Cloudのシェル環境です。
Cloud Shellはコンソールのホーム画面のこちらから開けます。

プロジェクIDはこちらから確認いただけます。

次に作業対象のプロジェクトを設定します。

gcloud config set project YOUR_PROJECT_ID

次に、BigQuery APIとVertex AI APIを有効化します。gcloud services enable でAPIを有効化できます。BigQuery APIのサービス名は bigquery.googleapis.com、Vertex AI APIのサービス名は aiplatform.googleapis.comです。

gcloud services enable bigquery.googleapis.com aiplatform.googleapis.com

補足
Cloud Shellを使う場合、Vertex AIのquickstartでは gcloud auth application-default login は不要と案内されています。ローカルマシンでは必要になることがありますが、Cloud Shellではこの手順を省略できます。

2. ADK プロジェクトを作る

ADKのPython quickstartでは、仮想環境を作って pip install google-adk する流れが案内されています。

mkdir adk-bigquery
cd adk-bigquery

python -m venv .venv
source .venv/bin/activate

pip install google-adk

エージェント用のディレクトリを作ります。ADKのquickstartに沿って、__init__.py、agent.py、.env を置く構成にします。

mkdir bigquery_agent
touch bigquery_agent/__init__.py
touch bigquery_agent/agent.py
touch bigquery_agent/.env

bigquery_agent/__init__.py は次の1行です。

from . import agent

.env にはVertex AIを使う設定を書きます。ADK quickstartでは、Vertex AI利用時にGOOGLE_GENAI_USE_VERTEXAI=TRUE、GOOGLE_CLOUD_PROJECT、GOOGLE_CLOUD_LOCATIONを設定する形が案内されています。

GOOGLE_GENAI_USE_VERTEXAI=TRUE
GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID
GOOGLE_CLOUD_LOCATION=global

3. BigQueryToolset を組み込んだエージェントを書く

BigQueryToolsetには、list_table_ids、get_table_info、execute_sql、ask_data_insights などのBigQuery向けツールが含まれています。最初はWriteMode.BLOCKEDを使って、読み取り専用で動かします。これは公式のBigQueryToolsetサンプルでも使われている構成です。

以下を bigquery_agent/agent.pyに保存します。
これは公式ドキュメントのBigQueryToolsetサンプルをベースに、今回のハンズオン向けに最小化したものです。

import google.auth

from google.adk.agents import Agent
from google.adk.tools.bigquery import BigQueryCredentialsConfig
from google.adk.tools.bigquery import BigQueryToolset
from google.adk.tools.bigquery.config import BigQueryToolConfig
from google.adk.tools.bigquery.config import WriteMode


credentials, project_id = google.auth.default()

credentials_config = BigQueryCredentialsConfig(
    credentials=credentials
)

tool_config = BigQueryToolConfig(
    write_mode=WriteMode.BLOCKED
)

bigquery_toolset = BigQueryToolset(
    credentials_config=credentials_config,
    bigquery_tool_config=tool_config
)

root_agent = Agent(
    name="bigquery_agent",
    model="gemini-3-flash-preview",
    description="BigQueryの公開データセットを探索し、SQLを実行して回答するエージェント",
    instruction=f"""
あなたはBigQueryのデータ分析を支援するAIエージェントです。
以下のルールで回答してください。

- 回答にはBigQueryのツールを使うこと
- まずは `bigquery-public-data.thelook_ecommerce`を対象にすること
- 必要に応じてテーブル一覧やテーブル情報を確認してからSQLを実行すること
- 推測ではなく、取得したデータに基づいて日本語で簡潔に答えること
- 書き込み操作は行わないこと

現在の実行プロジェクト: {project_id}
""",
    tools=[bigquery_toolset],
)

このコードのポイントは2つです。

• BigQueryへの接続にはADCを使っています。BigQueryToolsetのドキュメントでも、ローカル開発やCloud RunなどではADCが案内されています。
• WriteMode.BLOCKEDを設定しているため、まずは安全に「読むだけ」のエージェントとして始められます。

4. adk run で起動する

ADKではadk runでターミナル上でCLIベースでAgentの動作確認が可能です。

adk run bigquery_agent

※adk webを使ってみたのですが、どうもエラーになります。原因不明です。adk 1.26.0にもどすと問題なく動作します。

5. 動作確認

起動したら、まずはthelook_ecommerceを対象に、以下のようなプロンプトを試します。the Look eCommerceはECドメインの公開BigQueryデータセットで、顧客・商品・注文・物流・Webイベントなどのテーブルを含みます。

例1: テーブル一覧を確認する

bigquery-public-data.thelook_ecommerceにどんなテーブルがありますか？

回答はこちら。

BigQueryからデータセットを確認してみましたが、正しそうです。

例2: テーブル情報を確認する

ordersテーブルの主なカラムと意味を教えてください。

回答はこちら。

BigQueryからordersテーブルを確認してみましたが、こちらも正しそうです。

例3: SQL を伴う簡単な集計をさせる

注文数が多い商品カテゴリの上位5件を教えてください。

BigQueryでSQLクエリを実行しましたところ、同じ結果を得られました。

BigQueryToolsetには、テーブル一覧取得、テーブル情報取得、SQL実行、自然言語問い合わせのツールが含まれているため、こうした流れをエージェントに任せられます。

6. この時点で押さえておきたいこと

• 公開データセットを使う
  まずはデータ準備を省き、ADKとBigQueryToolsetの組み合わせに集中します。BigQueryの公開データセットは、選択したプロジェクトからそのまま利用できます。

• 読み取り専用で始める
  WriteMode.BLOCKED にしておくと、最初の検証で更新系の事故を避けやすくなります。

• まずは “テーブルを知る → SQLを実行する → 結果を要約する” 流れを作る
  いきなり複雑なマルチエージェントにせず、BigQueryをどう触らせるかを先に固めるほうが、後続のシリーズにもつながります。BigQueryToolsetにはそのための基本ツールがそろっています。

まとめ

今回は、ADK + BigQueryToolsetでBigQueryを自然言語で読める最小構成のAIエージェントを作りました。
題材には公開BigQueryデータセット bigquery-public-data.thelook_ecommerce を使い、Cloud Shell上で adk run を起動して確認する構成にしました。

今回は、公開データを使い、BigQueryToolsetの基本的な使い方を学んでもらいました。

構造化データを利用したAIエージェントの構築の一助になれば幸いです。