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

程式碼研究室簡介

上次更新時間：6月 16, 2025

作者：Author: Abirami Sukumaran

1. 總覽

代理是一種自主程式，可與 AI 模型對話，使用自身的工具和背景資訊執行以目標為導向的作業，並能根據事實做出自主決策！

如果應用程式有多個代理程式，且這些代理程式可根據需要自主運作，以便滿足更大的目的，且每個代理程式都具備獨立的知識，並負責特定專注領域，那麼您的應用程式就會成為多代理程式系統。

代理開發套件 (ADK)

Agent Development Kit (ADK) 是彈性模組化架構，可用於開發及部署 AI 代理。ADK 可將多個不同的代理程式例項組合成多代理系統 (MAS)，進而支援建構精密的應用程式。

在 ADK 中，多虛擬服務專員系統是指應用程式中不同虛擬服務專員 (通常會形成階層) 合作或協調，以達成更大的目標。以這種方式建構應用程式可帶來許多優點，包括強化模組化、專業化、可重複使用性和可維護性，以及使用專屬工作流程代理程式定義結構化控制流程的能力。

多代理系統的注意事項

首先，請務必正確理解每個服務專員的專長，並據此做出合理的判斷。—「你知道為什麼需要特定的次要代理人嗎？」，請先解決這個問題。

第二點：如何將這些訊息與根層級代理程式整合，以便路由及解讀每個回應。

第三點：您可以在這份說明文件中找到多種服務專員轉介方式。請確認哪一個適合您的應用程式流程。以及多代理程系統的流程控制所需的各種內容和狀態。

建構項目

我們來建構多代理系統，處理廚房翻修作業。我們會建構一個包含 3 個代理程式的系統。

整修提案代理程式
許可證和合規性檢查代理程式
訂單狀態檢查代理程式

Renovation Proposal Agent，用於產生廚房翻修提案文件。

執照和法規遵循服務代理人，負責處理執照和法規遵循相關工作。

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

我們會建立一個根代理程式，根據需求協調這些代理程式。

需求條件

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

2. 事前準備

建立專案

在 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 以上版本
請執行下列指令，啟用下列 API：

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

如要瞭解 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 思考方塊，該模型具備原生推理功能，可處理長篇幅的上下文要求。

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

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 Preview Image Generation」，即可生成圖片。

我得到以下輸出內容：

這就是 Gemini 的威力！

從理解影片、原生圖像生成，到使用 Google 搜尋提供真實資訊，這些功能都只能透過 Gemini 建構。

您可以透過 AI Studio 取得這個原型、取得 API 金鑰，並利用 Vertex AI ADK 的強大功能，將原型擴充為完整的代理應用程式。

4. ADK 設定

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

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

python -m venv .venv

啟用虛擬環境：

source .venv/bin/activate

安裝 ADK

pip install google-adk

5. 專案結構

透過 Cloud Shell Terminal，在所需專案位置建立目錄

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

前往 Cloud Shell 編輯器，建立下列專案結構的檔案 (一開始為空白)：

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

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 值 (在「設定環境變數」步驟中)。

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

依序前往「權限」->「查看主體」->「授予存取權」。將「主體」選為「allUsers」，「角色」選為「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.

建立依附元件清單

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

多代理系統原始碼說明

agent.py 檔案會使用代理開發套件 (ADK) 定義廚房翻修多代理系統的結構和行為。我們來逐一瞭解主要元件：

代理程式定義

RenovationProposalAgent

這個服務專員負責製作廚房翻修提案文件。可視需要採用廚房大小、所需風格、預算和客戶偏好設定等輸入參數。系統會根據這些資訊，使用大型語言模型 (LLM) Gemini 2.5 產生詳細提案。產生的提案會儲存在 Google Cloud Storage 值區中。

PermitsAndComplianceCheckAgent

這個服務專員的主要工作是確保整修工程符合當地建築法規。這項服務會接收有關擬議整修工程的資訊 (例如結構變更、電氣工程、管線修改)，並使用 LLM 檢查執照規定和法規遵循規定。代理程式會使用知識庫中的資訊 (您可以自訂知識庫，以便存取外部 API 並收集相關法規)。

OrderingAgent

這個代理程式 (如果您不想立即導入，可以註解掉) 會處理檢查裝修所需材料和設備的訂單狀態。如要啟用這項功能，您必須按照設定步驟建立 Cloud Run 函式。代理程式隨後會呼叫這個 Cloud Run 函式，與含有訂單資訊的 AlloyDB 資料庫互動。這裡示範如何整合資料庫系統，以便追蹤即時資料。

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

root_agent 可做為多代理系統的中央自動化調度管理器。它會接收初始翻修要求，並根據要求的需求決定要叫用哪些子代理程式。舉例來說，如果要求需要檢查許可規定，就會呼叫 PermitsAndComplianceCheckAgent。如果使用者想查看訂單狀態，系統會呼叫 OrderingAgent (如果已啟用)。

