此页面由 Cloud Translation API 翻译。

使用 ADK、MCP Toolbox 和 AlloyDB 构建体育用品商店智能体 AI 助理

1. 简介

构建内容

在此 Codelab 中，您将学习如何构建体育用品商店代理 AI 助理。这款由 ADK、MCP Toolbox 和 AlloyDB 提供支持的新一代 Agent AI 应用将协助用户完成各种任务，包括：

使用自然语言搜索商品。
查找附近的商店以购买推荐商品。
下单。
检查现有订单状态。
使用首选配送方式更新订单。

学习内容

预配和填充 AlloyDB for PostgreSQL 数据库。
为 AlloyDB for PostgreSQL 实例设置 MCP Toolbox for Databases。
使用智能体开发套件 (ADK) 设计和开发 AI 智能体，以帮助处理体育用品商店的查询。
在云环境中测试代理和 MCP Toolbox for Databases。
利用 AlloyDB 的高级查询功能实现智能代理响应。

所需条件

要完成本 Codelab，您需要：

Chrome 网络浏览器。
Gmail 账号。
启用了结算功能的 Google Cloud 项目。

此 Codelab 适用于各种水平的开发者，包括新手。

2. 准备工作

本部分将引导您完成 Google Cloud 项目中所需的初始设置，然后您才能开始构建 Sports Shop Agent AI 助理。

创建项目

在 Google Cloud Console 的项目选择器页面上，选择或创建一个 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 Virtual Private 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 中的模型，您需要向 AlloyDB 服务代理授予 Vertex AI 权限。

首先，检索您的 Google Cloud 项目编号，因为 IAM 绑定需要此编号。

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”。根据结果，使用掩码大小“/16”将最后 2 位数替换为 0.0。例如，它看起来会像“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 终端窗口中运行此命令。代理将在后台运行并转发连接。

./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）。

并为我们的应用创建商店数据库（逐个运行命令）：

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

注意：在此导入过程中，您可能会看到一些警告和错误消息，不过对于此 Codelab，您可以放心地忽略这些消息。如果转储包含完整架构，这些错误通常与已有的权限或对象相关。您会发现一些可以忽略的警告和错误

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 终端中运行以下命令：

如果您的 PROJECT_ID 变量未在此 Cloud Shell 终端窗口中设置，请执行以下命令：

export PROJECT_ID=[YOUR_PROJECT_ID]

然后，使用以下命令获取 PROJECT_NUMBER：

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

然后，依次前往“API 和服务”>“凭据”>“创建凭据”>“OAuth 客户端 ID”

使用以下信息创建凭据：

应用类型：“Web 应用”
名称：“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 是前端应用的预期部署网址，将在本 Codelab 的后续步骤中进行设置。请务必将 [YOUR_PROJECT_NUMBER] 替换为您复制的实际编号。

重要提示：创建完成后，系统会弹出一个窗口，其中显示您的 OAuth 客户端 ID，有时还会显示客户端密钥。将 OAuth 客户端 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 文件的 sources 部分中将来源定义为映射。通常，来源配置将包含连接数据库并与之互动所需的任何信息。

工具定义了代理可以执行的操作，例如读取和写入来源。工具表示代理可以执行的操作，例如运行 SQL 语句。您可以在 tools.yaml 文件的 tools 部分中将工具定义为映射。通常，工具需要一个来源才能发挥作用。

如需详细了解如何配置 tools.yaml，请参阅此文档。

运行 MCP Toolbox for Databases 服务器

运行以下命令（从 mcp-toolbox 文件夹）启动服务器：

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

现在，如果您在云端以 Web 预览模式打开服务器，应该能够看到 Toolbox 服务器正在运行，并且包含我们应用的所有工具。

MCP Toolbox 服务器默认在端口 5000 上运行。我们来使用 Cloud Shell 测试一下。

点击 Cloud Shell 中的“网页预览”，如下所示：

点击“更改端口”，然后将端口设置为 5000（如下所示），再点击“更改并预览”。

这应该会带来以下输出：

数据库的 MCP 工具包介绍了可用于验证和测试工具的 Python SDK，相关文档请参阅此处。我们将在下一部分中跳过这些工具，直接进入代理开发套件 (ADK)，该套件将使用这些工具。

接下来，我们将 Toolbox 部署到 Cloud Run

为了使您的 Toolbox 服务器可作为可与您的 AI 代理和其他应用集成的公共端点进行访问，您需要将其部署到 Cloud Run。如需详细了解如何在 Cloud Run 上托管该工具箱，请点击此处。

返回到 Cloud Shell 终端，然后前往 toolbox 文件夹：

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 文件作为 Secret，由于我们必须在 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

现在，您可以在浏览器中访问上面列出的服务网址。它应该会显示我们之前看到的“Hello World”消息。此外，您还可以访问以下网址，查看可用的工具：

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

