程式碼研究室簡介
1. 學習目標
歡迎參加 ADK 大師班 - 多代理系統入門課程
您即將踏入精彩的 AI 代理世界。忘掉只能回答問題的簡單聊天機器人吧！我們正深入研究 Agent Development Kit (ADK)，建構精密的自主系統，讓系統能夠推理、規劃及使用工具來完成複雜工作。
完成本教學課程後，您將能夠：
- 建構第一個 AI 服務專員：從無到有，建構出功能齊全的服務專員，瞭解使用者需求、使用 Google 搜尋等工具，並生成詳細實用的回應。
- 精通自訂工具：將代理程式連結至自訂函式和 API，充分發揮代理程式的強大功能。您將教導代理程式擷取即時資料，例如即時天氣預報。
- 建構多代理系統：瞭解「代理即工具」模式，這項革命性概念是指代理會將工作委派給其他專業代理，建立共同合作的 AI 專家團隊。
- 自動化調度管理複雜工作流程：除了簡單的委派作業，您還可以運用路由器、序列鏈結、迴圈和平行執行等進階模式，建構強大、有效率的智慧型應用程式，處理幾乎所有要求。
- 為代理提供記憶體：瞭解對話記憶體的重要角色，讓代理處理後續問題、從意見回饋中學習，以及順暢地管理多步驟工作。
我們開始吧！🚀
2. 設定 Google Cloud Platform 和 Gemini API 金鑰
設定 GCP 專案和 Gemini API 金鑰
如要為 AI 代理程式提供支援，我們需要兩項要素：提供基礎的 Google Cloud 專案，以及用來存取 Google 強大模型的 Gemini API 金鑰。
步驟 1：啟用帳單帳戶
步驟 2：建立新的 GCP 專案
- 前往 Google Cloud 控制台，建立新專案。
- 前往 Google Cloud 控制台，建立新專案。
- 開啟左側面板，按一下
Billing，確認帳單帳戶是否已連結至這個 GCP 帳戶。
如果看到這個頁面，請檢查 manage billing account，選擇 Google Cloud 試用方案，然後連結至該方案。
步驟 3：產生 Gemini API 金鑰
您必須先擁有金鑰，才能保護金鑰。
- 前往 Google AI Studio：https://aistudio.google.com/
- 使用 Gmail 帳戶登入。
- 按一下「取得 API 金鑰」按鈕，通常位於左側導覽窗格或右上角。
- 在「API keys」對話方塊中，按一下「Create API key in new project」(在新專案中建立 API 金鑰)。
- 選擇您建立的新專案，並設定帳單帳戶。
- 系統會為您產生新的 API 金鑰。立即複製這組金鑰，並暫時存放在安全的地方 (例如密碼管理工具或安全記事)。您會在後續步驟中使用這個值。
3. 工作階段 1：使用 Runner 建立第一個代理程式
我們先從基礎概念開始。我們將在此建立第一個簡單的代理程式 day_trip_agent。這個代理程式的目的是根據使用者要求 (包括預算考量)，產生全天行程。本範例介紹 ADK 中任何代理互動的三個核心元件：
- 代理程式：作業的核心大腦。這類代理程式的定義取決於指令 (個性與任務)、使用的 AI 模型 (例如 Gemini) 和可存取的工具。
- 工作階段：對話的記憶體。儲存互動記錄 (使用者訊息和代理程式回覆)，以便進行連續對話。
- 執行器：執行工作的引擎。這個函式會接收 Agent 和 Session，處理新的使用者查詢，並協調產生回應的步驟。
➡️ 如何在筆記本中找到這項功能
👉 這對應到「第 1 部分：您的第一個代理程式 - 規劃一日遊的精靈 🧞」底下的儲存格。🌟
- 代理程式定義：尋找
create_day_trip_agent()函式。代理程式定義於此。請注意詳細的指令字串，這是提示，可告知代理程式如何運作。我們也為 Gemini 提供第一個工具：Google 搜尋。 - 輔助函式：這裡定義了
run_agent_query()輔助函式。我們會在整個筆記本中使用這項公用程式，簡化查詢執行作業。 - 測試執行：
run_day_trip_genie()函式會模擬使用者要求「價格實惠」且「輕鬆」的一日遊。代理程式會根據指令和 Google 搜尋工具尋找合適的地點，並建立以 Markdown 格式編排的行程。
➡️ 動作：檢查 day_trip_agent 的指令提示。請注意，測試查詢中「平價」行程的要求，與代理程式「預算考量」的指引直接相關。
4. 第 2 堂課：自訂工具 🛠️
Google 搜尋功能強大，但如果將 AI 代理程式連結至專屬資料來源、API 或自訂邏輯，就能發揮真正的潛力。在本節中，我們會從簡單的 Python 函式建立自訂工具。
函式工具最重要的部分是其說明字串。ADK 會自動剖析 docstring，瞭解工具的用途、接受的參數 (Args) 和傳回的內容 (Returns)。大型語言模型 (LLM) 會讀取這段說明，判斷何時及如何使用工具。
➡️ 如何在筆記本中找到這項功能
👉 這對應至「2.1 The Simple FunctionTool: Calling a Real-Time Weather API」下的儲存格。🌟
- 工具定義：
get_live_weather_forecast(location: str)函式是自訂工具的核心。這個函式會接收城市名稱、呼叫公用的美國國家氣象局 API，並傳回包含溫度和預報的字典。 - 代理程式定義：系統會在初始化期間傳遞
tools=[get_live_weather_forecast]，建立 weather_agent 並配備新工具。代理程式的指令明確要求先使用這項工具，再建議戶外活動。 - 測試執行：查詢「我想在太浩湖附近健行，天氣如何？」時，代理程式會直接使用
get_live_weather_forecast工具，因為指令要求這麼做。
➡️ 動作：請閱讀 get_live_weather_forecast 函式的說明字串，以及 weather_agent 的指令。請注意兩者之間的直接關係。
5. 第 3 堂：將代理程式做為工具 🧑🍳
既然可以建立專家團隊，何必建立單一的巨型代理程式？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的函式。
- call_db_agent：呼叫
- 流程：
run_trip_data_concierge()中的測試執行作業會示範完整的委派鏈。- 使用者向協調器詢問飯店和附近的餐廳。
- 協調器的指令會要求先使用
call_db_agent工具取得飯店資料。 - 然後，協調器會使用
call_concierge_agent工具取得建議。 concierge_agent收到要求後，會使用自己的工具food_critic_agent取得餐廳建議。
美食評論家的回覆會傳回給服務人員，服務人員會禮貌地排版，然後傳回給協調器，最後由協調器呈現給使用者。
➡️ 動作：在 run_trip_data_concierge() 下的測試執行作業中追蹤執行流程。請注意，TOOL CALLED 列印內容會顯示從協調器到專家的委派鏈。這是依序執行的指令鏈。
6. 第 4 堂：代理程式記憶體 🧠
真正智慧的服務專員不只會回應一次性查詢，必須記住對話內容、瞭解背景資訊，並根據意見回饋調整。這項機制是透過適當的工作階段管理達成。「迴圈代理程式」是指參與持續對話迴圈的代理程式，並由記憶體提供支援。
如果對多個連續查詢使用相同的會期物件，代理程式就能「看到」整個對話記錄。因此可以處理後續問題、根據意見回饋修正錯誤，以及規劃多步驟工作。
➡️ 如何在筆記本中找到這項功能
👉 這對應到「第 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 堂：路由器代理程式 🚏
單一代理程式只能執行有限的動作。如要處理真正複雜的使用者要求，我們需要專業服務專員團隊。但我們如何知道要為特定查詢使用哪個代理程式？這時 Router Agent 就能派上用場。
路由器代理程式會做為「主要」代理程式或調度員。其唯一用途是分析傳入的使用者查詢，並決定哪位專業代理 (或代理工作流程) 最適合這項工作。不會直接回答查詢內容，只會將查詢內容轉送至正確的下游代理程式。
舉例來說，有關「最好吃的壽司」的查詢應交由 foodie_agent 處理，而有關「本週末的演唱會」的問題則應由 weekend_guide_agent 處理。
➡️ 如何在筆記本中找到這項資訊：
👉 這個概念是整個筆記本的核心，但首先會在「第 1 部分：多代理程式大混戰 - 循序工作流程 🧠→🤖→🤖」🌟中介紹。
- 代理程式定義：程式碼儲存格會定義多個專家代理程式 (day_trip_agent、foodie_agent、transportation_agent)，以及最重要的 router_agent。請密切注意 router_agent 的指令提示，系統明確要求只傳回最適合這項工作的代理程式名稱。
- 執行邏輯：run_sequential_app 函式會示範如何先呼叫 router_agent 取得決策 (chosen_route)，然後在
if/elif區塊中使用該決策，執行適當的專家代理程式。
8. 第 6 堂：SequentialAgent ⛓️
部分工作需要依特定順序執行多個步驟。例如：「在帕羅奧多找最好的壽司店，然後告訴我怎麼去。」這個過程分為兩步驟：先找出餐廳，再取得路線。
ADK 提供簡單又強大的方式，可透過 SequentialAgent 管理這項作業。這是特殊的工作流程代理程式，會以預先定義的順序執行子代理程式清單。
魔法就在於共用狀態。序列中某個代理程式的輸出內容可以自動儲存至共用狀態字典，然後做為下一個代理程式的輸入內容，因此不需要複雜的手動程式碼，即可在步驟之間傳遞資訊。
➡️ 如何在筆記本中找到這項資訊：
👉 這部分內容請參閱第 2 部分 (ADK 方式)：使用 SequentialAgent 進行多代理程式混亂 🧠→⛓️→🤖。🌟
- 代理程式重構：在本節的第一個程式碼儲存格中，請注意
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 🔁
並非所有問題都有直接的單一解決方案。有時我們需要提出解決方案、批評並修正，直到符合特定限制為止。
為此，ADK 提供 LoopAgent。這個工作流程代理程式會重複執行一系列子代理程式，直到符合特定條件為止。這非常適合用來建構「完美主義者」代理程式，這類代理程式可以規劃、評論及改進自己的工作。
圖表顯示 Planner Agent 先建立方案，接著輸入 LoopAgent。Critic Agent 會檢查方案。如果發現有瑕疵，Refiner Agent 會建立新版本，並重複上述流程。如果計畫良好，Refiner Agent 會呼叫 exit_loop 工具，並傳回最終的驗證計畫。
➡️ 如何在筆記本中找到這項資訊：
👉 這項功能在「使用 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 ⚡️
效率是關鍵。如果使用者一次要求多個不相關的資訊，逐一執行這些搜尋會很慢。
ParallelAgent就是解決方案。這個工作流程代理程式會並行執行子代理程式清單。所有平行工作完成後，系統會收集結果並綜合分析，產生單一的完整回覆。
這張圖表顯示 ParallelAgent 採用單一查詢，並將工作分叉成三個並行軌跡。museum_finder、concert_finder 和 restaurant_finder 會同時執行。這三項作業完成後，系統會合併個別結果 (儲存至共用狀態)，並傳遞至最終的合成代理程式，將結果合併為一個答案。
➡️ 如何在筆記本中找到這項資訊：
👉 這個工作流程的詳細說明請參閱「平行電源與 ParallelAgent 🧠→⚡️→🤖🤖🤖」一節。🌟
- 專家代理程式：定義三位專家代理程式，每位都有專屬的 output_key (例如 museum_result)。
- 並行工作流程：parallel_research_agent 定義為 ParallelAgent，並列出三個搜尋代理程式做為其 sub_agents。
- 綜合步驟：在平行步驟之後，最終的 synthesis_agent 會使用預留位置 (
{museum_result}、{concert_result}等) 收集共用狀態中的所有發現，並格式化成簡潔的摘要。
11. 附錄：ADK Web - 🍎 適用於 Mac/Linux
本指南將逐步說明如何在本機電腦上設定及執行 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：開啟瀏覽器
- 開啟瀏覽器並前往終端機中顯示的網址 (通常是
http://localhost:8000) - 在左上方的下拉式選單中，選取
agent - 開始與一日遊規劃代理人聊天！
你會看到類似以下的對話：
停用環境
完成專案後：
deactivate
這個指令在 Mac/Linux 和 Windows 上的運作方式相同。你會發現終端機提示中的 (.adk_env) 前置字串消失了。
Mac 疑難排解
- 找不到 Python：請使用
python3取代python - 權限遭拒：請先執行
chmod +x setup_venv.sh，再執行指令碼
12. 附錄：ADK Web - 🪟 適用於 Windows 使用者
本指南將逐步說明如何在本機電腦上設定及執行 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：開啟瀏覽器
- 開啟瀏覽器並前往終端機中顯示的網址 (通常是
http://localhost:8000) - 在左上方的下拉式選單中，選取
agent - 開始與一日遊規劃代理人聊天！
Windows 疑難排解
- PowerShell 執行政策錯誤：執行
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
你會看到類似以下的對話：
停用環境
完成專案後：
deactivate
這個指令在 Mac/Linux 和 Windows 上的運作方式相同。你會發現終端機提示中的 (.adk_env) 前置字串消失了。