Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

Cloud Run で Gemini と BigQuery MCP サーバーを使用して AI エージェントを構築してデプロイする

1. はじめに

学習内容

Agent Platform の Gemini で Agent Development Kit（ADK）を使用して AI エージェントを作成する方法。
BigQuery MCP サーバーを使用して、BigQuery の構造化データに AI エージェントがアクセスできるようにする方法。

Cloud Run は、基盤となるインフラストラクチャを管理することなく、コンテナ化されたアプリケーションとサービスを実行できるフルマネージドのサーバーレスコンピューティングプラットフォームです。

Agent Development Kit（ADK）は、エンタープライズ規模で信頼性の高い AI エージェントを構築、デバッグ、デプロイできるオープンソースのエージェント開発フレームワークです。

BigQuery は、大規模なデータセットの保存、クエリ、分析を可能にする、フルマネージドのサーバーレスエンタープライズデータウェアハウスです。

Model Context Protocol（MCP）により、大規模言語モデル（LLM）と AI アプリケーション（エージェント）が外部のデータソースに接続する方法が標準化されます。MCP サーバーを使用すると、そのツール、リソース、プロンプトを使用してアクションを実行し、バックエンドサービスから更新されたデータを取得できます。BigQuery MCP サーバーを使用すると、AI エージェントが BigQuery のデータを直接かつ安全に分析できます。このフルマネージド MCP サーバーを使うと、管理上のオーバーヘッドが削減され、インテリジェントエージェントの開発に集中できるようになります。

2. 設定と要件

まず、デフォルトのプロジェクトと Cloud Run リージョンを設定します。

# set the project
gcloud config set project YOUR_PROJECT_ID

YOUR_PROJECT_ID は、Google Cloud プロジェクト ID に置き換えます。

# set Cloud Run region
gcloud config set run/region CLOUD-RUN-REGION

CLOUD-RUN-REGION は、Cloud Run でサポートされているリージョンのいずれかに置き換えます。

この Codelab 全体で使用する環境変数は次のとおりです。これらは環境ファイルに保存して「ソース」にすることができます。プロジェクト ID の値と、必要に応じてリージョンを正しく設定してください。

# Cloud Project Id and Cloud Run region
export GOOGLE_CLOUD_PROJECT="${GOOGLE_CLOUD_PROJECT:-$(gcloud config get-value project -q)}"
export GOOGLE_CLOUD_REGION="${GOOGLE_CLOUD_REGION:-$(CR_REGION=$(gcloud config get-value run/region -q 2>/dev/null); echo "${CR_REGION:-us-central1}")}"
# Gemini API in Agent Platform
export GOOGLE_GENAI_USE_ENTERPRISE="True" # Use Agent Platform
export GOOGLE_CLOUD_LOCATION="global" # Use global Gemini API endpoint

この Codelab で必要な API を有効にします。API の変更が有効になるまで 2 ～ 3 分かかることがあります。

gcloud services enable --project "${GOOGLE_CLOUD_PROJECT}" \
    run.googleapis.com \
    cloudbuild.googleapis.com \
    artifactregistry.googleapis.com \
    bigquery.googleapis.com \
    aiplatform.googleapis.com

3. Agent Development Kit を使用してデータエージェントを作成する

エージェントのコードを記述する

Cloud Shell ターミナルまたはローカルターミナルで、エージェントアプリのルートディレクトリを作成します。

mkdir data_agent

Cloud Shell エディタまたは別のテキストエディタを開き、data_agent ディレクトリに agent.py を作成します。

data_agent/
    agent.py

agent.py

import os

from google.adk.agents import LlmAgent
from google.adk.tools.mcp_tool.mcp_toolset import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams

import google.auth
from google.auth.transport.requests import Request

# Fetch Application Default Credentials (ADC)
# to use as agent's own identity for accessing BigQuery MCP Server
_application_default_credentials, project_id = google.auth.default()
_request = Request()
_application_default_credentials.refresh(_request)

# Retrieve Google Cloud project to use.
project_id = os.getenv("GOOGLE_CLOUD_PROJECT", project_id)
if not project_id:
    raise ValueError("GOOGLE_CLOUD_PROJECT environment variable is not set.")

# Builds authentication headers for MCP Server requests,
# and refreshes credentials if needed.
def _adc_auth_header_provider(context = None) -> dict[str, str]:
    if not _application_default_credentials.valid:
        _application_default_credentials.refresh(_request)

    return {
        "Authorization": f"Bearer {_application_default_credentials.token}",
        "x-goog-user-project": project_id
    }

# Initialize the MCP Toolset with the connection parameters
bigquery_toolset = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://bigquery.googleapis.com/mcp",
        tool_filter=[
            'get_dataset_info',
            'list_table_ids',
            'get_table_info',
            # Using readonly is a security measure to prevent accidental data modification.
            'execute_sql_readonly',
        ]
    ),
    header_provider=_adc_auth_header_provider # Auth header provider function
)

# Configure the agent

system_instruction = f"""
You are a helpful assistant that can answer questions about data in BigQuery.
To answer the user's question, use data you have access to by using tools `list_table_ids` and `get_table_info`.
Your data is in `bigquery-public-data.new_york_citibike` dataset (Citi Bike trips and stations in the NYC area.)

Plan of action:
0. ALWAYS start by analyzing dataset.
1. Analyze your data, investigate schema and dimensions by querying distrinct values of columns using `execute_sql_readonly`.
   Output information about tables, columns, their data types and sets of values (for dimensions).
   Note which columns can be joined or used in aggregations/filters, and what type conversion may be needed for joining or aggregating.
   DO NOT MAKE ASSUMPTIONS ABOUT DATA (structure, type, values, relationships) BASED ON YOUR PRIOR KNOWLEDGE. ALWAYS VERIFY YOUR ASSUMPTIONS.
2. Understand and interpret the user's question.
3. Formulate a plan to answer the user's question.
4. Write a SQL query to retrieve relevant data in necessary form.
   This is where you must pay extra attention to column types and dimensions' sets of values.
5. Retrieve data by generating BigQuery SQL and using `execute_sql_readonly`.
   Always use Dry Run to verify SQL correctness.
   Use `{project_id}` to run BigQuery queries (`project_id` parameter of `execute_sql_readonly`).

Do not use LaTeX in your responses. When giving a final answer, use Markdown.
"""

