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

この Codelab について

最終更新: 6月 17, 2025

作成者: Author: Abirami Sukumaran

1. 概要

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

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

エージェント開発キット（ADK）

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

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

マルチエージェントシステムで考慮すべき点

まず、各エージェントの専門分野を適切に理解し、その理由を把握することが重要です。- 「特定のサブエージェントが必要である理由をご存じですか？」という質問にまず回答します。

次に、ルートエージェントと組み合わせて、各レスポンスをルーティングして解釈する方法について説明します。

3 つ目: エージェントルーティングには複数の種類があり、このドキュメントで確認できます。どちらがアプリケーションのフローに合っているかを確認します。また、マルチエージェントシステムのフロー制御に必要なさまざまなコンテキストと状態も確認します。

作成するアプリの概要

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

リノベーションの提案エージェント
許可証とコンプライアンスチェックエージェント
注文ステータス確認（データベース向け MCP ツールボックスを使用したツール）

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

許可とコンプライアンスエージェント: 許可とコンプライアンス関連のタスクを担当します。

Order Status Check Agent: AlloyDB に設定されている注文管理データベースで作業して、マテリアルの注文ステータスを確認します。このデータベース部分では、MCP Toolbox for AlloyDB を使用して、注文のステータス取得ロジックを実装します。

2. MCP

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

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

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

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

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

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

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

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

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

これは MCP より前の事実であることを明記する必要があります。

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

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

要件

ブラウザ（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/adk-renovation-agent/blob/main/agent.py

agent.py では、必要な依存関係をインポートし、.env ファイルから構成パラメータを取得し、このアプリケーションで作成する 3 つのサブエージェントをオーケストレートする root_agent を定義します。これらのサブエージェントのコア機能とサポート機能に役立つツールがいくつかあります。

Cloud Storage バケットがあることを確認する

これは、エージェントが生成した提案書を保存するためのものです。作成してアクセス権を付与すると、Vertex AI で作成したマルチエージェントシステムがアクセスできるようになります。手順は次のとおりです。

https://cloud.google.com/storage/docs/creating-buckets#console

バケットに「next-demo-store」など、任意の名前を付けます。.env ファイルの STORAGE_BUCKET の値を更新する必要があるため、メモしておいてください（ENV 変数の設定手順）。
ロケーション us-central1 に作成します。
バケットへのアクセスを設定するには、Cloud Storage コンソールでストレージバケットに移動します（この例では、バケット名は「next-demo-storage」です。https://console.cloud.google.com/storage/browser/next-demo-storage）。

[権限] > [プリンシパルの表示] > [アクセス権を付与] に移動します。プリンシパルに「allUsers」、ロールに「ストレージオブジェクトユーザー」を選択します。

Make sure to not enable "prevent public access". Since this is a demo/study application we are going with a public bucket. Remember to configure permission settings appropriately when you are building your application.

7. データベースの設定

ordering_agent が使用するツールの 1 つである「check_status」は、AlloyDB の注文データベースにアクセスして注文のステータスを取得します。このセクションでは、AlloyDB データベースクラスタとインスタンスを設定します。

クラスタとインスタンスを作成する

Cloud コンソールの AlloyDB ページに移動します。Cloud コンソールのほとんどのページは、コンソールの検索バーを使用して簡単に見つけることができます。
そのページで [クラスタを作成] を選択します。

次のような画面が表示されます。次の値を使用してクラスタとインスタンスを作成します（リポジトリからアプリケーションコードをクローンする場合は、値が一致していることを確認してください）。

クラスタ ID: "vector-cluster"
password: "alloydb"
PostgreSQL 16 互換 / 最新バージョンを推奨
Region: "us-central1"
ネットワーキング: 「default」

デフォルトのネットワークを選択すると、次のような画面が表示されます。

[接続の設定] を選択します。

[自動的に割り振られた IP 範囲を使用する] を選択し、[続行] をクリックします。情報を確認したら、[CREATE CONNECTION] を選択します。

6. 重要: インスタンス ID（クラスタ / インスタンスの構成時に確認できます）を

vector-instance。変更できない場合は、今後のすべての参照でインスタンス ID を使用してください。

Toolbox の設定に備えて、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 のすべての注文データベースインタラクションのコントロールプレーンとして機能する MCP Toolbox for Databases を設定しましょう。

8. データベース向け MCP ツールボックスの設定

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

データベース向け 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 について理解する

ソースは、ツールが操作できるさまざまなデータソースを表します。Source は、ツールが操作できるデータソースを表します。ソースは、tools.yaml ファイルの sources セクションでマップとして定義できます。通常、ソース構成には、データベースとの接続と操作に必要な情報が含まれます。

ツールは、エージェントが実行できるアクション（ソースへの読み取りや書き込みなど）を定義します。ツールは、エージェントが実行できるアクション（SQL ステートメントの実行など）を表します。ツールは、tools.yaml ファイルの tools セクションでマップとして定義できます。通常、ツールは対象となるソースを必要とします。

tools.yaml の構成の詳細については、こちらのドキュメントをご覧ください。

データベース向け MCP ツールボックスサーバーを実行する

次のコマンドを実行して（mcp-toolbox フォルダから）サーバーを起動します。

./toolbox --tools-file "tools.yaml"

クラウドでウェブプレビューモードでサーバーを起動すると、get-order-data という新しいツールを使用して Toolbox サーバーが稼働していることを確認できます。

MCP ツールボックスサーバーは、デフォルトでポート 5000 で実行されます。Cloud Shell を使用して、これをテストしてみましょう。

以下に示すように、Cloud Shell で [ウェブでプレビュー] をクリックします。

[ポートを変更] をクリックし、下に示すようにポートを 5000 に設定して、[変更してプレビュー] をクリックします。

出力は次のようになります。

MCP Toolkit for Databases には、ツールを検証してテストするための Python SDK が記載されています。この SDK については、こちらで説明しています。次のセクションでは、これらのツールを使用するエージェント開発キット（ADK）に直接進みます。

Toolbox を Cloud Run にデプロイする

まず、MCP Toolbox サーバーを 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 ファイルを変更します。

データベース向け MCP ツールボックスの依存関係を requirements.txt に含める

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>>
STORAGE_BUCKET=next-demo-store <<or your storage bucket name>>

プレースホルダは、独自の値に置き換えます。

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 Toolbox for Databases を使用してマルチエージェントアプリケーションが正常に作成されました。詳細については、プロダクトのドキュメント（エージェント開発キットとデータベース向け MCP ツールボックス）をご覧ください。

誤りを報告

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