程式碼研究室簡介
1. 總覽
今天的 AI 建構作業從何開始？對大多數人來說，這通常始於一個簡單的問題：「模型能否實際解決我一直在思考的問題？」這時，Google AI Studio 就能派上用場。您可以快速製作任何原型。我一直想重新裝潢廚房，相信 Gemini 可以提供協助。但我只是工程師，不是一般承包商。我甚至不知道該要求什麼，因為有太多因素需要考量，例如法規、固定裝置等等。因此，我們來細分問題，讓 Gemini 為我們產生超詳細的提示，然後產生完整的整修計畫，並以視覺化方式呈現改建工程！等等，我該如何協助商家擴大業務？輸入 AGENTS!!!
代理是一種自主程式，可與 AI 模型對話，使用自身的工具和背景資訊執行以目標為導向的作業，並能根據事實做出自主決策！
代理開發套件 (ADK)
Agent Development Kit (ADK) 是彈性模組化架構，可用於開發及部署 AI 代理。ADK 可將多個不同的代理程式例項組合成多代理系統 (MAS)，進而支援建構精密的應用程式。
在 ADK 中，多虛擬服務專員系統是指應用程式中不同虛擬服務專員 (通常會形成階層) 合作或協調，以達成更大的目標。以這種方式建構應用程式可帶來許多優點，包括強化模組化、專業化、可重複使用性和可維護性，以及使用專屬工作流程代理程式定義結構化控制流程的能力。
建構項目
準備好從 PROMPT 原型轉移到建構服務端了嗎？我們會建立代理程式，協助您為廚房翻修專案產生提案文件。本實驗室的學習內容如下：
- 建構簡單的代理程式，使用 ADK 產生翻修提案文件
- 將產生的整修提案文件儲存在 Cloud Storage 值區
- 在 Cloud Shell 和代理程式網頁輸出中測試代理程式
需求條件
2. 事前準備
建立專案
- 在 Google Cloud 控制台的專案選取器頁面中，選取或建立 Google Cloud 專案。
- 確認 Cloud 專案已啟用計費功能。瞭解如何檢查專案是否已啟用計費功能。
- 此外，如果您正在閱讀本文，並想獲得一些抵免額，以便開始使用 Google Cloud 和 ADK，請點選這個連結 兌換抵免額。
- 你可以按照這篇文章中的操作說明兌換。請注意，此連結的兌換期限為 2025 年 7 月 15 日。
- 按一下這個連結啟用 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 指令和用法，請參閱說明文件。
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 思考方塊，該模型具備原生推理功能，可處理長篇幅的上下文要求。
請參閱下方的回應程式碼片段：
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」，即可生成圖片。
我得到以下輸出內容：
這就是 Gemini 的威力！
從理解影片、原生圖像生成，到使用 Google 搜尋提供真實資訊，這些功能都只能透過 Gemini 建構。
您可以透過 AI Studio 取得這個原型、取得 API 金鑰，並利用 Vertex AI ADK 的強大功能，將原型擴充為完整的代理應用程式。
4. ADK 設定
接著，我們來使用在「開始前」一節中啟用的 Cloud Shell 終端機：
- 建立並啟用虛擬環境 (建議)
在 Cloud Shell 終端機中建立虛擬環境：
python -m venv .venv
啟用虛擬環境：
source .venv/bin/activate
- 安裝 ADK
pip install google-adk
5. 專案結構
- 在 Cloud Shell 終端機中，在所需的專案位置為代理應用程式建立根目錄：
mkdir agentic-apps
- 在主目錄中建立專屬於目前專案的資料夾：
mkdir renovation-agent
- 前往 Cloud Shell 編輯器，建立下列專案結構的檔案 (一開始可以是空白檔案)：
renovation-agent/
__init__.py
agent.py
requirements.txt
.env
6. 原始碼
- 前往「init.py」，並更新為以下內容：
from . import agent
- 前往 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 的工具。
- 確認您有 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) 定義廚房翻修多代理系統的結構和行為。我們來逐一瞭解主要元件：
服務專員定義
根代理程式 (自動化調度管理工具)：proposal_agent
root_agent 會擔任這個單一代理程式系統的調度器。它會接收初始翻修要求，並根據要求的需求決定要叫用哪些工具。
接著，root_agent 會收集工具的回應，並將這些回應合併，為使用者提供完整的回應。在本例中，我們只有一個工具「store_pdf」。
7. 資料流程與重要概念
使用者透過 ADK 介面 (終端機或網頁 UI) 發出要求。
- 要求會由 root_agent 接收。
- root_agent 會分析要求，並在需要時將其轉送至工具。
- 「store_pdf」工具可將修訂過的文字內容寫入 PDF 檔案，然後上傳至 Google Cloud Storage。
- 然後將回應傳回給 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 值區名稱
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>>
將預留位置替換為您的值。
10. 執行代理程式
- 使用終端機，前往服務專員專案的上層目錄：
cd agentic-apps/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 in a proper format that applies to a renovation contract. Remember this text will eventually be stored as a pdf file so make sure to have the formatting appropriate. I have no other specification.
12. 清除所用資源
如要避免系統向您的 Google Cloud 帳戶收取這篇文章所用資源的費用，請按照下列步驟操作：