1. 概要
エージェント とは、AI モデルと対話して、エージェントが持つツールとコンテキストを使用して目標ベースの操作を実行する自律型プログラムです。真実に基づいた自律的な意思決定が可能です。
アプリケーションに複数のエージェントがあり、それぞれが特定のフォーカス領域を独立して認識し、責任を負いながら、必要に応じて自律的に連携して、より大きな目的を達成する場合、そのアプリケーションはマルチエージェント システム になります。
Agent Development Kit（ADK）
Agent Development Kit（ADK）は、AI エージェントの開発とデプロイ用に設計された、柔軟性の高いモジュール型のフレームワークです。ADK では、複数の異なるエージェント インスタンスをマルチエージェント システム（MAS）に構成することで、高度なアプリケーションを構築できます。
ADK では、マルチエージェント システムは、さまざまなエージェント（多くの場合、階層を形成）が連携または調整して、より大きな目標を達成するアプリケーションです。このようにアプリケーションを構造化すると、モジュール性、専門性、再利用性、保守性の向上、専用のワークフロー エージェントを使用した構造化された制御フローの定義など、大きなメリットが得られます。
マルチエージェント システムに関する注意事項
まず、各エージェントの専門分野を適切に理解し、推論することが重要です。たとえば、「特定のサブエージェントが必要な理由を理解しているか」など、最初に確認します。
次に、ルートエージェントと連携して、各レスポンスをルーティングして理解する方法です。
3 つ目 は、このドキュメントに記載されているエージェント ルーティングのタイプです。アプリケーションのフローに適したものを選択してください。また、マルチエージェント システムのフロー制御に必要なさまざまなコンテキストと状態についても確認してください。
作成するアプリの概要
AlloyDB と ADK 用の MCP ツールボックスを使用して、キッチンの改修を処理するマルチエージェント システムを構築しましょう。
- 改修提案エージェント
- 許可とコンプライアンス チェック エージェント
- 注文ステータス チェック（データベース向け MCP ツールボックスを使用するツール）
リフォーム提案エージェント: キッチンのリフォーム提案書を作成します。
許可とコンプライアンス エージェント: 許可とコンプライアンスに関連するタスクを処理します。
注文ステータス チェック エージェント: AlloyDB に設定した注文管理データベースで、資材の注文ステータスを確認します。このデータベース部分では、AlloyDB 用の MCP ツールボックス を使用して、注文のステータス取得ロジックを実装します。
2. MCP
MCP は Model Context Protocol の略で、Anthropic が開発したオープン スタンダードです。AI エージェントが外部のツール、サービス、データに一貫した方法で接続できるようにします。基本的には、AI アプリケーションの共通標準として機能し、さまざまなデータソースやツールとシームレスに連携できます。
- クライアント サーバー モデルを使用します。AI アプリケーション（ホスト）は MCP クライアントを実行し、MCP サーバーと通信します。
- AI エージェントが特定のツールやデータにアクセスする必要がある場合は、構造化されたリクエストを MCP クライアントに送信し、MCP クライアントが適切な MCP サーバーに転送します。
- AI モデルは、統合ごとにカスタムコードを必要とせずに、外部のデータやツールにアクセスできます。
- 大規模言語モデル（LLM）上にエージェントと複雑なワークフローを構築するプロセスを簡素化します。
データベース向け MCP ツールボックス
Google のデータベース向け MCP ツールボックスは、データベース用のオープンソース MCP サーバーです。エンタープライズ グレードと本番環境品質を念頭に設計されています。これにより、接続プーリングや認証などの複雑な処理に対応して、ツールの開発をより簡単、迅速、セキュアに行うことができます。
エージェントがデータベース内のデータにアクセスできるようにするその方法を教えてください。
開発の簡素化: 10 行未満のコードでツールをエージェントに統合し、複数のエージェントまたはフレームワーク間でツールを再利用し、新しいバージョンのツールをより簡単にデプロイできます。
パフォーマンスの向上: 接続プーリング、認証などのベスト プラクティス。
セキュリティの強化: 統合認証により、データへのアクセスをより安全に行えます。
エンドツーエンドのオブザーバビリティ: OpenTelemetry の組み込みサポートによる、すぐに使える指標とトレース。
これは MCP より前のものだということを明記する必要があります。
データベース向け MCP ツールボックスは、エージェント アプリケーションのオーケストレーション フレームワークとデータベースの間に配置され、ツールの変更、配布、呼び出しに使用されるコントロール プレーンを提供します。ツールを保存して更新する一元的な場所を提供することで、ツールの管理を簡素化します。これにより、エージェントとアプリケーション間でツールを共有し、アプリケーションを再デプロイせずにツールを更新できます。
要件に基づいてこれらのエージェントをオーケストレートするルートエージェントを作成します。
要件
3. 始める前に
プロジェクトを作成する
- Google Cloud コンソールのプロジェクト選択ページで、Google Cloud プロジェクトを選択または作成します。
- Cloud プロジェクトに対して課金が有効になっていることを確認します。詳しくは、プロジェクトで課金が有効になっているかどうかを確認する方法をご覧ください。
- この リンクをクリックして Cloud Shell を有効にします。Cloud Shell の対応するボタンをクリックすると、Cloud Shell ターミナル（クラウド コマンドの実行用）とエディタ（プロジェクトの構築用）を切り替えることができます。
- Cloud Shell に接続したら、次のコマンドを使用して、すでに認証済みであることと、プロジェクトがプロジェクト ID に設定されていることを確認します。
gcloud auth list
- Cloud Shell で次のコマンドを実行して、gcloud コマンドがプロジェクトを認識していることを確認します。
gcloud config list project
- プロジェクトが設定されていない場合は、次のコマンドを使用して設定します。
gcloud config set project <YOUR_PROJECT_ID>
- 次のコマンドを実行して、次の API を有効にします。
gcloud services enable artifactregistry.googleapis.com \cloudbuild.googleapis.com \run.googleapis.com \aiplatform.googleapis.com \alloydb.googleapis.com
- Python 3.9 以降がインストールされていることを確認します。
- gcloud コマンドとその使用方法については、ドキュメントをご覧ください。
4. ADK の設定
- 仮想環境を作成して有効にします（推奨）。
Cloud Shell ターミナルで、仮想環境を作成します。
python -m venv .venv
仮想環境を有効にします。
source .venv/bin/activate
- ADK をインストールする
pip install google-adk
5. プロジェクト構造
- Cloud Shell ターミナルから次のコマンドを 1 つずつ実行して、ルートフォルダとプロジェクト フォルダを作成します。
mkdir agentic-apps
cd agentic-apps
mkdir renovation-agent
- Cloud Shell エディタに移動し、ファイルを作成して次のプロジェクト構造を作成します（最初は空のファイルを作成します）。
renovation-agent/
__init__.py
agent.py
.env
6. ソースコード
- init.py に移動し、次の内容で更新します。
from . import agent
- agent.py に移動し、次のパスから次の内容でファイルを更新します。
https://github.com/AbiramiSukumaran/renovation-agent-adk-mcp-toolbox/blob/main/agent.py
agent.py では、必要な依存関係をインポートし、.env ファイルから構成パラメータを取得し、1 つのツールを使用してツールボックス ツールを呼び出す root_agent を定義します。
- requirements.txt に移動し、次の内容で更新します。
https://github.com/AbiramiSukumaran/renovation-agent-adk-mcp-toolbox/blob/main/requirements.txt
7. データベースの設定
ordering_agent で使用されるツールの 1 つである「check_status」で、AlloyDB 注文データベースにアクセスして注文のステータスを取得します。このセクションでは、AlloyDB データベースクラスタとインスタンスを設定します。
クラスタとインスタンスを作成する
- Cloud コンソールの AlloyDB ページに移動します。 Cloud コンソールのほとんどのページは、コンソールの検索バーを使用して検索すると簡単に見つけることができます。
- そのページで [クラスタを作成] を選択します。
- 次のような画面が表示されます。次の値を使用して クラスタとインスタンス を作成します（リポジトリからアプリケーション コードをクローンする場合は、値が一致していることを確認してください）。
- クラスタ ID: "
vector-cluster" - パスワード: "
alloydb" - PostgreSQL 16 と互換性がある / 最新バージョンを使用することをおすすめします
- リージョン: "
us-central1" - ネットワーク: "
default"
- デフォルト ネットワークを選択すると、次のような画面が表示されます。
[接続を設定] を選択します。
- そこから、[自動的に割り当てられた IP 範囲を使用する] を選択して [続行] をクリックします。情報を確認したら、[接続を作成] を選択します。
6. 重要な注意事項: インスタンス ID を変更してください （クラスタ / インスタンスの構成時に確認できます）を
vector-instance 。変更できない場合は、以降のすべての参照でインスタンス ID を使用 してください。
- ツールボックスを設定する準備として、AlloyDB インスタンスでパブリック IP を有効 にして、新しいツールがデータベースにアクセスできるようにします。
- [パブリック IP 接続] セクションに移動し、[パブリック IP を有効にする] チェックボックスをオンにして、Cloud Shell マシンの IP アドレスを入力します。
- Cloud Shell マシンの IP を取得するには、Cloud Shell ターミナルに移動して「ifconfig」と入力します。結果から eth0 inet アドレスを特定し、最後の 2 桁を 0.0 に置き換え、マスクサイズを「/16」にします。たとえば、「XX.XX.0.0/16」のようになります。XX は数字です。
- この IP を、インスタンスの編集ページの [承認済み外部ネットワーク] の [ネットワーク] テキスト ボックスに貼り付けます。
- ネットワークを設定したら、クラスタの作成を続行できます。[クラスタを作成] をクリックして、次のようにクラスタの設定を完了します。
クラスタの作成には 10 分ほどかかります。成功すると、作成したクラスタの概要を示す画面が表示されます。
データの取り込み
店舗に関するデータを含むテーブルを追加します。AlloyDB に移動し、プライマリ クラスタを選択して、[AlloyDB Studio] を選択します。
インスタンスの作成が完了するまで待つ必要がある場合があります。 完了したら、クラスタの作成時に作成した認証情報を使用して AlloyDB にログインします。 PostgreSQL の認証には次のデータを使用します。
- ユーザー名: 「
postgres」 - データベース: 「
postgres」 - パスワード: 「
alloydb」
AlloyDB Studio で認証が成功すると、エディタに SQL コマンドが入力されます。 最後のウィンドウの右側にあるプラス記号を使用して、複数のエディタ ウィンドウを追加できます。
必要に応じて [実行]、[フォーマット]、[クリア] オプションを使用して、エディタ ウィンドウに AlloyDB のコマンドを入力します。
テーブルを作成する
AlloyDB Studio で次の DDL ステートメントを使用してテーブルを作成できます。
-- Table DDL for Procurement Material Order Status
CREATE TABLE material_order_status (
order_id VARCHAR(50) PRIMARY KEY,
material_name VARCHAR(100) NOT NULL,
supplier_name VARCHAR(100) NOT NULL,
order_date DATE NOT NULL,
estimated_delivery_date DATE,
actual_delivery_date DATE,
quantity_ordered INT NOT NULL,
quantity_received INT,
unit_price DECIMAL(10, 2) NOT NULL,
total_amount DECIMAL(12, 2),
order_status VARCHAR(50) NOT NULL, -- e.g., "Ordered", "Shipped", "Delivered", "Cancelled"
delivery_address VARCHAR(255),
contact_person VARCHAR(100),
contact_phone VARCHAR(20),
tracking_number VARCHAR(100),
notes TEXT,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
quality_check_passed BOOLEAN, -- Indicates if the material passed quality control
quality_check_notes TEXT, -- Notes from the quality control check
priority VARCHAR(20), -- e.g., "High", "Medium", "Low"
project_id VARCHAR(50), -- Link to a specific project
receiver_name VARCHAR(100), -- Name of the person who received the delivery
return_reason TEXT, -- Reason for returning material if applicable
po_number VARCHAR(50) -- Purchase order number
);
レコードを挿入する
上記の database_script.sql スクリプトから insert クエリ ステートメントをコピーして、エディタに貼り付けます。
[実行] をクリックします。
データセットの準備ができたので、AlloyDB のすべての注文データベースのやり取りのコントロール プレーンとして機能するように、データベース向け MCP ツールボックスを設定しましょう。
8. データベース向け MCP ツールボックスの設定
ツールボックスは、アプリケーションのオーケストレーション フレームワークとデータベースの間に配置され、ツールの変更、配布、呼び出しに使用されるコントロール プレーンを提供します。ツールを保存して更新する一元的な場所を提供することで、ツールの管理を簡素化します。これにより、エージェントとアプリケーション間でツールを共有し、アプリケーションを再デプロイせずにツールを更新できます。
データベース向け MCP ツールボックスでサポートされているデータベースの 1 つが AlloyDB です。前のセクションでプロビジョニングしたので、ツールボックスを設定しましょう。
- Cloud Shell ターミナルに移動し、プロジェクトが選択され、ターミナルのプロンプトに表示されていることを確認します。Cloud Shell ターミナルから次のコマンドを実行して、プロジェクト ディレクトリに移動します。
cd adk-renovation-agent
- 次のコマンドを実行して、新しいフォルダにツールボックスをダウンロードしてインストールします。
# see releases page for other versions
export VERSION=0.7.0
curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/v$VERSION/linux/amd64/toolbox
chmod +x toolbox
- Cloud Shell エディタ（コード編集モード）に移動し、プロジェクトのルートフォルダに「tools.yaml」というファイルを追加します。
sources:
alloydb-orders:
kind: "alloydb-postgres"
project: "<<YOUR_PROJECT_ID>>"
region: "us-central1"
cluster: "<<YOUR_ALLOYDB_CLUSTER>>"
instance: "<<YOUR_ALLOYDB_INSTANCE>>"
database: "<<YOUR_ALLOYDB_DATABASE>>"
user: "<<YOUR_ALLOYDB_USER>>"
password: "<<YOUR_ALLOYDB_PASSWORD>>"
tools:
get-order-data:
kind: postgres-sql
source: alloydb-orders
description: Get the status of an order based on the material description.
parameters:
- name: description
type: string
description: A description of the material to search for its order status.
statement: |
select order_status from material_order_status where lower(material_name) like lower($1)
LIMIT 1;
クエリ部分（上記の「statement」パラメータを参照）では、資材名がユーザーの検索テキストと一致する場合に、フィールド order_status の値を取得します。
tools.yaml について
ソース は、ツールが操作できるさまざまなデータソースを表します。ソースは、ツールが操作できるデータソースを表します。tools.yaml ファイルの sources セクションで、ソースをマップとして定義できます。通常、ソース構成には、データベースに接続して操作するために必要な情報が含まれます。
ツール は、エージェントが実行できるアクション（ソースの読み取りや書き込みなど）を定義します。ツールは、エージェントが実行できるアクション（SQL ステートメントの実行など）を表します。tools.yaml ファイルの tools セクションで、ツールをマップとして定義できます。通常、ツールは操作するソースを必要とします。
tools.yaml の構成について詳しくは、こちらの ドキュメントをご覧ください。
データベース向け MCP ツールボックス サーバーを実行する
次のコマンド（mcp-toolbox フォルダから）を実行して、サーバーを起動します。
./toolbox --tools-file "tools.yaml"
Cloud でウェブプレビュー モードでサーバーを開くと、get-order-data という名前の新しいツールでツールボックス サーバーが起動していることを確認できます。
MCP ツールボックス サーバーは、デフォルトでポート 5000 で実行されます。Cloud Shell を使用してテストしてみましょう。
次のように、Cloud Shell で [ウェブでプレビュー] をクリックします。
[ポートの変更] をクリックし、次のようにポートを 5000 に設定して、[変更してプレビュー] をクリックします。
次のような出力が表示されます。
データベース向け MCP ツールキットには、ツールの検証とテストを行うための Python SDK が用意されています。詳細については、こちらをご覧ください。次のセクションでは、これらのツールを使用する Agent Development Kit（ADK）に直接進みます。
ツールボックスを Cloud Run にデプロイする
まず、MCP ツールボックス サーバーを起動して Cloud Run でホストします。これにより、他のアプリケーションやエージェント アプリケーションと統合できるパブリック エンドポイントが提供されます。Cloud Run でホストする手順については、こちらをご覧ください。主な手順について説明します。
- 新しい Cloud Shell ターミナルを起動するか、既存の Cloud Shell ターミナルを使用します。ツールボックスのバイナリと tools.yaml が存在するプロジェクト フォルダ（この場合は adk-renovation-agent）に移動します。
- 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 にデプロイするツールボックス サービスの ID として機能する別のサービス アカウントを作成しましょう。
gcloud iam service-accounts create toolbox-identity
- また、このサービス アカウントに適切なロール（Secret Manager にアクセスして AlloyDB と通信する権限）が付与されていることを確認します。
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/alloydb.client
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \
--role roles/serviceusage.serviceUsageConsumer
- tools.yaml ファイルを Secret としてアップロードします。
gcloud secrets create tools --data-file=tools.yaml
Secret がすでに存在し、Secret バージョンを更新 する場合は、次のコマンドを実行します。
gcloud secrets versions add tools --data-file=tools.yaml
Cloud Run で使用するコンテナ イメージに環境変数を設定します。
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="--tools-file=/app/tools.yaml","--address=0.0.0.0","--port=8080" \
--allow-unauthenticated
これにより、構成済みの tools.yaml を使用してツールボックス サーバーを 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
エージェント アプリケーションで新しくデプロイしたツールを使用する準備が整いました。
ツールボックス ツールをエージェントに接続する
エージェント アプリケーションのソースはすでに作成しています。Cloud Run にデプロイした新しいデータベース向け MCP ツールボックス ツールを含めるように更新しましょう。
- リポジトリのソースを使用して requirements.txt ファイルを確認 します。
requirements.txt にデータベース向け MCP ツールボックスの依存関係を含めます。
https://github.com/AbiramiSukumaran/renovation-agent-adk-mcp-toolbox/blob/main/requirements.txt
- リポジトリのコードを使用して agent.py ファイルを確認 します。
ツールボックス エンドポイントを呼び出して、注文した特定の資材の注文データを取得するツールを含めます。
https://github.com/AbiramiSukumaran/renovation-agent-adk-mcp-toolbox/blob/main/agent.py
9. モデルの設定
エージェントがユーザー リクエストを理解してレスポンスを生成する機能は、大規模言語モデル（LLM）によって実現されています。エージェントは、この外部 LLM サービスに対して安全な呼び出しを行う必要があります。これには認証情報が必要です。有効な認証がないと、LLM サービスはエージェントのリクエストを拒否し、エージェントは機能しなくなります。
- Google AI Studio から API キーを取得します。
- .env ファイルを設定する次のステップで、
<<your API KEY>>を実際の API キーの値に置き換えます。
10. ENV 変数の設定
- テンプレート .env ファイルのパラメータの値を設定します。この例では、.env に次の変数があります。
GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=<<your API KEY>>
GOOGLE_CLOUD_LOCATION=us-central1 <<or your region>>
GOOGLE_CLOUD_PROJECT=<<your project id>>
PROJECT_ID=<<your project id>>
GOOGLE_CLOUD_REGION=us-central1 <<or your region>>
プレースホルダを独自の値に置き換えます。
11. エージェントを実行する
- ターミナルを使用して、エージェント プロジェクトの親ディレクトリに移動します。
cd renovation-agent
- 依存関係をインストールします。
pip install -r requirements.txt
- Cloud Shell ターミナルで次のコマンドを実行して、エージェントを実行できます。
adk run .
- 次のコマンドを実行して、ADK プロビジョニング済みウェブ UI で実行できます。
adk web
- 次のプロンプトでテストします。
user>>
Hello. Check order status for Cement Bags.
12. 結果
13. クリーンアップ
この投稿で使用したリソースについて、Google Cloud アカウントに課金されないようにするには、次の手順に従います。
- Google Cloud コンソールで、[リソースの管理] ページに移動します。
- プロジェクト リストで、削除するプロジェクトを選択し、[削除] をクリックします。
- ダイアログでプロジェクト ID を入力し、[シャットダウン] をクリックしてプロジェクトを削除します。
14. 完了
おめでとうございます！ADK とデータベース向け MCP ツールボックスを使用して、マルチエージェント アプリケーションを作成できました。詳細については、Agent Development Kit と データベース向け MCP ツールボックスのプロダクト ドキュメントをご覧ください。