話しかけるだけでBigQueryを分析！Conversational Analytics APIと【agents-cli】で爆速構築する会話型データアシスタント

「BigQuery のデータを、SQL を書かずに自然言語でサクッと分析できたらいいのに…」と思ったことはありませんか？

Google Cloud の Conversational Analytics API（Geminidataanalytics） と、Google のエージェント開発ツール agents-cli (ADK) を組み合わせれば、驚くほど簡単に「自然言語でデータベースに問いかけて回答をくれる AI アシスタント」を構築できます。

この記事では、AI エージェント開発が初めての方に向けて、GCP コンソールでのデータエージェント接続設定から、ローカルでのエージェント新規作成フロー、Pythonコードの実装、動作確認手順までをわかりやすく解説します！

1. 全体像と仕組み

今回作成するシステムは、以下のような仕組みで動きます。

ユーザーが「先月の売上はどうだった？」と自然言語で質問します。
AIエージェント（agents-cli で動作）が質問を解釈し、APIを叩くツールを実行します。
Conversational Analytics API が、Google Cloud 上に構築された Data Agent を介して BigQuery や Looker のデータを検索・分析します。
AIエージェントが分析結果を受け取り、分かりやすい日本語にまとめてユーザーに回答します。

2. 【準備】Google Cloud 側の設定と接続

まずは、Google Cloud 上で API を有効化し、BigQuery などのデータベースと接続するための「データエージェント（Data Agent）」を作成します。

ステップ 2-1: API の有効化

ご利用の Google Cloud プロジェクトで、以下のコマンドを実行して API を有効化します。

gcloud services enable geminidataanalytics.googleapis.com --project=YOUR_PROJECT_ID

ステップ 2-2: Data Agent（データエージェント）の作成とデータソース接続

Google Cloud Console 上で、実際のデータベースとデータエージェントを接続します。

コンソールでサービスを開く
Google Cloud Console の検索窓で「bigquery」と検索し、BigQuery のページに移動しエージェントタブを選択します。

データエージェントの新規作成
「Create Agent (エージェントの作成)」ボタンをクリックします。

エージェントの各種設定
エージェント名とコンテキストの設定と接続したいリソースを選択します。　
「指示 (Instructions)」または「説明 (Description)」: 接続したデータセットにどのようなデータが含まれているか（例: 「このデータセットには、2025年以降の製品売上履歴とユーザー属性情報が含まれていま
す」）などを記入することでAIがテーブル構造を正しく理解しやすくなります。

 （参考）今回準備した BigQuery データ構成の例
   本記事のデモでは、以下の売上データが格納されたテーブルを BigQuery に準備して紐づけています。
   * **データセット名**: `analytics_sales_data`
   * **テーブル名**: `sales_records` (製品売上テーブル)
     * `order_id` (注文ID): STRING
     * `product_name` (商品名): STRING
     * `quantity` (数量): INTEGER
     * `unit_price` (単価): FLOAT
     * `order_date` (注文日): DATE
     * `region` (販売地域: `Tokyo`, `New York`, `London` など): STRING

プレビュー画面で動作確認
プレビュー画面でエージェントがどのような挙動をするか確認します。

エージェントのデプロイとID取得
作成ボタンを押し、デプロイが完了するのを待ちます。
デプロイ後、画面に表示されるエージェントIDを確認します。

このエージェントIDを使って接続をします。

3. 【開発】agents-cli を使ったエージェントの作成フロー

ここからは、実際にローカルPC上で AI エージェントを作成していきます。

💡 ポイント: エージェントコードは「自然言語」でAIに作らせる！
agents-cli を使った開発では、人間がすべての Python コードをゼロから手書きする必要はありません。
開発用の AI コーディングアシスタント（Gemini CLI や AI Agent）に対し、「Conversational Analytics API を呼び出してデータを日本語でまとめるエージェントを ADK で作って」 と自然言語で指示を出すだけで、以下のようなファイル作成やコードの実装をAIが自動で行ってくれます。

ステップ 3-1: プロジェクトの新規作成 (Scaffold)

agents-cli を使用して、エージェント開発に必要なベースファイルを自動生成（スキャフォールディング）します。

ここでは、① コマンド一発で作成する方法 と、② 対話型（インタラクティブ）で作成する方法 の2通りが選べます。

① コマンド一発で作成する場合

引数で名前やテンプレートをすべて指定して作成します。

agents-cli scaffold create my-data-agent --agent adk --prototype

※今回はローカルで構築する形を取るのでデプロイ先を指定せずに–prototypeを指定しています。
デプロイ先を指定する場合は以下のようになります。

agents-cli scaffold create my-data-agent --agent adk --deployment-target agent_runtime

