ADK 密集課程 - 從新手到專家

1. 學習目標

歡迎參加 ADK 大師課程 - 踏上多代理系統之旅

您即將踏入精彩的 AI 代理世界。忘掉只能回答問題的簡單聊天機器人吧！我們深入研究 Agent Development Kit (ADK)，建構出精密的自治系統，能夠推論、規劃及使用工具來完成複雜工作。

課程藍圖

完成本教學課程後，您將能夠：

  • 建構第一個 AI 代理程式：從無到有，建構出功能齊全的代理程式，可瞭解使用者需求、使用 Google 搜尋等工具，並生成詳細實用的回覆。
  • 掌握自訂工具：將代理程式連結至自訂函式和 API，發揮代理程式的真正威力。您將教導代理程式擷取即時資料，例如即時天氣預報。
  • 建構多代理系統：瞭解「代理即工具」模式，這項革命性概念是指代理會將任務委派給其他專用代理，建立共同合作的 AI 專家團隊。
  • 協調複雜工作流程：除了簡單的委派作業，您還可以運用路由器、連續鏈結、迴圈和平行執行等進階模式，建構強大、高效且智慧的應用程式，處理幾乎所有要求。
  • 為代理提供記憶功能：瞭解對話記憶功能的重要性，讓代理能夠處理後續問題、從意見回饋中學習，並順暢管理多步驟工作。

我們開始吧！🚀

2. 設定 GCP

設定 GCP 專案

如要啟用 AI 代理程式，我們需要兩項資訊：提供基礎的 Google Cloud 專案，以及存取 Google 強大模型的專案 ID。

步驟 1：啟用帳單帳戶

如要執行本程式碼研究室，您需要有具備部分抵免額的帳單帳戶。請使用本程式碼研究室頂端橫幅中的抵免額開始操作。如果已連結帳單帳戶，可以略過這個步驟。

步驟 2：建立新的 GCP 專案

  • 前往 Google Cloud 控制台，建立新專案。

建立新的 GCP 帳戶

  • 前往 Google Cloud 控制台，建立新專案。
  • 開啟左側面板，按一下 Billing，確認帳單帳戶是否已連結至這個 GCP 帳戶。

將帳單帳戶連結至 GCP 帳戶

如果看到這個頁面，請檢查 manage billing account，選擇 Google Cloud 試用方案，然後連結至該方案。

步驟 3：複製專案 ID

  • 前往 console.cloud.google.com。
  • 按一下頁面頂端的專案選取器下拉式選單。
  • 按一下「全部」分頁標籤 (因為新專案可能尚未顯示在「最近」中)。
  • 選取剛才建立的專案 ID。

03-05-project-all.png

3. 第 1 堂：使用 Runner 打造第一個代理

roadmap1

我們先從基礎概念開始。我們將在此建立第一個簡單的代理程式 day_trip_agent。這個代理的目的是根據使用者要求生成全天行程，包括預算考量。本範例將介紹 ADK 中任何代理互動的三個核心元件：

  • 代理：作業的核心大腦。這類代理的定義取決於指令 (個性與任務)、使用的 AI 模型 (例如 Gemini) 和可存取的工具。
  • 工作階段：對話的記憶。儲存互動記錄 (使用者訊息和代理程式回覆)，以便進行連續對話。
  • 執行器：執行工作的引擎。這個函式會接收代理程式和工作階段，處理新的使用者查詢，並自動化調度管理生成回覆的步驟。

➡️ 如何在筆記本中找到這項功能

👉 這對應於「第 1 部分：您的第一個代理程式 - 旅遊行程規劃精靈 🧞」底下的儲存格。🌟

agent robot is reading

  • 代理程式定義：尋找 create_day_trip_agent() 函式。這是定義代理程式的位置。請注意詳細的指令字串，這是提示，可告知代理程式如何運作。我們也為它提供第一個工具：Google 搜尋。
  • 輔助函式：這裡定義了 run_agent_query() 輔助函式。我們會在整個筆記本中使用這項公用程式，簡化查詢執行作業。
  • 測試執行：run_day_trip_genie() 函式會模擬使用者要求「經濟實惠」且「輕鬆」的一日遊行程。代理會根據指令和 Google 搜尋工具尋找合適的地點，並建立以 Markdown 格式編排的行程。

