このページは Cloud Translation API によって翻訳されました。

ADK、MCP Toolbox、AlloyDB を使用してスポーツショップエージェント AI アシスタントを構築する

1. はじめに

作成するアプリの概要

この Codelab では、スポーツ用品店の AI アシスタントを構築する方法を学びます。ADK、MCP ツールボックス、AlloyDB を搭載した次世代のエージェント AI アプリケーションは、次のようなさまざまなタスクでユーザーを支援します。

自然言語を使用して商品を検索する。
おすすめの商品を購入できる近くの店舗を探す。
新規注文を行う。
既存の注文ステータスを確認します。
ご希望の配送方法で注文を更新します。

学習内容

AlloyDB for PostgreSQL データベースのプロビジョニングとデータの入力。
AlloyDB for PostgreSQL インスタンスで MCP Toolbox for Databases を設定する。
エージェント開発キット（ADK）を使用して、スポーツ用品店の問い合わせに対応する AI エージェントを設計、開発します。
クラウド環境でエージェントと MCP ツールボックス for Databases をテストする。
AlloyDB の高度なクエリ機能を活用して、インテリジェントなエージェント応答を実現します。

必要なもの

この Codelab を完了するには、次の準備が必要です。

Chrome ウェブブラウザ。
Gmail アカウント。
課金を有効にした Google Cloud プロジェクト

この Codelab は、初心者を含むあらゆるレベルのデベロッパーを対象としています。

2. 始める前に

このセクションでは、Sports Shop Agent AI アシスタントの構築を開始する前に Google Cloud プロジェクトで必要な初期設定について説明します。

プロジェクトの作成

Google Cloud コンソールのプロジェクト選択ページで、Google Cloud プロジェクトを選択または作成します。
Cloud プロジェクトに対して課金が有効になっていることを確認します。詳しくは、プロジェクトで課金が有効になっているかどうかを確認する方法をご覧ください。
このリンクをクリックして、Cloud Shell をアクティブにします。Cloud Shell で対応するボタンをクリックすると、Cloud Shell ターミナル（クラウドコマンドの実行用）とエディタ（プロジェクトのビルド用）を切り替えることができます。

Cloud Shell に接続したら、次のコマンドを使用して、すでに認証が完了しており、プロジェクトがプロジェクト ID に設定されていることを確認します。

gcloud auth list

Cloud Shell で次のコマンドを実行して、gcloud コマンドがプロジェクトを認識していることを確認します。

gcloud config list project

変数 PROJECT_ID を設定します。次のコマンドを使用して設定します。

export PROJECT_ID=[YOUR_PROJECT_ID]

gcloud config set project $PROJECT_ID

次のコマンドを実行して、次の API を有効にします。

gcloud services enable alloydb.googleapis.com \
                       compute.googleapis.com \
                       cloudresourcemanager.googleapis.com \
                       servicenetworking.googleapis.com \
                       vpcaccess.googleapis.com \
                       aiplatform.googleapis.com

3. AlloyDB インスタンスを作成する

このセクションでは、AlloyDB データベースクラスタとインスタンスを設定し、AI エージェントに必要なネットワーキングと権限を構成します。

まず、Cloud Shell ターミナルで次のコマンドを実行して、AlloyDB クラスタを作成します。

gcloud alloydb clusters create alloydb-cluster \
    --password=alloydb\
    --network=default \
    --region=us-central1 \
    --database-version=POSTGRES_16

AlloyDB は、安全で高性能なアクセスにプライベート IP 接続を使用します。Google が Google マネージドサービスネットワーキングインフラストラクチャへのサービスピアリング接続に使用するプライベート IP 範囲を VPC 内に割り当てる必要があります。次のコマンドを実行します。

gcloud compute addresses create peering-range-for-alloydb \
    --global \
    --purpose=VPC_PEERING \
    --prefix-length=16 \
    --description="Automatically allocated IP range for service networking" \
    --network=default

