本頁面由 Cloud Translation API 翻譯而成。

運用 ADK、MCP Toolbox 和 AlloyDB 建構運動用品店服務專員 AI 助理

1. 簡介

建構項目

在本程式碼研究室中，您將瞭解如何建構運動用品商店服務專員 AI 助理。這款新一代 Agent AI 應用程式採用 ADK、MCP Toolbox 和 AlloyDB 技術，可協助使用者完成各種工作，包括：

使用自然語言搜尋產品。
尋找附近的商店，購買推薦產品。
下新單。
查看現有訂單狀態。
更新訂單，選擇偏好的運送方式。

課程內容

佈建及填入 PostgreSQL 適用的 AlloyDB 資料庫。
使用 AlloyDB for PostgreSQL 執行個體設定資料庫適用的 MCP 工具箱。
使用 Agent Development Kit (ADK) 設計及開發 AI 代理，協助處理運動用品店的查詢。
在雲端環境中測試代理程式和 MCP Toolbox for Databases。
運用 AlloyDB 的進階查詢功能，提供智慧型代理程式回覆。

軟硬體需求

如要完成本程式碼研究室，請務必符合以下條件：

Chrome 網路瀏覽器。
Gmail 帳戶。
已啟用計費功能的 Google Cloud 專案。

本程式碼研究室適合所有程度的開發人員，包括初學者。

2. 事前準備

本節將逐步說明在 Google Cloud 專案中進行初始設定的必要步驟，完成後即可開始建構 Sports Shop Agent AI 助理。

建立專案

在 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 連線，確保存取安全無虞且效能優異。您必須在 VPC 內分配私人 IP 範圍，供 Google 用於服務對等互連連線，連至 Google 管理的服務網路基礎架構。執行下列指令：

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 虛擬私有雲 (VPC) 網路就能與 Google 的受管理服務 (包括 AlloyDB) 安全地進行私密通訊。執行下列指令：

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 中部署的模型，您必須將 Vertex AI 權限授予 AlloyDB 服務代理程式。

首先，請先擷取 Google Cloud 專案編號，因為 IAM 繫結需要這個編號。

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

然後將權限授予 AlloyDB 服務代理：

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」，然後編輯並前往「Public IP connectivity」(公用 IP 連線) 區段。勾選「啟用公開 IP」核取方塊，然後輸入 Cloud Shell 機器的 IP 位址。

如要取得 Cloud Shell 機器的 IP，請前往 Cloud Shell 終端機，然後輸入指令「ifconfig | grep -A 1 eth0」。從結果中，將最後 2 位數替換為 0.0，並使用遮罩大小「/16」。例如「XX.XX.0.0/16」，其中 XX 為數字。

將這個 IP 貼到編輯執行個體頁面的「授權外部網路」文字方塊中。

注意：更新作業最多可能需要 3 分鐘

4. 載入資料庫

建立商店資料庫

現在可以建立資料庫，並載入運動用品商店的初始資料。

如要讓 psql 從 Cloud Shell 連線至私人 AlloyDB 執行個體，請使用 AlloyDB Auth Proxy。這項公用程式會透過安全通道連線至資料庫。(請參閱「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 終端機視窗中執行這項指令。Proxy 會在背景執行並轉送連線。

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

重要事項：請勿關閉這個終端機視窗，並讓 Proxy 保持執行狀態。請勿關閉。

在 Cloud Shell 中開啟新的終端機視窗 (點選頂端「Cloud Shell 終端機」分頁旁的「+」圖示)。

使用 psql 連線至 AlloyDB 執行個體：

psql -h 127.0.0.1 -U postgres

注意：系統提示時，請輸入您在建立叢集時為 postgres 使用者設定的密碼 (如果您直接按照文件操作，密碼為 alloydb)。

並為應用程式建立商店資料庫 (逐一執行指令)：

CREATE DATABASE store;
\c store
exit

原始碼

現在，請複製程式碼研究室的原始碼存放區。請先確認目前的位置是主目錄或合適的位置，再複製並執行下列指令：

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 訊息，您可以放心忽略這些訊息。如果傾印包含完整結構定義，這些通常與權限或現有物件有關。您會發現一些可忽略的警告和錯誤

5. 設定授權服務

在本節中，您將為應用程式設定授權服務。這項服務對於確保存取安全，以及防範 AI 代理程式中的提示注入漏洞至關重要。

首先，您要在 store 資料庫的 users 資料表中新增範例使用者。這個使用者將用於應用程式中的驗證。

前往控制台並導覽至 AlloyDB，選取主要執行個體，然後選取 AlloyDB Studio：

系統提示時，請使用您設定叢集時建立的憑證登入 AlloyDB Studio：

使用者名稱：「postgres」
資料庫：「store」
密碼：「alloydb」

在 SQL 編輯器中執行 INSERT 陳述式，將使用者新增至資料庫。變更姓名和電子郵件地址。

重要事項：

保留範例中的 LOCATION
使用您在 Google Cloud 控制台註冊的電子郵件地址

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」

現在，您要建立前端應用程式將使用的 OAuth 用戶端 ID，以便透過 Google 驗證使用者身分。

首先，請確認您有 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)"