➡️ 動作：檢查 day_trip_agent 的指令提示。請注意，測試查詢中「實惠」行程的要求，與代理程式「注意預算」的指引直接相關。

4. 工作階段 2：自訂工具 🛠️

roadmap2

Google 搜尋功能強大，但如果將 AI 代理程式連結至專屬資料來源、API 或自訂邏輯，就能發揮真正的潛力。在本節中，我們會從簡單的 Python 函式建立自訂工具。

函式工具最重要的部分是 docstring。ADK 會自動剖析 docstring，瞭解工具的作用、接受的參數 (Args) 和傳回的內容 (Returns)。大型語言模型 (LLM) 會讀取這段說明，決定使用工具的時機和方式。

➡️ 如何在筆記本中找到這項功能

👉 這對應至「2.1 The Simple FunctionTool: Calling a Real-Time Weather API」(2.1 簡單的 FunctionTool：呼叫即時天氣 API) 下方的儲存格。🌟

ADK 工具

  • 工具定義：get_live_weather_forecast(location: str) 函式是自訂工具的核心。這個函式會接收城市名稱、呼叫公用的美國國家氣象局 API，並傳回包含溫度和天氣預報的字典。
  • 代理程式定義：建立 weather_agent 並在初始化時傳遞 tools=[get_live_weather_forecast]，為其配備新工具。代理程式的指令明確要求先使用這項工具，再建議戶外活動。
  • 測試執行：查詢「我想在太浩湖附近健行，天氣如何？」會直接觸發代理程式使用 get_live_weather_forecast 工具，因為指令要求這麼做。

➡️ 動作：請閱讀 get_live_weather_forecast 函式的 docstring 和 weather_agent 的指令。請注意兩者之間的直接關係。

5. 工作階段 3：代理即工具 🧑‍🍳

roadmap3

既然可以建立專家團隊，何必打造單一的單體代理？Agent-as-a-Tool 模式是建構複雜系統的強大方式，主要代理 (通常稱為協調器或路由器) 會將工作委派給其他更專注的代理。

這個模式可讓您建立模組化、可重複使用的代理程式。舉例來說，您可以讓一位代理專門負責資料庫查詢、另一位專門負責創意寫作，第三位則擔任友善的服務人員。協調器的工作是瞭解使用者的要求，並將要求轉送給合適的專家。

➡️ 如何在筆記本中找到這項功能

👉 這對應到「2.2 The Agent-as-a-Tool: Consulting a Specialist 🧑‍🍳」底下的儲存格。🌟

行程資料

這個範例會建構複雜的多層代理系統：

  • 專家：
    • food_critic_agent：高度專業的代理程式，只提供餐廳建議。
    • db_agent：模擬代理，假裝查詢資料庫中的飯店資訊。
    • concierge_agent：中階代理，可充當禮貌的禮賓服務專員。最重要的是，它本身就是 food_critic_agent。
  • 自動化調度管理工具 (trip_data_concierge_agent)：這是使用者互動的頂層代理程式。這項指令會將其變成「旅遊規劃大師」，並提供兩個可呼叫其他代理的工具：
    • call_db_agent：呼叫 db_agent 的函式。
    • call_concierge_agent：呼叫 concierge_agent 的函式。
  • 流程：run_trip_data_concierge() 中的測試執行會示範完整的委派鏈。
    • 使用者向協調器詢問飯店和附近的餐廳。
    • 協調器的指令會告知協調器，先使用 call_db_agent 工具取得飯店資料。
    • 然後，Orchestrator 會使用 call_concierge_agent 工具取得建議。
    • concierge_agent 收到要求後，會使用自己的工具 food_critic_agent 取得餐廳建議。

美食評論家的回覆會傳回給服務人員，服務人員會禮貌地將回覆整理成適當格式，然後傳回給協調器，最後由協調器向使用者顯示回覆。

動作：在 run_trip_data_concierge() 下的測試執行作業中追蹤執行流程。請注意，TOOL CALLED 列印內容會顯示從自動調度管理工具到專家的委派鏈。這是循序的指揮鏈。

6. 工作階段 4：代理程式記憶體 🧠

roadmap4