次に、VPC サービスピアリング接続を作成します。これにより、Google Cloud Virtual Private Cloud（VPC）ネットワークは、AlloyDB などの Google のマネージドサービスと安全かつプライベートに通信できます。次のコマンドを実行します。

gcloud services vpc-peerings connect \
--service=servicenetworking.googleapis.com \
--ranges=peering-range-for-alloydb \
--network=default

次に、AlloyDB クラスタ内にプライマリインスタンスを作成します。これは、アプリケーションが接続する実際のデータベースエンドポイントです。次のコマンドを実行して AlloyDB インスタンスを作成します。

gcloud alloydb instances create alloydb-inst \
     --instance-type=PRIMARY \
     --cpu-count=2 \
     --region=us-central1 \
     --cluster=alloydb-cluster \
     --availability-type=ZONAL \
     --ssl-mode=ALLOW_UNENCRYPTED_AND_ENCRYPTED

注: インスタンスの作成には約 10 分かかります。このオペレーションが完了するまで待ってから、続行してください。

Vertex AI のインテグレーションを有効にする

AlloyDB インスタンスでベクトル検索クエリ（セマンティック検索などの AI 機能に不可欠）を実行し、Vertex AI にデプロイされたモデルを呼び出すには、AlloyDB サービスエージェントに Vertex AI 権限を付与する必要があります。

まず、IAM バインディングに必要な Google Cloud プロジェクト番号を取得します。

PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
gcloud projects describe $PROJECT_ID --format="value(projectNumber)"

次に、AlloyDB サービスエージェントに Vertex AI 権限を付与します。

gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:service-$PROJECT_NUMBER@gcp-sa-alloydb.iam.gserviceaccount.com" \
--role="roles/aiplatform.user"

パブリック IP を有効にする

次の手順に備えて、AlloyDB インスタンスでパブリック IP 接続を有効にします。

コンソールで、画面中央上部の検索フィールドに「alloydb」と入力し、編集して [パブリック IP 接続] セクションに移動します。[パブリック IP を有効にする] チェックボックスをオンにして、Cloud Shell マシンの IP アドレスを入力します。

Cloud Shell マシンの IP を取得するには、Cloud Shell ターミナルに移動して「ifconfig | grep -A 1 eth0」というコマンドを入力します。結果から、最後の 2 桁をマスクサイズ「/16」で 0.0 に置き換えます。たとえば、「XX.XX.0.0/16」のようになります（XX は数字）。

この IP を、インスタンスの編集ページの [承認済み外部ネットワーク] の [ネットワーク] テキストボックスに貼り付けます。

注: 更新オペレーションには 3 分ほどかかることがあります

4. データベースを読み込む

ストアデータベースを作成する

次に、データベースを作成して、スポーツ用品店の初期データを読み込みます。

Cloud Shell からプライベート AlloyDB インスタンスに接続できるようにするには、AlloyDB Auth Proxy を使用します。psqlこのユーティリティは、データベースへの接続を安全にトンネリングします。（AlloyDB Auth Proxy を参照）

次のコマンドを使用して AlloyDB Auth Proxy をダウンロードします。

wget https://storage.googleapis.com/alloydb-auth-proxy/v1.13.3/alloydb-auth-proxy.linux.amd64 -O alloydb-auth-proxy

実行可能にする

chmod +x alloydb-auth-proxy

このコマンドは、最初の Cloud Shell ターミナルウィンドウで実行します。プロキシはバックグラウンドで実行され、接続を転送します。

./alloydb-auth-proxy "projects/$PROJECT_ID/locations/us-central1/clusters/alloydb-cluster/instances/alloydb-inst" --public-ip

重要: このターミナルウィンドウを開いたまま、プロキシを実行します。閉じないでください。

Cloud Shell で新しいターミナルウィンドウを開きます（上部の [Cloud Shell ターミナル] タブの横にある + アイコンをクリックします）。

psql を使用して AlloyDB インスタンスに接続します。

psql -h 127.0.0.1 -U postgres