然後依序前往「APIs and Services」(API 和服務) ->「Credentials」(憑證) ->「Create Credentials」(建立憑證) ->「OAuth Client ID」(OAuth 用戶端 ID)。

請使用下列資訊建立憑證：

應用程式類型：「網頁應用程式」
名稱：「Sports Shopping Agent AI App」(運動購物代理 AI 應用程式)

已授權的 JavaScript 來源：

網址 1：https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app

已授權的重新導向 URI：

網址 1：https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app

注意：https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app 是前端應用程式的預期部署網址，稍後會在程式碼研究室中設定。請務必將 [YOUR_PROJECT_NUMBER] 替換為您複製的實際編號。

重要事項：建立完成後，系統會顯示「OAuth 用戶端 ID」，有時也會顯示「用戶端密鑰」。將 OAuth 用戶端 ID 儲存在安全的地方，因為您會在後續步驟中設定前端時需要這個 ID。

6. MCP ToolBox for Databases 設定

Toolbox 位於應用程式的協調架構和資料庫之間，提供用於修改、發布或叫用工具的控制平面。這項功能提供集中式位置來儲存及更新工具，方便您管理工具，並在代理程式和應用程式之間共用工具，以及更新這些工具，不必重新部署應用程式。

MCP Toolbox for Databases 支援的資料庫之一是 AlloyDB，而我們已在上一節中佈建該資料庫，因此請繼續設定 Toolbox。

首先，您會在 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 版。在正式版環境中，請務必驗證並使用工具箱發布頁面的最新穩定版本。

前往 Cloud Shell 編輯器 (點選「編輯器」圖示即可從終端機切換)。

在同一個 sports-agent-adk-mcp-alloydb/src/toolbox 目錄中，您會找到名為 tools.yaml 的檔案。開啟這個檔案，然後使用上一個步驟中的 OAuth 用戶端 ID 和 Google Cloud 專案 ID 更新預留位置。

讓我們瞭解 tools.yaml

來源代表工具可互動的不同資料來源。來源代表工具可互動的資料來源。您可以在 tools.yaml 檔案的來源部分中，將來源定義為對應。一般來說，來源設定會包含連線及與資料庫互動所需的任何資訊。

工具會定義代理程式可執行的動作，例如讀取及寫入來源。工具代表代理程式可執行的動作，例如執行 SQL 陳述式。您可以在 tools.yaml 檔案的 tools 區段中，將工具定義為對應。一般來說，工具需要來源才能執行動作。

如要進一步瞭解如何設定 tools.yaml，請參閱這份說明文件。

執行 MCP Toolbox for Databases Server

執行下列指令 (從 mcp-toolbox 資料夾) 啟動伺服器：

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

現在，如果您在雲端以網頁預覽模式開啟伺服器，應該就能看到 Toolbox 伺服器已啟動並執行，且包含應用程式的所有工具。

MCP 工具箱伺服器預設會在通訊埠 5000 上執行。我們將使用 Cloud Shell 進行測試。

在 Cloud Shell 中按一下「網頁預覽」，如下所示：

按一下「變更通訊埠」，將通訊埠設為 5000，如下所示，然後按一下「變更並預覽」。

這應該會產生以下輸出內容：

