GENAI104

總覽：Agent Development Kit 的優點

使用 Agent Development Kit 建構代理應用程式，可以為開發人員帶來以下主要好處：

1. 多代理系統：可在階層結構中組合多個專用代理，建構出可擴充的模組化應用程式，藉以執行複雜的協調和委派作業。
2. 豐富的工具生態系統：為代理提供多元功能，像是使用預先建構的工具 (搜尋、程式碼執行等)、建立自訂函式、整合第三方代理框架的工具 (LangChain、CrewAI)，甚至還可以使用其他代理做為工具。
3. 彈性的自動化調度管理功能：使用工作流程代理 (SequentialAgent、ParallelAgent 和 LoopAgent) 來定義可預測的管道工作流程，或透過使用 LLM 的動態轉送功能 (LlmAgent 轉移)，創造靈活應變的代理。
4. 整合式開發人員體驗：使用功能強大的 CLI 和互動式開發 UI，在本機開發、測試及偵錯，逐步檢查事件、狀態和代理執行作業。
5. 內建評估功能：與預先定義的測試案例比較，評估最終回覆品質和逐步執行軌跡，有系統地判斷代理效能。
6. 可隨時部署：將代理容器化並部署至任何位置，無論是在本機執行、透過 Vertex AI Agent Engine 擴充，或使用 Cloud Run/Docker 整合至自訂基礎架構都沒問題。

雖然其他生成式 AI SDK 或代理框架同樣能查詢模型，甚至為模型提供工具，但您必須投入大量心力，在多個模型間靈活調度。

相較之下，Agent Development Kit 比上述工具更加高階，您可以輕鬆相互連結多個代理，建立複雜但方便維護的工作流程。

此外，您還能將複雜的代理系統部署至 Agent Engine 的全代管端點，讓自己只需專注在代理邏輯，把基礎架構配置和調度作業交由 ADK 處理即可。

目標

在本實驗室，您將建立一個可使用搜尋工具的代理，然後使用 ADK 的瀏覽器 UI、CLI 對話介面和程式指令碼，測試這項代理。

本實驗室的學習內容包括：

• Agent Development Kit 的主要功能
• ADK 的核心概念
• 如何建立 ADK 專案目錄結構
• ADK 代理的基礎參數，包括如何指定模型名稱和工具
• ADK 瀏覽器 UI 的部分功能
• 如何控管代理的輸出結構定義
• 如何透過三種方式 (瀏覽器 UI、程式和 CLI 對話介面) 執行代理

設定和需求

瞭解以下事項後，再點選「Start Lab」按鈕

請詳閱以下操作說明。實驗室活動會計時，且中途無法暫停。點選「Start Lab」後就會開始計時，顯示可使用 Google Cloud 資源的時間。

您將在真正的雲端環境完成實作實驗室活動，而不是模擬或示範環境。為此，我們會提供新的暫時憑證，供您在實驗室活動期間登入及存取 Google Cloud。

為了順利完成這個實驗室，請先確認：

• 可以使用標準的網際網路瀏覽器 (Chrome 瀏覽器為佳)。

• 是時候完成實驗室活動了！別忘了，活動一旦開始將無法暫停。

如何開始研究室及登入 Google Cloud 控制台

1. 點選「Start Lab」按鈕。如果實驗室會產生費用，畫面上會出現選擇付款方式的對話方塊。左側的「Lab Details」窗格會顯示下列項目：

   • 「Open Google Cloud console」按鈕
   • 剩餘時間
   • 必須在這個研究室中使用的臨時憑證
   • 完成這個實驗室所需的其他資訊 (如有)

2. 點選「Open Google Cloud console」；如果使用 Chrome 瀏覽器，也能按一下滑鼠右鍵，選取「在無痕視窗中開啟連結」。

   接著，實驗室會啟動相關資源，並開啟另一個分頁，顯示「登入」頁面。

   提示：您可以在不同的視窗中並排開啟分頁。

   注意：如果頁面中顯示「選擇帳戶」對話方塊，請點選「使用其他帳戶」。