注: プロンプトが表示されたら、クラスタの作成時に postgres ユーザーに設定したパスワードを入力します（ドキュメントに沿って操作している場合は、パスワードは alloydb です）。

アプリケーションのストアデータベースを作成します（コマンドを 1 つずつ実行します）。

CREATE DATABASE store;
\c store
exit

Source Code

次に、この Codelab のソースコードリポジトリのクローンを作成します。クローンを作成する前に、ホームディレクトリまたは適切な場所に移動し、次のコマンドを実行します。

git clone https://github.com/mtoscano84/sports-agent-adk-mcp-alloydb.git

データベースにデータを入力する

クローン作成したプロジェクトの data フォルダに移動して、データベースダンプファイルにアクセスします。

cd sports-agent-adk-mcp-alloydb/data

次に、リポジトリの store_backup.sql ファイルを使用して、サンプルデータセットを store データベースにインポートします。

psql -h 127.0.0.1 -U postgres -d store -f store_backup.sql

注: このインポート中に WARNING メッセージと ERROR メッセージが表示されることがありますが、この Codelab では無視してかまいません。ダンプに完全なスキーマが含まれている場合、これらは多くの場合、すでに存在する権限またはオブジェクトに関連しています。無視できる警告とエラーが表示されます。

5. Authorization Service の設定

このセクションでは、アプリケーションの認可サービスを設定します。このサービスは、アクセスを保護し、AI エージェントのプロンプトインジェクションの脆弱性から保護するために不可欠です。

まず、store データベースの users テーブルにサンプルユーザーを追加します。このユーザーは、アプリケーションの認証に使用されます。

コンソールに移動して AlloyDB に移動し、プライマリインスタンスと AlloyDB Studio を選択します。

プロンプトが表示されたら、クラスタの設定時に作成した認証情報を使用して AlloyDB Studio にログインします。

ユーザー名: 「postgres」
データベース: "store"
パスワード: 「alloydb」

SQL エディタで INSERT ステートメントを実行して、ユーザーをデータベースに追加します。名前、姓、メールアドレスを変更します。

重要:

例の LOCATION はそのままにします。
Google Cloud Console への登録に使用しているメールアドレスと同じものを使用します。

INSERT INTO users (user_id, first_name, last_name, Address, city, postal_code, location, email)
VALUES (10,'John', 'Doe', 'Carrer Muntaner 39', 'Barcelona', '08019', '0101000020E61000008AAE0B3F38B144401FBB0B9414780140', 'john.doe@example.com');

次に、プロジェクトの OAuth 同意画面を構成する必要があります。この画面は、アプリがユーザーの Google アカウントへのアクセスをリクエストしたときにユーザーに表示され、アプリのブランドを定義します。

コンソールで、[API とサービス]、[Google OAuth 同意] に移動します。

アプリケーションのブランドを作成するには、次の情報を入力します。

アプリ名: 「Sports Shopping Agent AI」
ユーザーサポートメール: 「YOUR_EMAIL」
対象ユーザー: 「外部」
連絡先情報: "YOUR_EMAIL"

次に、フロントエンドアプリケーションが Google でユーザー ID を検証するために使用する OAuth クライアント ID を作成します。

まず、Google Cloud プロジェクト番号があることを確認します。これは、リダイレクト URI を正しく構成するために必要です。Cloud Shell ターミナルで次のコマンドを実行します。

この Cloud Shell ターミナルウィンドウで PROJECT_ID 変数が設定されていない場合は、次のコマンドを実行します。

export PROJECT_ID=[YOUR_PROJECT_ID]

次のコマンドを使用して PROJECT_NUMBER を取得します。

gcloud projects describe $PROJECT_ID --format="value(projectNumber)"

[API とサービス] -> [認証情報] -> [認証情報を作成] -> [OAuth クライアント ID] に移動します。

次の情報を使用して認証情報を作成します。

アプリケーションタイプ: 「ウェブアプリケーション」
名前: 「Sports Shopping Agent AI App」