資料庫適用的 MCP 工具包說明 Python SDK，方便您驗證及測試工具，詳情請參閱這篇文章。我們將略過這部分，直接進入下一節的 Agent 開發套件 (ADK)，並使用這些工具。

將 Toolbox 部署至 Cloud Run

如要讓 Toolbox 伺服器成為可與其他應用程式和 AI 代理程式整合的公開端點，請將其部署至 Cloud Run。如需在 Cloud Run 上代管工具箱的詳細操作說明，請參閱這篇文章。

返回 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 服務身分。我們也會確保這個服務帳戶具備正確的角色，也就是有權存取 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

這會開始將 Toolbox 伺服器連同設定的 tools.yaml 部署至 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

您現在可以在瀏覽器中開啟上方列出的服務網址。系統應會顯示我們稍早看到的「Hello World」訊息。此外，您也可以造訪下列網址，查看可用的工具：

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

您也可以從 Google Cloud 控制台前往 Cloud Run，即可在 Cloud Run 的服務清單中看到 Toolbox 服務。

7. 以 ADK 建構的代理程式

在本節中，您將使用 Agent Development Kit (ADK) 建構 AI 代理程式，並部署至 Cloud Run。

首先，請在專案中啟用必要 API，以便在 Cloud Run 上建構及部署 Agent，並與 Artifact Registry 和 Cloud Storage 互動。在 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)")

將權限指派給預設 Compute 服務帳戶：

# 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"

將 Agent 連線至工具

我們將 Agent 連線至 Tools。在 ADK 的脈絡中，「工具」代表提供給 AI 代理的特定功能，可讓 AI 代理執行動作，並與核心文字生成和推理能力以外的世界互動。

在本例中，我們現在要為 Agent 配備在 MCP Toolbox for Databases 中設定的工具。

使用 Cloud Shell 編輯器前往 sports-agent-adk-mcp-alloydb/src/backend/，然後使用下列程式碼編輯「finn_agent.py」檔案。請注意，我們使用的是上一步部署的 MCP ToolBox 伺服器 Cloud Run 服務網址：

在 Cloud Run 上部署 Agent

最後，您會將設定的 AI 代理程式部署至 Cloud Run，透過 HTTP 端點存取。

首先，請在 Artifact Registry 中建立 Docker 存放區，用於儲存 Agent 的容器映像檔。在 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 建構 Agent 的 Docker 映像檔。在複製專案的根目錄 (sports-agent-adk-mcp-alloydb/) 中執行下列指令：

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

現在請部署 Agent 服務。這項指令會建立 Cloud Run 服務、從 Artifact Registry 提取映像檔，並設定環境變數

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)

您應該會看到類似以下的輸出內容，表示 Agent 已成功部署：

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

您會看到類似以下的輸出內容：

「你好！我是 Finn，你的 AI 運動購物助理。我可以協助你尋找運動產品、裝備和器材。請問你今天需要哪方面的協助？

此時，您已成功驗證 AlloyDB、MCP Toolbox 和使用 ADK 建構的 Agent 部署作業。

8. 部署前端

在本節中，您將在 Cloud Run 上部署 AI 助理的對話式使用者介面。這個前端是使用 React 和 JavaScript 建構而成。

部署前，您需要使用已部署的 Agent 網址和 OAuth 用戶端 ID，更新前端的原始碼。

