使用 MCP Toolbox for AlloyDB 和 ADK 构建多智能体应用

1. 概览

智能体是一种自主程序，它会与 AI 模型对话，使用其拥有的工具和上下文执行基于目标的运算，并且能够根据事实做出自主决策！

如果您的应用有多个智能体，这些智能体可以自主协作，也可以根据需要共同协作，以实现更大的目标，并且每个智能体都具备独立的知识，负责特定的专注领域，那么您的应用就成为了多智能体系统。

智能体开发套件 (ADK)

智能体开发套件 (ADK) 是一个灵活的模块化框架，用于开发和部署 AI 智能体。ADK 支持通过将多个不同的智能体实例组合成多智能体系统 (MAS) 来构建复杂的应用。

在 ADK 中，多智能体系统是指一个应用，其中不同的智能体（通常形成层次结构）通过协作或协调来实现更大的目标。以这种方式构建应用具有显著优势，包括增强的模块化、专业化、可重用性、可维护性，以及使用专用工作流代理定义结构化控制流的能力。

多智能体系统的注意事项

首先，务必要正确理解和推理每个智能体的专业领域。- “do you know why you need a specific sub-agent for something”，先解决这个问题。

其次，如何将它们与根代理结合起来，以路由和理解每个回答。

第三，您可以在本文档中找到多种类型的客服人员转接。请确保选择适合您应用流程的方案。此外，还需要考虑多智能体系统的流控制所需的各种上下文和状态。

构建内容

让我们使用 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 客户端将该请求转发给相应的 MCP 服务器。
允许 AI 模型访问外部数据和工具，而无需为每次集成编写自定义代码。
简化了基于大型语言模型 (LLM) 构建智能体和复杂工作流的过程。

MCP Toolbox for Databases

Google 的 MCP Toolbox for Databases 是一款适用于数据库的开源 MCP 服务器。它在设计时就考虑到了企业级和生产环境质量。它通过处理连接池、身份验证等复杂问题，让您能够更轻松、更快速、更安全地开发工具。

让智能体访问数据库中的数据！要怎么做呢？

简化开发：只需不到 10 行代码即可将工具集成到代理中，在多个代理或框架之间重复使用工具，并更轻松地部署新版本的工具。

更出色的性能：连接池、身份验证等最佳实践。

增强安全性：集成式身份验证，可更安全地访问您的数据

端到端可观测性：开箱即用的指标和跟踪功能，内置对 OpenTelemetry 的支持。

Have to call out the fact that this predated MCP!!!

MCP Toolbox for Databases 位于智能体应用的编排框架和数据库之间，提供用于修改、分发或调用工具的控制平面。它提供了一个集中存储和更新工具的位置，让您可以轻松管理工具，还可以在代理和应用之间共享工具，并更新这些工具，而无需重新部署应用。

我们将有一个根代理，用于根据要求协调这些代理。

要求

一个浏览器，例如 Chrome 或 Firefox
启用了结算功能的 Google Cloud 项目。

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/renovation-agent-adk-mcp-toolbox/blob/main/agent.py

在 agent.py 中，我们导入必要的依赖项，从 .env 文件中检索配置参数，并定义使用 1 个工具来调用工具箱工具的 root_agent。

前往 requirements.txt，并使用以下内容更新该文件：

https://github.com/AbiramiSukumaran/renovation-agent-adk-mcp-toolbox/blob/main/requirements.txt

7. 数据库设置

在 ordering_agent 使用的某个名为“check_status”的工具中，我们访问 AlloyDB 订单数据库以获取订单状态。在本部分中，我们将设置 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 命令，并根据需要使用“运行”“格式”和“清除”选项。

创建表

您可以在 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 中所有订单数据库交互的控制平面！

8. MCP Toolbox for Databases 设置

该工具箱位于应用的编排框架和数据库之间，提供用于修改、分发或调用工具的控制平面。它提供了一个集中存储和更新工具的位置，让您可以轻松管理工具，在代理和应用之间共享工具，并无需重新部署应用即可更新这些工具。

您可以看到，MCP Toolbox for Databases 支持的数据库之一是 AlloyDB，并且我们在上一部分中已预配该数据库，因此接下来设置 Toolbox。

前往 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 Editor（用于代码修改模式），然后在项目根文件夹中添加一个名为“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 部分中将来源定义为映射。通常，来源配置将包含连接数据库并与之互动所需的任何信息。

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

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

我们来运行 MCP Toolbox for Databases 服务器

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

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

现在，如果您在云端以网页预览模式打开服务器，应该能够看到工具箱服务器正在运行，其中包含名为 get-order-data 的新工具。

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

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

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

这应该会带来以下输出：

MCP Toolkit for Databases 介绍了可用于验证和测试工具的 Python 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 服务的身份。

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

如果您已有密文，并想更新密文版本，请执行以下操作：

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

您已一切就绪，可以在代理应用中使用新部署的工具了！

让我们将 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 文件：

我们添加了调用工具箱端点以提取特定订购材料的订单数据的工具。

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

将占位符替换为您的值。

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.

12. 结果

13. 清理

为避免系统因本博文中使用的资源向您的 Google Cloud 账号收取费用，请按照以下步骤操作：

在 Google Cloud 控制台中，前往管理资源页面。
在项目列表中，选择要删除的项目，然后点击删除。
在对话框中输入项目 ID，然后点击关停以删除项目。

14. 恭喜

恭喜！您已成功使用 ADK 和 MCP Toolbox for Databases 创建了一个多智能体应用！如需了解详情，请参阅产品文档：智能体开发套件和 MCP Toolbox for Databases。

使用 MCP Toolbox for AlloyDB 和 ADK 构建多智能体应用 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。