承認済みの JavaScript 生成元:

URL1: https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app

承認済みのリダイレクト URI:

URL1: https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app

注: URL https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app は、この Codelab の後半で設定するフロントエンドアプリケーションの想定されるデプロイ URL です。[YOUR_PROJECT_NUMBER] は、コピーした実際の番号に置き換えてください。

重要: 作成後、ポップアップに OAuth クライアント ID と、場合によってはクライアントシークレットが表示されます。OAuth クライアント ID は安全な場所に保存してください。この ID は、後のステップでフロントエンドを構成する際に必要になります。

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

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

データベース向け MCP ツールボックスでサポートされているデータベースの 1 つが AlloyDB であり、前のセクションで AlloyDB をすでにプロビジョニングしているため、ツールボックスの設定に進みましょう。

まず、Cloud Shell 環境に MCP Toolbox サーバーをローカルに設定して、その機能を確認します。

Cloud Shell ターミナルで、クローン作成されたプロジェクトリポジトリ内の toolbox フォルダに移動します。

cd sports-agent-adk-mcp-alloydb/src/toolbox

次のコマンドを実行して、Toolbox バイナリをダウンロードし、実行権限を付与します。

# 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

注: ここではバージョン 0.7.0 を指定します。本番環境では、必ず Toolbox リリースページで最新の安定版を確認して使用してください。

Cloud Shell エディタに移動します（エディタアイコンをクリックしてターミナルから切り替えることができます）。

同じ sports-agent-adk-mcp-alloydb/src/toolbox ディレクトリに、tools.yaml という名前のファイルがあります。このファイルを開き、前の手順で取得した OAuth クライアント ID と Google Cloud プロジェクト ID でプレースホルダを更新します。

tools.yaml について

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

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

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

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

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

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

クラウドでウェブプレビューモードでサーバーを開くと、アプリケーションのすべてのツールを備えた Toolbox サーバーが起動して実行されていることを確認できます。

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

Cloud Shell で [ウェブでプレビュー] をクリックします。

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

次のような出力が表示されます。

データベース用 MCP ツールキットには、ツールを検証してテストするための Python SDK が含まれています。これについては、こちらで説明しています。次のセクションでは、これらのツールを利用する Agent Development Kit（ADK）について説明します。

ツールボックスを Cloud Run にデプロイする

Toolbox サーバーを他のアプリケーションや AI エージェントと統合できるパブリックエンドポイントとしてアクセスできるようにするには、Cloud Run にデプロイします。Cloud Run で Toolbox をホストする詳細な手順については、こちらをご覧ください。

Cloud Shell ターミナルに戻り、ツールボックスフォルダに移動します。

cd sports-agent-adk-mcp-alloydb/src/toolbox

PROJECT_ID 環境変数が Google Cloud プロジェクト ID に設定されていることを確認します。

export PROJECT_ID=$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 へのアクセス権と AlloyDB との通信権限）があることも確認しています。

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/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 ファイルをシークレットとしてアップロードします。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

最後に、次のコマンドを使用して Toolbox サーバーを 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 [sports-store-agent-ai] region [us-central1]
OK Deploying... Done.
  OK Creating Revision...
  OK Routing traffic...
  OK Setting IAM Policy...
Done.
Service [toolbox] revision [toolbox-00002-dn2] has been deployed and is serving 100 percent of traffic.
Service URL: https://toolbox-[YOUR_PROJECT_NUMBER].us-central1.run.app

上記のサービス URL をブラウザで開くことができます。先ほど確認した「Hello World」というメッセージが表示されます。また、次の URL にアクセスして、利用可能なツールを確認することもできます。

https://toolbox-[YOUR_PROJECT_NUMBER].us-central1.run.app/api/toolset

Google Cloud コンソールから Cloud Run にアクセスすることもできます。Cloud Run のサービスリストに Toolbox サービスが表示されます。

7. ADK で構築されたエージェント

