BigQuery MCP を使用して Google トレンドアナリストエージェントを構築する

1. 概要

この Codelab では、Google ADK を使用して Google トレンドアナリストエージェントを構築します。このエージェントは、BigQuery MCP サーバーを活用して、Google トレンドの一般公開データセット（bigquery-public-data.google_trends）をクエリするツールを動的に検出して実行します。

学習内容

ADK 開発用にプロジェクトを設定する方法。
BigQuery 用のマネージド MCP サーバーを有効にして使用する方法。
MCP ツールを使用するエージェントを構築する方法。
テスト用にエージェントをローカルで実行する方法。
エージェントを Google Cloud Run にデプロイする方法。

必要なもの

課金を有効にした Google Cloud プロジェクト
ウェブブラウザ（Chrome など）
Python 3.11 以降

この Codelab は、Python と Google Cloud にある程度精通している中級レベルのデベロッパーを対象としています。

この Codelab を完了するには 15 ～ 20 分ほどかかります。

この Codelab で作成するリソースの費用は 5 ドル未満です。

2. 環境を設定する

Google Cloud プロジェクトの作成

Google Cloud コンソールのプロジェクトセレクタページで、Google Cloud プロジェクトを選択または作成します。
Cloud プロジェクトに対して課金が有効になっていることを確認します。プロジェクトで課金が有効になっているかどうかを確認する方法をご覧ください。

環境変数の設定

次の環境変数を設定します。

export GOOGLE_CLOUD_PROJECT=<INSERT_YOUR_GCP_PROJECT_HERE>
export GOOGLE_GENAI_USE_VERTEXAI=1

注: GOOGLE_GENAI_USE_VERTEXAI=1 を設定すると、ADK は Vertex AI を使用し、GEMINI_API_KEY の代わりに Cloud IAM を認証に使用します。

gcloud を認証して構成する

Google アカウントにログインし、アクティブなプロジェクトを設定して、アプリケーションのデフォルト認証情報を構成します。

gcloud auth login
gcloud auth application-default login

注: gcloud auth login は gcloud CLI コマンドを認証し、gcloud auth application-default login はローカルアプリケーションコードを認証します。

Google Cloud プロジェクトを設定します。

gcloud config set project ${GOOGLE_CLOUD_PROJECT}

必要な API を有効にする

Cloud Run、Artifact Registry、BigQuery、Vertex AI に必要な Google Cloud API を有効にします。

gcloud services enable run.googleapis.com \
                       cloudbuild.googleapis.com \
                       artifactregistry.googleapis.com \
                       bigquery.googleapis.com \
                       aiplatform.googleapis.com

BigQuery の MCP を有効にする

マネージド MCP サーバーは、プロジェクトで明示的に有効にする必要があります。

gcloud beta services mcp enable bigquery.googleapis.com

プロジェクトフォルダを作成する

まず、エージェントのルートフォルダと、エージェント実装用の内部フォルダを作成します。

mkdir google-trends-agent
cd google-trends-agent
mkdir google_trends

3. エージェントコードを作成する

google_trends/__init__.py という名前の空のファイルを作成します。

touch google_trends/__init__.py

次に、google_trends/agent.py という名前のファイルを作成し、次のコードを貼り付けます。

import os
import textwrap
import warnings
from datetime import date

import google.auth
from google.adk.agents import LlmAgent
from google.adk.apps import App
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
from google.auth.transport.requests import Request

# Suppress experimental ADK credential warnings
warnings.filterwarnings("ignore")

def get_agent_instruction(project_id: str) -> str:
    """Generates a clear and formatted prompt for the data analyst."""
    instruction = f"""
    # ROLE
    You are a Google Search Trends Analyst. Your mission is to provide clear answers using SQL data.

    # DATA CONSTRAINTS
    - BigQuery tool `execute_sql` requires explicit billing project mapping. Use: '{project_id}'.
    - Target dataset strictly: `bigquery-public-data.google_trends`

    # SCHEMA DISCOVERY (CRITICAL)
    1. DO NOT call `get_table_info` or `list_table_ids` (Triggers Permission Errors).
    2. Run `SELECT * FROM table LIMIT 0` via `execute_sql` for field definition mapping.

    # OUTPUT PRESENTATION
    - Render purely as a cleanly aligned Markdown table.
    - Use clear and descriptive headers for each column.
    - Remove conversational preambles. Output only the results.
    """
    return textwrap.dedent(instruction).strip()

def get_auth_headers() -> dict[str, str]:
    """Fetch auth headers for the project using Google Cloud Platform scopes."""
    credentials, _ = google.auth.default(
        scopes=["https://www.googleapis.com/auth/cloud-platform"]
    )
    request = Request()
    credentials.refresh(request)

    return {"Authorization": f"Bearer {credentials.token}"}

def get_todays_date() -> str:
    """Returns today's date in YYYY-MM-DD format."""
    return date.today().isoformat()

# --- Application Initialization ---
project_id = os.environ.get("GOOGLE_CLOUD_PROJECT")
if not project_id:
    raise ValueError("GOOGLE_CLOUD_PROJECT environment variable is not set")