一旦、prototypeで作成し後からデプロイ先を指定してデプロイすることも可能です。

agents-cli scaffold enhance . --deployment-target agent_runtime

② 対話型（インタラクティブ）で作成する場合

コマンドに --interactive（または -i）オプションを付けて実行すると、対話式で質問に答えながら作成できます。

agents-cli scaffold create --interactive

この場合、ターミナル上で「エージェント名は何にしますか？」「どのテンプレートを使用しますか？」「デプロイ先はどうしますか？」などの質問が自然言語で表示されます。初めてでコマンドのオプションが分からない場合は、この対話モードを使用するのが非常におすすめです。

コマンド実行後、以下のようなフォルダ・ファイル構成が自動生成されます。

my-data-agent/
├── app/                  # エージェントのソースコードを入れるフォルダ
│   ├── agent.py          # ★ここにメインのロジックや指示を記述します
│   └── tools.py          # ★API呼び出しなどのカスタムツールを記述します
├── .env                  # 環境変数の設定ファイル
└── pyproject.toml        # パッケージ管理ファイル

ステップ 3-2: 環境変数の設定

新しく作成されたプロジェクトのルートディレクトリにある .env ファイルに、先ほど取得した Google Cloud の接続情報を設定します。

# 接続先の Google Cloud プロジェクト ID
GEMINI_DATA_ANALYTICS_PROJECT="your-gcp-project-id"

# データエージェントがデプロイされているリージョン (通常は us-central1)
GEMINI_DATA_ANALYTICS_LOCATION="us-central1"

# 先ほど作成したデータエージェントの ID
GEMINI_DATA_ANALYTICS_AGENT_ID="sales-analysis-agent"

ステップ 3-3: 接続ツールの実装 (`app/tools.py`)

外部API（今回は GCP の Conversational Analytics API）を呼び出すカスタムツールを関数として定義します。AIアシスタントに指示を出すと、Python SDK (google-cloud-geminidataanalytics) を使用した以下のようなコードが自動生成されます。

import os
from google.cloud import geminidataanalytics_v1alpha

PROJECT_ID = os.getenv("GEMINI_DATA_ANALYTICS_PROJECT")
LOCATION = os.getenv("GEMINI_DATA_ANALYTICS_LOCATION", "us-central1")
AGENT_ID = os.getenv("GEMINI_DATA_ANALYTICS_AGENT_ID")

def query_conversational_analytics_api(message: str) -> dict:
    """Conversational Analytics APIを介してデータベースへ自然言語で問い合わせを行うツール。"""
    # 接続クライアントの初期化
    client = geminidataanalytics_v1alpha.DataChatServiceClient()

    # リソースパスの設定
    agent_path = f"projects/{PROJECT_ID}/locations/{LOCATION}/dataAgents/{AGENT_ID}"
    parent_path = f"projects/{PROJECT_ID}/locations/{LOCATION}"

    # リクエスト構造の組み立て
    user_msg = geminidataanalytics_v1alpha.UserMessage(text=message)
    msg = geminidataanalytics_v1alpha.Message(user_message=user_msg)
    data_agent_context = geminidataanalytics_v1alpha.DataAgentContext(data_agent=agent_path)

    request = geminidataanalytics_v1alpha.ChatRequest(
        parent=parent_path, messages=[msg], data_agent_context=data_agent_context
    )

    # API呼び出し
    response_stream = client.chat(request=request)

    # 結果のパース処理をして返却
    response_texts = [msg.system_message.text for msg in response_stream if msg.system_message]
    return {"status": "success", "response_text": "".join(response_texts)}

ステップ 3-4: エージェントの定義と指示の記述 (`app/agent.py`)

作成した接続ツールを AI モデルに紐づけ、エージェントとしての動作方針（システムプロンプト）を設定します。こちらもAIに任せることで、適切なプロンプトやインポート文が含まれたファイルが自動でできあがります。

from google.adk.agents import LlmAgent
from google.adk.apps import App
from google.adk.models import Gemini
from app.tools import query_conversational_analytics_api

# 1. 使用する AI モデルの定義
model = Gemini(model="gemini-flash-latest")

# 2. システムプロンプト（指示文）の定義
SYSTEM_INSTRUCTION = """
あなたは Conversational Analytics API のゲートウェイエージェントです。
ユーザーから売上やデータベースのデータに関する質問があった場合、
必ず `query_conversational_analytics_api` ツールを実行して結果を取得し、
分かりやすい日本語にまとめて回答してください。
"""

# 3. エージェントの作成 (モデル、指示、ツールをバインド)
root_agent = LlmAgent(
    name="data_gateway_agent",
    model=model,
    instruction=SYSTEM_INSTRUCTION,
    tools=[query_conversational_analytics_api],
)