このセクションでは、エージェント開発キット（ADK）を使用して構築した AI エージェントを Cloud Run にデプロイします。

まず、Cloud Run でエージェントをビルドしてデプロイし、Artifact Registry と Cloud Storage を操作するために、プロジェクトで必要な API を有効にします。Cloud Shell ターミナルで次のコマンドを実行します。

gcloud services enable artifactregistry.googleapis.com \
                       cloudbuild.googleapis.com \
                       run.googleapis.com \
                       storage.googleapis.com

次に、プロジェクトのデフォルトの Compute サービスアカウントに必要な権限を割り当てます。まず、Cloud Shell ターミナルで次のコマンドを実行して PROJECT_NUMBER を取得します。

PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")

デフォルトのコンピューティングサービスアカウントに権限を割り当てます。

# Grant Cloud Run service account access to GCS
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role="roles/storage.admin"

gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role="roles/run.admin"

gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role="roles/artifactregistry.writer"

gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER@cloudbuild.gserviceaccount.com" \
--role="roles/artifactregistry.repoAdmin"

# Grant Vertex AI User role to the service account
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role="roles/aiplatform.user"

# Grant Vertex AI Model User role to the service account
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role="roles/aiplatform.modelUser"

エージェントをツールに接続する

エージェントをツールに接続します。ADK のコンテキストでは、ツールは AI エージェントに提供される特定の機能を表します。これにより、エージェントはコアのテキスト生成と推論の能力を超えて、アクションを実行し、世界とやり取りできます。

この例では、データベース用 MCP ツールボックスで構成したツールをエージェントに装備します。

Cloud Shell エディタを使用して、sports-agent-adk-mcp-alloydb/src/backend/ に移動し、次のコードを使用して「finn_agent.py」ファイルを編集します。前の手順でデプロイした MCP ToolBox サーバーの Cloud Run サービス URL を使用していることに注意してください。

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

最後に、構成した AI エージェントを Cloud Run にデプロイし、HTTP エンドポイント経由でアクセスできるようにします。

まず、Artifact Registry に Docker リポジトリを作成して、エージェントのコンテナイメージを保存します。Cloud Shell で次のコマンドを実行します。

gcloud artifacts repositories create finn-agent-images \
    --repository-format=docker \
    --location=us-central1 \
    --project=$PROJECT_ID \
    --description="Repository for finn-agent images"

次に、Cloud Build を使用してエージェントの Docker イメージをビルドします。クローン作成したプロジェクトのルートディレクトリ（sports-agent-adk-mcp-alloydb/）から次のコマンドを実行します。

gcloud builds submit src/backend/ --tag us-central1-docker.pkg.dev/$PROJECT_ID/finn-agent-images/finn-agent

次に、エージェントサービスをデプロイします。このコマンドは、Cloud Run サービスを作成し、Artifact Registry からイメージを pull して、環境変数を構成します。

gcloud run deploy finn-agent \
    --image us-central1-docker.pkg.dev/$PROJECT_ID/finn-agent-images/finn-agent \
    --platform managed \
    --allow-unauthenticated \
    --region us-central1 \
    --project $PROJECT_ID --set-env-vars="GOOGLE_CLOUD_PROJECT=$PROJECT_ID,GOOGLE_CLOUD_LOCATION=us-central1,GOOGLE_GENAI_USE_VERTEXAI=TRUE"

注: GOOGLE_CLOUD_PROJECT（シェル変数 $PROJECT_ID を使用）などの環境変数を動的に設定しています。

次のような出力が表示され、エージェントのデプロイが成功したことが示されます。

Deploying container to Cloud Run service [finn-agent] in project [sports-store-agent-ai] region [us-central1]
OK Deploying... Done.
  OK Creating Revision...
  OK Routing traffic...
  OK Setting IAM Policy...
Done.
Service [finn-agent] revision [finn-agent-00005-476] has been deployed and is serving 100 percent of traffic.
Service URL: https://finn-agent-359225437509.us-central1.run.app

