AlloyDB と ADK 用の MCP ツールボックスを使用してマルチエージェントアプリを作成する

1. 概要

エージェントは、AI モデルと対話して、エージェントが持つツールとコンテキストを使用して目標ベースの操作を実行する自律型プログラムです。真実に基づいた自律的な意思決定を行うことができます。

アプリケーションに複数のエージェントがあり、それぞれが特定の重点分野について独立して知識を持ち、責任を負い、必要に応じて自律的に連携して、より大きな目的を達成する場合、そのアプリケーションはマルチエージェントシステムになります。

Agent Development Kit（ADK）

Agent Development Kit（ADK）は、AI エージェントの開発とデプロイ用に設計された、柔軟性の高いモジュラーフレームワークです。ADK は、複数の個別のエージェントインスタンスをマルチエージェントシステム（MAS）に構成して、高度なアプリケーションを構築することをサポートしています。

ADK では、マルチエージェントシステムは、多くの場合階層を形成するさまざまなエージェントが連携または調整して、より大きな目標を達成するアプリケーションです。このようにアプリケーションを構造化すると、モジュール性、専門性、再利用性、保守性の向上や、専用のワークフローエージェントを使用した構造化された制御フローの定義など、大きなメリットが得られます。

マルチエージェントシステムの注意点

まず、各エージェントの専門分野を正しく理解し、その推論を把握することが重要です。- 「特定のサブエージェントが必要な理由を知っていますか？」、まずそれを解決します。

2 つ目は、ルートエージェントと統合して、各レスポンスをルーティングして理解する方法です。

3 つ目に、エージェントのルーティングには複数のタイプがあり、このドキュメントで確認できます。アプリケーションのフローに適した方を選択してください。また、マルチエージェントシステムのフロー制御に必要なさまざまなコンテキストと状態も確認します。

作成するアプリの概要

AlloyDB と ADK 用の MCP ツールボックスを使用して、キッチンのリフォームを処理するマルチエージェントシステムを構築しましょう。

リフォーム提案エージェント
Permits and Compliance Check Agent
注文ステータスの確認（データベース向け MCP ツールボックスを使用するツール）

キッチンリフォームの提案書を生成するリフォーム提案エージェント。

Permits and Compliance Agent（許可とコンプライアンスエージェント）: 許可とコンプライアンスに関連するタスクを処理します。

Order Status Check Agent: AlloyDB に設定した注文管理データベースで、マテリアルの注文ステータスを確認します。ただし、このデータベース部分では、AlloyDB 向け MCP ツールボックスを使用して、注文のステータス取得ロジックを実装します。

2. MCP

MCP は Model Context Protocol の略です。これは、Anthropic が開発したオープンスタンダードで、AI エージェントが外部のツール、サービス、データに接続するための統一された方法を提供します。これは基本的に AI アプリケーションの共通標準として機能し、さまざまなデータソースやツールとシームレスにやり取りできるようにします。

クライアント / サーバーモデルを使用します。AI アプリケーション（ホスト）は MCP クライアントを実行し、MCP クライアントは MCP サーバーと通信します。
AI エージェントが特定のツールやデータにアクセスする必要がある場合、構造化されたリクエストを MCP クライアントに送信し、MCP クライアントが適切な MCP サーバーに転送します。
AI モデルが外部データやツールにアクセスできるようにします。統合ごとにカスタムコードを作成する必要はありません。
大規模言語モデル（LLM）上にエージェントと複雑なワークフローを構築するプロセスを簡素化します。

データベース向け MCP ツールボックス

Google のデータベース向け MCP ツールボックスは、データベース用のオープンソース MCP サーバーです。これは、エンタープライズグレードと本番環境品質を念頭に置いて設計されています。これにより、接続プーリングや認証などの複雑な処理に対応して、ツールの開発をより簡単、迅速、セキュアに行うことができます。

エージェントがデータベース内のデータにアクセスできるようにします。方法

簡素化された開発: 10 行未満のコードでツールをエージェントに統合し、複数のエージェントまたはフレームワーク間でツールを再利用し、ツールの新しいバージョンをより簡単にデプロイできます。

パフォーマンスの向上: 接続プーリングや認証などのベストプラクティス。

セキュリティの強化: 統合認証により、データへのアクセスをより安全に

エンドツーエンドのオブザーバビリティ: OpenTelemetry のサポートが組み込まれた、すぐに使用できる指標とトレース。

これは MCP よりも前のものだということを明記する必要があります。

データベース用 MCP ツールボックスは、エージェントアプリケーションのオーケストレーションフレームワークとデータベースの間に配置され、ツールの変更、配布、呼び出しに使用されるコントロールプレーンを提供します。ツールを保存して更新する一元化された場所を提供することで、ツールの管理を簡素化します。これにより、エージェントとアプリケーション間でツールを共有し、必ずしもアプリケーションを再デプロイしなくてもツールを更新できます。

要件に基づいてこれらのエージェントをオーケストレートするルートエージェントがあります。

要件

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

3. 始める前に

プロジェクトを作成する

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

また、Google Cloud の利用を開始して ADK を使用する際に役立つクレジットをご希望の場合は、こちらのリンクからクレジットをご利用ください。特典を利用するには、こちらの手順に沿って操作してください。このリンクは 5 月末まで有効です。

このリンクをクリックして、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"
password: "alloydb"
PostgreSQL 16 互換 / 最新バージョンを推奨
Region: "us-central1"
Networking: "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 を、インスタンスの編集ページの [承認済み外部ネットワーク] の [ネットワーク] テキストボックスに貼り付けます。

ネットワークを設定したら、クラスタの作成を続行できます。[CREATE CLUSTER] をクリックして、次のようにクラスタの設定を完了します。

クラスタの作成には 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 のすべての Order Database インタラクションのコントロールプレーンとして機能するように、データベース向け MCP ツールボックスを設定しましょう。

8. MCP Toolbox for Databases の設定

ツールボックスは、アプリケーションのオーケストレーションフレームワークとデータベースの間に配置され、ツールの変更、配布、呼び出しに使用されるコントロールプレーンを提供します。ツールを保存して更新する一元化された場所が提供されるため、ツールの管理が簡素化されます。これにより、エージェントとアプリケーション間でツールを共有し、必ずしもアプリケーションを再デプロイすることなく、ツールを更新できます。

データベース向け MCP ツールボックスでサポートされているデータベースの 1 つが AlloyDB であることがわかります。前のセクションで 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/genai-toolbox/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"

クラウドでウェブプレビューモードでサーバーを開くと、get-order-data という名前の新しいツールで Toolbox サーバーが起動して実行されていることを確認できます。

MCP Toolbox サーバーは、デフォルトでポート 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 にデプロイする Toolbox サービスの 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 ファイルをシークレットとしてアップロードします。

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 を使用して 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

これで、新しくデプロイしたツールをエージェントアプリケーションで使用する準備が整いました。

ツールボックスツールをエージェントに接続しましょう。

エージェントアプリケーションのソースはすでに作成されています。Cloud Run にデプロイしたばかりの新しい MCP Toolbox for Databases ツールを含めるように更新しましょう。

リポジトリのソースを使用して 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 に次の変数があります。

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 Toolbox for Databases をご覧ください。

AlloyDB と ADK 用の MCP ツールボックスを使用してマルチエージェント アプリを作成する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。