程式碼研究室簡介
1. 總覽
代理是一種自主程式，可與 AI 模型對話，使用自身的工具和背景資訊執行以目標為導向的作業，並能根據事實自主做出決策！
如果應用程式有多個代理程式，且這些代理程式可根據需要自主運作，以便滿足更大的目的，且每個代理程式都具備獨立的知識，並負責特定專注領域，那麼您的應用程式就會成為多代理程式系統。
代理開發套件 (ADK)
代理開發套件 (ADK) 是彈性模組化架構，可用於開發及部署 AI 代理。ADK 可將多個不同的代理程式例項組合成多代理系統 (MAS)，進而支援建構精密的應用程式。
在 ADK 中，多虛擬服務專員系統是指應用程式中不同虛擬服務專員 (通常會形成階層) 合作或協調，以達成更大的目標。以這種方式建構應用程式可帶來許多優點，包括強化模組化、專業化、可重複使用性和可維護性，以及使用專屬工作流程代理程式定義結構化控制流程的能力。
多代理系統的注意事項
首先，請務必正確理解每個服務專員的專長，並據此做出合理判斷。—「你知道為什麼需要特定的次要代理人嗎？」，請先解決這個問題。
第二點：如何將這些訊息與根層級代理程式整合，以便路由及解讀每個回應。
第三點：您可以在這份說明文件中找到多種服務專員轉介方式。請確認哪一個適合您的應用程式流程。以及多代理程系統的流程控制所需的各種內容和狀態。
建構項目
讓我們使用 MCP Toolbox for AlloyDB 和 ADK，建構多代理系統來處理廚房翻修作業。
- 整修提案代理程式
- 許可證和合規性檢查代理程式
- 訂單狀態檢查 (使用 MCP Toolbox for Databases 的工具)
Renovation Proposal Agent，用於產生廚房翻修提案文件。
執照和法規遵循服務代理人，負責處理執照和法規遵循相關工作。
訂單狀態檢查代理程式，可透過 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 控制台的專案選取器頁面中，選取或建立 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>
- 請確認您已安裝 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 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 值 (在「設定環境變數」步驟中)。
7. 資料庫設定
在 ordering_agent 使用的其中一個工具 (稱為「check_status」) 中，我們會存取 AlloyDB 訂單資料庫，取得訂單狀態。在本節中，我們將設定 AlloyDB 資料庫叢集和執行個體。
建立叢集和執行個體
- 前往 Cloud 控制台的 AlloyDB 頁面。如要輕鬆在 Cloud Console 中找到大部分的頁面，請使用控制台的搜尋列進行搜尋。
- 在該頁面中選取「建立叢集」：
- 您會看到類似下方的畫面。使用下列值建立叢集和執行個體 (如果您要從存放區複製應用程式程式碼，請務必確認這些值相符)：
- 叢集 ID："
vector-cluster" - 密碼："
alloydb" - PostgreSQL 15 / 最新版本 (建議使用)
- Region："
us-central1" - 網路："
default"
- 選取預設網路後，畫面會顯示如下圖所示畫面。
選取「設定連線」。
- 接著選取「使用系統自動分配的 IP 範圍」，然後按一下「繼續」。查看相關資訊後，請選取「建立連線」。
- 網路設定完成後，您可以繼續建立叢集。按一下「CREATE CLUSTER」，完成叢集設定，如下所示：
請務必變更執行個體 ID (您可以在設定叢集 / 執行個體時找到) 為
vector-instance。如果無法變更，請務必在所有後續參照中使用例項 ID。
請注意，叢集建立作業大約需要 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 查詢陳述式複製到編輯器中。
按一下「執行」。
資料集準備就緒後，我們就來為 Toolbox 實作準備 AlloyDB：
在設定工具箱前，我們先在 AlloyDB 例項中啟用公開 IP 連線，讓新工具可以存取資料庫。
- 前往 AlloyDB 執行個體，按一下「編輯」，即可前往「編輯主要執行個體」頁面。
- 前往「公開 IP 連線」專區，勾選「啟用公開 IP」核取方塊，然後輸入 Cloud Shell 機器的 IP 位址。
- 如要取得 Cloud Shell 機器的 IP，請前往 Cloud Shell 終端機並輸入 ifconfig。從結果中找出 eth0 inet 位址，並將最後 2 個數字替換為 0.0，並使用遮罩大小「/16」例如「XX.XX.0.0/16」，其中 XX 為數字。
- 將這個 IP 貼到「Networks」(網路) 文字方塊的「Authorized external networks」(授權外部網路) 中。
- 完成後，按一下「更新執行個體」。
這項作業需要幾分鐘才能完成。
資料集準備就緒後，請設定 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
- 執行下列指令，即可在新的資料夾中下載及安裝 Toolbox：
# see releases page for other versions
export VERSION=0.1.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 區段中，將來源定義為對應項目。通常，來源設定會包含連線至資料庫並與其互動所需的所有資訊。
工具定義代理程式可執行的動作，例如讀取及寫入來源。工具代表代理程式可採取的動作，例如執行 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 中的「網頁預覽」按鈕，如下所示：
按一下「Change port」，將通訊埠設為 5000，如以下所示，然後按一下「Change and Preview」。
這應該會產生以下輸出內容：
資料庫適用的 MCP Toolkit 說明瞭 Python SDK，可讓您驗證及測試工具，相關文件請參閱這裡。我們將略過這部分，直接在下一節中介紹 Agent Development Kit (ADK)，並說明如何使用這些工具。
將 Toolbox 部署至 Cloud Run
首先，我們可以開始使用 MCP Toolbox 伺服器，並將其託管在 Cloud Run 上。這樣一來，我們就能取得可與任何其他應用程式和/或代理程式整合的公開端點。如要瞭解如何在 Cloud Run 上代管此服務，請參閱這篇文章。我們現在就來逐步說明重點步驟。
- 啟動新的 Cloud Shell 終端機，或使用現有的 Cloud Shell 終端機。前往 toolbox 二進位檔和 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 檔案上傳為密鑰：
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 檔案：
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>>
STORAGE_BUCKET = next-demo-store <<or your storage bucket name>>
將預留位置替換為您的值。
11. 執行代理程式
- 使用終端機，前往服務專員專案的上層目錄：
cd renovation-agent
- 您可以在 Cloud Shell 終端機中執行下列指令，執行這個代理程式：
adk run .
- 您可以執行下列指令，在 ADK 佈建的網頁 UI 中執行此指令：
adk web
- 請使用下列提示進行測試：
user>>
Hello. Check order status for Cement Bags.
13. 清除所用資源
如要避免系統向您的 Google Cloud 帳戶收取這篇文章中所用資源的費用，請按照下列步驟操作：
14. 恭喜
恭喜！您已成功使用 ADK 和 MCP Toolbox for Databases 建立多代理應用程式！詳情請參閱產品說明文件：Agent Development Kit 和 MCP Toolbox for Databases。