GENAI106

總覽

本實驗室說明如何在 Google Agent Development Kit (Google ADK) 中，自動調度管理多代理系統。

此外，本實驗室假設您熟悉下列實驗室涵蓋的 ADK 基本知識和工具使用方式：

• 開始使用 Google Agent Development Kit (ADK)
• 為 ADK 代理提供工具

目標

本實驗室的學習內容如下：

• 建立多個代理並按照上下層關係相互連結。
• 寫入工作階段狀態字典，在多輪對話與多個代理間建構內容。
• 指示代理讀取工作階段狀態值，做為回覆時參考的脈絡資訊。
• 使用工作流程代理，直接在代理間傳遞對話。

設定和需求

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

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

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

需求條件

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

• 可以使用標準的網際網路瀏覽器 (Chrome 瀏覽器為佳)。
• 已預留充足時間可完成實驗室。

注意：如果您擁有個人 Google Cloud 或專案，請勿用於本實驗室。

注意：如果您使用的是 Pixelbook，請在無痕視窗執行本實驗室。

如何開始研究室及登入 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 產品和服務，請點選「導覽選單」，或在「搜尋」欄位輸入服務或產品名稱。

多代理系統

開發人員可以使用 Agent Development Kit，讓生成式模型的多步驟行為更可靠精細。您不必編寫冗長、複雜且不一定能穩定提供結果的提示詞，只要建構多個簡單的代理，再劃分工作和責任，並組成一套流程，代理就會合作解決複雜問題。

採取這種架構有幾個主要優點，例如：

• 設計更簡單：您可以想成代理會各司其職，而且各有所長。
• 以更穩定的效能發揮專門作用：專用代理可從明確的樣本中學習，更穩定執行特定工作。
• 梳理工作流程：將工作流程劃分為不同代理，能使處理方式更有條理，更有助於思考。
• 容易改良及維護：直接變更複雜代理來修正某項行為，可能會連帶影響其他行為。相比之下，優化或修正專用元件更簡單。
• 模組化：您可以輕鬆複製工作流程中的特定代理，然後加進其他類似的工作流程。

階層式代理樹狀結構

您可以使用 Agent Development Kit，將代理整理成樹狀結構，限制每個代理的轉移選項，以控管及預測對話在樹狀結構中可能採取的路徑。階層式結構的優點包括：

• 從現實世界的協作團隊汲取靈感，更容易設計及推論多代理系統的行為。
• 與一般軟體開發模式相同，對開發人員而言，相當符合直覺。
• 開發人員能進一步控管系統內的資訊流向和工作委派流程，方便掌握可能的路徑並為系統偵錯。舉例來說，在系統流程的不同環節中，如果有兩個報告生成代理的說明類似，您可以透過樹狀結構，更輕鬆確保叫用的代理正確無誤。

這類結構的開頭一律為 root_agent 變數中定義的代理，但也可能以其他面向使用者的名稱來做區別。root_agent 為父代理，底下有一或多個子代理，每個子代理可以再有自己的子代理。

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

在本實驗室環境，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_multiagent_systems .

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

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

工作 2：瞭解父代理、子代理和同層代理間的轉移方向

對話一律會從 root_agent 變數中定義的代理開始。

父代理的預設行為是解讀每個子代理的說明，並判斷是否應在任何時間點，將對話掌控權轉移給子代理。

您可以在父代理的 instruction 中，參照子代理的 name 參數值 (而非變數名稱) 來引導轉移方向。請試著完成以下範例活動：

1. 在 Cloud Shell 終端機執行下列指令，建立 .env 檔案來驗證 parent_and_subagents 目錄中的代理。

   cd ~/adk_multiagent_systems cat << EOF > parent_and_subagents/.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. 執行下列指令，將 .env 檔案複製到本實驗室稍後會用到的 workflow_agents 目錄：

   cp parent_and_subagents/.env workflow_agents/.env

3. 在 Cloud Shell 編輯器檔案總管窗格，前往 adk_multiagent_systems/parent_and_subagents 目錄。

4. 點選「agent.py」來開啟這個檔案。

