关于此 Codelab
1. 概览
智能体是一种自主程序，可与 AI 模型交互，使用其拥有的工具和上下文执行基于目标的操作，并且能够基于事实做出自主决策！
如果您的应用有多个代理，并且这些代理能够根据需要自主协作，共同实现更大的目标，并且每个代理都拥有独立的知识，并负责特定的重点领域，那么您的应用就成为了一个多代理系统。
Agent Development Kit (ADK)
智能体开发套件 (ADK) 是一个灵活的模块化框架，用于开发和部署 AI 智能体。ADK 支持将多个不同的代理实例组合到多智能体系统 (MAS) 中，从而构建复杂的应用。
在 ADK 中，多智能体系统是一种应用，其中不同的智能体（通常会形成层次结构）协作或协调以实现更大的目标。以这种方式构建应用具有显著优势，包括增强的模块化、专业化、可重用性和可维护性，以及能够使用专用工作流代理定义结构化控制流。
多代理系统的注意事项
首先，请务必正确理解每个代理的专业领域并据此推理。-“您知道为什么需要为某项内容使用特定子代理吗？”，请先解决这个问题。
第二点：如何将这些服务与根代理结合起来，以路由和解读每个响应。
第三，您可以在本文档中找到多种类型的客服人员转接。确定哪种方式适合您的应用流程。此外，您需要为多代理系统的流控制提供哪些不同的上下文和状态。
构建内容
我们将使用 MCP Toolbox for AlloyDB 和 ADK 构建一个多智能体系统来处理厨房装修。
- 装修方案代理
- 许可和合规性检查代理
- 订单状态检查（使用 MCP Toolbox for Databases 的工具）
翻新提案代理，用于生成厨房翻新提案文档。
许可和合规性代理，负责处理与许可和合规性相关的任务。
订单状态检查代理，用于处理我们在 AlloyDB 中设置的订单管理数据库，以检查材料的订单状态。不过，对于此数据库部分，我们将使用 MCP Toolbox for AlloyDB 实现订单的状态检索逻辑。
2. MCP
MCP 是 Model Context Protocol 的缩写，由 Anthropic 开发的一种开放标准，可让 AI 智能体以一致的方式与外部工具、服务和数据连接。它本质上是 AI 应用的通用标准，可让这些应用与不同的数据源和工具无缝互动。
- 它采用客户端-服务器模型，其中 AI 应用（主机）运行 MCP 客户端，该客户端与 MCP 服务器进行通信。
- 当 AI 代理需要访问特定工具或数据时，它会向 MCP 客户端发送结构化请求，客户端会将其转发到适当的 MCP 服务器。
- 让 AI 模型能够访问外部数据和工具，而无需为每次集成都编写自定义代码。
- 简化了基于大语言模型 (LLM) 构建智能体和复杂工作流的过程。
MCP Toolbox for Databases
Google 的 MCP Toolbox for Databases 是一个适用于数据库的开源 MCP 服务器。在设计时便已考虑到企业级和生产环境质量要求。它可以处理连接池、身份验证等复杂问题，让您能够更轻松、更快速、更安全地开发工具。
让客服人员访问数据库中的数据！如何做到？
简化开发流程：只需不到 10 行代码即可将工具集成到代理中，在多个代理或框架之间重复使用工具，并更轻松地部署工具的新版本。
提升性能：连接池、身份验证等最佳实践。
增强型安全性：集成身份验证，更安全地访问您的数据
端到端可观测性：开箱即用的指标和跟踪功能，内置对 OpenTelemetry 的支持。
必须指出，这发生在 MCP 之前！
适用于数据库的 MCP Toolbox 位于代理应用的编排框架和数据库之间，提供用于修改、分发或调用工具的控制平面。它为您提供了一个集中的位置来存储和更新工具，从而简化了工具管理。您可以在代理和应用之间共享工具，并更新这些工具，而无需重新部署应用。
我们将有一个根代理，用于根据要求协调这些代理。
要求
3. 准备工作
创建项目
- 在 Google Cloud Console 的项目选择器页面上，选择或创建一个 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 终端中，依次运行以下命令以创建根目录和项目文件夹：
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 文件检索配置参数，并定义 root_agent，用于协调我们打算在此应用中创建的 3 个子代理。有几种工具可帮助实现这些子代理的核心功能和支持功能。
- 确保您拥有 Cloud Storage 存储分区
用于存储代理生成的提案文档。创建该集群并提供访问权限，以便使用 Vertex AI 创建的多智能体系统可以访问该集群。具体方法如下：
https://cloud.google.com/storage/docs/creating-buckets#console
- 将存储分区命名为“
next-demo-store”或您允许的任何名称。记下该值，因为您需要在 .env 文件中更新 STORAGE_BUCKET 的值（在“环境变量设置”步骤中）。 - 在 us-central1 位置创建该角色
- 如需设置对存储分区的访问权限，请前往 Cloud Storage 控制台并找到您的存储分区（在本例中，存储分区名称为“next-demo-storage”：https://console.cloud.google.com/storage/browser/next-demo-storage。
依次前往“权限”->“查看主账号”->“授予访问权限”。将“Principals”（正文）选择为“allUsers”，将“Role”（角色）选择为“Storage Object User”（存储对象用户）。
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 使用的工具（名为“check_status”）中，我们会访问 AlloyDB orders 数据库以获取订单状态。在本部分中，我们将设置 AlloyDB 数据库集群和实例。
创建集群和实例
- 在 Cloud 控制台中，前往 AlloyDB 页面。在 Cloud 控制台中查找大多数页面时，最简单的方法是使用控制台的搜索栏进行搜索。
- 从该页面中选择创建集群：
- 您将看到如下所示的界面。使用以下值创建集群和实例（如果您要从代码库克隆应用代码，请确保这些值一致）：
- 集群 ID：“
vector-cluster” - 密码：“
alloydb” - 建议使用与 PostgreSQL 16 兼容 / 最新版本
- 区域："
us-central1" - 网络：“
default”
- 选择默认网络后，您会看到如下所示的界面。
选择设置连接。
- 然后，选择使用自动分配的 IP 范围并点击“继续”。查看信息后，选择“创建关联”。
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 地址粘贴到“修改实例”页面上的“已获授权的外部网络”"网络"文本框中。
- 设置好网络后，您可以继续创建集群。点击“创建集群”以完成集群设置，如下所示：
请注意，创建集群大约需要 10 分钟。成功完成后，您应该会看到一个屏幕，其中显示了您刚刚创建的集群的概览。
数据注入
现在，我们需要添加一个包含商店数据的表格。前往 AlloyDB，选择主集群，然后选择 AlloyDB Studio：
您可能需要等待实例创建完成。完成后，使用您在创建集群时创建的凭据登录 AlloyDB。使用以下数据对 PostgreSQL 进行身份验证：
- 用户名：“
postgres” - 数据库：“
postgres” - 密码：“
alloydb”
成功通过身份验证登录 AlloyDB Studio 后，您可以在编辑器中输入 SQL 命令。您可以使用最后一个窗口右侧的加号添加多个编辑器窗口。
您将在编辑器窗口中输入 AlloyDB 命令，并根据需要使用“Run”“Format”和“Clear”选项。
创建表
您可以在 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 查询语句复制到编辑器中。
点击运行。
现在，数据集已准备就绪，接下来我们将设置 MCP Toolbox for Databases，以便其充当 AlloyDB 中所有 Order 数据库交互的控制平面！
8. MCP Toolbox for Databases 设置
Toolbox 位于应用的编排框架和数据库之间，提供用于修改、分发或调用工具的控制平面。它为您提供了一个集中存储和更新工具的位置，从而简化了工具管理。您可以在代理和应用之间共享工具，并更新这些工具，而无需重新部署应用。
您可以看到，MCP 数据库工具箱支持的数据库之一是 AlloyDB，由于我们已在前面部分预配了该数据库，因此接下来继续设置 Toolbox。
- 前往 Cloud Shell 终端，确保已选择您的项目，并且该项目显示在终端的提示中。在 Cloud Shell 终端中运行以下命令，进入项目目录：
cd adk-renovation-agent
- 运行以下命令，在您的新文件夹中下载并安装 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
- 前往 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 部分将 Sources 定义为映射。通常，来源配置将包含与数据库建立连接和互动所需的所有信息。
工具用于定义代理可以执行的操作，例如读取和写入来源。工具代表代理可以执行的操作，例如运行 SQL 语句。您可以在 tools.yaml 文件的 tools 部分将“Tools”定义为映射。通常，工具需要有操作的来源。
如需详细了解如何配置 tools.yaml，请参阅此文档。
我们来运行 MCP Toolbox for Databases 服务器
运行以下命令（从 mcp-toolbox 文件夹中运行）以启动服务器：
./toolbox --tools-file "tools.yaml"
现在，如果您在云端以 Web 预览模式打开服务器，应该可以看到 Toolbox 服务器已启动并运行，并且您新创建的工具名为 get-order-data。
MCP Toolbox 服务器默认在端口 5000 上运行。我们来使用 Cloud Shell 进行测试。
在 Cloud Shell 中，点击“网页预览”，如下所示：
点击“更改端口”，将端口设置为 5000（如下所示），然后点击“更改并预览”。
这应该会生成以下输出：
数据库专用 MCP 工具包介绍了 Python SDK，可供您验证和测试工具，详见此处。我们将跳过该部分，直接进入下一部分，在其中使用这些工具来介绍 Agent Development Kit (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 服务的身份。
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 文件作为 Secret 上传：
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
这应该会启动将 Toolbox 服务器与配置好的 tools.yaml 部署到 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
您已一切就绪，可以开始在代理应用中使用新部署的工具了！
我们来将 Toolbox 工具与客服人员联系起来！
我们已经为多代理系统创建了源代码。我们来更新一下，添加我们刚刚在 Cloud Run 中部署的新 MCP Toolbox for Databases 工具。
- 使用代码库中的源代码修改 requirements.txt 文件：
我们将在 requirements.txt 中添加 MCP Toolbox for Databases 的依赖项
https://github.com/AbiramiSukumaran/renovation-agent-adk-mcp-toolbox/blob/main/requirements.txt
- 使用代码库中的代码修改 agent.py 文件：
我们将添加一个工具，用于调用 Toolbox 端点以提取订购的特定材料的订单数据。
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>>
STORAGE_BUCKET=next-demo-store <<or your storage bucket name>>
将占位符替换为您的值。
11. 运行代理
- 使用终端，前往代理项目的父级目录：
cd renovation-agent
- 安装依赖项：
pip install -r requirements.txt
- 您可以在 Cloud Shell 终端中运行以下命令来执行代理：
adk run .
- 您可以运行以下命令，在 ADK 预配的 Web 界面中运行它：
adk web
- 使用以下提示进行测试：
user>>
Hello. Check order status for Cement Bags.
14. 恭喜
恭喜！您已成功使用 ADK 和 MCP Toolbox for Databases 创建了一个多智能体应用！如需了解详情，请参阅产品文档：智能体开发套件和 MCP Toolbox for Databases。