使用 ADK 建構多代理系統

1. 簡介

總覽

本實驗室將說明如何使用 Google 代理開發套件 (Google ADK)，協調複雜的多代理系統。您將從簡單的代理程式階層，進展到建構自動化協作工作流程。

建構項目

您將建構兩個不同的多代理系統：

• 簡單的旅遊規劃代理程式，可學習在「腦力激盪」代理程式和「景點規劃」代理程式之間轉移對話。
• 更進階的電影提案生成器，使用自動化代理程式 (例如研究人員、編劇和影評) 的「編劇室」，以迴圈方式共同作業，建立完整的電影情節。

課程內容

• 如何建立父項和子項代理商關係。
• 如何從工具將資料寫入工作階段 state。
• 如何使用鍵範本 (例如 state{my_key?})。
• 如何使用 SequentialAgent 建立逐步工作流程。
• 如何使用 LoopAgent 建立疊代改良週期。
• 如何使用 ParallelAgent 並行執行獨立工作。

2. 多代理系統

Agent Development Kit (ADK) 可協助開發人員從生成模型取得更可靠、精密的行為，並執行多個步驟。ADK 可讓您建構多個較簡單的代理流程，這些代理會分工合作，共同解決問題，而不必使用複雜的提示。

與使用單一的整體式提示相比，這種方法有幾個優點：

• 設計更簡單：設計及整理小型專用代理程式流程，比設計大型複雜提示更簡單。
• 可靠性：相較於複雜的大型代理程式，專門代理程式在特定工作上更可靠。
• 可維護性：修正或改良小型專用代理程式時，不會影響系統其他部分。
• 模組化：為某個工作流程建構的代理程式，可輕鬆重複用於其他工作流程。

階層式代理程式樹狀結構

在 ADK 中，您可以透過樹狀結構整理代理程式。這個層級架構是控制對話流程的關鍵，因為它會限制哪些服務專員可以將對話「轉移」給其他服務專員。這樣一來，系統的行為會更易於預測，偵錯也更輕鬆。好處包括：

• 直覺式設計：結構靈感來自現實世界的團隊，因此更容易理解。
• 受控流程：階層可讓您精確控制工作委派，有助於偵錯。舉例來說，即使您有兩個描述類似的代理程式，樹狀結構也能確保系統呼叫正確的報告撰寫代理程式。

整個結構以 root_agent 開頭。這個代理程式會做為父項，並可擁有一或多個子項代理程式，而子項代理程式本身也能做為父項，擁有自己的子項代理程式，形成樹狀結構。

3. 專案設定

Google 帳戶

如果沒有個人 Google 帳戶，請建立 Google 帳戶。

請使用個人帳戶，而非公司或學校帳戶。

公司和學校帳戶可能設有限制，導致您無法啟用本實驗室所需的 API。

登入 Google Cloud 控制台

使用個人 Google 帳戶登入 Google Cloud 控制台。

啟用計費功能

兌換 $5 美元的 Google Cloud 抵免額 (選用)

如要參加這個研討會，您需要有具備部分抵免額的帳單帳戶。如果您打算使用自己的帳單，可以略過這個步驟。

1. 按一下這個連結，然後登入個人 Google 帳戶。您會看到類似下方的畫面：
2. 按一下「按這裡存取抵免額」按鈕。系統會將您帶往設定帳單資料的頁面
3. 按一下「確認」

您現在已連結至 Google Cloud Platform 試用帳單帳戶。

設定個人帳單帳戶

如果使用 Google Cloud 抵免額設定計費，可以略過這個步驟。

如要設定個人帳單帳戶，請前往這裡在 Cloud 控制台中啟用帳單。

注意事項：

• 完成本實驗室的 Cloud 資源費用應不到 $1 美元。
• 您可以按照本實驗室結尾的步驟刪除資源，避免產生額外費用。
• 新使用者可享有價值 $300 美元的免費試用期。

建立專案 (選用)

如果沒有要用於這個實驗室的現有專案，請在這裡建立新專案。

4. 開啟 Cloud Shell 編輯器