真正的智慧型代理不只是回應單次查詢，必須記住對話內容、瞭解情境，並根據意見回饋調整。這項機制是透過適當的工作階段管理來達成。「迴圈代理」是指持續進行對話迴圈的代理，並由記憶體提供支援。

如果對多個依序查詢使用相同的會期物件，代理程式就能「看到」整個對話記錄。因此可以處理後續問題、根據意見回饋修正內容，以及規劃多步驟工作。

➡️ 如何在筆記本中找到這項功能

👉 這對應到「第 3 部分：具備記憶功能的代理程式 - 適應性規劃工具 🗺️」下方的儲存格。🌟

代理記憶

  • 代理定義：create_multi_day_trip_agent() 函式定義的代理會逐步規劃行程。這項指令的重點在於記住背景資訊、處理意見回饋，以及每天規劃行程。

情境 3a：具備記憶功能的代理程式 (✅)

這項測試會在 run_adaptive_memory_demonstration() 函式中執行。

  • 系統會建立單一 trip_session，並在連續三回合中重複使用。
  • 第 1 回合：使用者發起 2 天的行程規劃。
  • 第 2 輪：使用者提供意見回饋 (「我不太喜歡城堡」)。由於代理程式會記住第 1 輪對話，因此瞭解要變更計畫的哪個部分，並提供替代方案。
  • 第 3 輪：使用者確認變更並要求下一個步驟。服務專員會記住所有資訊，並繼續規劃第 2 天的行程。

情境 3b：沒有記憶功能的代理程式 (❌)

這項測試會在 run_memory_failure_demonstration() 函式中執行。

這項作業會刻意出錯，藉此說明工作階段管理的重要性。每次對話都會啟動新工作階段。

  • 第 1 回合：使用者在 session_one 中啟動行程。代理會正確回覆。
  • 第 2 輪：使用者要求規劃第 2 天的行程，但查詢是在全新的 session_two 中傳送。由於這個新工作階段沒有記錄，因此服務專員會感到困惑。他失憶了！因此無法得知你正在規劃哪趟行程。

動作：比較 run_adaptive_memory_demonstration() 和 run_memory_failure_demonstration() 中的代理程式回覆。這是筆記本中最重要的概念：持續對話需要持續工作階段。

7. 第 5 堂：路由器代理程式 🚏

roadmap5

單一代理程式能做的事有限。如要處理真正複雜的使用者要求，我們需要專業的服務專員團隊。但我們如何知道要為特定查詢使用哪個代理程式？這時 Router Agent 就能派上用場。

路由器代理會做為「主要」代理或調度員，這項代理的唯一用途是分析使用者傳入的查詢，並決定哪位專員代理 (或代理工作流程) 最適合這項工作。這個代理不會直接回答查詢，只會將查詢轉送給正確的下游代理。

舉例來說，查詢「最好吃的壽司」應交由 foodie_agent 處理，而「本週末的演唱會」問題則應由 weekend_guide_agent 處理。

➡️ 在筆記本中尋找這項資訊：

這個概念是整個筆記本的核心，但首先會在「第 1 部分：多代理程式大混戰 - 循序工作流程 🧠→🤖→🤖」🌟中介紹。

Router Agent

  • 代理定義：程式碼儲存格會定義多個專門代理 (day_trip_agent、foodie_agent、transportation_agent)，以及最重要的 router_agent。請密切注意 router_agent 的指令提示，其中明確指出只能傳回最適合這項工作的代理名稱。
  • 執行邏輯：run_sequential_app 函式會示範如何先呼叫 router_agent 取得決策 (chosen_route)，然後在 if/elif 區塊中使用該決策，執行適當的專家代理程式。

8. 第 6 堂：SequentialAgent ⛓️

roadmap6

部分工作需要依特定順序執行多個步驟。例如：「在帕羅奧圖找一家最好吃的壽司店，然後告訴我怎麼去。」這項程序分為兩個步驟：先找出餐廳，再取得路線。

ADK 提供簡潔有力的管理方式，可透過 SequentialAgent 達成此目的。這是特殊的工作流程代理，會依預先定義的順序執行子代理清單。

魔法就在於共用狀態。序列中某個代理程式的輸出內容可自動儲存至共用狀態字典，然後做為下一個代理程式的輸入內容，因此不需要複雜的手動程式碼，即可在步驟之間傳遞資訊。