3. 如有必要，請將下方的 Username 貼到「登入」對話方塊。

   {{{user_0.username | "Username"}}}

   您也可以在「Lab Details」窗格找到 Username。

4. 點選「下一步」。

5. 複製下方的 Password，並貼到「歡迎使用」對話方塊。

   {{{user_0.password | "Password"}}}

   您也可以在「Lab Details」窗格找到 Password。

6. 點選「下一步」。

   重要事項：請務必使用實驗室提供的憑證，而非自己的 Google Cloud 帳戶憑證。 注意：如果使用自己的 Google Cloud 帳戶來進行這個實驗室，可能會產生額外費用。

7. 按過後續的所有頁面：

   • 接受條款及細則。
   • 由於這是臨時帳戶，請勿新增救援選項或雙重驗證機制。
   • 請勿申請免費試用。

Google Cloud 控制台稍後會在這個分頁開啟。

注意：如要使用 Google Cloud 產品和服務，請點選「導覽選單」，或在「搜尋」欄位輸入服務或產品名稱。

工作 1：安裝 ADK 並設定環境

啟用 Vertex AI 建議的 API

1. 在本實驗室環境中，Vertex AI API 已啟用。如要在專案中執行這些步驟，請前往 Vertex AI，然後按照提示啟用。

準備 Cloud Shell 編輯器分頁

1. 選取 Google Cloud 控制台視窗，然後依序按下鍵盤上的 G 和 S 鍵，開啟 Cloud Shell。或者，您也可以點選 Cloud 控制台右上方的「啟用 Cloud Shell」按鈕 。
2. 點選「繼續」。
3. 系統提示您授權 Cloud Shell 時，點選「授權」。
4. 點選 Cloud Shell 終端機面板右上角的「在新視窗中開啟」 按鈕 。
5. 點選窗格頂端的「開啟編輯器」鉛筆圖示 ，即可查看檔案。
6. 點選左側導覽選單頂端的「檔案總管」圖示 ，開啟檔案總管。
7. 點選「開啟資料夾」按鈕。
8. 在隨即開啟的「開啟資料夾」對話方塊，點選「確定」，選取 Qwiklab 學員帳戶的主資料夾。
9. 關閉畫面右側顯示的其他教學課程或 Gemini 面板，為程式碼編輯器保留更多視窗空間。
10. 操作本實驗室其餘步驟時，您可以全程將這個視窗當成 IDE 使用，搭配 Cloud Shell 編輯器和 Cloud Shell 終端機作業。

下載並安裝本實驗室所需的 ADK 和程式碼範例

1. 將下列指令貼到 Cloud Shell 終端機，從 Cloud Storage bucket 複製含有本實驗室所需程式碼的專案目錄：

   gcloud storage cp -r gs://{{{project_0.project_id| YOUR_GCP_PROJECT_ID}}}-bucket/adk_project .

   在 Cloud Shell 終端機執行下列指令，更新 PATH 環境變數，並安裝 ADK。注意：您需要指定版本，確保安裝的 ADK 版本與本實驗室所用者相符：

   export PATH=$PATH:"/home/${USER}/.local/bin" python3 -m pip install google-adk

2. 將下列指令貼到 Cloud Shell 終端機，從 Cloud Storage bucket 複製檔案並解壓縮，建立本實驗室所需的程式碼專案目錄：

   gcloud storage cp gs://{{{project_0.project_id| YOUR_GCP_PROJECT_ID}}}-bucket/*.zip ./adk_project.zip unzip adk_project.zip

3. 在 Cloud Shell 終端機執行下列指令，更新 PATH 環境變數，加入使用者的本機環境，並安裝 ADK 和實驗室所需的其他項目。

   export PATH=$PATH:"/home/${USER}/.local/bin" python3 -m pip install google-adk -r adk_project/requirements.txt

Agent Development Kit 的核心概念

Google ADK 有以下幾個核心設計概念，因此功能強大且靈活：

