使用 MCP Toolbox for AlloyDB 和 ADK 建構多代理應用程式

1. 總覽

代理是一種自主程式，會與 AI 模型對話，並使用手邊的工具和情境資訊執行目標導向的作業，還能根據事實自主決策！

如果應用程式有多個代理，可視需要自主協同運作，以達成更大的目標，且每個代理都具備獨立知識，並負責特定領域，那麼應用程式就會成為多代理系統。

Agent Development Kit (ADK)

Agent Development Kit (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 用戶端轉送至適當的 MCP 伺服器。
讓 AI 模型存取外部資料和工具，不必為每個整合項目編寫自訂程式碼。
簡化以大型語言模型 (LLM) 為基礎建構代理程式和複雜工作流程的程序。

MCP Toolbox for Databases

Google 的 MCP Toolbox for Databases 是資料庫專用的開放原始碼 MCP 伺服器。這項服務的設計宗旨是提供企業級的生產品質。這項服務可處理連線集區和驗證等複雜作業，讓您更輕鬆、快速且安全地開發工具。

讓代理程式存取資料庫中的資料！做法：

簡化開發作業：只需不到 10 行程式碼，即可將工具整合至代理，在多個代理或架構之間重複使用工具，並更輕鬆地部署新版工具。

提升效能：連線集區、驗證等最佳做法。

提升安全性：整合驗證機制，確保資料存取安全無虞

端對端觀測能力：內建支援 OpenTelemetry，可提供立即可用的指標和追蹤記錄功能。

必須強調這項技術早於 MCP！

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

我們會根據需求，讓根代理程式自動調度管理這些代理程式。

需求條件

Chrome 或 Firefox 瀏覽器
已啟用計費功能的 Google Cloud 專案。

3. 事前準備

建立專案

在 Google Cloud 控制台的專案選取器頁面中，選取或建立 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 檔案擷取設定參數，並定義 root_agent，該代理會使用 1 項工具來叫用工具箱工具。

前往 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」
password：「alloydb」
與 PostgreSQL 16 相容 / 建議使用最新版本
Region：「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 貼到編輯執行個體頁面的「授權外部網路」文字方塊中。

設定網路後，即可繼續建立叢集。按一下「CREATE CLUSTER」，完成叢集設定，如下所示：

請注意，建立叢集約需 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 設定

Toolbox 位於應用程式的自動化調度管理框架和資料庫之間，提供用於修改、發布或叫用工具的控制層。這項功能提供集中式位置來儲存及更新工具，方便您管理工具，並在代理程式和應用程式之間共用工具，以及更新工具 (不一定需要重新部署應用程式)。

您可以看到 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 編輯器 (程式碼編輯模式)，在專案根資料夾中新增名為「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;

在查詢部分 (請參閱上方的「陳述式」參數)，我們只會在物料名稱與使用者的搜尋文字相符時，擷取 order_status 欄位的值。

讓我們瞭解 tools.yaml。

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

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

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

執行 MCP Toolbox for Databases 伺服器

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

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

現在，如果您在雲端以網頁預覽模式開啟伺服器，應該就能看到 Toolbox 伺服器已啟動並執行，且其中包含名為 get-order-data 的新工具。

MCP Toolbox 伺服器預設會在通訊埠 5000 上執行。我們將使用 Cloud Shell 測試這項功能。

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

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

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

MCP Toolkit for Databases 說明如何使用 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

如果您已有密鑰，並想更新密鑰版本，請執行下列指令：

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 檔案，其中包含存放區的程式碼：

我們將納入呼叫工具箱端點的工具，以便擷取特定訂購素材的訂單資料。

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 佈建的網頁版 UI 中執行，請執行下列指令：

adk web

使用下列提示詞進行測試：

user>> 

Hello. Check order status for Cement Bags.

12. 結果

13. 清理

如要避免系統向您的 Google Cloud 帳戶收取本文章所用資源的費用，請按照下列步驟操作：

在 Google Cloud 控制台中前往「管理資源」頁面。
在專案清單中選取要刪除的專案，然後點按「刪除」。
在對話方塊中輸入專案 ID，然後按一下「Shut down」(關機) 即可刪除專案。

14. 恭喜

恭喜！您已成功使用 ADK 和 MCP Toolbox for Databases 建立多代理應用程式！詳情請參閱產品說明文件：Agent Development Kit 和 MCP Toolbox for Databases。

使用 MCP Toolbox for AlloyDB 和 ADK 建構多代理應用程式 透過集合功能整理內容 你可以依據偏好儲存及分類內容。