您还可以通过 Google Cloud 控制台访问 Cloud Run，然后在 Cloud Run 的服务列表中看到 Toolbox 服务。

7. 基于 ADK 构建的代理

在本部分中，您将使用智能体开发套件 (ADK) 构建 AI 智能体，并将其部署到 Cloud Run。

首先，在项目中启用必要的 API，以便在 Cloud Run 上构建和部署代理，并与 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"

将我们的代理连接到工具

我们将把代理连接到工具。在 ADK 的上下文中，工具表示提供给 AI 代理的特定功能，使代理能够执行操作并与世界互动，而不仅仅是进行核心文本生成和推理。

在本例中，我们将为智能体配备在 MCP Toolbox for Databases 中配置的工具。

使用 Cloud Shell 编辑器，前往 sports-agent-adk-mcp-alloydb/src/backend/，然后使用以下代码修改“finn_agent.py”文件。请注意，我们使用的是在上一步中部署的 MCP ToolBox 服务器的 Cloud Run 服务网址：

在 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 中拉取映像，并配置环境变量

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（使用 shell 变量 $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

您将看到类似于以下内容的输出：

“您好！我是 Finn，你的 AI 运动购物助理。我可以帮助您查找运动产品、装备和器械。您今天需要哪些方面的帮助？

至此，您已成功验证 AlloyDB、MCP Toolbox 和使用 ADK 构建的智能体的部署。

8. 部署前端

在本部分中，您将在 Cloud Run 上部署 AI 助理的对话式界面。此前端使用 React 和 JavaScript 构建。

在部署之前，您需要使用已部署的代理的网址和您的 OAuth 客户端 ID 更新前端的源代码。

使用 Cloud Shell 编辑器，找到 sports-agent-adk-mcp-alloydb/src/frontend/src/pages/ 并打开 Home.jsx 文件。您需要更新代理的 Cloud Run 服务网址的占位符。然后，将其替换为上一步中获取的代理的 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 了。

在 Cloud Shell 终端中从根目录 (sports-agent-adk-mcp-alloydb/) 运行以下命令，以在 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 现已全面部署，随时可以帮助您完成购买！

打开网络浏览器，然后前往上一步中前端应用的 Service 网址。网址采用以下格式：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 Agent 及其功能，请观看以下视频：

由 AlloyDB 提供支持的体育经纪人 AI 助理演示

10. 结果

执行完上一个脚本后，您已成功验证 ADK 代理的完整集成、其与 AlloyDB 的连接以及其对 MCP 工具箱的利用。本部分重点介绍您已实现的核心功能。

授权服务

数据库的 MCP 工具箱提供联合授权服务（在本 Codelab 中特指 Google 登录）的功能，以对应用中的用户进行身份验证。借助 MCP Toolbox，当调用工具时，系统会使用您的 OAuth 客户端 ID 来验证用户身份。

这种强大的身份验证机制可为您的智能体应用提供出色的解决方案，以防范提示注入攻击。在这种攻击中，恶意输入会试图绕过或操纵智能体的预期行为。如需了解详情，请参阅维基百科上有关提示注入的文章

在此应用中，当用户要求“查看订单状态”或“显示我的购物清单”时，系统会使用此技术。该代理旨在仅显示经过身份验证的用户的订单，以防止未经授权访问订单信息。

向量搜索

您的代理式应用利用 AlloyDB for PostgreSQL 提供高级查询功能，尤其是通过向量搜索。AlloyDB 支持使用 SQL 函数直接在数据库内生成在线嵌入。

借助此强大功能，代理可以将用户的自然语言输入转换为数值嵌入表示形式。随后，它可以根据这些嵌入内容针对您的产品目录（或其他相关数据）执行相似性搜索，从而提供高度相关的搜索结果。

在应用中，当您向 Finn 提出“I'm looking for running shoes for an ultra-trail”（我想找一双适合超长距离越野跑的跑鞋）这样的问题时，就会体验到这种技术。

地理空间功能 (PostGIS)

AlloyDB for PostgreSQL 与标准 PostgreSQL 功能保持 100% 兼容。在此应用中，我们利用热门的 PostgreSQL 扩展程序 PostGIS 为代理提供地理空间位置功能。

当您向代理提出“查找我附近的商店”这一问题时，代理会执行一个工具，该工具利用数据库中的 PostGIS 索引高效地查找距离用户指定或推断出的位置最近的商店。

11. （可选）测试 AlloyDB AI 自然语言到 SQL

本部分将介绍 AlloyDB for PostgreSQL 的一项高级预发布版功能：自然语言到 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 功能：

打开 Web 浏览器，然后使用服务网址打开应用：“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 应用

如需了解详情，请参阅产品文档：代理开发套件、适用于数据库的 MCP 工具箱和 AlloyDB for PostgreSQL