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

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

程式碼研究室簡介

subject上次更新時間：5月 25, 2025
account_circle作者：Author: Abirami Sukumaran

1. 總覽

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

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

代理開發套件 (ADK)

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

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

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

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

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

建構項目

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

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

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

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

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

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

需求條件

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

2. 事前準備

建立專案

  1. 在 Google Cloud 控制台的專案選取器頁面中，選取或建立 Google Cloud 專案。
  2. 確認 Cloud 專案已啟用計費功能。瞭解如何檢查專案是否已啟用計費功能。

此外，如果您正在閱讀本文，並想取得一些抵免額來開始使用 Google Cloud 和 ADK，請點選這個連結兌換抵免額。你可以按照這裡的說明兌換優惠。請注意，這個連結的兌換期限只到 5 月底。

  1. 按一下這個連結啟用 Cloud Shell。您可以點選 Cloud Shell 中的對應按鈕，在 Cloud Shell 終端機 (用於執行雲端指令) 和編輯器 (用於建構專案) 之間切換。
  2. 連線至 Cloud Shell 後，請使用下列指令確認您已通過驗證，且專案已設為您的專案 ID：
gcloud auth list
  1. 在 Cloud Shell 中執行下列指令，確認 gcloud 指令知道您的專案。
gcloud config list project
  1. 如果未設定專案，請使用下列指令進行設定：
gcloud config set project <YOUR_PROJECT_ID>
  1. 請確認您已安裝 Python 3.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 思考方塊，這項功能具備原生推理能力，可處理長篇幅的上下文要求。

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

a80d4bad4b3864f7.png

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

我得到以下輸出內容：

b5b1e83fcada28f5.png

這就是 Gemini 的威力！

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

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

4. ADK 設定

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

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

python -m venv .venv

啟用虛擬環境：

source .venv/bin/activate
  1. 安裝 ADK
pip install google-adk

5. 專案結構

  1. 在 Cloud Shell 終端機中，在所需專案位置建立目錄
mkdir renovation-agent
  1. 前往 Cloud Shell 編輯器，建立下列專案結構的檔案 (一開始為空白)：
renovation-agent/
        __init__.py
        agent.py
        .env

6. 原始碼

  1. 前往「init.py」，並更新為以下內容：
from . import agent
  1. 前往 agent.py，並使用下列路徑中的內容更新檔案：
https://github.com/AbiramiSukumaran/adk-renovation-agent/blob/main/agent.py

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

  1. 確認您有 Cloud Storage 值區

用於儲存服務專員產生的提案文件。建立並提供存取權，讓使用 Vertex AI 建立的多代理系統能夠存取。方法如下：

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

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

  1. 建立依附元件清單

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

7. 資料庫設定

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

建立叢集和執行個體

  1. 前往 Cloud 控制台的 AlloyDB 頁面。如要輕鬆在 Cloud Console 中找到大部分的頁面，請使用控制台的搜尋列進行搜尋。
  2. 在該頁面中選取「建立叢集」：

f76ff480c8c889aa.png

  1. 您會看到類似下方的畫面。使用下列值建立叢集和執行個體 (如果您要從存放區複製應用程式程式碼，請務必確認這些值相符)：
  • 叢集 ID："vector-cluster"
  • 密碼："alloydb"
  • PostgreSQL 15 / 最新版本 (建議使用)
  • Region："us-central1"
  • 網路："default"

538dba58908162fb.png

  1. 選取預設網路後，畫面會顯示如下圖所示畫面。

選取「設定連線」。
7939bbb6802a91bf.png

  1. 接著選取「使用系統自動分配的 IP 範圍」，然後按一下「繼續」。查看相關資訊後，請選取「建立連線」。768ff5210e79676f.png
  2. 網路設定完成後，您可以繼續建立叢集。按一下「CREATE CLUSTER」，完成叢集設定，如下所示：

e06623e55195e16e.png

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

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

請注意，叢集建立作業大約需要 10 分鐘。成功後，畫面上會顯示剛剛建立的叢集總覽。

資料擷取

接下來，我們要新增一個包含商店資料的表格。前往 AlloyDB，選取主要叢集，然後選取 AlloyDB Studio：

847e35f1bf8a8bd8.png

您可能需要等待執行個體建立完成。完成後，請使用建立叢集時建立的憑證登入 AlloyDB。使用下列資料驗證 PostgreSQL：

  • 使用者名稱："postgres"
  • 資料庫：postgres
  • 密碼：alloydb

成功驗證 AlloyDB Studio 後，您就可以在編輯器中輸入 SQL 指令。您可以使用最後一個視窗右側的加號新增多個編輯器視窗。

91a86d9469d499c4.png

您會在編輯器視窗中輸入 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 函式，擷取訂單狀態資訊

  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 中的預留位置程式碼，替換為這個 repo 中「Cloud Run 函式」資料夾中相應檔案的程式碼。
  3. 在 ProposalOrdersTool.java 中找到下列程式碼行，將預留位置值替換為設定中的值：
String ALLOYDB_INSTANCE_NAME = "projects/<<YOUR_PROJECT_ID>>/locations/us-central1/clusters/<<YOUR_CLUSTER>>/instances/<<YOUR_INSTANCE>>";
  1. 按一下「建立」。
  2. 系統會建立及部署 Cloud Run 函式。

重要步驟：

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

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

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

828cd861864d99ea.png

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

6559ccfd10e597f2.png

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

199b0ccd80215004.png

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

8. 模型設定

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

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

9. 設定環境變數

  1. 請在這個 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. 執行代理程式

  1. 使用終端機，前往服務專員專案的上層目錄：
cd renovation-agent
  1. 安裝所有依附元件
pip install -r requirements.txt
  1. 您可以在 Cloud Shell 終端機中執行下列指令，執行這個代理程式：
adk run .
  1. 您可以執行下列指令，在 ADK 佈建的網頁 UI 中執行此指令：
adk web
  1. 請使用下列提示進行測試：
user>> 

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

11. 結果

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

623fa35fce53b51b.png

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. 清除所用資源

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

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

14. 恭喜

恭喜！您已成功使用 ADK 建立第一個服務專員，並與該服務專員互動！

bug_report 回報錯誤