➡️ 在筆記本中尋找這項資訊：

👉 這部分內容請參閱第 2 部分 (ADK 方法)：使用 SequentialAgent 建立多代理系統 🧠→⛓️→🤖。🌟

Sequential Agent

  • 代理程式重構：在本節的第一個程式碼儲存格中，請注意 foodie_agent 和 transportation_agent 的主要變更：
    • 「foodie_agent」現在有 output_key="destination"。這會告知 ADK 將最終答案儲存到共用狀態中名為 destination 的變數。
    • 「transportation_agent」的指令提示現在含有預留位置「{destination}」。ADK 會自動將共用狀態的值插入這個預留位置。
  • 定義工作流程：find_and_navigate_agent 定義為 SequentialAgent，且 sub_agents 設為 [foodie_agent, transportation_agent]，確保這些代理會依確切順序執行。
  • 簡化執行：請參閱本節中的 run_sequential_app 函式。複雜的 if/elif 邏輯消失了！find_and_navigate_agent 現在會視為單一可呼叫的單元，ADK 會自動處理內部循序步驟。

9. 第 7 堂：LoopAgent 🔁

roadmap7

並非所有問題都有直接的解決方法。有時我們需要提出解決方案、批評並修正，直到符合特定限制為止。

為此，ADK 提供 LoopAgent。這個工作流程代理程式會反覆執行一連串的子代理程式，直到符合特定條件為止。這非常適合用來建構「完美主義者」代理程式，這類代理程式可以規劃、評論及改善自己的工作。

圖表顯示 Planner Agent 先建立計畫，接著輸入 LoopAgent。Critic Agent會檢查方案。如果發現有瑕疵，Refiner Agent 會建立新版本，然後重複上述流程。如果計畫可行，Refiner Agent 會呼叫 exit_loop 工具，並傳回經過驗證的最終計畫。

Loop Agent

➡️ 在筆記本中尋找這項資訊：

👉 如需相關說明，請參閱「使用 LoopAgent 疊代發想點子 🧠→🔁→🤖」一文。🌟

  • 核心代理：工作流程會使用 planner_agent、critic_agent 和 refiner_agent。
  • 迴圈定義：refinement_loop 定義為 LoopAgent，可協調 critic_agent、refiner_agent 和 sets max_iterations=3。
  • 結束條件：當 critic_agent 核准計畫時，迴圈會終止，並導致 refiner_agent 呼叫自訂 exit_loop 工具。

10. 第 8 集：ParallelAgent ⚡️

roadmap8

效率至關重要。如果使用者一次要求多項不相關的資訊，逐一執行這些搜尋會很慢。

ParallelAgent就是解決方案。這個工作流程代理會並行執行子代理清單。所有平行工作完成後，系統會收集結果並綜合分析，產生單一的完整回覆。

這張圖表顯示 ParallelAgent 採用單一查詢，並將工作分成三個並行軌。museum_finder、concert_finder 和 restaurant_finder 會同時執行。這三項作業完成後，系統會合併個別結果 (儲存至共用狀態)，並傳遞至最終的 Synthesis Agent，將結果整合成一個答案。

➡️ 在筆記本中尋找這項資訊：

👉 這個工作流程的詳細說明請參閱「使用 ParallelAgent 進行平行電源 🧠→⚡️→🤖🤖🤖」一節。🌟

Parallel Agent

  • 專家代理程式：定義三個專家代理程式，每個代理程式都有專屬的 output_key (例如 museum_result)。
  • 平行工作流程：parallel_research_agent 定義為 ParallelAgent，並列出三個搜尋代理做為子代理。
  • 綜合步驟：在平行步驟之後，最終的 synthesis_agent 會使用預留位置 ({museum_result}、{concert_result} 等) 從共用狀態收集所有發現，並格式化成簡潔的摘要。

11. 附錄：ADK Web - 🍎 適用於 Mac/Linux

roadmap9

本指南將逐步說明如何在本機電腦上設定及執行 ADK Day Trip Planning Agent。

必要條件

  • Python 3.8 以上版本
    • Python 3.9 以上版本：安裝 google-adk==1.5.0 (最新版本，具備完整功能)
    • Python 3.8：安裝 google-adk==0.3.0 (相容版本)
  • Google AI Studio API 金鑰
  • 網際網路連線

