はじめに
株式会社ネクストスケープ Chief Technology Office所属の小野塚です。
Google の Agent Development Kit（ADK）と Vertex AI Agent Engine を使って、BigQuery のデータを自然言語で照会できるエージェントを作ってみました。
普段は Cursor や Claude Code を使っていて「AIエージェントを作る」ということ自体にピンときていなかったのですが、実際にやってみると「自分が使うツール」と「他の人が使える仕組みを作る」は全く別物だということがわかりました。
本記事では、環境構築からエージェント実装・動作確認までの過程と、そこで得られた気づきを共有します。
今回作ったもの
BigQuery に入っている店舗の売上データに対して、自然言語で照会・集計・分析ができるエージェントです。
例えば「東京の売上データを見せてください」と入力すると、エージェントが自動で BigQuery にクエリを投げ、結果を集計・分析して返してくれます。
構成・処理の流れは以下のようになります。
ユーザー
↓
自然言語で質問 ADK エージェント（Cloud Shell上でローカル実行）
↓
query_shop_sales / query_monthly_summary ツールを呼び出し BigQuery（sales_sample.shop_sales テーブル / v_monthly_shop_summary ビュー）
↓
クエリ結果を返す エージェントが結果を整形・分析してユーザーに回答
環境構築
使用した環境
・GCP プロジェクト：新規作成
・作業環境：Cloud Shell（ブラウザだけで完結）
・ADK バージョン：2.3.0
・Python：3.13
・Gemini モデル：gemini-2.5-flash
今回はGoogle Cloud Japan様 が公開している以下の内容を参考にしています。
上記リポジトリはADKのハンズオン資材で、step01〜step05 の段階的な構成でエージェントが実行できるようになっています。
セットアップ手順
まずは画面右上のCloudshellを起動するアイコンをクリックします。
すると以下のように画面下部にシェルが開きます。
シェルで以下のコマンドを実行していきます。
ーーー
#リポジトリをクローン
git clone https://github.com/google-cloud-japan/next-tokyo-assets.git
cd next-tokyo-assets/2025/adk-agentengine-basic
# Vertex AI API を有効化
gcloud services enable aiplatform.googleapis.com
# .env を設定（Vertex AI を使う設定に変更）
cat > .env << 'EOF'
GOOGLE_GENAI_USE_VERTEXAI=TRUE
GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_CLOUD_LOCATION=us-central1
EOF
# uv でライブラリインストール
curl -LsSf https://astral.sh/uv/install.sh | sh source $HOME/.local/bin/env && uv sync
ーーー
サンプルエージェントの実行
まず ADK の基本を理解するために step01 と step02 を動かしました。
uv run adk web .
上記コマンドを実行することでlocalhostでWebアプリが起動し、エージェントを実行できます。
step01：最もシンプルなエージェント
ブラウザでアプリを開き、step01 を選択すると、チャット画面が表示されます。
step01 はツールなしの基本エージェントで、Gemini の知識だけで回答します。Trace で処理フローを確認するとcall_llm、つまりAIモデルを使った問い合わせが1回だけ実行されます。
step02：fetch ツールを追加
step02 では URL を取得するfetchツールが追加されています。URL を含む質問を送ると、エージェントが自律的に fetch ツールを呼び出してページの内容を取得し、それをもとに回答を生成します。
Trace タブで処理の流れが確認できるのですが、Step01とStep02ではその違いが明確です：
step01: call_llm（1回だけ）
step02: call_llm → execute_tool fetch → call_llm（3段階）
エージェントが「fetch を使うかどうか」を自分で判断しているため、これを BigQuery に置き換えるだけで、自然言語でのデータ照会が実現できます。
逆に言えばこのfetchを使わなければ外部のサイトの情報取得はできないことになります。
他にもサンプルエージェントがあるのですが、一旦飛ばして本来の目的であるエージェントの作成へと進みます。
BigQuery サンプルデータの作成
まずはBigQuery上に東京・大阪・名古屋の3地域、仮想のカフェ・ベーカリー・レストランの店舗に関する2025年1〜3月の週次売上データを作成します。
あとは上記のデータに対する月次サマリーのビューも作成しました。BigQueryではクエリも作成・保存ができるのですが、ビューにしたのは理由がありまして別途後述します。
次にエージェントの実装ですが、フォルダ構成は以下のように非常にシンプルなものです。
my_bq_agent/
├── __init__.py
└── agent.py
agent.py の中身は大きく3つのパートに分かれます。
1. BigQuery クライアントの初期化
2. ツール関数の定義
エージェントが使う「手足」をPython関数として定義します。今回は2つ作りました。
・query_shop_sales：明細データの照会
・query_monthly_summary：ビュー経由の月次集計
ここが発見だったのですが、BigQuery の「保存済みクエリ」は API から呼び出すことができませんでした。一方、ビューは普通に SELECT できます。なのでビューにロジックを逃がして、エージェントのコードは「「 SELECT * FROM ビュー名」だけにしました。
3. エージェントの定義
では動作確認してみます。
ブラウザでアプリを開き、今回作成したエージェント「my_bq_agent」を選択します。
そして以下のプロンプトを投げます。
「東京の売上データを見せてください」
結果は以下の通り
聞いたのはこれだけです。エージェントが自律的に以下を返してくれました：
・東京地域の売上概要（総売上・総原価・総利益）
・店舗別売上（渋谷カフェ・新宿ベーカリー）
・カテゴリ別売上（カフェ・ベーカリー）
事前に「店舗別に分類して」「カテゴリで比較して」とプログラムしていないのに、自律的に分析してくれます。
「2025年1月の店舗別月次サマリーを見せてください」
ビュー経由のクエリもスムーズに動きました。エージェントが関数 query_monthly_summary を選択し、月次データを取得。さらに地域別・カテゴリ別のコメントまで自律的に生成してくれました。
得られた気づき
1. 「保存済みクエリ」は API から呼び出せない、「ビュー」は呼び出せる
BigQuery の保存済みクエリは Dataform で管理された GUI 上のテキストであり、API 経由で実行する仕組みがないとのこと。
一方、ビューはテーブルと同じように SELECT できるため、エージェントから直接呼び出せます。
そこで既存の複雑なSQLをビューに逃がしてしまえば、エージェント側のコードは 「 SELECT * FROM ビュー名 WHERE 条件 」だけで済みます。
2. SQLの骨格は人間が書く、条件の判断はAIが担う
AIエージェントにSQLを全部書かせることもできますが、ハルシネーションのリスクがあります。安全な設計は：
・SQLの骨格（FROM句・JOIN・集計ロジック）は人間が書く → 正しいデータが返る保証
・どの条件を使うか（WHERE句のパラメータ）はAIが判断 → 自然言語への柔軟な対応
3. データ取得は信頼できる、分析・推測は人間の確認が必要
どのAIを使っても必要な作業にはなりますが、AIの出力内容についてはそれぞれ確認が必要となります。
単純に実データ（レコード内容）やクエリ結果であれば確認する必要は無いのですが、分析結果のようにそこにAIの解釈が入る場合には確認が必要となります。
|
種類 |
信頼度 |
|---|---|
|
データ取得（件数・金額・日付） |
高い（人間が書いたSQLの実行結果） |
|
単純集計（合計・平均） |
高い（SQL集計関数の結果） |
|
分析コメント（「最も高い」「目立つ」） |
要確認（AIの解釈が入る） |
|
原因分析・予測 |
要確認（AIの解釈が入る） |
4. 「自分が使うAI」と「他の人が使えるAIを作る」は別物
Cursor や Claude Code は「自分が使うAI」で、ADK エージェントは「他の人が使える仕組みを作るAI」という理解です。
・Cursor / Claude Code → 開発者自身の作業を助ける → 毎回エンジニアが操作する
・ADK エージェント → 一度作れば誰でも自律的に使える → エンジニアがいなくても動く仕組み
5. 3層の独立した役割
このエージェントを今回のようなWebアプリやGemini Enterpriseで呼び出すようにした場合、以下のような3つの層で構成されることになります。
・AIモデル（Gemini 2.5 Flash等） → 何を答えるか（頭脳）
・ADK エージェント（Agent Engine） → どこからデータを取るか（手足）
・Webアプリ or Gemini Enterprise → 誰が使えるか（玄関）
「回答の精度を上げたい」→ モデルを変える。「別のデータも照会したい」→ ツールを追加する。「使える人を増やしたい」→ アクセス管理の話。それぞれ全く別の対応になります。
終わりに
ADK は急速に進化しており、本記事執筆時点（2026年6月）ではバージョン間の互換性に注意が必要ですが、BigQuery のデータを自然言語で照会できる仕組みを比較的少ないコードで実現できることは確認できました。
当社ネクストスケープはこのように生成AIをはじめとした新しい技術・知識を日々取り入れており、Webサイト、スマホアプリ、Hololensアプリの開発をはじめ、CMSを利用したサイトの新規構築やリニューアルなど、お客様のニーズに幅広く対応いたします。お困りのことがございましたら、いつでもお気軽にお問い合わせください。
（以下当社お問合せフォーム）
当社では一緒に働いてくれる仲間を募集しています。是非以下のサイトよりお申込みください。