提示：由於 Python 程式碼要求先定義子代理，才能新增至代理，如要依對話流程順序讀取 agent.py 檔案，建議從底層代理開始往上讀取。

5. 請注意，這裡有三個代理：

   • root_agent：在 ADK 開發 UI 和指令列介面中顯示的名稱為 steering。這個代理會向使用者提問 (例如是否知道要去哪裡旅遊，還是需要協助決定)，然後根據回覆，判斷要將對話導向兩個子代理中的哪一個。請注意，這個代理只有簡單的 instruction，而且未提及子代理，但知道子代理的說明。
   • travel_brainstormer：如果使用者不知道要去哪裡旅遊，這個代理會協助發想。
   • attractions_planner：使用者決定好旅遊國家/地區後，這個代理會列出觀光景點清單。

6. 在建立的 root_agent 加入下列程式碼，將 travel_brainstormer 和 attractions_planner 做為 root_agent 的子代理：

   sub_agents=[travel_brainstormer, attractions_planner]

7. 儲存檔案。

8. 請不要將對應的「parent」參數加入子代理，必須在建立父代理時指定 sub_agents，才能定義出階層式樹狀結構。

9. 在 Cloud Shell 終端機執行下列指令，使用 ADK 指令列介面與代理對話：

   cd ~/adk_multiagent_systems adk run parent_and_subagents

10. 看到 [user]: 提示詞時，請輸入下列內容向代理打招呼：

    你好

    輸出內容範例 (實際結果可能略有差異)：

    user: 你好 [steering]: 你好！你已經想好要去哪個國家/地區旅遊了嗎？還是需要我協助？

11. 告訴代理：

    我需要一些協助才能決定。

    輸出內容範例 (實際結果可能略有差異)：

    user: 我需要一些協助才能決定。 [travel_brainstormer]: 好的！為提供最合適的建議，我需要瞭解你對這趟旅遊的期望。 ...

12. 您會發現回覆中，以中括號括住的名稱為 [travel_brainstormer]，這表示 root_agent (名稱為 [steering]) 只根據子代理的 description，將對話轉給適當的子代理。

13. 在 user: 提示詞中輸入 exit，即可結束對話。

14. 您也能在代理的 instructions 提供更詳細的指令，說明何時要將對話轉給子代理。在 agent.py 檔案，將下列幾行指令加入 root_agent 的 instruction：

    如果使用者需要代理協助決定， 請導向至「travel_brainstormer」。 如果使用者已經想好要前往的國家/地區， 請導向至「attractions_planner」。

15. 儲存檔案。

16. 在 Cloud Shell 終端機執行下列指令，再次啟動指令列介面：

    adk run parent_and_subagents

17. 輸入下列內容，向代理打招呼：

    你好

18. 回覆代理的問候，並輸入下列內容：

    我想去日本旅遊。

    輸出內容範例 (實際結果可能略有差異)：

    user: 我想去日本旅遊。 [attractions_planner]: 好的！我可以為你提供協助。以下是日本的熱門景點： * **東京：** * 淺草寺 * 澀谷十字路口 * 東京晴空塔 * **京都：** …

19. 您會發現對話已轉給另一個子代理 attractions_planner。

20. 這時請回覆：

    其實我不知道該去哪個國家/地區旅遊。

    輸出內容範例 (實際結果可能略有差異)：

    user: 其實我不知道該去哪個國家/地區旅遊。 [travel_brainstormer]: 沒關係！我可以幫你想幾個適合旅遊的國家/地區…

21. 您會發現對話已轉給 travel_brainstormer 代理，也就是 attractions_planner 的同層代理。這項功能預設為允許。如果不希望對話轉給同層代理，可以將 attractions_planner 代理的 disallow_transfer_to_peers 參數設為 True。

22. 在使用者提示詞中輸入 exit，結束工作階段。

逐步模式：如要讓代理逐步引導使用者完成程序，建議將第一步的代理設為 root_agent，然後將第二步的代理設為 root_agent 的唯一子代理，之後每個步驟的代理都是前一步代理的唯一子代理。