root_agent = LlmAgent(
    model="gemini-3.6-flash",
    name="data_agent",
    instruction=system_instruction,
    description="A helpful assistant that can answer questions using NYC Citibike data.",
    tools=[bigquery_toolset]
)

ADK のデプロイには __init__.py と requirements.txt も必要です。

__init__.py にはエージェントのインポートが必要です。
requirements.txt リストの Python 依存関係: Agent Development Kit の場合は google-adk、Model Context Protocol クライアントの場合は mcp。

これらのコマンドは、__init__.py と requirements.txt の作成に役立ちます。

echo "from . import agent" > data_agent/__init__.py
echo -e "google-adk==2.4.*\nmcp==1.29.*" > data_agent/requirements.txt

最終的なフォルダ構造は次のようになります。

data_agent/
    __init__.py
    agent.py
    requirements.txt

ローカルでエージェントを試す

Agent Development Kit には、エージェントをテストするためのインタラクティブなターミナルインターフェースである adk CLI ツールが付属しています。これは、簡単なテスト、スクリプト化されたインタラクション、CI/CD パイプラインに便利です。この機能の 1 つが adk web - ADK ウェブインターフェースです。これは、エージェントをインタラクティブに開発してデバッグするための簡単な方法です。ADK Web は本番環境でのデプロイを想定していませんが、エージェントを簡単に試すことができます。

このコマンドは、ポート 8080 でローカルウェブサーバーを起動する adk web を起動します。

uv tool run --with "mcp==1.29.*" --from "google-adk[mcp]==2.4.*" adk web --allow_origins="*" --port 8080 .

サービスが起動したら、ローカル ADK ウェブページ（http://localhost:8080/）を開きます。

Google Cloud Shell を使用している場合は、[ウェブでプレビュー] ボタンをクリックし、[ポート 8080 でプレビュー] メニュー項目を選択します。

ADK ウェブ UI で、エージェントにアクセスできるデータについて質問します。

What data do you have?

エージェントは BigQuery MCP ツールを使用して、citibike データセットを探索します。これにより、Citibike データセットで使用可能なテーブルとフィールドの概要が表示されます。

4. Cloud Run にエージェントをデプロイする

このコマンドは、ADK CLI を使用してエージェントを Cloud Run にデプロイします。

uv tool run --from google-adk==2.4.0 \
  adk deploy cloud_run \
      --with_ui \
      --project $GOOGLE_CLOUD_PROJECT \
      --region $GOOGLE_CLOUD_REGION \
      --service_name bq-data-agent \
      --app_name data_agent \
      data_agent \
      -- \
      --allow-unauthenticated \
      --max-instances 1 \
      --set-env-vars GOOGLE_GENAI_USE_ENTERPRISE=True,GOOGLE_CLOUD_PROJECT="${GOOGLE_CLOUD_PROJECT},GOOGLE_CLOUD_LOCATION=${GOOGLE_CLOUD_LOCATION}"

エージェントを試す

エージェントのデプロイには --with_ui オプションを使用しました。ADK ウェブインターフェースを使用してエージェントをデプロイしました。

ウェブブラウザでエージェントの URL を開きます。adk deploy コマンドで返されます。また、gcloud run services コマンドを実行して URL を取得することもできます。

gcloud run services describe bq-data-agent \
  --project $GOOGLE_CLOUD_PROJECT \
  --region $GOOGLE_CLOUD_REGION \
  --format 'value(status.url)'

エージェントに、利用可能な Citibike データについて推論するよう依頼します。

We have budget for 3 coffee trucks.
We want to find the best city bike stations to place our coffee trucks.

エージェントは、BigQuery MCP サーバーを使用して Citibike データセットを探索し、いくつかの SQL クエリを実行して、3 つの Citibike ステーションのリストを返す必要があります。

5. 完了

以上で、この Codelab は完了です。

Cloud Run のドキュメントを確認することをおすすめします。

学習した内容

Agent Development Kit と Gemini を使用して AI エージェントを作成する方法
エージェントを BigQuery MCP サーバーに接続する方法。
エージェントを Cloud Run にデプロイする方法。

6. クリーンアップ

このチュートリアルで使用したリソースについて、Google Cloud アカウントに課金されないようにするには、プロジェクトを削除するか、個々のリソースを削除します。

オプション 1: Service を削除する

Cloud Run サービスを削除する

gcloud run services delete bq-data-agent \
      --project "${GOOGLE_CLOUD_PROJECT}" \
      --region "${GOOGLE_CLOUD_REGION}" \
      --quiet

オプション 2: プロジェクトを削除する

プロジェクト全体を削除するには、[リソースの管理] に移動し、ステップ 2 で作成したプロジェクトを選択して、[削除] を選択します。プロジェクトを削除した場合は、Cloud SDK でプロジェクトを変更する必要があります。gcloud projects list を実行すると、使用可能なすべてのプロジェクトのリストを表示できます。コマンドラインを使用する場合は、次のコマンドも使用できます。

gcloud projects delete ${GOOGLE_CLOUD_PROJECT}