使用 Cloud Shell 編輯器前往 sports-agent-adk-mcp-alloydb/src/frontend/src/pages/，然後開啟 Home.jsx 檔案。您需要更新 Agent 的 Cloud Run 服務網址預留位置。然後將其替換為上一步中 Agent 的 Cloud Run 服務網址 (例如 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。

在根目錄 (sports-agent-adk-mcp-alloydb/) 的 Cloud Shell 終端機中執行下列指令，在 Artifact Registry 中為前端映像檔建立 Docker 存放區。

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

開啟網路瀏覽器，然後使用上一步中的服務網址，開啟由 AI 代理程式支援的新部署應用程式！

9. 執行我們的代理程式

體育用品商店的 AI 助理 Finn 已全面上線，隨時準備好協助你購物！

開啟網路瀏覽器，然後前往上一步中前端應用程式的服務網址。網址格式如下：https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app

前端載入後，按一下右上方的按鈕 (通常標示為「登入」或類似提示)，使用 Google 憑證進行驗證。這項操作會使用您先前設定的 OAuth 設定。

驗證成功後，即可與 Finn 互動！按一下「立即購物」按鈕，即可開始對話式購物體驗。

使用下列指令碼測試 AI 代理程式的各項功能。將這些提示逐一複製並貼到對話介面：

你好，Finn！
我想找適合超級越野跑的跑鞋
請提供 Ultra Glide 的詳細資訊
將 Ultra Glide、尺寸 40、顏色紅/灰加入我的購物清單
顯示我的購物清單
尋找附近的商店
請使用我的購物清單，向 Sports Diagonal Mar 下單
查看訂單狀態
請列出「Sports Diagonal Mar」商店的運送方式
將訂單 [YOUR_ORDER_NUMBER] 的運送方式變更為快速運送
查看訂單狀態
謝謝 Finn！

如要觀看已部署的 Finn 代理程式及其功能的示範影片，請參閱下方影片：

AlloyDB 支援的運動代理 AI 助理示範

10. 結果

執行上述指令碼後，您已成功驗證 ADK 代理程式的完整整合、與 AlloyDB 的連線，以及 MCP 工具箱的使用情形。本節將重點說明您實作的核心功能。

授權服務

資料庫適用的 MCP 工具箱可提供授權服務 (在本程式碼研究室中，具體來說是 Google 登入) 的同盟功能，用於驗證應用程式中的使用者。使用 MCP Toolbox 時，系統會使用 OAuth 用戶端 ID 驗證工具叫用時的使用者身分。

這項強大的驗證機制可有效防範提示詞注入攻擊，這類攻擊會嘗試規避或操縱代理程式的預期行為。詳情請參閱維基百科上有關提示注入的文章。

在本應用程式中，當使用者要求「查看訂單狀態」或「顯示我的購物清單」時，就會使用這項技術。這個代理程式的設計宗旨是只顯示通過驗證的使用者所下的訂單，防止未經授權者存取訂單資訊。

Vector Search

您的代理式應用程式會運用 PostgreSQL 適用的 AlloyDB 提供進階查詢功能，特別是透過向量搜尋。AlloyDB 支援使用 SQL 函式，直接在資料庫中產生線上嵌入項目。

這項強大功能可讓代理程式將使用者的自然語言輸入內容翻譯為數值嵌入表示法。接著，系統會根據這些嵌入內容，對產品目錄 (或其他相關資料) 執行相似度搜尋，提供高度相關的搜尋結果。

在應用程式中，當你詢問 Finn「我想找適合超級越野跑的跑鞋」時，就會體驗到這項技術。

地理空間功能 (PostGIS)

PostgreSQL 適用的 AlloyDB 完全相容於標準 PostgreSQL 功能。在本應用程式中，我們使用熱門的 PostgreSQL 擴充功能 PostGIS，為代理程式提供地理空間位置功能。

當你詢問代理程式「尋找我附近的商店」時，代理程式會執行工具，利用資料庫中的 PostGIS 索引，有效找出距離使用者指定或推斷位置最近的商店。

11. (選用) 測試 AlloyDB AI 自然語言轉 SQL 功能

本節將介紹 PostgreSQL 適用的 AlloyDB 的進階 Pre-GA 功能：自然語言轉 SQL。這項功能可讓您直接透過自然語言提示生成 SQL 查詢，在資料庫中運用 AI 的強大功能。

重要事項：這項功能尚未正式發布，因此您必須先註冊，並為 Google Cloud 專案、AlloyDB 叢集和資料庫啟用存取權。

申請存取權：請填寫這份表單，為專案申請存取權
說明文件：如要進一步瞭解如何運用 AlloyDB AI Natural Language to 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';

在 Agent 的「tools.yaml」中，你會看到名為「check-inventory-by-store-brand-category」的工具。這項工具會使用 AlloyDB 自然語言轉 SQL 功能：

開啟網路瀏覽器，然後使用服務網址開啟應用程式：「https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app」

接著，在對話介面中使用下列指令碼，測試這項新功能：

你好，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 應用程式

詳情請參閱產品文件：Agent Development Kit、MCP Toolbox for Databases 和 AlloyDB for PostgreSQL。