點選「Check my progress」，確認目標已達成。 瞭解父代理、子代理和同層代理間的轉移方向

工作 3：使用工作階段狀態來儲存及擷取特定資訊

ADK 中的每段對話都存放於 Session，所有參與對話的代理都能存取。工作階段包含對話記錄，代理會讀取這些內容並據此生成回覆。此外，工作階段還包含工作階段狀態字典，可供您進一步控管要醒目標示的重要資訊，以及這些資訊的存取方式。

這項功能非常實用，有助代理互相傳遞資訊，或與使用者對話期間維持簡單的資料結構 (例如工作清單)。

請按照下列步驟新增和讀取狀態：

1. 返回 adk_multiagent_systems/parent_and_subagents/agent.py 檔案。

2. 將下列函式定義貼到 # Tools 標頭後方：

   def save_attractions_to_state( tool_context: ToolContext, attractions: List[str] ) -> dict[str, str]: """將景點清單儲存至 state["attractions"]. Args: attractions [str]：要新增至景點清單的字串清單 Returns: None """ # 從狀態載入現有景點。如果不存在，則啟動空清單 existing_attractions = tool_context.state.get("attractions", []) # 使用新舊清單的組合更新「attractions」鍵。 # 工具執行時，ADK 會建立事件，並 # 對工作階段狀態做相應更新。 tool_context.state["attractions"] = existing_attractions + attractions # 工具的最佳做法是在回傳的 dict 中傳回狀態訊息 return {"status": "success"}

3. 以上程式碼有幾點需要留意：

   • 工作階段會以 ToolContext 的形式傳遞至工具函式，您只需要指派參數接收即可，如上方所示的 tool_context 參數。接著您就能使用 tool_context 存取工作階段資訊，例如對話記錄 (透過 tool_context.events)，以及工作階段狀態字典 (透過 tool_context.state)。如果工具函式修改了 tool_context.state 字典，必須等到工具執行完畢，變更才會反映在工作階段狀態中。
   • docstring 會明確說明引數區段和傳回值。
   • 函式程式碼註解會說明如何輕鬆更新狀態字典。

4. 建立 attractions_planner 代理時，加入 tools 參數來新增工具：

   tools=[save_attractions_to_state]

5. 在 attractions_planner 代理現有的 instruction 中，新增下列項目符號清單：

   - 當使用者回覆時，請使用工具儲存選定的景點，接著提供更多可能的選項。 - 如果他們要求查看清單，請以項目符號列出 { attractions? }，然後再推薦一些。

6. 注意以大括號括住的區段 { attractions? }。這是 ADK 的索引鍵範本功能，會從狀態字典載入 attractions 索引鍵的值。在 attractions 索引鍵後方加上問號，可避免欄位尚未出現時發生錯誤。

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 連結，在新分頁開啟網頁介面。

9. 系統會開啟新的瀏覽器分頁，顯示 ADK 開發 UI。

10. 在左側的「Select an agent」下拉式選單，選取「parent_and_subagents」代理。

11. 輸入 hello 開始對話。

12. 代理向您打招呼後，請回覆：

    我想去埃及。

    對話應會轉給 attractions_planner，並顯示景點清單。

13. 選擇景點，例如：

    我想參觀人面獅身像。

14. 代理應會透過回覆確認您的要求，例如「好的，我已將人面獅身像存到清單中。以下是其他景點...」。

15. 點選標有勾號的回覆工具方塊，查看根據工具回覆建立的事件。您會發現其中的「actions」欄位包含 state_delta，作用是說明狀態變更。

16. 代理應會提示您選取其他景點。請從列出的景點中擇一，然後回覆給代理。

17. 在左側導覽選單點選「X」，退出先前查看的事件視窗。

18. 現在側欄應會顯示事件清單和數個分頁選項。請選取「State」分頁標籤，即可查看目前的狀態，包括 attractions 陣列，當中有您要求的兩個值。

    

19. 向代理傳送下列訊息：

    清單中有哪些景點？

20. 代理應會根據 instruction 傳回以項目符號標示的清單。

