使用 ADK、Agent Engine 和 AlloyDB 建構多代理應用程式

1. 總覽

代理是一種自主程式，會與 AI 模型對話，運用手邊的工具和脈絡執行以目標為導向的作業，並根據事實自主決策！

如果應用程式有多個自主協同運作的代理，每個代理都具備獨立知識且負責特定領域，並可在必要時共同達成更宏大的目標，該應用程式即屬於多代理系統。

Agent Development Kit (ADK)

Agent Development Kit (ADK) 是一個彈性十足的模組化框架，可用於開發及部署 AI 代理。ADK 支援將多個不同的代理執行個體整合成多代理系統 (MAS)，打造精密的應用程式。

在 ADK 框架下，多代理系統是指由多種代理構成的應用程式。這些代理通常會形成階層架構，彼此協同運作來達成更宏大的目標。這種應用程式建構方式具有顯著優勢，包括模組化能力更強、專業程度與複用性更高、更方便維護，以及能透過專用工作流程代理，定義有條理的控管流程。

多代理系統注意事項

首先，務必充分瞭解各個代理的專責領域，以及如此安排的原因。換句話說，要先想清楚「為什麼要由特定子代理來負責某件事」。

第二，思考如何透過根代理轉送及解讀個別回覆，將子代理整合起來。

第三，本文件說明瞭多種代理轉送方式，請確認哪種方式適合您的應用程式流程，並釐清多代理系統流量控制所需的各種情境和狀態。

建構項目

我們來打造一個廚房翻修多代理系統。內含以下 3 個代理：

1. 翻修提案代理
2. 許可證與法規遵循檢查代理
3. 訂單狀態檢查代理

翻修提案代理，生成廚房翻修提案文件。

許可證與法規遵循代理，負責處理許可證與法規遵循相關工作。

訂單狀態檢查代理程式，可透過在 AlloyDB 中設定的訂單管理資料庫，檢查物料的訂單狀態。

我們還會建立一個根代理，根據需求自動調度管理上述代理。

需求條件

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

2. 事前準備

建立專案

1. 在 Google Cloud 控制台的專案選取器頁面中，選取或建立 Google Cloud 專案。
2. 確認 Cloud 專案已啟用計費功能。瞭解如何檢查專案是否已啟用計費功能。
3. 按一下這個連結，啟用 Cloud Shell。點選 Cloud Shell 中的對應按鈕，即可在 Cloud Shell 終端機 (用於執行雲端指令) 和編輯器 (用於建構專案) 之間切換。
4. 連至 Cloud Shell 後，請使用下列指令確認驗證已完成，專案也已設為獲派的專案 ID：

gcloud auth list

5. 在 Cloud Shell 中執行下列指令，確認 gcloud 指令已瞭解您的專案。

gcloud config list project

6. 如果未設定專案，請使用下列指令設定：

gcloud config set project <YOUR_PROJECT_ID>

7. 確認已安裝 Python 3.9 以上版本。
8. 執行下列指令，啟用下列 API：

gcloud services enable artifactregistry.googleapis.com \cloudbuild.googleapis.com \run.googleapis.com \aiplatform.googleapis.com

9. 如要瞭解 gcloud 指令和用法，請參閱說明文件。

3. 原型

如果您決定為專案採用「Gemini 2.5 Pro」模型，可以略過這個步驟。

前往 Google AI Studio。開始輸入提示。我的提示如下：

I want to renovate my kitchen, basically just remodel it. I don't know where to start. So I want to use Gemini to generate a plan. For that I need a good prompt. Give me a short yet detailed prompt that I can use.

調整並設定右側的參數，取得最佳回應。

根據這段簡單的描述，Gemini 為我製作了非常詳細的提示，讓我開始進行裝修！也就是說，我們使用 Gemini，讓 AI Studio 和模型提供更優質的回覆。您也可以根據用途選取要使用的模型。

我們選擇了 Gemini 2.5 Pro。這是「思考」模型，因此我們可獲得更多輸出權杖，最多可達 65,000 個權杖，用於長篇分析和詳細文件。啟用 Gemini 2.5 Pro 後，系統會顯示 Gemini 思考方塊。Gemini 2.5 Pro 具備原生推論能力，可接受長脈絡要求。

請參閱以下回應的程式碼片段：

