使用 ADK 將原型轉換為代理程式

1. 總覽

今天的 AI 建構作業從何開始?對大多數人來說,這通常始於一個簡單的問題:「模型能否實際解決我一直在思考的問題?」這時,Google AI Studio 就能派上用場。您可以快速製作任何原型。我一直想重新裝潢廚房,相信 Gemini 可以提供協助。但我只是工程師,不是一般承包商。我甚至不知道該要求什麼,因為有太多因素需要考量,例如法規、固定裝置等等。因此,我們來細分問題,讓 Gemini 為我們產生超詳細的提示,然後產生完整的整修計畫,並將改建內容視覺化!等等,我如何才能真正協助商家擴大規模?輸入 AGENTS!!!

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

代理開發套件 (ADK)

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

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

建構項目

準備好從 PROMPT 原型轉移到建構服務代理了嗎?我們會建立代理程式,協助您為廚房翻修專案產生提案文件。在本實驗室中,您將:

  1. 使用 ADK 建構簡單的代理程式,產生整修提案文件
  2. 將產生的整修提案文件儲存在 Cloud Storage 值區
  3. 在 Cloud Shell 和代理程式網頁輸出中測試代理程式

需求條件

  • ChromeFirefox 等瀏覽器
  • 已啟用計費功能的 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. 原型

前往 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 甚至會引用來源!

接著,請嘗試使用其他提示來實現這個想法:

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
        requirements.txt
        .env

6. 原始碼

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

在 agent.py 中,我們會匯入必要的依附元件、從 .env 檔案擷取設定參數,並定義 root_agent,產生提案文件並儲存在 Cloud Storage 值區中。為了執行 Cloud Storage 步驟,我們使用名為 store_pdf 的工具。

  1. 確認您有 Cloud Storage 值區

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

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

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

  1. 建立依附元件清單

在 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 會收集子代理程式的回應,並將這些回應合併,為使用者提供完整的回應。這可能包括概述提案、列出必要許可,以及提供訂單狀態更新。

7. 資料流程與重要概念

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

  1. 要求會由 root_agent 接收。
  2. root_agent 會分析要求,並將其導向適當的子代理程式。
  3. 子代理程式會使用 LLM、知識庫、API 和資料庫,處理要求並產生回覆。
  4. 子代理程式會將回應傳回至 root_agent。
  5. 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 值區名稱

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

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

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. 結果

如要使用 adk run . 指令:

ae50e6f6b2bab0a0.png

38a2c34667a8fd05.png

...

a8a39e8323d3ceb9.png

你可以驗證是否已在 Cloud Storage 值區中建立裝修提案文件。

12. 清理

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

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

13. 恭喜

恭喜!您已成功使用 ADK 建立及互動多代理應用程式!多代理系統旨在自動執行提案產生、檢查執照和追蹤訂單狀態等工作,簡化廚房裝修流程。每個代理程式都有特定角色,而 root_agent 會協調這些活動,提供全面的解決方案。系統會利用大型語言模型、Google Cloud 服務,以及可能的外部 API 來提供功能。這裡是產品說明文件的連結。