mcp_headers = {
    "Content-Type": "application/json",
    "Accept": "application/json, text/event-stream",
} | get_auth_headers()

# Configure BigQuery Tools via MCP
bq_tools = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://bigquery.googleapis.com/mcp",
        headers=mcp_headers,
    )
)

# Initialize the LLM Agent
root_agent = LlmAgent(
    name="google_trends",
    model="gemini-3-flash-preview",
    tools=[get_todays_date, bq_tools],
    instruction=get_agent_instruction(project_id),
)

# Create the ADK App
app = App(name=root_agent.name, root_agent=root_agent)

4. エージェントを実行する

このステップでは、ローカルの Python 仮想環境を設定し、依存関係をインストールして、エージェントを実行してマシン（または Google Cloud Shell）での動作を確認します。

アプリケーションのルートディレクトリ（google-trends-agent）に移動します。
仮想環境を作成します。

python -m venv mcp_demo_env
source mcp_demo_env/bin/activate

必要な Python パッケージをインストールします。

pip install google-auth google-adk

ADK ウェブを使用して、新しいエージェントをテストします。

ローカルでの開発とテストの場合は、次のコマンドを実行します。

adk web

Google Cloud Shell 内で開発とテストを行うには、次のコマンドを実行します。

adk web --allow_origins="*"

これにより、ADK ウェブサーバーが起動します。ローカルウェブインターフェース（通常は http://localhost:8000）を使用してエージェントを操作できます。

注: より簡単な adk run google_trends コマンドを使用してエージェントをテストすることもできます。

5. Cloud Run にデプロイする

次の手順に沿って、エージェントを Google Cloud Run に安全にデプロイします。

権限の付与

Cloud Run には、Vertex AI にアクセスして BigQuery MCP ツールを使用する権限が必要です。

# Get your project number automatically
PROJECT_NUMBER=$(gcloud projects describe $GOOGLE_CLOUD_PROJECT --format='value(projectNumber)')

# Vertex AI Access: To talk to the Gemini model
gcloud projects add-iam-policy-binding ${GOOGLE_CLOUD_PROJECT} \
  --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
  --role="roles/aiplatform.user"

# MCP & BigQuery: To execute tools and run SQL jobs
gcloud projects add-iam-policy-binding ${GOOGLE_CLOUD_PROJECT} \
  --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
  --role="roles/mcp.toolUser"

gcloud projects add-iam-policy-binding ${GOOGLE_CLOUD_PROJECT} \
  --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
  --role="roles/bigquery.jobUser"

gcloud projects add-iam-policy-binding ${GOOGLE_CLOUD_PROJECT} \
  --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
  --role="roles/bigquery.dataViewer"

Dockerfile を作成する

プロジェクトのルート（google-trends-agent）に Dockerfile という名前のファイルを作成し、次の内容を貼り付けます。

FROM python:3.11-slim
WORKDIR /app

# Create a non-root user
RUN adduser --disabled-password --gecos "" myuser
USER myuser
ENV PATH="/home/myuser/.local/bin:$PATH"

# Copy the agent folder into the container
COPY --chown=myuser:myuser google_trends/ /app/agents/google_trends/

# Install the python packages
RUN pip install google-auth google-adk

# Set environment variables
ENV GOOGLE_GENAI_USE_VERTEXAI=1

# Expose port
EXPOSE 8080

# Run ADK web server
CMD ["adk", "web", "--port=8080", "--host=0.0.0.0", "/app/agents"]

エージェントをデプロイする

ルートディレクトリから次のコマンドを実行します。これにより、エージェントがコンテナ化され、Cloud Run にデプロイされます。

gcloud run deploy google-trends-agent \
  --source . \
  --region us-west1 \
  --allow-unauthenticated \
  --set-env-vars="GOOGLE_CLOUD_PROJECT=${GOOGLE_CLOUD_PROJECT}"

クイック確認

デプロイが完了すると、コンソールにサービス URL が出力されます。この URL をブラウザで開きます。ローカルで見たのと同じインタラクティブ UI が表示されますが、今度はクラウドで実行されています。

ログをモニタリングして、すべてがスムーズに実行されていることを確認することもできます。

gcloud logging read "resource.type=cloud_run_revision AND resource.labels.service_name=google-trends-agent" --limit 10

6. クリーンアップ

継続的な課金が発生しないようにするには、この Codelab で作成したリソースを削除します。

Cloud Run サービスを削除します。

gcloud run services delete google-trends-agent --region us-west1

この Codelab 専用のプロジェクトを作成した場合は、プロジェクト全体を削除できます。

gcloud projects delete ${GOOGLE_CLOUD_PROJECT}

この Codelab に関連するすべてのファイルを削除することもできます。

deactivate
cd ..
rm -rf google-trends-agent

7. 完了

おめでとうございます！Google トレンドアナリストエージェントを正常に構築してデプロイしました。

学習した内容

MCP を使用してエージェントの機能を動的に拡張する方法
Google ADK を使用して LLM エージェントを構築して提供する方法
Cloud Run でエージェントをデプロイしてスケーリングする方法

次のステップ

エージェントを変更して別の BigQuery データセットをクエリしてみる
エージェントの機能を拡張するために MCP ツールを追加する