21. 測試完代理後，請關閉網路瀏覽器分頁，接著在 Cloud Shell 終端機按下 CTRL + C 鍵來停止伺服器。

    在本實驗室的後續部分，您將示範如何使用狀態在代理間通訊。

點選「Check my progress」，確認目標已達成。 使用工作階段狀態來儲存及擷取特定資訊

如要將代理的完整文字回覆儲存於狀態字典，而非只儲存一小部分，可以在定義代理時設定 output_key 參數，代理的完整輸出內容就會儲存於狀態字典，並以該欄位名稱命名。

工作流程代理

如果想讓使用者與多個專用子代理逐一互動，在代理間建立上下層轉移關係，是非常合適的做法。

不過，如果想讓代理接連採取行動，而不必等使用者回覆，則可考慮使用工作流程代理。以下列舉幾個適合使用工作流程代理的範例情境：

• 規劃及執行：由某個代理準備項目清單，再由其他代理根據該清單執行後續工作，例如編寫文件。
• 研究及撰寫內容：由某個代理呼叫函式，從 Google 搜尋或其他資料來源收集脈絡資訊，然後由其他代理根據這些資訊輸出內容。
• 草擬及修訂：由某個代理草擬文件，然後由其他代理檢查並反覆修改。

為完成這類工作，工作流程代理設有多個子代理，而且會確保每個子代理都採取行動。您可以在 Agent Development Kit 自行定義工作流程代理，也能使用內建的三種工作流程代理：

• SequentialAgent
• LoopAgent
• ParallelAgent

在本實驗室的後續部分，您將建構多代理系統，並使用多個 LLM 代理、工作流程代理和工具來控管代理流程。

具體來說，您需要建構代理，為新上映的賣座傳記電影製作提案文件。這部電影是根據某個歷史人物的生平改編而成。您的子代理將負責研究，並與 screenwriter 和 critic 代理來回撰寫及修改。最後，其他子代理會協助發想選角構想，並根據歷來票房資料預測票房結果。

這個多代理系統最終將如下所示 (點選圖片即可放大檢視)：

不過，您會先從簡單的版本著手。

工作 4：開始使用 SequentialAgent 建構多代理系統

SequentialAgent 會以線性序列執行子代理。也就是說，sub_agents 清單中的各個子代理會依定義的順序逐一運作。

如果工作流程中的工作必須依特定順序執行，而且前一項工作的輸出內容會做為後一項工作的輸入內容，就非常適合使用 SequentialAgent。

在這項工作，您將執行 SequentialAgent，建構電影提案製作多代理系統的第一個版本。代理結構的初稿大致如下：

• root_agent：名稱為 greeter，會歡迎使用者並詢問要以哪個歷史人物做為電影題材

• SequentialAgent：名稱為 film_concept_team，包含下列代理：

  • researcher：使用「為 ADK 代理提供工具」實驗室介紹的 LangChain 工具，透過維基百科深入瞭解指定的歷史人物。代理可選擇連續呼叫工具多次，因此如果 researcher 判斷需進行更多研究，就會連續執行該動作多次。
  • screenwriter：根據研究結果編寫劇情大綱。
  • file_writer：為生成的電影設定片名，並將序列結果寫入檔案。

1. 在 Cloud Shell 編輯器，前往 adk_multiagent_systems/workflow_agents 目錄。

2. 點選 workflow_agents 目錄中的「agent.py」檔案。

3. 詳閱這個代理的定義檔。由於必須先定義子代理，才能指派至父代理，如要依對話流程順序讀取檔案，請從檔案底部往上讀取代理。

4. 您也能使用 append_to_state 函式工具，允許代理在狀態字典值中新增內容。如果代理可能會多次呼叫工具，或在 LoopAgent 的多個迴圈中執行動作，這項工具就特別實用，因為代理每次執行動作時的輸出內容都會儲存。

5. 從 Cloud Shell 終端機啟動網頁介面，試用目前的代理版本。請使用 --reload_agents 引數，根據代理變更即時重新載入代理：

   cd ~/adk_multiagent_systems adk web --reload_agents 注意：如未關閉先前的 adk web 工作階段，預設通訊埠 8000 會遭到封鎖。只要使用 adk web --port 8001 等指令，即可透過新通訊埠啟動開發 UI。