1. 按一下這個連結，直接前往 Cloud Shell 編輯器
2. 如果系統在今天任何時間提示您授權，請點選「授權」繼續操作。
3. 如果畫面底部未顯示終端機，請開啟終端機：
   • 按一下「查看」
   • 按一下「終端機」
4. 在終端機中，使用下列指令設定專案：

   gcloud config set project [PROJECT_ID]
   

   • 範例：

     gcloud config set project lab-project-id-example
     

   • 如果忘記專案 ID，可以使用下列指令列出所有專案 ID：

     gcloud projects list
     

     
5. 您應該會看到下列訊息：

   Updated property [core/project].
   

   如果看到 WARNING 並收到 Do you want to continue (Y/n)? 提示，表示您可能輸入了錯誤的專案 ID。按下 n 鍵和 Enter 鍵，然後再次嘗試執行 gcloud config set project 指令。

5. 啟用 API

如要使用 Vertex AI API 並與 Gemini 模型互動，您需要在 Google Cloud 專案中啟用 Vertex AI API。

1. 在終端機中啟用 API：

   gcloud services enable aiplatform.googleapis.com
   

以下是更新後的章節，取代手動建立檔案的步驟，改為複製 GitHub 存放區並安裝依附元件。

Python 適用的 Vertex AI SDK 簡介

如要從 Python 應用程式與 Vertex AI 上代管的模型互動，請使用 Python 適用的 Vertex AI SDK。這個 SDK 可簡化傳送提示、指定模型參數及接收回應的程序，不必直接處理基礎 API 呼叫的複雜性。

如需 Python 適用的 Vertex AI SDK 完整說明文件，請參閱「Python 適用的 Vertex AI SDK 簡介 | Google Cloud」。

6. 設定專案環境

建立存放區的本機複本

1. 在終端機中，複製含有範例檔案的存放區。

   git clone --depth 1 https://github.com/GoogleCloudPlatform/devrel-demos.git
   

   --depth 1 旗標只會複製最新版本，速度較快。
2. 在終端機中，前往這個實驗室的正確工作目錄。

   cd devrel-demos/ai-ml/build-multiagent-systems-with-adk/adk_multiagent_systems
   

啟動虛擬環境

3. 在終端機中，使用 uv 建立並啟動虛擬環境：

   uv venv
   source .venv/bin/activate
   

4. 在終端機中，從 requirements.txt 檔案安裝 google-adk 和其他依附元件：

   uv pip install -r requirements.txt
   

檢查檔案結構

現在所有檔案都已建立，請在檔案總管中開啟 adk_multiagent_systems 資料夾，查看完整結構。

1. 在 Cloud Shell 編輯器選單中，依序選取「File」 >「Open Folder...」。
   
   
2. 在彈出式方塊中，於使用者名稱後方新增下列資料夾資訊：devrel-demos/ai-ml/build-multiagent-systems-with-adk/adk_multiagent_systems/。按一下「確定」。
   應該會類似這樣：
   
   
3. 左側的「探索」面板會重新整理。您現在應該會看到完整的專案結構，其中包含 parent_and_subagents 和 workflow_agents 子目錄，可供進行後續步驟。
   

如果終端機因此消失，請依序點選頂端選單中的「View」(檢視) 和「Terminal」(終端機)，重新開啟終端機。

設定環境變數

1. 你已在 adk_multiagent_systems 目錄中。在終端機中，建立 .env 檔案來儲存環境變數：

   cloudshell edit .env
   

2. 將下列內容貼到編輯器中開啟的 .env 檔案：

   GOOGLE_GENAI_USE_VERTEXAI=TRUE
   GOOGLE_CLOUD_PROJECT="[YOUR-PROJECT-ID]"
   GOOGLE_CLOUD_LOCATION=global
   MODEL="gemini-2.5-flash"
   

3. 將 [YOUR-PROJECT-ID] 替換為實際的 Google Cloud 專案 ID。(例如：PROJECT_ID = "google-cloud-labs")
   如果您不記得專案 ID，請在終端機中執行下列指令。畫面會列出所有專案及其 ID。

   gcloud projects list
   