• 代理：核心構成元素，專門用來完成特定工作，並會透過 LLM 推論、規劃及使用工具達成目標，甚至能共同處理複雜專案。
• 工具：代理可以透過工具執行對話以外的動作，例如與外部 API 互動、搜尋資訊、執行程式碼或呼叫其他服務。
• 工作階段服務：負責處理一段對話 (Session) 的背景資訊，包括對話記錄 (Events)，以及代理保有的對話相關工作記憶 (State)。
• 回呼：您提供的自訂程式碼片段，可在代理的特定程序點執行，用於檢查、記錄或修改行為。
• 構件管理：代理可透過構件儲存、載入及管理與工作階段或使用者相關的檔案或二進位資料 (例如圖片或 PDF)。
• 執行元件：管理執行流程的引擎，可根據事件自動調度管理代理互動，並與後端服務協作。

工作 2：查看 Agent Development Kit 專案目錄結構

1. 在 Cloud Shell 編輯器的檔案總管窗格，找出 adk_project 資料夾，然後點選並開啟資料夾。

2. 這個目錄包含其他三個目錄：my_google_search_agent、app_agent 和 llm_auditor，每個分別代表不同的代理。將代理各自放在專案目錄對應的位置，即可提供組織架構，讓 Agent Development Kit 瞭解有哪些代理。

3. 點按「my_google_search_agent」，探索代理目錄。

4. 您會發現目錄中有 __init__.py 檔案和 agent.py 檔案。__init__.py 通常用來指定目錄做為 Python 套件，能以其他 Python 程式碼匯入。點選「init.py」檔案即可查看內容。

5. 您也會發現 init.py 檔案只有從 agent.py 檔案匯入的一行程式碼。ADK 會依據這行程式碼，將這個目錄指定為代理套件：

   from . import agent

6. 現在點選 agent.py 檔案，其中有一個簡單的代理。您將為這個代理配備強大的搜尋工具，讓代理能使用 Google 搜尋，在網際網路尋找資訊。檔案有以下幾個重點：

   • 注意從 google.adk 匯入的項目：Agent 類別和 tools 模組中的 google_search 工具
   • 詳閱程式碼註解，瞭解這個簡單代理的設定參數。

7. 將匯入的 google_search 工具傳遞給代理，即可使用這項工具。在 agent.py 檔案內，找到 Agent 物件建立程式碼結尾的指定位置，並貼上下列程式碼：

   tools=[google_search]

8. 儲存檔案。

工作 3：使用 ADK 開發 UI 執行代理

ADK 具備可在本機執行的開發 UI，來協助開發及測試代理。開發 UI 會提供各類圖表，方便您瞭解每個代理的活動，以及多個代理之間的互動情形。在本工作中，您將探索這個介面。

1. 在 Cloud Shell 終端機執行下列指令，寫入 .env 檔案。系統會讀取這個檔案來設定環境變數，指示代理使用您的專案和全域端點：

   cd ~/adk_project cat << EOF > my_google_search_agent/.env GOOGLE_GENAI_USE_VERTEXAI=TRUE GOOGLE_CLOUD_PROJECT={{{project_0.project_id| YOUR_GCP_PROJECT_ID}}} GOOGLE_CLOUD_LOCATION=global MODEL={{{project_0.startup_script.gemini_flash_model_id | gemini_flash_model_id}}} EOF

2. 儲存檔案。

6. 在 Cloud Shell 終端機執行下列指令，確認您位於 adk_project 目錄，也就是代理子目錄的所在位置：

   cd ~/adk_project

7. 使用下列指令啟動 Agent Development Kit 開發 UI：

   adk web

   輸出內容

   INFO: Started server process [2434] INFO: Waiting for application startup. +-------------------------------------------------------+ | ADK Web Server started | | | | For local testing, access at http://localhost:8000. | +-------------------------------------------------------+ INFO: Application startup complete. INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

8. 點按終端機輸出內容中的 http://127.0.0.1:8000 連結，在新分頁開啟網頁介面。系統會透過 Proxy，將您連結至這個在本機 Cloud Shell 執行個體執行的應用程式。

9. ADK 開發 UI 會在新的瀏覽器分頁開啟。

10. 在左側的「選取代理」下拉式選單中，選取「my_google_search_agent」。

    