6. 點選終端機輸出內容中的 http://127.0.0.1:8000 連結，在新分頁開啟網頁介面。

7. 系統會開啟新的瀏覽器分頁，顯示 ADK 開發 UI。

8. 在左側的「Select an agent」下拉式選單，選取「workflow_agents」。

9. 輸入 hello 開始對話。代理可能要過一下子才會回覆，但應該會請您輸入歷史人物，開始生成電影劇情。

10. 代理提示您輸入歷史人物時，可任選一位，或使用下列人物範例：

    • Zhang Zhongjing (張仲景)：西元 2 世紀的著名中醫師。
    • Ada Lovelace (愛達·勒芙蕾絲)：英國數學家兼作家，以研究早期電腦而聞名。
    • Marcus Aurelius (馬可·奧理略)：羅馬皇帝，以哲學著作而聞名。

11. 代理現在應會相互依序呼叫其他代理，開始執行工作流程，將劇情大綱檔案寫入 ~/adk_multiagent_systems/movie_pitches 目錄。檔案寫入磁碟時，您應會收到通知。

    如果代理未回報檔案生成完畢，或詢問您是否想嘗試其他人物，可點選右上方的「+ New Session」，然後再試一次。

12. 在 Cloud Shell 編輯器查看代理的輸出內容。只要在 Cloud Shell 編輯器選單依序啟用「View」>「Word Wrap」，即可查看完整文字，不必頻繁水平捲動。

13. 在 ADK 開發 UI，點選表示一輪對話的任一代理圖示 ，開啟事件檢視畫面。

14. 事件檢視畫面會以樹狀結構呈現這個工作階段使用的代理和工具。您可能需要捲動事件面板，才能查看完整內容。

15. 除了圖表檢視畫面，您還能點選事件的「Request」分頁標籤，查看這個代理在要求中收到的資訊，包括對話記錄。
16. 您也能點選事件的「Response」分頁標籤，查看代理傳回的內容。

注意：雖然系統能生成有趣的結果，但不代表指令可以很簡短或省略樣本。為每個代理額外加入更嚴謹的指令和樣本，才能大幅提升系統的可靠性。

點選「Check my progress」，確認目標已達成。 開始使用 SequentialAgent 建構多代理系統

工作 5：新增 LoopAgent 來執行疊代作業

LoopAgent 會依定義的序列執行子代理，然後再次從頭開始，過程中不會停下來等待使用者輸入。這個迴圈會一再重複，直到達到指定疊代次數，或其中一個子代理呼叫結束迴圈為止 (通常是呼叫內建的 exit_loop 工具)。

LoopAgent 非常適合需要持續修正、監控或反覆執行的工作流程。以下列舉幾個範例：

• 反覆修正：透過重複的代理循環，持續改良文件或計畫。
• 持續監控：使用一系列代理，定期檢查資料來源或條件。
• 討論或協商：代理互相反覆模擬討論，以獲得更理想的結果。

您將新增 LoopAgent，在構思故事時，讓電影提案代理執行多輪研究和疊代作業。LoopAgent 不僅可協助修正腳本，還能讓使用者先輸入較籠統的內容。簡單來說，使用者可能不會提出具體的歷史人物，只知道自己想要一段關於古代醫師的故事。在這種情況下，代理可反覆進行「研究 > 寫作」循環，找出合適的人物，然後編寫故事。

修改後的代理運作流程大致如下：

• root_agent greeter：維持不變。
• 現在 SequentialAgent film_concept_team 會由下列代理組成：
  • LoopAgent：名稱為 writers_room，位於序列開頭，包含下列代理：
    • researcher：作用與先前相同。
    • screenwriter：作用與先前類似。
    • critic：在迴圈中，對目前的草稿提出重要意見，進而啟動下一輪研究和改進。
  • 迴圈終止時，對話掌控權將回到 SequentialAgent film_concept_team，再傳遞至序列中的下一個代理 file_writer。該代理會設定電影片名，並將序列結果寫入檔案，與先前一樣。