4. 在終端機中，將這個 .env 檔案複製到子代理程式目錄，讓子代理程式也能存取變數：

   cp .env parent_and_subagents/.env
   cp .env workflow_agents/.env
   

   檔案結構現在應如下所示：
   

7. 瞭解父項、子項和同層級代理程式之間的轉移作業

對話一律會以 root_agent 開頭。根據預設，父項代理程式會使用子項代理程式的 description，決定何時轉移對話。您也可以使用子代理程式的 name，在父項的 instruction 中明確引導這些轉移作業。

我們來試試。

1. 在 Cloud Shell 編輯器中開啟 adk_multiagent_systems/parent_and_subagents/agent.py。請注意 agent.py 檔案中的三個代理程式：
   • root_agent (命名為 steering)：向使用者提問，決定要轉移至哪個子代理程式。一開始只會依賴子代理程式的 description。
   • travel_brainstormer：協助使用者激發目的地構想。
   • attractions_planner：協助使用者列出特定國家/地區的待辦事項。

   提示：如要依對話流程順序閱讀 agent.py 檔案，最簡單的方法通常是從底部的 root_agent 開始往上閱讀。這是因為 Python 程式碼規定，我們必須先定義子代理程式，才能將其新增至代理程式。

2. 將 travel_brainstormer 和 attractions_planner 設為 root_agent 的子代理程式，方法是在建立 root_agent 時加入下列程式碼：

       sub_agents=[travel_brainstormer, attractions_planner]
   

   注意：代理程式階層僅由父項的 sub_agents 清單定義，子項代理程式不需要 parent 參數。

3. 在終端機中，與代理程式對話：

   cd ~/devrel-demos/ai-ml/build-multiagent-systems-with-adk/adk_multiagent_systems
   adk run parent_and_subagents
   

4. 在終端機的 [user]: 提示中輸入：

   hello
   

   輸出內容範例 (可能與您的輸出內容略有不同)：

   [steering]: Hi there! Do you already have a country in mind for your trip, or would you like some help deciding where to go?
   

5. 現在，請在終端機中告知代理程式：

   I could use some help deciding.
   

   輸出內容範例 (可能與您的輸出內容略有不同)：

   [travel_brainstormer]: Okay! To give you the best recommendations, I need to understand what you're looking for in a trip.
   ...
   

   請注意 [travel_brainstormer] 標記。root_agent 轉移的控制權僅以子代理商的 description 為依據。
6. 在終端機的 user: 提示中，輸入 exit 並按下 Enter 鍵，即可結束對話。
7. 現在我們來明確一點。在 agent.py 中，將下列內容新增至 root_agent 的 instruction：

           If they need help deciding, send them to 'travel_brainstormer'.
           If they know what country they'd like to visit, send them to the 'attractions_planner'.
   

8. 在終端機中，再次執行代理程式：

   adk run parent_and_subagents
   

9. 在終端機的 [user]: 提示中輸入：

   hello
   

10. 請回覆：

    I would like to go to Japan.
    

    輸出內容範例 (可能與您的輸出內容略有不同)：

    [attractions_planner]: Okay, I can help you with that! Here are some popular attractions in Japan:
    ...
    

    按照新指示，將轉移作業通知傳送至 attractions_planner。
11. 現在請回覆：

    Actually I don't know what country to visit.
    

    輸出內容範例 (可能與您的輸出內容略有不同)：

    [travel_brainstormer]: Okay! I can help you brainstorm some countries for travel...
    

    請注意，您已轉移至 attractions_planner 的同層級 travel_brainstormer。這項功能預設為啟用。

    如要避免轉移，可以在 attractions_planner 代理程式上設定 disallow_transfer_to_peers=True。

12. 在使用者提示中輸入 exit，即可結束工作階段。

重點回顧

在本節中，您已瞭解代理程式階層和對話流程的基本概念：

• 對話一律以 root_agent 開頭。
• 父項代理程式可根據 description 自動轉移至子項代理程式。
• 您可以將 instruction 提供給家長，讓家長透過 name 將通話轉接給子代理程式，明確控管這項流程。
• 根據預設，服務專員可以轉移給 peer 服務專員 (階層中的同層)。