11. 輸入以下問題，讓代理使用 Google 搜尋工具查詢：

    What is some recent global news?

12. 從結果可看出，代理能使用 Google 搜尋取得最新資訊，而不是只提供模型訓練時的資料。

    以 Google 搜尋結果為基準的回覆包含可立即顯示的 HTML「搜尋建議」，和代理回覆底部顯示的內容類似。因此以 Google 搜尋建立基準時，須顯示這些建議，讓使用者能進一步查看模型做為回覆依據的資訊。

13. 請注意，左側欄預設會顯示「追蹤記錄」分頁。點按上次的查詢文字 (What is some recent global news?)，即可查看追蹤記錄，瞭解查詢各部分花了多少時間執行。您可以根據記錄，對工具呼叫相關的複雜執行作業偵錯，瞭解各個程序與回覆延遲之間的關聯。

    

14. 點選代理回覆旁的代理圖示 () 或「事件」分頁列出的內容，即可檢查代理傳回的事件，包括 content (傳回給使用者的內容)，以及 groundingMetadata (回覆所依據的搜尋結果詳細資訊)。

15. 探索完開發 UI 後，請關閉這個瀏覽器分頁，然後返回 Cloud Shell 終端機的瀏覽器分頁，點選終端機窗格，並按下 CTRL + C 鍵停止網路伺服器。

點選「Check my progress」，確認目標已達成。 使用 ADK 的網路 UI 執行代理。

工作 4：透過程式執行代理

雖然開發 UI 適合用於測試及偵錯，但在正式環境中，最好不要向多名使用者顯示您的代理。

如要大型應用程式中執行代理，則必須在 agent.py 指令碼加入一些額外元件。在上一個工作中，這些元件是由網頁應用程式處理。請按照下列步驟，開啟並檢查含有這些元件的指令碼。

1. 如果代理目錄中沒有 .env 檔案，即可為所有代理設定環境變數。在 Cloud Shell 終端機執行下列指令，匯出環境變數：

   export GOOGLE_GENAI_USE_VERTEXAI=TRUE export GOOGLE_CLOUD_PROJECT={{{project_0.project_id| YOUR_GCP_PROJECT_ID}}} export GOOGLE_CLOUD_LOCATION=global export MODEL={{{project_0.startup_script.gemini_flash_model_id | gemini_flash_model_id}}}

2. 在 Cloud Shell 編輯器的檔案瀏覽器，選取「adk_project/app_agent」目錄。

3. 選取這個目錄中的「agent.py」檔案。

4. 這個代理的用途是做為應用程式的一部分來執行，因此請詳閱 agent.py 的程式碼註解，並特別留意程式碼中的下列元件：

   元件	功能	說明
   InMemoryRunner()	監督代理執行作業	Runner 程式碼負責接收使用者查詢、傳遞給適當的代理、接收代理的回覆事件並將傳回呼叫的應用程式/UI，然後觸發後續事件。詳情請參閱 ADK 事件迴圈說明文件。
   runner.session_service.create_session()	對話記錄和共用狀態	Session 元件可讓代理保留狀態，記住項目清單、工作目前的狀態或其他現有資訊。為簡單起見，本實驗室選擇建立本機工作階段服務，但在正式環境中，這項服務可由資料庫處理。
   types.Content() 和 types.Part()	結構化的多模態訊息	系統不會向代理傳遞簡單的字串，而是傳遞 Content 物件，其中可能包含多個 Part。如此一來，您就可以用特定順序，將包括文字和多模態內容的複雜訊息傳遞給代理。

5. 您會發現指令碼包含一個給代理的硬式編碼查詢，內容為「What is the capital of France?」。

6. 在 Cloud Shell 終端機執行下列指令，透過程式執行這個代理：

   python3 app_agent/agent.py

   輸出內容節錄：

   trivia_agent: The capital of France is Paris.

7. 您也可以為代理定義特定的輸入和/或輸出內容結構定義。

   現在您要在 Pydantic 結構定義類別「BaseModel」和「Field」新增匯入項目，並用來定義結構定義的類別。這個類別只有一個欄位，索引鍵為「capital」，字串值為國家/地區的首都名稱。新增其他匯入項目後，即可直接將下列程式碼貼至 app_agent/agent.py 檔案：

   from pydantic import BaseModel, Field class CountryCapital(BaseModel): capital: str = Field(description="國家/地區的首都。")

