使用 ADK 建構多代理系統

1. 簡介

總覽

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

建構項目

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

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

課程內容

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

2. 多代理系統

開發人員可使用 Agent Development Kit (ADK)，讓生成式模型的多步驟行為更可靠精細。您不必編寫複雜的提示詞，只要使用 ADK 建構多個簡單的代理流程，代理就會劃分工作並合作解決問題。

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

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

階層式代理樹狀結構

呈現階層式代理的樹狀結構

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

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

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

3. 專案設定

Google 帳戶

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

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

登入 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. 如果系統在今天任何時間提示您授權，請點選「授權」繼續操作。按一下即可授權 Cloud Shell
  3. 如果畫面底部未顯示終端機，請開啟終端機：
    • 按一下「查看」
    • 按一下「終端機」在 Cloud Shell 編輯器中開啟新終端機
  4. 在終端機中，使用下列指令設定專案：
    gcloud config set project [PROJECT_ID]
    • 範例：
      gcloud config set project lab-project-id-example
    • 如果忘記專案 ID，可以使用下列指令列出所有專案 ID：
      gcloud projects list
      在 Cloud Shell 編輯器終端機中設定專案 ID
  5. 您應該會看到下列訊息：
    Updated property [core/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 devrel-demos-multiagent-lab
    --depth 1 旗標只會複製最新版本，速度較快。
  2. 在終端機中，將實驗室專屬資料夾移至主目錄，並重新命名，使其符合實驗室的預期結構。
    mv devrel-demos-multiagent-lab/ai-ml/build-multiagent-systems-with-adk/adk_multiagent_systems ~
  3. 在終端機中，前往本實驗室的正確工作目錄 (adk_multiagent_systems)。
    cd ~/adk_multiagent_systems

檢查檔案結構

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

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

啟動虛擬環境

  1. 在終端機中，使用 uv 建立並啟動虛擬環境。確保專案依附元件不會與系統 Python 或其他專案發生衝突。
    uv venv
source .venv/bin/activate
  2. 在終端機中，從 requirements.txt 檔案安裝 google-adk 和其他依附元件：
    uv pip install -r requirements.txt

設定環境變數

  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
    檔案結構現在應如下所示：
    顯示開啟的 adk_multiagent_systems 資料夾的「Explorer」面板

7. 瞭解父代理、子代理和同層代理之間的轉移方向

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

我們來試試。

  1. 在 Cloud Shell 編輯器中開啟 adk_multiagent_systems/parent_and_subagents/agent.py。請注意 agent.py 檔案中的三個代理：
    • root_agent (命名為 steering)：向使用者提問，決定要轉移至哪個子代理程式。一開始，它只會依據子代理的 description。
    • travel_brainstormer：協助使用者發想目的地。
    • attractions_planner：協助使用者列出特定國家/地區的待辦事項。
  2. 在建立 root_agent 時加入下列程式碼，將 travel_brainstormer 和 attractions_planner 做為 root_agent 的子代理：
        sub_agents=[travel_brainstormer, attractions_planner]
  3. 在終端機中，與代理程式對話：
    cd ~/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...
    請注意，對話已轉移至 travel_brainstormer，也就是 attractions_planner 的同層代理。這項功能預設為允許。
  12. 在使用者提示詞中輸入 exit，結束工作階段。

重點回顧

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

  • 對話一律從 root_agent 開始。
  • 父代理可根據 description 自動轉移給子代理。
  • 您可以透過 name，明確控制將 instruction 轉移給子代理的流程。
  • 根據預設，代理可以轉移給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. 建立 attractions_planner 代理時，加入 tools 參數來新增工具：
        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.
  5. 在終端機中執行下列指令，啟動 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)
  6. 在 Cloud Shell 終端機中，按一下「Web Preview」(網頁預覽) 按鈕，然後選取「Change Port」(變更通訊埠)，即可在新分頁中查看網頁介面。
    「網頁預覽」選單
  7. 輸入通訊埠編號 8000，然後按一下「變更並預覽」。系統會開啟新的瀏覽器分頁，顯示 ADK 開發人員使用者介面。
    變更通訊埠彈出式方塊，並在文字方塊中輸入 8000
  8. 在左側的「Select an agent」下拉式選單中，選擇 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 陣列，其中應包含您選取的兩個項目。網頁 UI 中的工作階段狀態預覽畫面
  17. 向代理傳送下列訊息：
    What is on my list?
    現在，代理程式應會從狀態讀取並傳回清單。
  18. 如果試用完代理，請關閉網路瀏覽器分頁，然後在 Cloud Shell 終端機按下 CTRL + C 鍵來停止伺服器。

章節回顧

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

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

9. 工作流程代理

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

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

  • SequentialAgent
  • LoopAgent
  • ParallelAgent

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

您將建構代理，為新上映的歷史人物電影製作提案文件。代理程式會負責研究、反覆撰寫及生成報告。

最終系統會如下所示：

film_concept_team 多代理系統圖

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

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

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

第一個版本結構如下：

Film_concept_team 多代理系統步驟 1

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

章節回顧

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

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

11. 新增 LoopAgent 來執行疊代作業

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

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

Film_concept_team 多代理系統步驟 2

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

  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,
)
  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 開發 UI 分頁，然後點選右上方的「+ New Session」。
  6. 輸入 hello 開始新的對話。
  7. 系統顯示提示時，請提供更廣泛的主題。您可以參考以下構想：
    • an industrial designer who made products for the masses
    • 製圖師 (地圖製作者)
    • that guy who made crops yield more food
    代理程式現在會透過迴圈運作。在 ADK 開發 UI 中，您會看到代理多次執行時的記錄 (例如「[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 建立「前置製作團隊」，並行作業。一位經紀人會研究票房潛力，另一位經紀人則同時激盪選角點子。這通常稱為「分散與收集」模式：ParallelAgent「分散」工作，而後續的代理程式 (我們的 file_writer)「收集」結果。

Film_concept_team 多代理系統步驟 3

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

  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 開發人員使用者介面分頁，然後按一下「+ New Session」。
  5. 輸入 hello 即可開始對話。
  6. 按照提示詞輸入新的人物構想，您可以參考以下構想：
    • 發明 Wi-Fi 技術的女演員
    • an exciting chef
    • key players in the worlds fair exhibitions
  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。舉例來說，您可以嘗試建構一個代理程式，只有在工作階段狀態中存在特定鍵時，才會有條件地執行。