8. 使用工作階段狀態儲存及擷取資訊

每個 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]:
       """Saves the list of attractions to state["attractions"].
   
       Args:
           attractions [str]: a list of strings to add to the list of attractions
   
       Returns:
           None
       """
       # Load existing attractions from state. If none exist, start an empty list
       existing_attractions = tool_context.state.get("attractions", [])
   
       # Update the 'attractions' key with a combo of old and new lists.
       # When the tool is run, ADK will create an event and make
       # corresponding updates in the session's state.
       tool_context.state["attractions"] = existing_attractions + attractions
   
       # A best practice for tools is to return a status message in a return dict
       return {"status": "success"}
   

   請注意以下程式碼：
   • 這個函式會接收 tool_context: ToolContext。這個物件是工作階段的閘道。
   • tool_context.state["attractions"] = ... 行會直接從工作階段的狀態字典讀取及寫入資料。ADK 會處理其餘作業。
3. 新增 tools 參數，將工具新增至 attractions_planner 代理程式：

       tools=[save_attractions_to_state]
   

4. 在 attractions_planner 代理程式現有的 instruction 中新增下列項目：

           - When they reply, use your tool to save their selected attraction and then provide more possible attractions.
           - If they ask to view the list, provide a bulleted list of { attractions? } and then suggest some more.
   

   請注意大括號中的部分：{ attractions? }。這項 ADK 功能「鍵範本」會將狀態中的 attractions 鍵值插入代理程式的提示。? 會將其設為選用，避免索引鍵尚不存在時發生錯誤。

5. 在終端機中執行下列指令，啟動 Agent Development Kit Web 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)
   

   注意：如果通訊埠 8000 正在使用中，您可以改用其他通訊埠執行，例如：adk web --port 8001。您必須在後續步驟中更新通訊埠編號，確保兩者一致。

6. 在 Cloud Shell 終端機中，按一下「Web Preview」(網頁預覽) 按鈕，然後選取「Change Port」(變更通訊埠)，即可在新分頁中查看網頁介面。
   
7. 輸入通訊埠編號 8000，然後按一下「變更並預覽」。系統會開啟新的瀏覽器分頁，顯示 ADK 開發使用者介面。
   
8. 在左側的「選取代理程式」下拉式選單中，選擇 parent_and_subagents。
9. 與 hello 展開對話
10. 客服專員向你問候後，請回覆：

    I'd like to go to Egypt.
    

    系統應會將你轉移至 attractions_planner，並提供景點清單。
11. 選擇景點，例如：

    I'll go to the Sphinx
    

12. 你應該會收到類似以下的回覆：好的，我已將獅身人面像儲存到你的清單...
13. 按一下回覆工具方塊 (標示勾號)，即可查看從工具回覆建立的事件。
    請注意，其中包含 actions 欄位，內含 stateDelta，說明狀態的變更。
14. 從服務專員的清單中回覆其他景點。
15. 在左側導覽選單中，按一下「X」即可結束先前檢查的事件。
16. 按一下左側邊欄的「狀態」分頁標籤。您現在可以在工作階段的狀態中看到 attractions 陣列，其中應包含您選取的兩個項目。
17. 將這則訊息傳送給服務專員：

    What is on my list?
    

    現在，代理程式應會從狀態讀取並傳回清單。
18. 完成代理程式實驗後，請關閉網頁瀏覽器分頁，並在 Cloud Shell 終端機中按下 CTRL + C 鍵停止伺服器。

如要將代理程式的完整文字回覆儲存在狀態中，您可以在定義代理程式時設定 output_key 參數，系統會將完整輸出內容儲存在該欄位名稱下的狀態字典中。

章節回顧

在本節中，您學會如何使用 Session 狀態分享資料：

• 寫入狀態：您可以使用 tool_context.state 物件 (例如 tool_context.state["my_list"] = [...])。
• 讀取狀態：使用鍵範本 (例如 instructionHere is your list: {my_list?})。
• 檢查狀態：您可以使用「State」分頁標籤，在 ADK 開發人員 UI 中即時監控工作階段狀態。