8. 在 root_agent 的 Agent 定義中設定 output_schema 參數，使用您在上方程式碼指定的 CountryCapital 結構定義：

   output_schema=CountryCapital,

9. 再次執行代理指令碼，查看 output_schema 後方的回覆：

   python3 app_agent/agent.py

   輸出內容節錄：

   ** User says: {'parts': [{'text': 'What is the capital of France?'}], 'role': 'user'} ** trivia_agent: {"capital": "Paris"}

點選「Check my progress」，確認目標已達成。 透過程式執行代理。

工作 5：透過指令列介面與代理對話

您還可以在本機開發環境中，使用指令列介面與代理對話。開發代理時，這項功能可幫助您快速偵錯及測試。

與網頁介面相同，指令列介面也會建立代理的工作階段服務、構件服務和執行元件。

請按照下列步驟，使用指令列介面執行互動工作階段：

1. 在 Cloud Shell 終端機執行下列指令：

   adk run my_google_search_agent

   輸出內容：

   Log setup complete: /tmp/agents_log/agent.20250322_010300.log To access latest log: tail -F /tmp/agents_log/agent.latest.log Running agent basic_search_agent, type exit to exit. user:

2. 輸入下列訊息：

   印度過去一個月內有哪些新電影？

   輸出內容範例 (可能會與實際輸出內容略有不同)：

   [google_search_agent]：以下是印度在過去一個月 (2026 年 1 月至 2026 年 2 月初) 上映的電影： * **2026 年 1 月 16 日**：《Bihu Attack》、《Happy Patel: Khatarnak Jasoos》。 * **2026 年 1 月 23 日**：《Border 2》。 * **2026 年 1 月 30 日**：《Mardaani 3》、《Mayasabha - The Hall of Illusion》。 * **2026 年 2 月 5 日**：《Vadh 2》、《Haunted 3D: Ghosts Of The Past》。 * **2026 年 2 月 13 日**：《Tu Yaa Main》、《O'Romeo》、《Swayambhu》。 * **2026 年 2 月 19 日**：《Veer Murarbaji》、《Do Deewane Seher Mein》。 * **2026 年 2 月 20 日**：《Epic: Elvis Presley In Concert》、《Hamnet》。 * **2026 年 2 月 26 日**：《The Kerala Story 2 Goes Beyond》。

3. 在指令列介面與代理對話完畢時，於後續的使用者提示詞輸入 exit，即可結束對話。

點選「Check my progress」，確認目標已達成。 透過指令列介面與代理對話。

工作 6：多代理範例預覽

「使用 ADK 建構多代理系統」實驗室課程會進一步解說如何建構多代理系統，但由於多代理能力是 Agent Development Kit 的核心服務，本課程將帶您預先探索這類系統。

這個代理系統會評估 LLM 是否以事實做為回覆基準，並加以改善。這個系統使用以下代理： - critic_agent：可自動查核事實 - reviser_agent：如需根據驗證後的發現項目修正錯誤，會重新編寫回覆

請按照下列步驟探索代理：

1. 透過 Cloud Shell 編輯器的檔案總管前往 adk_project/llm_auditor 目錄，瞭解這個多代理系統的程式碼。

2. 選取 llm_auditor 目錄中的「agent.py」檔案。

3. 這個多代理範例有幾項重點需要注意：

   • 注意 SequentialAgent 類別的匯入和使用方式。這個工作流程類別範例可在代理之間依序傳遞對話控管權限，無須使用者介入。因此執行代理時，您會發現系統不須等待使用者採取動作，critic_agent 和 reviser_agent 就會依序回應。
   • 注意這些子代理都是從 sub_agents 目錄中對應的目錄匯入。
   • 子代理目錄同樣包含您先前在目錄結構中看到的 __init__.py 和 agent.py 檔案，另外還有一個 prompt.py 檔案。這個檔案會提供專屬位置，存放完整且結構良好的提示詞，以便編輯後匯入 agent.py 檔案。