現在，請按照下列步驟進行變更：

1. 在 adk_multiagent_systems/workflow_agents/agent.py 檔案新增這項工具的匯入語句，代理即可視需要結束迴圈：

   from google.adk.tools import exit_loop

2. 新增 critic 代理來判斷劇情大綱是否完成，進而決定是否結束迴圈。請將下列新代理貼到 agent.py 檔案的 # Agents 區段標頭下方，不必覆寫現有代理。請注意，exit_loop 是其中一項工具，附帶使用時機說明：

   critic = Agent( name="critic", model=model_name, description="審閱大綱，找出可改進的地方。", instruction=""" INSTRUCTIONS: 請思考關於 PLOT_OUTLINE 的下列問題： - 符合令人滿意的三幕式電影結構嗎？ - 角色們的掙扎是否引人入勝？ - 是否以真實的歷史時期為背景？ - 是否充分融入 RESEARCH 提供的歷史細節？ 如果 PLOT_OUTLINE 在這些問題上表現良好，請使用「exit_loop」工具退出寫作迴圈。 如果能大幅調整，則使用「append_to_state」工具將意見新增至「CRITICAL_FEEDBACK」欄位。 請說明你的決定，並簡述意見回饋。 PLOT_OUTLINE: { PLOT_OUTLINE? } RESEARCH: { research? } """, before_model_callback=log_query_to_model, after_model_callback=log_model_response, tools=[append_to_state, exit_loop] )

3. 建立新的 LoopAgent 並命名為 writers_room，再以 researcher、screenwriter 和 critic 組成疊代迴圈。每次迴圈結束時，代理都會嚴格審查當前工作，促成下一輪的改良。請將下列內容貼到現有 SequentialAgent film_concept_team 區段之前。

   writers_room = LoopAgent( name="writers_room", description="反覆進行研究和寫作，改良電影情節大綱。", sub_agents=[ researcher, screenwriter, critic ], max_iterations=5, )

4. 您會發現建立的 LoopAgent 包含 max_iterations 參數。這個參數會定義迴圈結束前的執行次數。無論您是否想以其他方法中斷迴圈，都建議限制疊代總次數。

5. 更新 SequentialAgent film_concept_team，將 researcher 和 screenwriter 換成您剛才建立的 LoopAgent writers_room。file_writer 代理則應留在序列結尾。現在 film_concept_team 應如下所示：

   film_concept_team = SequentialAgent( name="film_concept_team", description="撰寫電影劇情大綱，並儲存為文字檔。", sub_agents=[ writers_room, file_writer ], )

6. 返回 ADK 開發 UI 分頁，點選右上方的「+ New Session」按鈕，開始新的工作階段。

7. 輸入 hello 開始新的對話。

8. 代理提示您選擇歷史人物類型時，請選擇有興趣的人物，例如：

   • an industrial designer who made products for the masses
   • a cartographer (a map maker)
   • that guy who made crops yield more food

9. 選擇人物類型後，代理應會反覆循環運作，最後設定電影片名，並將大綱寫入檔案。

10. 使用 Cloud Shell 編輯器查看生成的檔案。該檔案應儲存於 adk_multiagent_systems/movie_pitches 目錄。與先前一樣，在編輯器選單依序啟用「View」>「Word Wrap」，即可查看完整文字，不必頻繁水平捲動。

點選「Check my progress」，確認目標已達成。 新增 LoopAgent 來執行疊代作業

工作 6：以「擴散收集」模式，使用 ParallelAgent 生成報告

ParallelAgent 可同時執行多個子代理。每個子代理都會各自運作，而且預設不會在同步執行時，直接共用對話記錄或狀態。

如果工作可劃分為獨立的子工作並同時處理，就很適合採用這種代理。使用 ParallelAgent 後，這類工作的整體執行時間將大幅縮短。

在本實驗室，您將加入補充報告，內容包含潛在票房表現研究和選角初步構想，藉此提升新電影提案的說服力。

修改後的代理運作流程大致如下：