9. 工作流程代理

到目前為止，您已瞭解父項代理程式如何轉移至子項代理程式，然後等待使用者。工作流程代理程式則不同，這類代理程式會以自動化流程執行子代理程式，不必等待使用者輸入內容。

這項功能非常適合自動執行的多步驟工作，例如「規劃與執行」或「草擬與修訂」管道。ADK 提供三種內建工作流程代理程式來管理這項作業：

• SequentialAgent
• LoopAgent
• ParallelAgent

本實驗室的其餘部分將著重於使用這三個工作流程代理程式，建構多代理程式系統。

您將建構一個代理程式，為以歷史人物為主題的新電影製作宣傳文件。代理程式會負責研究、反覆撰寫和生成報告。

最後，您的系統會如下所示：

您將逐步建構這個系統，從最簡單的工作流程開始。

10. 使用 SequentialAgent 建構多代理系統

SequentialAgent 是指以簡單的線性序列執行子代理程式的工作流程代理程式。sub_agents 清單中的每個代理程式都會依序執行。這非常適合必須依特定順序執行工作的管道，例如您現在要建構的電影提案代理程式。

第一個版本會採用以下結構：

• root_agent (greeter) 會歡迎使用者，並取得電影主題。
• 然後轉移至名為 film_concept_team 的 SequentialAgent，該 SequentialAgent 會：
  1. 執行 researcher 代理程式，從維基百科取得事實。
  2. 執行 screenwriter 代理程式，根據這些事實編寫劇情。
  3. 執行 file_writer 代理程式，將最終繪圖儲存至檔案。

執行看看。

1. 在 Cloud Shell 編輯器中開啟 adk_multiagent_systems/workflow_agents/agent.py。
   詳閱這個代理程式定義檔。由於子代理程式必須先定義，才能指派給上層代理程式，因此如要依對話流程順序讀取檔案，請從檔案底部讀取代理程式。
2. 請注意 append_to_state 工具。代理程式可透過這個輔助函式，將資料附加至工作階段狀態中的清單，researcher 和 screenwriter 就是透過這種方式傳遞工作。
3. 試用代理程式。在終端機中，啟動已啟用即時重新載入功能的網頁介面：

   cd ~/devrel-demos/ai-ml/build-multiagent-systems-with-adk/adk_multiagent_systems
   adk web --reload_agents
   

   注意：如果通訊埠 8000 正在使用中，您可以改用其他通訊埠執行，例如：adk web --reload_agents --port 8001。

4. 在 Cloud Shell 終端機中，按一下「Web Preview」(網頁預覽) 按鈕，然後選取「Change Port」(變更通訊埠)，即可在新分頁中查看網頁介面。
   
5. 輸入通訊埠編號 8000，然後按一下「變更並預覽」。系統會開啟新的瀏覽器分頁，顯示 ADK 開發使用者介面。
   
6. 從「選取代理程式」下拉式選單中選取 workflow_agents。
7. 與 hello 展開對話。greeter 代理程式會回覆。
8. 系統顯示提示時，請輸入歷史人物。你可以使用這些範本，也可以自行製作：
   • 張仲景
   • 林可欣
   • 馬可．奧理略
9. 現在由 SequentialAgent 接手。你不會看到任何中間訊息。researcher、screenwriter 和 file_writer 會依序執行。代理程式只會在整個序列完成時回覆。
   如果失敗，請按一下右上方的「+ 新增工作階段」，然後再試一次。
10. 代理程式確認檔案已寫入後，請在 Cloud Shell 編輯器的 movie_pitches 目錄中找出並開啟新的 .txt 檔案，查看輸出內容。
11. 在 ADK 開發人員 UI 中，按一下對話記錄中的最後一個代理程式圖示，開啟事件檢視畫面。
12. 事件檢視畫面會顯示代理程式樹狀結構的視覺化圖表。您可以查看 greeter 如何呼叫 film_concept_team，然後依序呼叫每個子代理程式。
13. 您可以點選圖表中任何代理程式的「要求」和「回應」分頁標籤，檢查傳遞的確切資料，包括工作階段狀態。