4. 為這個代理建立 .env 檔案，然後在 Cloud Shell 終端機執行下列指令，再次啟動開發 UI：

   cd ~/adk_project cat << EOF > llm_auditor/.env GOOGLE_GENAI_USE_VERTEXAI=TRUE GOOGLE_CLOUD_PROJECT={{{project_0.project_id| YOUR_GCP_PROJECT_ID}}} GOOGLE_CLOUD_LOCATION=global MODEL={{{project_0.startup_script.gemini_flash_model_id | gemini_flash_model_id}}} EOF adk web 注意：如未關閉先前的 adk web 工作階段，預設的 8000 連接埠便會封鎖。不過只要輸入指令 (例如 adk web --port 8001)，就能透過新連接埠啟動開發 UI。

5. 點選終端機輸出內容中的「http://127.0.0.1:8000」連結。ADK 開發 UI 會在新的瀏覽器分頁開啟。

6. 在左側的「選取代理」下拉式選單中，選取「llm_auditor」。

7. 輸入下列錯誤敘述展開對話：

   查證以下敘述：與火星相比，地球距離太陽更遠。

8. 您應該會在對話區看到代理的兩則回覆：

   • 首先是 critic_agent 的詳細回覆。該代理會使用 Google 搜尋查核事實，然後根據結果確認敘述是否為真。
   • 其次是 reviser_agent 修正您輸入的錯誤敘述後，輸出的簡要敘述，例如「與火星相比，地球距離太陽更近」。

9. 點按每則回覆旁的代理圖示 ()，即可開啟該回覆的事件面板，您也可以在「事件」面板找出並選取相應編號的事件。事件檢視畫面頂端會以圖表呈現這個多代理系統中，代理與工具之間的關係。系統會醒目顯示負責這則回覆的代理。

10. 您可以進一步探索程式碼，或在開發 UI 提出其他事實查核範例問題。例如，您可以嘗試再提出以下問題：

    問：為什麼天空是藍的？答：因為天空反射海洋的顏色。

11. 如要重設對話，只要使用 ADK 開發 UI 右上方的「+ 新增工作階段」連結，即可重新開始對話。

12. 向這個代理提問完畢後，請關閉瀏覽器分頁，並在終端機中按下 CTRL + C 鍵停止伺服器。

點選「Check my progress」，確認目標已達成。 多代理範例預覽。

恭喜！

在本實驗室中，您已瞭解：

• Agent Development Kit 的主要功能
• ADK 的核心概念
• 如何建立 ADK 專案目錄結構
• ADK 代理的基礎參數，包括如何指定模型名稱和工具
• ADK 瀏覽器 UI 的部分功能
• 如何控管代理的輸出結構定義
• 如何透過三種方式 (瀏覽器 UI、程式和 CLI 對話介面) 執行代理

後續步驟

如要進一步瞭解如何使用 Agent Development Kit 建構及部署代理，請參閱下列實驗室：

• 為 ADK 代理提供工具
• 使用 ADK 建構多代理系統
• 將 ADK 代理部署至 Agent Engine

如要進一步瞭解 ADK，請參閱說明文件和 GitHub 存放區：

• Agent Development Kit 說明文件：Agent Development Kit
• adk-docs 的 GitHub 存放區：adk-docs

Google Cloud 教育訓練與認證

協助您瞭解如何充分運用 Google Cloud 的技術。我們的課程會介紹專業技能和最佳做法，讓您可以快速掌握要領並持續進修。我們提供從基本到進階等級的訓練課程，並有隨選、線上和虛擬課程等選項，方便您抽空參加。認證可協助您驗證及證明自己在 Google Cloud 技術方面的技能和專業知識。

使用手冊上次更新日期：2026 年 2 月 12 日

實驗室上次測試日期：2026 年 2 月 12 日

Copyright 2026 Google LLC 保留所有權利。Google 和 Google 標誌是 Google LLC 的商標，其他公司和產品名稱則有可能是其關聯公司的商標。