# 4. エージェントをアプリケーションとしてラップ
app = App(
    root_agent=root_agent,
    name="app",
)

4. 【実践】agents-cli を使ってエージェントを動かす

コードの実装が完了したら、agents-cli を使って実際に動作確認を行います。

ステップ 4-1: 依存関係のインストール

プロジェクトのディレクトリで以下のコマンドを実行し、記述したコードに必要なライブラリを自動インストールします。

agents-cli install

ステップ 4-2: Playground（対話型 Web 画面）を起動する

以下のコマンドを実行すると、ブラウザ上でエージェントとチャットができるローカル開発サーバーが起動します。

agents-cli playground

コマンド実行後、画面に表示される URL（例: `http://localhost:8000`）にアクセスすると、美しいチャット画面が表示されます。ここでデータベースに関する質問を入力してテストを行います。

このような画面が表示されます。

質問を入れてみるとデータを分析して結果を返してくれます。

データをもとに次のアクションなども提案してくれます。

ステップ 4-3: CLI から直接テストする

コマンドラインから素早く動作確認をしたい場合は、以下のコマンドを実行します。

agents-cli run "製品別の売上データを出して"

このようなにコマンドラインベースでも確認することが可能です

5. まとめ

agents-cli と Conversational Analytics API を使うことで、プロジェクトの立ち上げからプロンプトの調整、コード実装、ローカルテストまでの一連の開発を極めてスムーズに進めることができました。

データベースの構造や複雑な SQL の知識がない現場のメンバーでも、自然言語で安全にデータを探索できるようになります。ぜひ社内のデータ活用や DX 推進に役立ててみてください！

話しかけるだけでBigQueryを分析！Conversational Analytics APIと【agents-cli】で爆速構築する会話型データアシスタント

1. 全体像と仕組み

2. 【準備】Google Cloud 側の設定と接続

ステップ 2-1: API の有効化

ステップ 2-2: Data Agent（データエージェント）の作成とデータソース接続

3. 【開発】agents-cli を使ったエージェントの作成フロー

ステップ 3-1: プロジェクトの新規作成 (Scaffold)

① コマンド一発で作成する場合

② 対話型（インタラクティブ）で作成する場合

ステップ 3-2: 環境変数の設定

ステップ 3-3: 接続ツールの実装 (`app/tools.py`)

ステップ 3-4: エージェントの定義と指示の記述 (`app/agent.py`)

4. 【実践】agents-cli を使ってエージェントを動かす

ステップ 4-1: 依存関係のインストール

ステップ 4-2: Playground（対話型 Web 画面）を起動する

ステップ 4-3: CLI から直接テストする

5. まとめ

ウワサのClaude Design、使ってみた

Python × Ollama x Gemma4：ローカルLLMで業務を自動化する

Figma Makeとは？徹底解説します！

AI駆動開発の第一歩！エクセル設計書を「AIが読める」マークダウンに変換する最強プロンプト術

Claude Code の精度90%では、私が満足できなかった理由

話しかけるだけでBigQueryを分析！Conversational Analytics APIと【agents-cli】で爆速構築する会話型データアシスタント

1. 全体像と仕組み

2. 【準備】Google Cloud 側の設定と接続

ステップ 2-1: API の有効化

ステップ 2-2: Data Agent（データエージェント）の作成とデータソース接続

3. 【開発】agents-cli を使ったエージェントの作成フロー

ステップ 3-1: プロジェクトの新規作成 (Scaffold)

① コマンド一発で作成する場合

② 対話型（インタラクティブ）で作成する場合

ステップ 3-2: 環境変数の設定

ステップ 3-3: 接続ツールの実装 (app/tools.py)

ステップ 3-4: エージェントの定義と指示の記述 (app/agent.py)

4. 【実践】agents-cli を使ってエージェントを動かす

ステップ 4-1: 依存関係のインストール

ステップ 4-2: Playground（対話型 Web 画面）を起動する

ステップ 4-3: CLI から直接テストする

5. まとめ

関連記事Related Articles

ADK マルチエージェントを BigQuery と連携させる

Gen AI evaluation service で ADK マルチエージェントの応答品質を測る

オーケーアプリ事例に関する技術解説（構成について）

BigQueryに大幅アップデート！コスト最適化の可能性あり

Cloud StorageへのCSVファイル配置をトリガーにNode.jsでBigQueryに書き込む⽅法

ステップ 3-3: 接続ツールの実装 (`app/tools.py`)

ステップ 3-4: エージェントの定義と指示の記述 (`app/agent.py`)