接著，root_agent 會收集子代理程式的回應，並將這些回應合併，為使用者提供完整的回應。這可能包括概述提案、列出必要許可，以及提供訂單狀態更新。

資料流程與重要概念

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

要求會由 root_agent 接收。
root_agent 會分析要求，並將其導向適當的子代理程式。
子代理程式會使用 LLM、知識庫、API 和資料庫，處理要求並產生回覆。
子代理程式會將回應傳回至 root_agent。
root_agent 會將回應合併，並為使用者提供最終輸出內容。

大型語言模型 (LLM)

這些服務專員主要仰賴大型語言模型生成文字、回答問題，以及執行推理工作。大型語言模型是代理程式瞭解及回應使用者要求的「大腦」。我們在這個應用程式中使用 Gemini 2.5。

Google Cloud Storage

用於儲存產生的裝修提案文件。您必須建立值區，並授予必要權限，讓服務機器人可以存取該值區。

Cloud Run (選用)

OrderingAgent 會使用 Cloud Run 函式與 AlloyDB 連結。Cloud Run 提供無伺服器環境，可因應 HTTP 要求執行程式碼。

AlloyDB

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

.env 檔案

.env 檔案會儲存 API 金鑰、資料庫憑證和值區名稱等機密資訊。請務必妥善保管這個檔案，並勿將檔案提交至存放區。也會儲存代理程式和 Google Cloud 專案的設定。root_agent 或支援函式通常會從這個檔案讀取值。請確認所有必要變數都已正確設定在 .env 檔案中。包括 Cloud Storage 值區名稱

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 (您可以在設定叢集 / 執行個體時找到這個 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 查詢陳述式複製到編輯器中。

按一下「執行」。

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

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

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

替換預留位置程式碼

將 Java 檔案名稱變更為「ProposalOrdersTool.java」，並將類別名稱變更為「ProposalOrdersTool」。
將 ProposalOrdersTool.java 和 pom.xml 中的預留位置程式碼，替換為這個 repo 中「Cloud Run 函式」資料夾中相應檔案的程式碼。
在 ProposalOrdersTool.java 中找到下列程式碼行，將預留位置值替換為設定中的值：

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

按一下「建立」。
系統會建立及部署 Cloud Run 函式。

重要步驟：

部署完成後，我們會建立 VPC 連接器，讓 Cloud 函式能夠存取 AlloyDB 資料庫執行個體。

部署作業完成後，您應該會在 Google Cloud Run Functions 控制台中看到函式。搜尋新建立的函式 (check-status)，然後點選該函式，接著點選「編輯並部署新修訂版本」 (可透過 Cloud Run 函式控制台頂端的「編輯」圖示 (筆) 辨識)，然後變更下列項目：

前往「Networking」(網路) 分頁：

依序選取「連線至虛擬私有雲，以傳出流量」和「使用無伺服器虛擬私有雲存取連接器」
在「Network」下拉式選單的「Settings」下方，點選「Network」下拉式選單，然後選取「Add New VPC Connector」選項 (如果您尚未設定「預設」)，並按照彈出式對話方塊中的操作說明進行：

請為 VPC 連接器提供名稱，並確認區域與執行個體相同。將「Network」值保留為預設值，並將「Subnet」設為「Custom IP Range」，IP 範圍為 10.8.0.0 或可用的類似值。
展開「顯示縮放設定」，並確認設定值是否完全符合下列設定：

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

8. 模型設定

代理程式能夠理解使用者要求並產生回覆，這項能力仰賴大型語言模型 (LLM) 的支援。您的代理程式需要向這個外部 LLM 服務發出安全呼叫，而這項操作需要驗證憑證。如果沒有有效的驗證，LLM 服務會拒絕代理程式的要求，代理程式就無法運作。

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

9. 設定環境變數

請在這個 repo 的範本 .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. 執行代理程式

cd renovation-agent

安裝所有依附元件

pip install -r requirements.txt

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

adk run .

您可以執行下列指令，在 ADK 佈建的網頁 UI 中執行此指令：

adk web

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

user>> 

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

11. 結果

@ 廚房翻修任務的多代理系統

12. 部署至 Agent Engine

既然您已測試多重代理程式系統並確認運作正常，現在就讓我們將其改為無伺服器架構，並在雲端上提供，讓任何人 / 任何應用程式都能使用。從該存放區的 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. 一行部署選項

您已測試已部署的多代理系統，現在讓我們瞭解更簡單的方法，藉此抽象化我們在上一個步驟中執行的部署步驟：一行部署選項：

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

您可以將已部署的端點用於後端整合。

給 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 帳戶收取這篇文章所用資源的費用，請按照下列步驟操作：

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

15. 恭喜

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

回報錯誤