步驟 1：複製存放區

開啟終端機並執行：

git clone https://github.com/cuppibla/ADK_Basic.git
cd ADK_Basic

步驟 2：設定虛擬環境並安裝依附元件

選項 A：自動設定 (建議)

# Run the setup script
chmod +x setup_venv.sh
./setup_venv.sh

選項 B：手動設定

# Create virtual environment
python3 -m venv .adk_env

# Activate virtual environment
source .adk_env/bin/activate

# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt

步驟 3：🔥 重要 - 建立環境變數

⚠️ 請勿略過這個步驟！在 agent/ 目錄中建立 .env 檔案：

# Create the .env file
touch agent/.env

# Open it in your default text editor
open agent/.env

在檔案中新增下列幾行內容：

GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here

🚨 重要：請將 your_actual_api_key_here 替換為實際的 API 金鑰！

步驟 4：啟動虛擬環境 (如果尚未啟動)

source .adk_env/bin/activate

終端機提示詞開頭應會顯示 (.adk_env)。

步驟 5：執行 ADK 網頁介面

adk web

步驟 6：開啟瀏覽器

  1. 開啟瀏覽器並前往終端機中顯示的網址 (通常是 http://localhost:8000)
  2. 在左上方的下拉式選單中，選取 agent
  3. 開始與一日遊規劃代理人對話！

你會看到類似以下的對話：ADK 網頁 UI 範例

停用環境

完成專案後：

deactivate

這個指令在 Mac/Linux 和 Windows 上的運作方式相同。你會發現終端機提示中的 (.adk_env) 前置字串消失了。

Mac 疑難排解

  • 找不到 Python：請使用 python3 取代 python
  • 權限遭拒：請先執行 chmod +x setup_venv.sh，再執行指令碼

12. 附錄：ADK Web - 🪟 Windows 使用者適用

roadmap9

本指南將逐步說明如何在本機電腦上設定及執行 ADK Day Trip Planning Agent。

必要條件

  • Python 3.8 以上版本
    • Python 3.9 以上版本：安裝 google-adk==1.5.0 (最新版本，具備完整功能)
    • Python 3.8：安裝 google-adk==0.3.0 (相容版本)
  • Google AI Studio API 金鑰
  • 網際網路連線

步驟 1：複製存放區

開啟命令提示字元或 PowerShell，然後執行：

git clone https://github.com/cuppibla/ADK_Basic.git
cd ADK_Basic

步驟 2：設定虛擬環境並安裝依附元件

選項 A：自動設定 (建議)

# Run the setup script in Command Prompt
setup_venv.bat

選項 B：手動設定

命令提示字元：

# Create virtual environment
python -m venv .adk_env

# Activate virtual environment
.adk_env\Scripts\activate

# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt

PowerShell：

# Create virtual environment
python -m venv .adk_env

# Activate virtual environment
.adk_env\Scripts\Activate.ps1

# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt

步驟 3：🔥 重要 - 建立環境變數

⚠️ 請勿略過這個步驟！在 agent/ 目錄中建立 .env 檔案：

# Create the .env file
type nul > agent\.env

# Open it in Notepad
notepad agent\.env

在檔案中新增下列幾行內容：

GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here

🚨 重要：請將 your_actual_api_key_here 替換為實際的 API 金鑰！

步驟 4：啟動虛擬環境 (如果尚未啟動)

命令提示字元：

.adk_env\Scripts\activate

PowerShell：

.adk_env\Scripts\Activate.ps1

提示開頭應會顯示 (.adk_env)。

步驟 5：執行 ADK 網頁介面

adk web

步驟 6：開啟瀏覽器

  1. 開啟瀏覽器並前往終端機中顯示的網址 (通常是 http://localhost:8000)
  2. 在左上方的下拉式選單中，選取 agent
  3. 開始與一日遊規劃代理人對話！

Windows 疑難排解

  • PowerShell 執行政策錯誤：執行 Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

你會看到類似以下的對話：ADK 網頁 UI 範例

停用環境

完成專案後：

deactivate

這個指令在 Mac/Linux 和 Windows 上的運作方式相同。你會發現終端機提示中的 (.adk_env) 前置字串消失了。