注意：由於提示簡單，這個代理程式的輸出內容品質有限。在實際系統中，您會為每個代理提供更嚴格的指令和範例，以提高可靠性。

章節回顧

在本節中，您已瞭解如何使用工作流程代理程式：

• SequentialAgent 會依序執行子代理程式，步驟之間不會等待使用者輸入內容。
• 這就是「工作流程」，因為使用者會與 root_agent 對話，然後將「工作」交給 SequentialAgent 完成。
• 序列中的子代理程式會使用工作階段狀態 (例如 { PLOT_OUTLINE? }) 存取先前代理程式的工作。
• 您可以使用開發人員 UI 中的事件圖表，以視覺化方式呈現並偵錯整個代理程式對代理程式的工作流程。

11. 新增 LoopAgent，進行疊代作業

LoopAgent 是工作流程代理程式，會依序執行子代理程式，然後從頭開始重複執行。這個「迴圈」會持續執行，直到滿足條件為止，例如達到 max_iterations 計數，或是子代理呼叫內建的 exit_loop 工具。

這項功能適用於需要反覆修正的作業。您將新增這個 LoopAgent，為電影提案代理程式建立「編劇室」。這項功能可讓 researcher、screenwriter 和新的 critic 代理程式在迴圈中運作，每次傳遞都會改善劇情，直到 critic 判斷劇情已準備就緒。這也有助於代理程式處理較模糊的使用者輸入內容 (例如「古代醫生」)，讓代理程式研究並修正想法。

如要進行這些變更，請按照下列步驟操作：

1. 在 adk_multiagent_systems/workflow_agents/agent.py 中，加入 exit_loop 的匯入項目 (其他 google.adk 匯入項目附近)：

   from google.adk.tools import exit_loop
   