AI Studio 分析我的資料後，生成了櫥櫃、檯面、擋水板、地板、水槽、凝聚力、調色盤和材質選擇等所有項目。Gemini 甚至會引用來源！

反覆嘗試不同模型，直到滿意為止。但我想說，既然有 Gemini 2.5，何必這麼麻煩呢 :)

無論如何，現在請試著使用其他提示詞，看看這個想法是否能實現：

Add flat and circular light accessories above the island area for my current kitchen in the attached image.

附上現有廚房的圖片連結 (或任何廚房圖片範例)。將模型變更為「Gemini 2.0 Flash 圖像生成預先發布版」，即可生成圖像。

我得到以下輸出內容：

這就是 Gemini 的威力！

從解讀影片、生成原生圖片，到以 Google 搜尋為基準提供真實資訊，只有採用 Gemini 技術才能做到。

您可以在 AI Studio 中取得這個原型和 API 金鑰，然後運用 Vertex AI ADK 的強大功能，將原型擴展為完整的代理程式應用程式。

4. ADK 設定

1. 建立並啟用虛擬環境 (建議)

在 Cloud Shell 終端機中建立虛擬環境：

python -m venv .venv

啟動虛擬環境：

source .venv/bin/activate

2. 安裝 ADK

pip install google-adk

5. 專案結構

3. 在 Cloud Shell 終端機中，於所需專案位置建立目錄

mkdir agentic-apps
cd agentic-apps
mkdir renovation-agent

4. 前往 Cloud Shell 編輯器建立檔案 (內容先保持空白)，打造如下所示的專案架構：

renovation-agent/
        __init__.py
        agent.py
        .env
        requirements.txt

6. 原始碼

5. 開啟「init.py」，並使用下列程式碼更新：

from . import agent

6. 開啟 agent.py，並使用以下路徑的內容更新檔案：

https://github.com/AbiramiSukumaran/adk-renovation-agent/blob/main/agent.py

在 agent.py 中，我們會匯入必要的依附元件、從 .env 檔案擷取設定參數，並定義 root_agent，以協調我們要在這個應用程式中建立的 3 個子代理。我們提供多種工具，協助這些子代理程式執行核心和支援功能。

7. 確認您擁有 Cloud Storage bucket

為了儲存代理生成的提案文件，請建立相應 bucket，並授予存取權給透過 Vertex AI 建立的多代理系統。詳細步驟如下：

https://cloud.google.com/storage/docs/creating-buckets#console

將值區命名為「next-demo-store」。如果命名為其他名稱，請記得更新 .env 檔案中的 STORAGE_BUCKET 值 (在「設定環境變數」步驟中)。