最後に、Cloud Shell ターミナルから次の curl コマンドを実行して、エージェントをテストします。

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"message":"Hello"}' \
  https://finn-agent-[YOUR_PROJECT_NUMBER].us-central1.run.app/chat

次のような出力が表示されます。

「こんにちは。私は AI スポーツショッピングアシスタントの Finn です。スポーツ用品、ギア、用具の検索をお手伝いいたします。本日はどのようなご用件でしょうか？」

これで、AlloyDB、MCP ツールボックス、ADK を使用して構築したエージェントのデプロイが正常に検証されました。

8. フロントエンドをデプロイする

このセクションでは、AI アシスタントの会話型ユーザーインターフェースを Cloud Run にデプロイします。このフロントエンドは React と JavaScript を使用して構築されています。

デプロイする前に、デプロイされたエージェントの URL と OAuth クライアント ID を使用して、フロントエンドのソースコードを更新する必要があります。

Cloud Shell エディタを使用して sports-agent-adk-mcp-alloydb/src/frontend/src/pages/ に移動し、Home.jsx ファイルを開きます。エージェントの Cloud Run サービス URL のプレースホルダを更新する必要があります。次に、前の手順で取得したエージェントの Cloud Run サービス URL（例: https://finn-agent-[YOUR_PROJECT_NUMBER].us-central1.run.app）。

次に、sports-agent-adk-mcp-alloydb/src/frontend/src/components/ に移動して GoogleSignInButton.jsx ファイルを開きます。このファイルは、「認証サービスのセットアップ」セクションで取得した OAuth クライアント ID で更新します。

Cloud Run にフロントエンドをデプロイする

これでフロントエンドアプリケーションが構成されたので、Cloud Run にデプロイする準備が整いました。

Cloud Shell ターミナルでルートディレクトリ（sports-agent-adk-mcp-alloydb/）から次のコマンドを実行して、フロントエンドイメージ用の Docker リポジトリを Artifact Registry に作成します。

gcloud artifacts repositories create finn-frontend-images \
    --repository-format=docker \
    --location=us-central1 \
    --project=$PROJECT_ID \
    --description="Repository for finn-frontend images"

次に、Cloud Build を使用して、フロントエンドアプリケーションの Docker イメージをビルドします。プロジェクトのルートディレクトリから次のコマンドを実行します。

gcloud builds submit src/frontend/ --tag us-central1-docker.pkg.dev/$PROJECT_ID/finn-frontend-images/finn-frontend

最後に、次のコマンドを使用してフロントエンドを Cloud Run にデプロイします。

gcloud run deploy finn-frontend \
    --image us-central1-docker.pkg.dev/$PROJECT_ID/finn-frontend-images/finn-frontend \
    --platform managed \
    --allow-unauthenticated \
    --region us-central1 \
    --project $PROJECT_ID

次のような出力が表示され、フロントエンドのデプロイが成功したことがわかります。

Deploying container to Cloud Run service [finn-frontend] in project [sport-store-agent-ai] region [us-central1]
OK Deploying... Done.
  OK Creating Revision...
  OK Routing traffic...
  OK Setting IAM Policy...
Done.
Service [finn-frontend] revision [finn-frontend-00002-mwc] has been deployed and is serving 100 percent of traffic.
Service URL: https://finn-frontend-535807247199.us-central1.run.app

ウェブブラウザを開き、前の手順のサービス URL を使用して、AI エージェントを搭載した新しくデプロイされたアプリケーションを開きます。

9. エージェントを実行する

スポーツ用品店の AI アシスタント Finn が完全にデプロイされ、購入をサポートできるようになりました。

ウェブブラウザを開き、前の手順で取得したフロントエンドアプリケーションのサービス URL に移動します。URL は https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app の形式になります。

フロントエンドが読み込まれたら、右上のボタン（通常は [ログイン] などのラベルが付いています）をクリックして、Google の認証情報を使用して認証します。このアクションでは、以前に設定した OAuth 構成が使用されます。

