1. はじめに
この Codelab では、データベース向け MCP ツールボックスを利用する Agent Development Kit（ADK）を使用してエージェントを構築します。
この Codelab では、次の手順でアプローチします。
- ホテル データベースとサンプルデータを含む Cloud SQL for PostgreSQL データベースをプロビジョニングします。
- データへのアクセスを提供するデータベース向け MCP ツールボックスを設定します。
- Agent Development Kit（ADK）を使用して、MCP ツールボックスを利用してユーザーからのクエリに回答するエージェントを設計、開発する。
- Cloud Run サービスを介して、エージェントとデータベース向け MCP ツールボックスをローカルと Google Cloud でテストするオプションについて説明します。
演習内容
- 特定の地域のホテルに関するユーザーのクエリに回答したり、名前でホテルを検索したりするエージェントを設計、構築、デプロイします。
学習内容
- Cloud SQL for PostgreSQL データベースのプロビジョニングとサンプルデータの入力。
- Cloud SQL for PostgreSQL データベース インスタンス用にデータベース向け MCP ツールボックス を設定します。
- Agent Development Kit（ADK）を使用して、ユーザーのクエリに回答するエージェントを設計して開発します。
- ローカル環境でエージェントとデータベース向け MCP ツールボックスをテストします。
- （省略可）Google Cloud に Agent とデータベース向け MCP ツールボックスをデプロイします。
必要なもの
- Chrome ウェブブラウザ
- Gmail アカウント
- 課金が有効になっている Cloud プロジェクト
この Codelab は、初心者を含むあらゆるレベルのデベロッパーを対象としており、サンプル アプリケーションで Python を使用します。ただし、Python の知識は必要ありません。基本的なコードの読み取り能力があれば、提示されたコンセプトを理解するのに十分です。
2. 始める前に
プロジェクトを作成する
- Google Cloud コンソールのプロジェクト選択ページで、Google Cloud プロジェクトを選択または作成します。
- Cloud プロジェクトに対して課金が有効になっていることを確認します。詳しくは、プロジェクトで課金が有効になっているかどうかを確認する方法をご覧ください。
- Cloud Shell（Google Cloud で動作するコマンドライン環境）を使用します。この環境には bq がプリロードされています。Google Cloud コンソールの上部にある [Cloud Shell をアクティブにする] をクリックします。
![[Cloud Shell をアクティブにする] ボタンの画像](https://codelabs.developers.google.com/static/travel-agent-mcp-toolbox-adk/img/91567e2f55467574.png?hl=ja)
- Cloud Shell に接続したら、次のコマンドを使用して、すでに認証済みであることと、プロジェクトがプロジェクト ID に設定されていることを確認します。
gcloud auth list
- Cloud Shell で次のコマンドを実行して、gcloud コマンドがプロジェクトを認識していることを確認します。
gcloud config list project
- プロジェクトが設定されていない場合は、次のコマンドを使用して設定します。
gcloud config set project <YOUR_PROJECT_ID>
- 次のコマンドを使用して、必要な API を有効にします。この処理には数分かかることがあります。
gcloud services enable cloudresourcemanager.googleapis.com \
servicenetworking.googleapis.com \
run.googleapis.com \
cloudbuild.googleapis.com \
cloudfunctions.googleapis.com \
aiplatform.googleapis.com \
sqladmin.googleapis.com \
compute.googleapis.com
コマンドが正常に実行されると、次のようなメッセージが表示されます。
Operation "operations/..." finished successfully.
gcloud コマンドの代わりに、コンソールで各プロダクトを検索するか、こちらのリンクを使用します。
API が見つからない場合は、実装中にいつでも有効にできます。
gcloud コマンドとその使用方法については、ドキュメントをご覧ください。
3. Cloud SQL インスタンスを作成する
ホテルのデータを保存するために、Google Cloud SQL for PostgreSQL インスタンスを使用します。Cloud SQL for PostgreSQL は、Google Cloud Platform 上のフルマネージド データベース サービスで、PostgreSQL リレーショナル データベースの設定、維持、管理、運営に役立ちます。
Cloud Shell で次のコマンドを実行して、インスタンスを作成します。
gcloud sql instances create hoteldb-instance \
--database-version=POSTGRES_15 \
--tier db-g1-small \
--region=us-central1 \
--edition=ENTERPRISE \
--root-password=postgres
このコマンドの実行には 3 ～ 5 分ほどかかります。コマンドが正常に実行されると、コマンドが完了したことを示す出力と、NAME、DATABASE_VERSION、LOCATION などの Cloud SQL インスタンス情報が表示されます。
4. ホテル データベースを準備する
ここからは、ホテル エージェントのサンプルデータを作成します。
Cloud コンソールの Cloud SQL ページにアクセスします。hoteldb-instance が準備完了して作成されていることを確認します。次の図に示すように、インスタンスの名前（hoteldb-instance）をクリックします。
Cloud SQL の左側のメニューで、次のように Cloud SQL Studio メニュー オプションに移動します。
Cloud SQL Studio へのログインが求められます。ここで、いくつかの SQL コマンドを実行します。[Database option] に postgres を選択し、[User] と [Password] の両方に postgres を使用します。AUTHENTICATE をクリックします。
まず、次のスキーマに従ってホテル テーブルを作成します。Cloud SQL Studio のいずれかのエディタ ペインで、次の SQL を実行します。
CREATE TABLE hotels(
id INTEGER NOT NULL PRIMARY KEY,
name VARCHAR NOT NULL,
location VARCHAR NOT NULL,
price_tier VARCHAR NOT NULL,
checkin_date DATE NOT NULL,
checkout_date DATE NOT NULL,
booked BIT NOT NULL
);
次に、hotels テーブルにサンプルデータを入力します。次の SQL を実行します。
INSERT INTO hotels(id, name, location, price_tier, checkin_date, checkout_date, booked)
VALUES
(1, 'Hilton Basel', 'Basel', 'Luxury', '2024-04-20', '2024-04-22', B'0'),
(2, 'Marriott Zurich', 'Zurich', 'Upscale', '2024-04-14', '2024-04-21', B'0'),
(3, 'Hyatt Regency Basel', 'Basel', 'Upper Upscale', '2024-04-02', '2024-04-20', B'0'),
(4, 'Radisson Blu Lucerne', 'Lucerne', 'Midscale', '2024-04-05', '2024-04-24', B'0'),
(5, 'Best Western Bern', 'Bern', 'Upper Midscale', '2024-04-01', '2024-04-23', B'0'),
(6, 'InterContinental Geneva', 'Geneva', 'Luxury', '2024-04-23', '2024-04-28', B'0'),
(7, 'Sheraton Zurich', 'Zurich', 'Upper Upscale', '2024-04-02', '2024-04-27', B'0'),
(8, 'Holiday Inn Basel', 'Basel', 'Upper Midscale', '2024-04-09', '2024-04-24', B'0'),
(9, 'Courtyard Zurich', 'Zurich', 'Upscale', '2024-04-03', '2024-04-13', B'0'),
(10, 'Comfort Inn Bern', 'Bern', 'Midscale', '2024-04-04', '2024-04-16', B'0');
次の SELECT SQL を実行して、データを検証しましょう。
SELECT * FROM hotels;
次のように、hotels テーブルにレコード数が表示されます。
これで、Cloud SQL インスタンスの設定プロセスが完了し、サンプルデータが作成されました。次のセクションでは、データベース向け MCP ツールボックスを設定します。
5. データベース向け MCP ツールボックスを設定する
データベース向け MCP ツールボックスは、データベース用のオープンソース MCP サーバーです。エンタープライズ グレードと本番環境品質を念頭に置いて設計されています。これにより、接続プーリングや認証などの複雑な処理に対応して、ツールの開発をより簡単、迅速、セキュアに行うことができます。
ツールボックスは、エージェントがデータベース内のデータにアクセスできるようにする生成 AI ツールの構築に役立ちます。Toolbox には次の機能があります。
- 開発の簡素化: 10 行未満のコードでツールをエージェントに統合し、複数のエージェントまたはフレームワーク間でツールを再利用し、ツールの新しいバージョンをより簡単にデプロイできます。
- パフォーマンスの向上: 接続プーリングや認証などのベスト プラクティス。
- セキュリティの強化: 統合認証によるデータへのより安全なアクセス
- エンドツーエンドのオブザーバビリティ: OpenTelemetry のサポートが組み込まれた、すぐに使用できる指標とトレース。
ツールボックスは、アプリケーションのオーケストレーション フレームワークとデータベースの間に配置され、ツールの変更、配布、呼び出しに使用されるコントロール プレーンを提供します。ツールを保存して更新する一元化された場所が提供されるため、ツールの管理が簡素化されます。エージェントとアプリケーション間でツールを共有し、アプリケーションを再デプロイすることなくツールを更新できます。
データベース向け MCP ツールボックスでサポートされているデータベースの 1 つが Cloud SQL であり、前のセクションでプロビジョニングしたことがわかります。
ツールボックスのインストール
Cloud Shell ターミナルを開き、mcp-toolbox という名前のフォルダを作成します。
mkdir mcp-toolbox
以下のコマンドで mcp-toolbox フォルダに移動します。
cd mcp-toolbox
以下のスクリプトを使用して、データベース向け MCP ツールボックスのバイナリ バージョンをインストールします。次のコマンドは Linux 用です。Mac または Windows を使用している場合は、正しいバイナリをダウンロードしてください。オペレーティング システムとアーキテクチャのリリース ページを確認し、正しいバイナリをダウンロードします。
export VERSION=1.13.1
curl -L -o toolbox https://storage.googleapis.com/mcp-toolbox-for-databases/v$VERSION/linux/amd64/toolbox
chmod +x toolbox
これで、ツールボックスのバイナリ バージョンを使用できるようになりました。ツールボックス バイナリが正しく設定され、正しいバージョンを示していることを確認しましょう。
次のコマンドを実行して、ツールボックスのバージョンを確認します。
./toolbox -v
次のステップでは、データソースやその他の構成を使用してツールボックスを構成します。
tools.yaml を構成する
Toolbox を構成する主な方法は、tools.yaml ファイルを使用することです。同じフォルダ（mcp-toolbox）に tools.yaml という名前のファイルを作成します。その内容は次のとおりです。
Cloud Shell で使用できる nano エディタを使用できます。nano コマンドは「nano tools.yaml」です。
YOUR_PROJECT_ID の値は、実際の Google Cloud プロジェクト ID に置き換えてください。
kind: source
name: my-cloud-sql-source
type: cloud-sql-postgres
project: YOUR_PROJECT_ID
region: us-central1
instance: hoteldb-instance
database: postgres
user: postgres
password: postgres
---
kind: tool
name: search-hotels-by-name
type: postgres-sql
source: my-cloud-sql-source
description: Search for hotels based on name.
parameters:
- name: name
type: string
description: The name of the hotel.
statement: SELECT * FROM hotels WHERE name ILIKE '%' || $1 || '%';
---
kind: tool
name: search-hotels-by-location
type: postgres-sql
source: my-cloud-sql-source
description: Search for hotels based on location. Result is sorted by price from least to most expensive.
parameters:
- name: location
type: string
description: The location of the hotel.
statement: |
SELECT *
FROM hotels
WHERE location ILIKE '%' || $1 || '%'
ORDER BY
CASE price_tier
WHEN 'Midscale' THEN 1
WHEN 'Upper Midscale' THEN 2
WHEN 'Upscale' THEN 3
WHEN 'Upper Upscale' THEN 4
WHEN 'Luxury' THEN 5
ELSE 99 -- Handle any unexpected values, place them at the end
END;
---
kind: toolset
name: my_first_toolset
tools:
- search-hotels-by-name
- search-hotels-by-location
ファイルについて簡単に説明します。
Sourcesは、ツールが操作できるさまざまなデータソースを表します。ソースは、ツールが操作できるデータソースを表します。tools.yaml ファイルの sources セクションでSourcesをマップとして定義できます。通常、移行元構成には、データベースに接続して操作するために必要な情報が含まれます。この例では、認証情報を使用して Cloud SQL for PostgreSQL インスタンスを指す単一のソースを構成しています。詳細については、ソースのリファレンスをご覧ください。Toolsは、エージェントが実行できるアクション（ソースへの読み取りや書き込みなど）を定義します。ツールは、エージェントが実行できるアクション（SQL ステートメントの実行など）を表します。tools.yaml ファイルの tools セクションでToolsをマップとして定義できます。通常、ツールは処理対象のソースを必要とします。この例では、search-hotels-by-nameとsearch-hotels-by-locationの 2 つのツールを定義し、SQL とパラメータとともに、ツールが動作するソースを指定しています。詳しくは、ツールのリファレンスをご覧ください。- 最後に、
Toolsetがあります。これにより、一緒に読み込むツール グループを定義できます。これは、エージェントまたはアプリケーションに基づいてさまざまなグループを定義する場合に便利です。この例では、my_first_toolsetという 1 つのツールセットがあり、これには定義した 2 つのツールが含まれています。
次の手順で、nano エディタに tools.yaml ファイルを保存します。
Ctrl + O（「書き出し」コマンド）を押します。- [File Name to Write] の確認を求められます。
Enterを押すだけです。 Ctrl + Xを押して終了します。
データベース向け MCP ツールボックス サーバーを実行する
次のコマンド（mcp-toolbox フォルダから）を実行して、サーバーを起動します。
./toolbox --config "tools.yaml"
理想的には、サーバーがデータソースに接続し、ツールセットとツールを読み込んだことを示す出力が表示されます。出力例を次に示します。
2026-09-26T14:00:35.898358+05:30 INFO "Starting MCP Toolbox for Databases version 1.13.1+binary.darwin.arm64.e14cda6"
2026-09-26T14:00:39.571556+05:30 INFO "Initialized 1 sources: my-cloud-sql-source"
2026-09-26T14:00:39.571634+05:30 INFO "Initialized 0 authServices: "
2026-09-26T14:00:39.571648+05:30 INFO "Initialized 0 embeddingModels: "
2026-09-26T14:00:39.571728+05:30 INFO "Initialized 2 tools: search-hotels-by-name, search-hotels-by-location"
2026-09-26T14:00:39.571745+05:30 INFO "Initialized 0 prompts: "
2026-09-26T14:00:39.571756+05:30 INFO "Initialized 0 resources: "
2026-09-26T14:00:39.571767+05:30 INFO "Initialized 0 resource templates: "
2026-09-26T14:00:39.571851+05:30 INFO "Initialized 2 groups: my_first_toolset, default"
2026-09-26T14:00:39.571905+05:30 WARN "wildcard (*) allows any website to access the primitives. This creates a security risk regardless of whether you are in a production or local development environment. Recommended to use --allowed-origins with specific local addresses."
2026-09-26T14:00:39.571939+05:30 WARN "wildcard (*) hosts allow any domain to access this resource, making it vulnerable to DNS rebinding attacks regardless of whether you are in a production or local development environment. For improved security, use the --allowed-hosts flag to specify trusted domains."
2026-09-26T14:00:39.572261+05:30 INFO "Server ready to serve!"
MCP ツールボックス サーバーは、デフォルトでポート 5000 で実行されます。ポート 5000 がすでに使用されている場合は、次のコマンドに示すように、別のポート（7000 など）を使用してください。以降のコマンドでは、5000 ポートではなく 7000 を使用してください。
./toolbox --config "tools.yaml" --port 7000
Cloud Shell を使用してテストしてみましょう。
次の図に示すように、Cloud Shell で [ウェブでプレビュー] をクリックします。
[ポートを変更] をクリックし、下に示すようにポートを 5000 に設定して、[変更してプレビュー] をクリックします。
次の出力が表示されます。
データベース向け MCP ツールボックスの UI を使用してツールをテストする
ツールボックスには、シンプルなウェブ UI 内でパラメータの変更、ヘッダーの管理、呼び出しの実行を行うことでツールを直接操作できるビジュアル インターフェース（ツールボックス UI）が用意されています。
テストする場合は、--ui オプションを指定して、Toolbox Server の起動に使用したコマンドを実行します。
これを行うには、実行中のデータベース向け MCP ツールボックス サーバーの以前のインスタンスをシャットダウンし、次のコマンドを実行します。
./toolbox --config "tools.yaml" --ui
理想的には、サーバーがデータソースに接続し、ツールセットとツールを読み込んだことを示す出力が表示されます。以下にサンプル出力を示します。Toolbox UI が起動して実行中であることがわかります。
2026-09-26T14:01:17.208487+05:30 INFO "Starting MCP Toolbox for Databases version 1.13.1+binary.darwin.arm64.e14cda6"
2026-09-26T14:01:20.823447+05:30 INFO "Initialized 1 sources: my-cloud-sql-source"
2026-09-26T14:01:20.82353+05:30 INFO "Initialized 0 authServices: "
2026-09-26T14:01:20.823545+05:30 INFO "Initialized 0 embeddingModels: "
2026-09-26T14:01:20.823629+05:30 INFO "Initialized 2 tools: search-hotels-by-name, search-hotels-by-location"
2026-09-26T14:01:20.823649+05:30 INFO "Initialized 0 prompts: "
2026-09-26T14:01:20.82366+05:30 INFO "Initialized 0 resources: "
2026-09-26T14:01:20.823671+05:30 INFO "Initialized 0 resource templates: "
2026-09-26T14:01:20.823745+05:30 INFO "Initialized 2 groups: my_first_toolset, default"
2026-09-26T14:01:20.823795+05:30 WARN "wildcard (*) allows any website to access the primitives. This creates a security risk regardless of whether you are in a production or local development environment. Recommended to use --allowed-origins with specific local addresses."
2026-09-26T14:01:20.823829+05:30 WARN "wildcard (*) hosts allow any domain to access this resource, making it vulnerable to DNS rebinding attacks regardless of whether you are in a production or local development environment. For improved security, use the --allowed-hosts flag to specify trusted domains."
2026-09-26T14:01:20.824193+05:30 INFO "Server ready to serve!"
2026-09-26T14:01:20.824231+05:30 INFO "Toolbox UI is up and running at: http://127.0.0.1:5000/ui"
UI の URL をクリックし、次のことを確認します。
/ui
URL の末尾（Cloud Shell で実行している場合、ブラウザのリダイレクトにより、末尾に /ui が表示されません）。次のような UI が表示されます。
左側の [ツール] オプションをクリックして、構成済みのツールを表示します。この例では、次の図に示すように、search-hotels-by-name と search-hotels-by-location の 2 つのツールが表示されます。
いずれかのツール（search-hotels-by-location）をクリックすると、必要なパラメータ値を指定してツールをテストするためのページが表示されます。そこで [Run Tool] をクリックすると、結果が表示されます。実行例を以下に示します。
前の図（下図）をもう一度見てみると、データベースと MCP サーバーの設定が完了し、次の 2 つのパスが用意されています。
- MCP サーバーを AI アシスト ターミナル / IDE に構成する方法については、ステップ 6 をご覧ください。ここでは、MCP ツールボックス サーバーを
Gemini CLIに統合する方法について説明します。 Agent Development Kit (ADK) using Pythonの使用方法、MCP Server Toolbox をツールとして使用できる独自のエージェントの作成方法、データセットに関連する質問への回答方法については、ステップ 7 と 8 をご覧ください。
6. Antigravity CLI での MCP ツールボックスの統合
Antigravity CLI は、Antigravity の軽量なターミナル ユーザー インターフェース（TUI）サーフェスです。 Antigravity と同じコア エージェント機能（マルチステップ推論、マルチファイル編集、ツール呼び出し、会話履歴など）をターミナルに直接提供します。コーディング タスクとコーディング以外のタスクの両方に使用できます。さまざまなツールが統合されており、MCP サーバーもサポートされています。
動作する MCP サーバーがあるので、このセクションの目標は、Antigravity CLI で MCP Toolbox for Databases サーバーを構成し、Antigravity CLI を使用してデータと通信することです。
まず、Cloud Shell ターミナルのいずれかで Toolbox が起動しているかどうかを確認します。デフォルトのポート 5000 で実行している場合、MCP サーバー インターフェースはエンドポイント http://localhost:5000/mcp で使用できます。
新しいターミナルを開き、次のように my-gemini-cli-project という名前のフォルダを作成します。my-gemini-cli-project フォルダにも移動します。
mkdir my-agy-cli-project
cd my-agy-cli-project
次のコマンドを実行して、Antigravity CLI で構成された MCP サーバーのリストに MCP サーバーを追加します。
agy mcp add "MCPToolbox" "http://localhost:5000/mcp"
Antigravity CLI で構成されている MCP サーバーの現在のリストは、次のコマンドで確認できます。
agy mcp list
理想的には、構成した MCPToolbox の横に緑色のチェックマークが表示されます。これは、Gemini CLI が MCP サーバーに接続できたことを示しています。
NAME TYPE STATUS COMMAND/URL
MCPToolbox http enabled http://localhost:5000/mcp
Gemini CLI を起動する前に、Gemini CLI がリクエストを正しいモデルに転送できるように、次の環境変数を設定することをおすすめします。
export GOOGLE_CLOUD_PROJECT=YOUR_GOOGLE_CLOUD_PROJECT_ID
export GOOGLE_CLOUD_LOCATION=global
同じターミナルで、my-agy-cli-project フォルダにいることを確認します。コマンド agy を使用して Antigravity CLI を起動します。
Antigravity CLI インターフェースが表示されます。/mcp コマンドを使用して、MCP サーバーとツールのリストを表示できます。たとえば、出力例は次のようになります。
MCP Servers
Plugins (~/.gemini/config/plugins)
> ✓ MCPToolbox Tools: search-hotels-by-location, search-hotels-by-name
次のいずれかのプロンプトを入力できます。
Which hotels are there in Basel?Tell me more about the Hyatt Regency?
上記のクエリを実行すると、Antigravity CLI が MCPToolbox から適切なツールを選択します。ツールの実行権限を求められます。必要な権限を付与すると、結果がデータベースから返されることがわかります。
7. Agent Development Kit（ADK）を使用したエージェントの作成
Agent Development Kit（ADK）をインストールする
Cloud Shell で新しいターミナルタブを開き、次のように my-agents という名前のフォルダを作成します。my-agents フォルダにも移動します。
mkdir my-agents
cd my-agents
次に、次のように venv を使用して仮想 Python 環境を作成します。
python -m venv .venv
次のように仮想環境を有効にします。
source .venv/bin/activate
ADK とデータベース向け MCP ツールボックスのパッケージを langchain の依存関係とともに次のようにインストールします。
pip install google-adk toolbox-core
これで、次のように adk ユーティリティを呼び出すことができます。
adk
コマンドのリストが表示されます。
$ adk
Usage: adk [OPTIONS] COMMAND [ARGS]...
Agent Development Kit CLI tools.
Options:
--version Show the version and exit.
--help Show this message and exit.
Commands:
api_server Starts a FastAPI server for agents.
conformance Conformance testing tools for ADK.
create Creates a new app in the current folder with prepopulated...
deploy Deploys agent to hosted environments.
eval Evaluates an agent given the eval sets.
eval_set Manage Eval Sets.
migrate ADK migration commands.
optimize Optimizes the root agent instructions using the GEPA...
run Runs an agent.
telemetry Manage telemetry settings.
test Runs pytest on agent test JSON files under the specified...
web Starts a FastAPI server with Web UI for agents.
最初のエージェント アプリケーションを作成する
次に、adk を使用して、adk create コマンドとアプリ名 **(hotel_agent_app)**を介して、ホテル エージェント アプリケーションのスキャフォールディングを作成します。
adk create hotel_agent_app
手順に沿って、以下を選択します。
- ルート エージェントのモデルを選択するための
gemini-3.8-flashモデルを選択します。 - バックエンドに
Vertex AIを選択します。 - デフォルトの Google プロジェクト ID が表示されます。それを選択します。
- 現在の Google Cloud プロジェクトのリージョンが表示されます。
globalと入力してください。
Choose a model for the root agent:
1. gemini-3.5-flash
2. gemini-3.8-flash
3. Other models (fill later)
Choose model (1, 2, 3): 2
1. Google AI
2. Vertex AI
3. Login with Google
Choose a backend (1, 2, 3): 2
You need an existing Google Cloud account and project, check out this link for details:
https://google.github.io/adk-docs/get-started/quickstart/#gemini---google-cloud-vertex-ai
Enter Google Cloud project ID [YOUR_PROJECT_ID]:
Enter Google Cloud region [us-central1]: global
Agent created in <YOUR_HOME_FOLDER>/my-agents/hotel_agent_app:
- .env
- .gitignore
- __init__.py
- agent.py
エージェントのデフォルト テンプレートと必要なファイルが作成されたフォルダを確認します。ファイルは、ターミナルの ls -al コマンドを使用して <YOUR_HOME_FOLDER>/my-agents/hotel_agent_app ディレクトリで確認できます。
まず、.env ファイルです。このファイルは前述のようにすでに作成されています。以下のファイルの内容を確認してください。
GOOGLE_GENAI_USE_ENTERPRISE=1
GOOGLE_CLOUD_PROJECT=YOUR_GOOGLE_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_GOOGLE_PROJECT_REGION
これらの値は、Google Cloud プロジェクト ID とロケーションのそれぞれの値とともに Vertex AI 経由で Gemini を使用することを示しています。
次に、__init__.py ファイルがあります。このファイルはフォルダをモジュールとしてマークし、agent.py ファイルからエージェントをインポートする単一のステートメントを含んでいます。
from . import agent
最後に、agent.py ファイルを見てみましょう。内容は次のとおりです。
from google.adk.agents.llm_agent import Agent
root_agent = Agent(
model='gemini-3.8-flash',
name='root_agent',
description='A helpful assistant for user questions.',
instruction='Answer user questions to the best of your knowledge',
)
これは、ADK で記述できる最もシンプルなエージェントです。ADK ドキュメントのページによると、エージェントは特定の目標を達成するために自律的に動作するように設計された、自己完結型の実行ユニットです。エージェントは、タスクの実行、ユーザーとのやり取り、外部ツールの利用、他のエージェントとの連携を行うことができます。
具体的には、LLMAgent（通常は Agent というエイリアスが付けられます）は、大規模言語モデル（LLM）をコアエンジンとして使用して、自然言語の理解、推論、計画、応答の生成を行い、どのように進めるか、どのツールを使用するかを動的に決定します。そのため、柔軟な言語中心のタスクに最適です。LLM エージェントの詳細については、こちらをご覧ください。
agent.py のコードを次のように変更します。
from google.adk.agents.llm_agent import Agent
root_agent = Agent(
model='gemini-3.8-flash',
name='root_agent',
description='A helpful assistant that answers questions about a specific city.',
instruction='Answer user questions about a specific city to the best of your knowledge. Do not answer questions outside of this.',
)
エージェント アプリをローカルでテストする
既存のターミナル ウィンドウから次のコマンドを実行します。hotel_agent_app フォルダを含む親フォルダ (my-agents) にいることを確認します。
adk web
実行例を以下に示します。
...
INFO: Started server process [61397]
INFO: Waiting for application startup.
+-----------------------------------------------------------------------------+
| ADK Web Server started |
| |
| For local testing, access at http://127.0.0.1:8000. |
+-----------------------------------------------------------------------------+
INFO: Application startup complete.
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
最後のリンクをクリックすると、エージェントをテストするためのウェブ コンソールが表示されます。次のように、ブラウザで起動されます。
左上に hotel_agent_app が表示されています。これで、エージェントとの会話を開始できます。都市について尋ねるプロンプトをいくつか提供します。会話の例を以下に示します。
Cloud Shell ターミナルで実行されているプロセスをシャットダウンできます（Ctrl+C）。
エージェントをテストする別の方法として、my-agents フォルダから次の adk run コマンドを使用する方法があります。
adk run hotel_agent_app
コマンドを試すと、コマンドライン（ターミナル）でエージェントと会話できます。「exit」と入力して会話を終了します。
8. エージェントをツールに接続する
エージェントを作成してローカルでテストする方法がわかったので、このエージェントをツールに接続します。ADK のコンテキストでのツールとは、AI エージェントに提供される特定の機能を指します。ツールにより、エージェントはテキスト生成や推論といった中核的な機能の枠を超え、アクションを実行したり、外部世界とやり取りしたりできるようになります。
今回は、データベース向け MCP ツールボックスで構成したツールをエージェントに装備します。
agent.py ファイルを次のコードで変更します。コードではデフォルトのポート 5000 を使用していますが、別のポート番号を使用している場合は、そのポート番号を使用してください。
from google.adk.agents import Agent
from toolbox_core import ToolboxSyncClient
toolbox = ToolboxSyncClient("http://127.0.0.1:5000")
# Load single tool
# tools = toolbox.load_tool('search-hotels-by-location')
# Load all the tools
tools = toolbox.load_toolset('my_first_toolset')
root_agent = Agent(
name="hotel_agent",
model="gemini-3.8-flash",
description=(
"Agent to answer questions about hotels in a city or hotels by name."
),
instruction=(
"You are a helpful agent who can answer user questions about the hotels in a specific city or hotels by name. Use the tools to answer the question"
),
tools=tools,
)
これで、データベース向け MCP ツールボックスで構成された PostgreSQL データベースから実際のデータを取得するエージェントをテストできます。
手順は次のとおりです。
Cloud Shell の 1 つのターミナルで、データベース向け MCP ツールボックスを起動します。先ほどテストしたように、ポート 5000 でローカルに実行されている可能性があります。そうでない場合は、次のコマンド（mcp-toolbox フォルダから）を実行してサーバーを起動します。
./toolbox --config "tools.yaml"
理想的には、サーバーがデータソースに接続し、ツールセットとツールを読み込んだことを示す出力が表示されます。
MCP サーバーが正常に起動したら、別のターミナルで、以下に示す adk run（my-agents フォルダから）コマンドを使用して、前述のようにエージェントを起動します。必要に応じて、adk web コマンドを使用することもできます。
$ adk run hotel_agent_app/
...
Running agent hotel_agent, type exit to exit.
[user]: what can you do for me?
[hotel_agent]: I can help you search for and find information about hotels! Specifically, I can:
* **Find hotels in a specific city or location:** Look up available hotels, sorted by price from least to most expensive.
* **Search for hotels by name:** Get details on a specific hotel you're interested in.
Feel free to tell me where you're planning to stay or which hotel you'd like to look up!
[user]: I would like to search for hotels?
[hotel_agent]: I'd be happy to help!
Where are you planning to travel, or is there a specific hotel name you have in mind?
[user]: I am planning to travel to Basel
[hotel_agent]: Here are the hotels available in **Basel**, listed from least to most expensive:
1. **Holiday Inn Basel**
* **Price Tier:** Upper Midscale
* **Available Dates:** April 9, 2024 – April 24, 2024
2. **Hyatt Regency Basel**
* **Price Tier:** Upper Upscale
* **Available Dates:** April 2, 2024 – April 20, 2024
3. **Hilton Basel**
* **Price Tier:** Luxury
* **Available Dates:** April 20, 2024 – April 22, 2024
Would you like more details about any of these hotels, or do you have specific travel dates in mind?
[user]:
. . .
エージェントが、データベース向け MCP ツールボックスで構成した 2 つのツール（search-hotels-by-name と search-hotels-by-location）を利用して、正しいオプションを提供していることに注目してください。これにより、PostgreSQL インスタンス データベースからデータをシームレスに取得し、それに応じてレスポンスの形式を設定できます。
これで、Agent Development Kit（ADK）を使用して構築し、データベース向け MCP ツールボックスで構成したツールで動作するホテル エージェントのローカル開発とテストが完了しました。
9. （省略可）データベース向け MCP ツールボックスとエージェントを Cloud Run にデプロイする
前のセクションでは、Cloud Shell ターミナルを使用して MCP ツールボックス サーバーを起動し、エージェントでツールをテストしました。これは、Cloud Shell 環境でローカルに実行されていました。
MCP ツールボックス サーバーとエージェントの両方を、これらのアプリケーションをホストできる Google Cloud サービスにデプロイすることもできます。
Cloud Run で MCP ツールボックス サーバーをホストする
まず、MCP ツールボックス サーバーから始めて、Cloud Run でホストできます。これにより、他のアプリケーションやエージェント アプリケーションと統合できるパブリック エンドポイントが提供されます。Cloud Run でホストする手順については、こちらをご覧ください。それでは、主な手順を見ていきましょう。
新しい Cloud Shell ターミナルを起動するか、既存の Cloud Shell ターミナルを使用します。toolbox バイナリと tools.yaml が存在する mcp-toolbox フォルダに移動します。
次のコマンドを実行します（各コマンドの説明は次のとおりです）。
PROJECT_ID 変数を Google Cloud プロジェクト ID を指すように設定します。
export PROJECT_ID="YOUR_GOOGLE_CLOUD_PROJECT_ID"
次に、プロジェクトで次の Google Cloud サービスが有効になっていることを確認します。
gcloud services enable run.googleapis.com \
cloudbuild.googleapis.com \
artifactregistry.googleapis.com \
iam.googleapis.com \
secretmanager.googleapis.com
Google Cloud Run にデプロイする Toolbox サービスの ID として機能する別のサービス アカウントを作成しましょう。また、このサービス アカウントに正しいロール（Secret Manager にアクセスして Cloud SQL と通信する機能）があることも確認します。
gcloud iam service-accounts create toolbox-identity
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \
--role roles/secretmanager.secretAccessor
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \
--role roles/cloudsql.client
tools.yaml ファイルをシークレットとしてアップロードします。Cloud Run に Toolbox をインストールする必要があるため、Toolbox の最新のコンテナ イメージを使用して、IMAGE 変数に設定します。
gcloud secrets create tools --data-file=tools.yaml
export IMAGE=us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest
Cloud Run へのデプロイ コマンドの最後のステップ:
gcloud run deploy toolbox \
--image $IMAGE \
--service-account toolbox-identity \
--region us-central1 \
--set-secrets "/app/tools.yaml=tools:latest" \
--args="--config=/app/tools.yaml","--address=0.0.0.0","--port=8080" \
--allow-unauthenticated
これにより、構成済みの tools.yaml を使用して Toolbox サーバーを Cloud Run にデプロイするプロセスが開始されます。デプロイが成功すると、次のようなメッセージが表示されます。
Deploying container to Cloud Run service [toolbox] in project [YOUR_PROJECT_ID] region [us-central1]
OK Deploying new service... Done.
OK Creating Revision...
OK Routing traffic...
OK Setting IAM Policy...
Done.
Service [toolbox] revision [toolbox-00001-zsk] has been deployed and is serving 100 percent of traffic.
Service URL: https://toolbox-<SOME_ID>.us-central1.run.app
上記の Service URL にブラウザでアクセスできるようになりました。先ほど表示された「Hello World」というメッセージが表示されます。
Google Cloud コンソールから Cloud Run にアクセスすると、Cloud Run のサービスリストに Toolbox サービスが表示されます。
注: ホテル エージェントをローカルで実行しながら、新しくデプロイされた Cloud Run サービスに接続する場合は、my-agents/hotel_agent_app/agent.py ファイルを 1 つ変更するだけで済みます。
次のようにします。
toolbox = ToolboxSyncClient("http://127.0.0.1:5000")
次のように、Cloud Run サービスのサービス URL に変更します。
toolbox = ToolboxSyncClient("CLOUD_RUN_SERVICE_URL")
前述のように、adk run または adk web を使用して、エージェント アプリケーションをテストします。
Cloud Run へのホテル エージェント アプリのデプロイ
まず、上記の手順に沿って my-agents/hotel_agent_app/agent.py で変更を行い、ローカルホストではなく Cloud Run で実行されている Toolbox サービスの URL を指すようにします。
新しい Cloud Shell ターミナルまたは既存のターミナル セッションで、先ほど設定した正しい Python 仮想環境にいることを確認します。
まず、以下に示すように my-agents/hotel_agent_app フォルダに requirements.txt ファイルを作成します。
google-adk
toolbox-core
my-agents フォルダに移動し、まず次の環境変数を設定します。
export GOOGLE_CLOUD_PROJECT=YOUR_GOOGLE_CLOUD_PROJECT_ID
export GOOGLE_CLOUD_LOCATION=us-central1
export AGENT_PATH="hotel_agent_app/"
export SERVICE_NAME="hotels-service"
export APP_NAME="hotels-app"
Export GOOGLE_GENAI_USE_ENTERPRISE=1
最後に、次の adk deploy cloud_run コマンドを使用して、エージェント アプリケーションを Cloud Run にデプロイします。サービスへの未認証の呼び出しを許可するかどうかを尋ねられた場合は、現時点では値として「y」を指定してください。
adk deploy cloud_run \
--project=$GOOGLE_CLOUD_PROJECT \
--region=$GOOGLE_CLOUD_LOCATION \
--service_name=$SERVICE_NAME \
--app_name=$APP_NAME \
--with_ui \
$AGENT_PATH
これにより、ホテル エージェント アプリケーションを Cloud Run にデプロイするプロセスが開始されます。ソースをアップロードして Docker コンテナにパッケージ化し、Artifact Registry に push してから、Cloud Run にサービスをデプロイします。この処理には数分かかることがあります。
次のようなメッセージが表示されます。
Start generating Cloud Run source files in /tmp/cloud_run_deploy_src/20250905_132636
Copying agent source code...
Copying agent source code completed.
Creating Dockerfile...
Creating Dockerfile complete: /tmp/cloud_run_deploy_src/20250905_132636/Dockerfile
Deploying to Cloud Run...
Building using Dockerfile and deploying container to Cloud Run service [hotels-service] in project [YOUR_PROJECT_ID] region [us-central1]
- Building and deploying... Uploading sources.
- Uploading sources...
. Building Container...
OK Building and deploying... Done.
OK Uploading sources...
OK Building Container... Logs are available at [https://console.cloud.google.com/cloud-build/builds;region=us-central1/d1f7e76b-0587-4bb6-b9c0-bb4360c07aa0?project=415
458962931]. f
OK Creating Revision...
OK Routing traffic...
Done.
Service [hotels-service] revision [hotels-service-00003-hrl] has been deployed and is serving 100 percent of traffic.
Service URL: <YOUR_CLOUDRUN_APP_URL>
INFO: Display format: "none"
Cleaning up the temp folder: /tmp/cloud_run_deploy_src/20250905_132636
デプロイが成功すると、サービス URL の値が提供されます。この URL をブラウザで開くと、先ほどのローカル設定で見たように、ホテル エージェントとチャットできる同じウェブ アプリケーションが表示されます。
10. クリーンアップ
Google Cloud アカウントに継続的に課金されないようにするには、このワークショップで作成したリソースを削除することが重要です。Cloud SQL インスタンスを削除します。必要に応じて、ツールボックスとホテルアプリを Cloud Run にデプロイした場合は、これらのサービスも削除します。
プロジェクトとリージョンに応じて、次の環境変数が正しく設定されていることを確認します。
export PROJECT_ID="YOUR_PROJECT_ID"
export REGION="YOUR_REGION"
次の 2 つのコマンドは、デプロイした Cloud Run サービスを削除します。
gcloud run services delete toolbox --platform=managed --region=${REGION} --project=${PROJECT_ID} --quiet
gcloud run services delete hotels-service --platform=managed --region=${REGION} --project=${PROJECT_ID} --quiet
次のコマンドは、Cloud SQL インスタンスを削除します。
gcloud sql instances delete hoteldb-instance
11. 完了
お疲れさまでした。これで、データベース向け MCP ツールボックスを利用する Agent Development Kit（ADK）を使用して、旅行エージェントを正常に構築できました。また、エージェントを独自のデータベースに接続する方法と、必要に応じて Cloud Run にエージェントとツールボックスをインストールする方法も学びました。