8. 如要設定 bucket 的存取權，請前往 Cloud Storage 控制台和 Storage Bucket (在本例中，bucket 名稱為「next-demo-storage」：https://console.cloud.google.com/storage/browser/next-demo-storage)。

依序前往「權限」->「查看主體」->「授予存取權」。將主體選取為「allUsers」，角色選取為「Storage 物件使用者」。

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.

9. 建立依附元件清單

在 requirements.txt 中列出所有依附元件。您可以從 repo 複製這項資訊。

多代理系統原始碼說明

agent.py 檔案使用 Agent Development Kit (ADK)，定義廚房翻修多代理系統的架構和行為。下文將詳細說明關鍵要素：

代理定義

RenovationProposalAgent

這個代理負責製作廚房翻修提案文件。使用者可視需要輸入參數，例如廚房大小、期望的風格、預算和顧客偏好。代理會根據這些資訊，使用 Gemini 2.5 大型語言模型 (LLM) 生成詳細提案，並儲存到 Google Cloud Storage bucket。

PermitsAndComplianceCheckAgent

這個代理著重於確保翻修專案符合當地建築法規，會接收翻修提案相關資訊 (例如結構變更、電氣工程、管線調整)，並使用 LLM 檢查許可證需求和需要遵循的法規。代理會使用知識庫資料執行上述檢查，而您可以自訂知識庫，存取外部 API 來收集相關法規資訊。

OrderingAgent

這個代理 (若您還不想導入，可以註解排除) 會檢查翻修所需材料和設備的訂單狀態，且需要您依設定步驟建立 Cloud Run 函式才能啟用。該代理會呼叫這個 Cloud Run 函式，藉此與包含訂單資訊的 AlloyDB 資料庫互動。這展示了如何整合資料庫系統來追蹤即時資料。

根代理 (自動調度管理工具)

root_agent 就像多代理系統的中央調度員，會接收初始翻修要求，然後根據具體需求決定該叫用哪些子代理。舉例來說，如果使用者要求檢查許可證需求，root_agent 就會呼叫 PermitsAndComplianceCheckAgent；而在收到檢查訂單狀態的要求時，則會呼叫 OrderingAgent (如已啟用)。

接著，root_agent 會收集並整理子代理的回應，向使用者提供詳盡的回覆，例如提案摘要、所需許可證清單，以及訂單狀態最新資訊。

資料流程與重要概念

使用者透過 ADK 介面 (終端機或網頁版 UI) 發出要求。

1. root_agent 收到要求。
2. root_agent 分析要求並轉送給合適的子代理。
3. 子代理使用 LLM、知識庫、API 和資料庫，處理要求並生成回覆。
4. 子代理將回覆傳送到 root_agent。
5. root_agent 合併回覆，向使用者提供最終輸出結果。

LLM (大型語言模型)

代理主要依靠 LLM 來生成文字內容、回答問題，以及執行推論工作。LLM 就像「大腦」，是代理理解及回應使用者要求的關鍵。本文中的應用程式使用的 LLM 為 Gemini 2.5。

Google Cloud Storage

用於儲存生成的翻修提案文件。您需要建立 bucket，並授予代理必要的存取權限。

Cloud Run (選用)

OrderingAgent 會使用 Cloud Run 函式調用 AlloyDB 資料。Cloud Run 提供無伺服器環境，可根據 HTTP 要求執行程式碼。

AlloyDB

使用 OrderingAgent 時，必須設定 AlloyDB 資料庫來儲存訂單資訊。我們會在下一節「資料庫設定」中詳細說明。

.env 檔案

.env 檔案會儲存 API 金鑰、資料庫憑證和 bucket 名稱等機密資訊，因此請務必妥善保管，不要提交至存放區。這個檔案還會儲存代理和 Google Cloud 專案設定。root_agent 或輔助函式通常會讀取這個檔案中的值，所以請務必妥善設定其中的所有必要變數，包括 Cloud Storage bucket 名稱

7. 資料庫設定

在 ordering_agent 使用的其中一項工具 (名為「check_status」) 中，我們會存取 AlloyDB 訂單資料庫，取得訂單狀態。在本節中，我們將設定 AlloyDB 資料庫叢集和執行個體。

建立叢集和執行個體

1. 在 Cloud 控制台中前往 AlloyDB 頁面。如要在 Cloud 控制台尋找大部分的頁面，只要使用控制台的搜尋列搜尋即可。
2. 從該頁面選取「建立叢集」：

3. 你會看到如下所示的畫面。使用下列值建立叢集和執行個體 (如果您要從存放區複製應用程式碼，請確保值相符)：

• 叢集 ID：「vector-cluster」
• password：「alloydb」
• PostgreSQL 15 / 最新建議版本
• Region：「us-central1」
• 網路：「default」

4. 選取預設網路後，你會看到如下畫面。

選取「設定連線」。

5. 然後選取「使用系統自動分配的 IP 範圍」並繼續。確認資訊後，選取「建立連結」。
6. 設定網路後，即可繼續建立叢集。按一下「CREATE CLUSTER」(建立叢集)，完成叢集設定，如下所示：

請務必變更執行個體 ID (您可以在設定叢集 / 執行個體時找到)，然後

vector-instance。如果無法變更，請記得在所有後續參照中使用例項 ID。

請注意，建立叢集約需 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 查詢陳述式，並貼到編輯器。

按一下「執行」。

資料集已準備就緒，現在來建立 Java Cloud Run 函式應用程式，擷取狀態。

以 Java 建立 Cloud Run 函式，擷取訂單狀態資訊

1. 在以下網址建立 Cloud Run 函式：https://console.cloud.google.com/run/create?deploymentType=function
2. 將函式名稱設為「check-status」，並選擇「Java 17」做為執行階段。
3. 由於這是示範應用程式，您可以採用「允許未經驗證的叫用」驗證設定。
4. 選擇「Java 17」做為執行階段，並選擇「內嵌編輯器」做為原始碼。
5. 此時，編輯器會載入預留位置程式碼。

取代預留位置程式碼

1. 將 Java 檔案名稱改為「ProposalOrdersTool.java」，類別名稱則改為「ProposalOrdersTool」。
2. 將 ProposalOrdersTool.java 和 pom.xml 中的預留位置程式碼，換成本存放區「Cloud Run 函式」資料夾內對應檔案的程式碼。
3. 在 ProposalOrdersTool.java 中找到下列程式碼行，並將預留位置值換成您設定中的值：

String ALLOYDB_INSTANCE_NAME = "projects/<<YOUR_PROJECT_ID>>/locations/us-central1/clusters/<<YOUR_CLUSTER>>/instances/<<YOUR_INSTANCE>>";

4. 按一下「建立」。
5. 系統會建立並部署 Cloud Run 函式。

重要步驟：

部署完成後，為了允許 Cloud 函式存取 AlloyDB 資料庫執行個體，我們將建立 VPC 連接器。

部署完成後，您應該就能在 Google Cloud Run Functions 控制台中看到函式。搜尋新建立的函式 (check-status)，然後依序點選該函式和「EDIT AND DEPLOY NEW REVISIONS」(編輯並部署新修訂版本) (Cloud Run Functions 控制台頂端的「編輯」圖示 (筆))，並變更下列項目：

1. 前往「網路」分頁：

2. 選取「連線至虛擬私有雲，以傳出流量」，然後選取「使用無伺服器 VPC 存取連接器」
3. 在「網路」下拉式選單下方，按一下「網路」下拉式選單，然後選取「新增虛擬私有雲連接器」選項 (如果您尚未設定「預設」連接器)，並按照彈出式對話方塊中的操作說明進行：

4. 提供 VPC 連接器的名稱，並確認區域與執行個體相同。將「網路」值保留為預設值，並將「子網路」設為「自訂 IP 範圍」，IP 範圍為 10.8.0.0 或類似的可用範圍。
5. 展開「顯示縮放設定」，確認設定完全符合下列條件：

6. 按一下「建立」，這個連接器現在應該會列在輸出設定中。
7. 選取新建立的連接器。
8. 選擇透過這個虛擬私有雲連接器轉送所有流量。
9. 依序點選「NEXT」和「DEPLOY」。
10. 更新後的 Cloud 函式部署完成後，您應該會看到產生的端點。
11. 點選 Cloud Run Functions 控制台頂端的「測試」按鈕，並在 Cloud Shell 終端機中執行產生的指令，即可測試函式。
12. 部署的端點是您需要在 .env 變數 CHECK_ORDER_STATUS_ENDPOINT 中更新的網址。

8. 模型設定

代理理解使用者要求和生成回覆的能力，是由大型語言模型 (LLM) 驅動。您的代理程式需要安全地呼叫這個外部 LLM 服務，因此需要驗證憑證。如果沒有有效的驗證，LLM 服務會拒絕代理程式的要求，代理程式也無法運作。

1. 從 Google AI Studio 取得 API 金鑰。
2. 在下一個步驟中設定 .env 檔案時，請將 <<your API KEY>> 換成實際的 API 金鑰值。

9. 設定環境變數

1. 在範本 .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>>
CHECK_ORDER_STATUS_ENDPOINT=<<YOUR_ENDPOINT_TO_CLOUD FUNCTION_TO_READ_ORDER_DATA_FROM_ALLOYDB>>

將預留位置替換為您的值。

10. 執行代理程式

2. 使用終端機前往代理程式專案的上層目錄：

cd renovation-agent

3. 安裝所有依附元件

pip install -r requirements.txt

4. 您可以在 Cloud Shell 終端機中執行下列指令，執行代理程式：

adk run .

5. 如要在 ADK 佈建的網頁版 UI 中執行，請執行以下指令：

adk web

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

user>> 

Hello. Generate Proposal Document for the kitchen remodel requirement. I have no other specification.

11. 結果

@ Multi-agent system for Kitchen Renovation tasks

12. 部署至 Agent Engine

您已測試多代理系統，確認運作正常，現在要將系統設為無伺服器，並在雲端上提供給任何人 / 任何應用程式使用。取消註解 repo 中 agent.py 的下列程式碼片段，即可部署多代理系統：

# Agent Engine Deployment:
# Create a remote app for our multiagent with agent Engine.
# This may take 1-2 minutes to finish.
# Uncomment the below segment when you're ready to deploy.

app = AdkApp(
    agent=root_agent,
    enable_tracing=True,
)

vertexai.init(
    project=PROJECT_ID,
    location=GOOGLE_CLOUD_LOCATION,
    staging_bucket=STAGING_BUCKET,
)

remote_app = agent_engines.create(
    app,
    requirements=[
        "google-cloud-aiplatform[agent_engines,adk]>=1.88",
        "google-adk",
        "pysqlite3-binary",
        "toolbox-langchain==0.1.0",
        "pdfplumber",
        "google-cloud-aiplatform",
        "cloudpickle==3.1.1",
        "pydantic==2.10.6",
        "pytest",
        "overrides",
        "scikit-learn",
        "reportlab",
        "google-auth",
        "google-cloud-storage",
    ],
)
# Deployment to Agent Engine related code ends

使用下列指令，再次從專案資料夾中執行 agent.py：

>> cd adk-renovation-agent

>> python agent.py

這項作業需要幾分鐘才能完成。完成後，您會收到類似下列形式的端點：

'projects/123456789/locations/us-central1/reasoningEngines/123456'

您可以新增「test.py」檔案，並使用下列程式碼測試已部署的代理：

import vertexai
from vertexai.preview import reasoning_engines
from vertexai import agent_engines
import os
import warnings
from dotenv import load_dotenv
load_dotenv() 


GOOGLE_CLOUD_PROJECT = os.environ["GOOGLE_CLOUD_PROJECT"]
GOOGLE_CLOUD_LOCATION = os.environ["GOOGLE_CLOUD_LOCATION"]
GOOGLE_API_KEY = os.environ["GOOGLE_API_KEY"]
GOOGLE_GENAI_USE_VERTEXAI=os.environ["GOOGLE_GENAI_USE_VERTEXAI"]
AGENT_NAME = "adk_renovation_agent"
MODEL_NAME = "gemini-2.5-pro-preview-03-25" 
warnings.filterwarnings("ignore")
PROJECT_ID = GOOGLE_CLOUD_PROJECT

reasoning_engine_id = "<<YOUR_DEPLOYED_ENGINE_ID>>"

vertexai.init(project=PROJECT_ID, location="us-central1")
agent = agent_engines.get(reasoning_engine_id)
print("**********************")
print(agent)
print("**********************")


for event in agent.stream_query(
    user_id="test_user",
    message="I want you to check order status.",
):
    print(event)

在上述程式碼中，取代預留位置「<<YOUR_DEPLOYED_ENGINE_ID>>」的值，然後執行「python test.py」指令，即可與已部署 Agent Engine 的多代理系統互動，開始翻修廚房！

13. 單行部署選項

您已測試部署的多代理系統，現在來瞭解更簡單的方法，將上一步驟的部署步驟抽象化：單行部署選項：

1. Cloud Run：

語法：

adk deploy cloud_run \
--project=<<YOUR_PROJECT_ID>> \
--region=us-central1 \
--service_name=<<YOUR_SERVICE_NAME>> \
--app_name=<<YOUR_APP_NAME>> \
--with_ui \
./<<YOUR_AGENT_PROJECT_NAME>>

在這種情況下：

adk deploy cloud_run \
--project=<<YOUR_PROJECT_ID>> \
--region=us-central1 \
--service_name=renovation-agent \
--app_name=renovation-app \
--with_ui \
./renovation-agent

您可以將部署的端點用於下游整合。

2. Agent Engine：

語法：

adk deploy agent_engine \
  --project <your-project-id> \
  --region us-central1 \
  --staging_bucket gs://<your-google-cloud-storage-bucket> \
  --trace_to_cloud \
  path/to/agent/folder

在這種情況下：

adk deploy agent_engine --project <<YOUR_PROJECT_ID>> --region us-central1 --staging_bucket gs://<<YOUR_BUCKET_NAME>> --trace_to_cloud renovation-agent

Google Cloud 控制台的 Agent Engine UI 應會顯示新代理程式。詳情請參閱這篇網誌。

14. 清理

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

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

15. 恭喜

恭喜！您已成功使用 ADK 建立第一個代理並與其互動！