認証が完了すると、Finn とのやり取りを開始できます。[今すぐ購入] ボタンをクリックして、会話型ショッピングを開始します。

次のスクリプトを使用して、AI エージェントのさまざまな機能をテストします。これらのプロンプトを 1 つずつコピーして、チャットインターフェースに貼り付けます。

Hello Finn !
ウルトラトレイル用のランニングシューズを探しています
Ultra Glide について詳しく教えてください
ショッピングリストに Ultra Glide のサイズ 40、色 Red/Grey を追加して
ショッピングリストを見る
近くの店舗を探す
ショッピングリストにある Sports Diagonal Mar の商品を注文して
注文のステータスを確認する
Sports Diagonal Mar の配送方法を教えてください
注文 [YOUR_ORDER_NUMBER] の配送方法を速達に変更してください
注文のステータスを確認する
Finn さん、ありがとうございます。

デプロイされた Finn Agent とその機能のデモ動画については、以下をご覧ください。

AlloyDB を活用したスポーツエージェント AI アシスタントのデモ

10. 結果

前のスクリプトを実行すると、ADK エージェントの完全な統合、AlloyDB への接続、MCP ツールボックスの利用が正常に検証されます。このセクションでは、実装したコア機能について説明します。

承認サービス

MCP Toolbox for Databases には、認可サービス（この Codelab では特に Google ログイン）を連携して、アプリケーション内のユーザーを認証する機能が用意されています。MCP Toolbox では、ツールが呼び出されるときに、OAuth クライアント ID を使用してユーザー ID が検証されます。

この堅牢な認証メカニズムは、悪意のある入力がエージェントの意図した動作をバイパスまたは操作しようとする攻撃であるプロンプトインジェクションからエージェントアプリケーションを保護する優れたソリューションです。詳しくは、Wikipedia の記事「プロンプトインジェクション」をご覧ください。

このアプリケーションでは、ユーザーが「注文のステータスを確認して」や「ショッピングリストを表示して」とリクエストしたときに、この手法が使用されます。エージェントは、認証済みユーザーに属する注文のみを表示するように設計されており、注文情報への不正アクセスを防ぎます。

ベクトル検索

エージェントアプリケーションは、AlloyDB for PostgreSQL を活用して、特にベクトル検索を通じて高度なクエリ機能を提供します。AlloyDB は、SQL 関数を使用してデータベース内で直接オンラインエンベディング生成をサポートしています。

この強力な機能により、エージェントはユーザーの自然言語入力を数値エンベディング表現に変換できます。その後、これらのエンベディングに基づいて商品カタログ（またはその他の関連データ）に対して類似性検索を実行し、関連性の高い検索結果を表示できます。

この手法は、アプリで「ウルトラトレイル用のランニングシューズを探しています」と Finn に尋ねたときに体験できます。

地理空間機能（PostGis）

AlloyDB for PostgreSQL は、標準の PostgreSQL 機能との 100% の互換性を維持しています。このアプリケーションでは、一般的な PostgreSQL 拡張機能である PostGIS を使用して、エージェントに地理空間位置情報機能を提供します。

エージェントに「近くの店舗を探して」と尋ねると、エージェントはデータベース内の PostGIS インデックスを活用するツールを実行し、ユーザーが指定した場所または推測された場所に最も近い店舗を効率的に見つけます。

11. （省略可）AlloyDB AI の自然言語から SQL への変換をテストする

このセクションでは、AlloyDB for PostgreSQL の高度な Pre-GA 機能である Natural Language to SQL について説明します。この機能を使用すると、自然言語プロンプトから SQL クエリを直接生成し、データベース内の AI の力を活用できます。

重要: これは一般提供前の機能であるため、登録して、Google Cloud プロジェクト、AlloyDB クラスタ、データベースへのアクセスを有効にする必要があります。

アクセスに登録する: プロジェクトのアクセス権をリクエストするには、こちらのフォームに記入してください。
ドキュメント: AlloyDB AI の自然言語から SQL への変換の活用について詳しくは、公式ドキュメントをご覧ください。