2. 新增 critic 代理程式。這個代理程式會審查劇情。如果結果良好，則會呼叫 exit_loop。如果不是，則會將意見回饋新增至下一個迴圈的狀態。
   將下列代理程式定義貼到 # Agents 區段下方：

   critic = Agent(
       name="critic",
       model=model_name,
       description="Reviews the outline so that it can be improved.",
       instruction="""
       INSTRUCTIONS:
       Consider these questions about the PLOT_OUTLINE:
       - Does it meet a satisfying three-act cinematic structure?
       - Do the characters' struggles seem engaging?
       - Does it feel grounded in a real time period in history?
       - Does it sufficiently incorporate historical details from the RESEARCH?
   
       If the PLOT_OUTLINE does a good job with these questions, exit the writing loop with your 'exit_loop' tool.
       If significant improvements can be made, use the 'append_to_state' tool to add your feedback to the field 'CRITICAL_FEEDBACK'.
       Explain your decision and briefly summarize the feedback you have provided.
   
       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. 建立 writers_room LoopAgent。其中包含要在迴圈中運作的三個代理程式。
   將下列程式碼貼到 film_concept_team 代理程式定義「上方」：

   writers_room = LoopAgent(
       name="writers_room",
       description="Iterates through research and writing to improve a movie plot outline.",
       sub_agents=[
           researcher,
           screenwriter,
           critic
       ],
       max_iterations=5,
   )
   

   請注意 max_iterations=5 參數。即使有結束條件，這也是防止無限迴圈的重要安全措施。

4. 更新 film_concept_team SequentialAgent，使用新的 writers_room 迴圈。將 researcher 和 screenwriter 替換為單一 writers_room 代理程式。將現有的 film_concept_team 定義替換為以下內容：

   film_concept_team = SequentialAgent(
       name="film_concept_team",
       description="Write a film plot outline and save it as a text file.",
       sub_agents=[
           writers_room,
           file_writer
       ],
   )
   

5. 返回 ADK 開發人員使用者介面分頁，然後按一下右上方的「+ New Session」。
6. 與 hello 展開新對話
7. 系統顯示提示時，請提供更廣泛的主題。您可以參考以下構想：
   • 為大眾設計產品的工業設計師
   • 製圖師 (地圖製作者)
   • 讓農作物產出更多食物的那個人
   代理程式現在會透過迴圈運作。在 ADK 開發人員使用者介面中，您會看到代理多次執行時的記錄 (例如 「[researcher]」、「[screenwriter]」、「[critic]」、「[researcher]」、「[screenwriter]」、「[critic]...」)。
8. 迴圈完成後，代理程式就會寫入檔案。查看 adk_multiagent_systems/movie_pitches 目錄中產生的檔案。
9. 檢查開發人員使用者介面中的事件圖表，查看迴圈結構。

章節回顧

在本節中，您已瞭解如何使用 LoopAgent：

• LoopAgent 是工作流程代理程式，會重複執行子代理程式序列，為疊代工作建立「內部迴圈」。
• 迴圈中的代理程式會使用工作階段狀態傳遞工作 (例如PLOT_OUTLINE) 和意見回饋 (例如 CRITICAL_FEEDBACK) 給彼此。
• 達到 max_iterations 限制或代理程式呼叫 exit_loop 工具時，迴圈就會停止。

12. 使用 ParallelAgent 執行「扇出和收集」作業

ParallelAgent 是工作流程代理程式，會同時 (並行) 執行所有子代理程式。如果工作可以分成獨立的子工作，例如執行兩項不同的研究工作，這項功能就非常實用。

您將使用 ParallelAgent 建立「前置製作團隊」，並行作業。一位經紀人會研究票房潛力，另一位經紀人則同時激盪選角點子。這通常稱為「扇出和收集」模式：ParallelAgent「扇出」工作，稍後的代理程式 (我們的 file_writer) 則「收集」結果。

最終的代理程式流程如下：

1. greeter (根) 會發起即時通訊。
2. 並轉移至 film_concept_team (SequentialAgent)，該程序會執行：
   • 用於建立情節的 writers_room (LoopAgent)。
   • 新的 preproduction_team (ParallelAgent) 可同時研究票房和選角。
   • file_writer：收集所有結果並儲存檔案。

如要進行這些變更，請按照下列步驟操作：

1. 在 adk_multiagent_systems/workflow_agents/agent.py 中，將新 ParallelAgent 及其子代理程式貼到 # Agents 標頭下方。

   box_office_researcher = Agent(
       name="box_office_researcher",
       model=model_name,
       description="Considers the box office potential of this film",
       instruction="""
       PLOT_OUTLINE:
       { PLOT_OUTLINE? }
   
       INSTRUCTIONS:
       Write a report on the box office potential of a movie like that described in PLOT_OUTLINE based on the reported box office performance of other recent films.
       """,
       output_key="box_office_report"
   )
   
   casting_agent = Agent(
       name="casting_agent",
       model=model_name,
       description="Generates casting ideas for this film",
       instruction="""
       PLOT_OUTLINE:
       { PLOT_OUTLINE? }
   
       INSTRUCTIONS:
       Generate ideas for casting for the characters described in PLOT_OUTLINE
       by suggesting actors who have received positive feedback from critics and/or
       fans when they have played similar roles.
       """,
       output_key="casting_report"
   )
   
   preproduction_team = ParallelAgent(
       name="preproduction_team",
       sub_agents=[
           box_office_researcher,
           casting_agent
       ]
   )
   

2. 更新 film_concept_team SequentialAgent 的 sub_agents 清單，加入新的 preproduction_team (介於 writers_room 和 file_writer 之間)。請將現有的 film_concept_team 定義替換為以下內容：

   film_concept_team = SequentialAgent(
       name="film_concept_team",
       description="Write a film plot outline and save it as a text file.",
       sub_agents=[
           writers_room,
           preproduction_team,
           file_writer
       ],
   )
   

3. 更新 file_writer 代理程式的 instruction，以便「收集」狀態中的新報表，並將其新增至檔案。
   將 file_writer 的 instruction 字串替換為：

       instruction="""
       INSTRUCTIONS:
       - Create a marketable, contemporary movie title suggestion for the movie described in the PLOT_OUTLINE.
       If a title has been suggested in PLOT_OUTLINE, you can use it, or replace it with a better one.
       - Use your 'write_file' tool to create a new txt file with the following arguments:
       - for a filename, use the movie title
       - Write to the 'movie_pitches' directory.
       - For the 'content' to write, include:
       - The PLOT_OUTLINE
       - The BOX_OFFICE_REPORT
       - The CASTING_REPORT
   
       PLOT_OUTLINE:
       { PLOT_OUTLINE? }
   
       BOX_OFFICE_REPORT:
       { box_office_report? }
   
       CASTING_REPORT:
       { casting_report? }
       """,
   

4. 返回 ADK 開發人員 UI 分頁，然後按一下「+ New Session」。
5. 輸入 hello 即可開始對話。
6. 當系統提示時，輸入新的角色構想。您可以參考以下構想：
   • 發明 Wi-Fi 技術的女演員
   • 令人興奮的廚師
   • 世界博覽會展覽的關鍵參與者
7. 代理程式完成工作後，請檢查 adk_multiagent_systems/movie_pitches 目錄中的最終檔案。現在，這份文件應該會包含劇情、票房報告和演員報告。

章節回顧

在本節中，您已瞭解如何使用 ParallelAgent：

• ParallelAgent「分散」工作，同時執行所有子代理程式，而非依序執行。
• 如果工作彼此不相依 (例如研究兩個不同的主題)，這項功能就非常有效率。
• 後續代理程式會「收集」平行代理程式的結果。做法是讓平行代理程式將工作儲存至工作階段狀態 (使用 output_key)，並讓最終代理程式 (例如 file_writer) 讀取這些鍵。

13. 自訂工作流程代理

如果 SequentialAgent、LoopAgent 和 ParallelAgent 的預先定義工作流程代理程式無法滿足您的需求，CustomAgent 可讓您彈性實作新的工作流程邏輯。

您可以定義子代理程式之間的流程控制、條件式執行或狀態管理模式。這項功能適用於複雜的工作流程、有狀態的調度管理，或將自訂商業邏輯整合至架構的調度管理層。

本實驗室不會介紹如何建立 CustomAgent，但您不妨瞭解這項功能，以備不時之需！

14. 恭喜！

您已成功使用 Google Agent Development Kit (ADK)，建構精密的多代理系統。您已從簡單的父項-子項代理關係，進展到自動化調度管理複雜的工作流程，可研究、撰寫及修飾創意專案。

重點回顧

在本實驗室中，您已完成下列作業：

• 以階層樹狀結構整理代理程式，並建立父項和子項代理程式關係。
• 控管代理程式對代理程式的轉移，包括自動 (使用 description) 和明確 (使用 instruction) 轉移。
• 使用工具將資料寫入 tool_context.state 字典。
• 使用鍵範本 (例如 { PLOT_OUTLINE? }) 從工作階段狀態讀取資料，並引導服務專員的提示。
• 實作 SequentialAgent，建立簡單的逐步工作流程 (研究 -> 撰寫 -> 儲存)。
• 使用 LoopAgent 搭配 critic 代理程式和 exit_loop 工具，建立疊代精修週期。
• 使用 ParallelAgent「分散」獨立工作 (例如選角和票房研究)，以便同時執行。

持續進行實驗

您可以透過多種方式，進一步運用所學知識。不妨參考下列建議：

• 新增更多代理：嘗試在 preproduction_team ParallelAgent 中新增代理。舉例來說，您可以建立 marketing_agent，根據 PLOT_OUTLINE 為電影撰寫宣傳標語。
• 新增更多工具：為 researcher 代理程式提供更多工具。您可以建立工具，使用 Google 搜尋 API 尋找 Wikipedia 上沒有的資訊。
• 探索 CustomAgent：實驗室提到不符合標準範本的工作流程 CustomAgent。舉例來說，您可以嘗試建構一個代理程式，只有在工作階段狀態中存在特定鍵時，才會有條件地執行。