• greeter：維持不變。
• 現在 SequentialAgent film_concept_team 會由下列代理組成：
  • LoopAgent writers_room 同樣包含下列代理：
    • researcher
    • screenwriter
    • critic
  • 新的 ParallelAgent preproduction_team 會隨即運作。這個代理涵蓋：
    • box_office_researcher 代理：根據歷來票房資料，生成這部電影的潛在票房表現報告。
    • casting_agent 代理：找出曾主演類似電影的演員，據此提供選角初步構想。
  • file_writer 代理：將序列結果寫入檔案，與先前一樣。

儘管本例中的許多創意工作通常由人類團隊完成，但這項工作流程旨在說明如何將複雜的任務鏈拆分給多個子代理，藉以生成複雜文件的草稿，供人類團隊成員編輯和改進。

1. 將下列新代理和 ParallelAgent 貼到 workflow_agents/agent.py 檔案 # Agents 標頭的下方：

   box_office_researcher = Agent( name="box_office_researcher", model=model_name, description="考量這部電影的票房潛力", instruction=""" PLOT_OUTLINE: { PLOT_OUTLINE? } INSTRUCTIONS: 根據其他近期電影的票房表現，為 PLOT_OUTLINE 中的這類電影撰寫一份票房潛力報告。 """, output_key="box_office_report" ) casting_agent = Agent( name="casting_agent", model=model_name, description="為這部電影生成選角構想", instruction=""" PLOT_OUTLINE: { PLOT_OUTLINE? } INSTRUCTIONS: 為 PLOT_OUTLINE 所述的角色生成選角構想，推薦曾飾演類似角色，並獲得影評人及/或粉絲好評的演員。 """, output_key="casting_report" ) preproduction_team = ParallelAgent( name="preproduction_team", sub_agents=[ box_office_researcher, casting_agent ] )

2. 更新現有 film_concept_team 代理的 sub_agents 清單，在 writers_room 與 file_writer 間加入 preproduction_team：

   film_concept_team = SequentialAgent( name="film_concept_team", description="撰寫電影劇情大綱，並儲存為文字檔。", sub_agents=[ writers_room, preproduction_team, file_writer ], )

3. 將 file_writer 的 instruction 改為：

   INSTRUCTIONS: - 為 PLOT_OUTLINE 所述的電影，建議一個有市場潛力、符合時下潮流的片名。如果 PLOT_OUTLINE 中有建議的片名，可以沿用或換一個更好的片名。 - 使用「write_file」工具建立新的文字檔，並指定下列引數： - 檔名：使用電影片名 - 寫入「movie_pitches」目錄 - 寫入的「內容」應包含： - 劇情大綱 - 票房報告 - 選角報告 PLOT_OUTLINE: { PLOT_OUTLINE? } BOX_OFFICE_REPORT: { box_office_report? } CASTING_REPORT: { casting_report? }

4. 儲存檔案。

5. 點選 ADK 開發 UI 右上方的「+ New Session」。

6. 輸入 hello 開始對話。

7. 代理提示時，輸入您有興趣的新人物構想，例如：

   • that actress who invented the technology for wifi
   • an exciting chef
   • key players in the worlds fair exhibitions

8. 代理完成編寫並生成報告後，請前往 adk_multiagent_systems/movie_pitches 目錄查看生成的檔案。如果部分程序失敗，請點選右上方的「+ New session」，然後再試一次。

自訂工作流程代理

如果預先定義的工作流程代理 SequentialAgent、LoopAgent 和 ParallelAgent 無法滿足需求，不妨使用 CustomAgent 彈性導入新的工作流程邏輯。您可以定義子代理間的流程控制、條件式執行或狀態管理模式。這個代理適用於複雜的工作流程、有狀態的自動化調度管理作業，或將自訂商業邏輯整合至框架的自動化調度管理層。

本實驗室不會說明如何建立 CustomAgent，但您可以先認識這個代理，需要時就能使用！

恭喜！

在本實驗室，您學會如何建立多個代理並按照上下層關係相互連結、將資料新增至工作階段狀態再指示代理讀取，以及使用工作流程代理，直接在代理間傳遞對話。

Google Cloud 教育訓練與認證

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

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

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

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