登録してプロジェクトのアクセス権を確認したら、AlloyDB Studio で次の手順に進みます。

クラスタの作成時に作成した認証情報を使用して AlloyDB にログインします。

ユーザー名: 「postgres」
データベース: "store"
パスワード: 「alloydb」

1- alloydb_ai_nl 拡張機能を作成します。この拡張機能は、AlloyDB AI の自然言語機能に必要な関数を提供します。

CREATE EXTENSION alloydb_ai_nl cascade;

2- アプリケーションの構成を作成します。構成は、AI モデルがデータベースを理解するために使用するスキーマコンテキストを定義します。

SELECT
 alloydb_ai_nl.g_create_configuration(
   'finn_app_config'        -- configuration_id
 );

3- スキーマ / テーブルを構成に登録します。アプリケーションのエージェントがやり取りする特定のテーブルとスキーマを構成に追加します。

SELECT alloydb_ai_nl.g_manage_configuration(
   operation => 'register_table_view',
   configuration_id_in => 'finn_app_config',
   table_views_in=>'{public.products, public.products_variants, public.orders, public.orders_items, public.users, public.inventory, public.stores}'
);

4- スキーマ / テーブルのコンテキストを生成します。このステップでは、登録されたテーブルを処理して、AI モデルに必要なコンテキストを生成します。この処理には 2 ～ 3 分ほどかかります。

SELECT alloydb_ai_nl.generate_schema_context(
 'finn_app_config',
 TRUE
);

5- 特定のテーブルと列の自動生成されたコンテキストを確認します（省略可）。生成されたコンテキストを検査して、AI モデルがスキーマをどのように解釈するかを理解できます。

SELECT object_context
FROM alloydb_ai_nl.generated_schema_context_view
WHERE schema_object = 'public.inventory';


SELECT object_context
FROM alloydb_ai_nl.generated_schema_context_view
WHERE schema_object = 'public.products.name';


SELECT object_context
FROM alloydb_ai_nl.generated_schema_context_view
WHERE schema_object = 'public.products.popularity_score';

エージェントの「tools.yaml」に「check-inventory-by-store-brand-category」というツールがあります。このツールは、AlloyDB の自然言語から SQL への変換を使用します。

ウェブブラウザを開き、サービス URL を使用してアプリケーションを開きます（https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app）。

次に、チャットインターフェースで次のスクリプトを使用して、この新機能をテストします。

Hello Finn !
「Sports Diagonal Mar」店舗の Salomon のランニングカテゴリ商品の在庫の合計数量はどれくらいですか？

AlloyDB AI が自然言語入力から生成した実際の SQL クエリを確認するには、AlloyDB Studio に戻って次のクエリを実行します。

SELECT
   alloydb_ai_nl.get_sql(
       'finn_app_config',
       'What is the total quantity of category Running products of Salomon in stock at the "Sports Diagonal Mar" store?'
   ) ->> 'sql';

これにより、AlloyDB AI によって生成された SQL ステートメントが表示されます。

12. クリーンアップ

このラボで使用したリソースについて、Google Cloud アカウントに課金されないようにするには、次の操作を行います。

Google Cloud コンソールで、[リソースの管理] ページに移動します。
プロジェクトリストで、削除するプロジェクトを選択し、[削除] をクリックします。
ダイアログでプロジェクト ID を入力し、[シャットダウン] をクリックしてプロジェクトを削除します。

13. 完了

これで、ADK、MCP Toolbox for Databases、AlloyDB for PostgreSQL を使用して、データドリブンエージェント AI アプリケーションが正常に作成されました。

詳細については、プロダクトドキュメント（エージェント開発キット、データベース向け MCP ツールボックス、AlloyDB for PostgreSQL）をご覧ください。

ADK、MCP Toolbox、AlloyDB を使用してスポーツ ショップ エージェント AI アシスタントを構築する