GENAI129

評分：您必須獲得 80% 或更高的分數，才能通過這項挑戰實驗室。

總覽

在本實驗室，您將展現使用 Agent Development Kit (ADK) 建立代理、將其部署至 Agent Runtime，以及透過網頁應用程式使用這些代理的能力。

目標

在這個實驗室，您會執行下列操作：

• 使用 Agent Development Kit (ADK) 建構代理 (包含根代理和子代理)
• 讓代理能夠使用 Agent Search 工具，並將 Python 函式當成工具使用
• 將代理輸出內容儲存至工作階段狀態中，並從工作階段狀態中擷取值，供後續的代理指令使用
• 將代理部署至 Agent Runtime
• 向部署至 Agent Runtime 的代理查詢資訊

相關學習資源

如要尋找實用資源，培養順利完成本實驗室所需的技能，建議參考下列資源的相關章節：

類別	資源
課程	- 運用 Agent Development Kit (ADK) 與 Agent Runtime 部署多代理系統
學習實驗室	- 開始使用 Agent Development Kit (ADK) - 為 ADK 代理提供工具 - 使用 ADK 建構多代理系統 - 將 ADK 代理部署至 Agent Runtime - 使用 AI Applications 建構 Agent Search 應用程式

設定和需求

實驗室活動啟動須知

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

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

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

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

注意事項：請使用無痕模式 (建議選項) 或私密瀏覽視窗執行此實驗室，這可以防止個人帳戶和學員帳戶之間的衝突，避免個人帳戶產生額外費用。

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

注意事項：務必使用實驗室專用的學員帳戶。如果使用其他 Google Cloud 帳戶，可能會產生額外費用。

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

挑戰情境

Cymbal Shops 是一家販售家用品、電子產品與服飾的美國零售連鎖店，總部位於明尼亞波里斯。

Cymbal Shops 已將業務拓展至歐洲，並成立新的油漆部門。公司計畫透過全新的線上平台，簡化消費者選購 DIY 住家整修專用油漆的流程。

您的同事已開始開發代理 Paint Agent，協助使用者：

• 依據 Cymbal Shops 的油漆產品資料表挑選油漆產品
• 從選定的產品系列中挑選顏色
• 依據房間尺寸判斷所需的油漆用量
• 依據所選項目計算價格

不過，該同事因遇到錯誤而卡關，最後也離開了公司。

您是 Cymbal Shops 新進的機器學習工程師，目前的工作是完成 Paint Agent 的部署作業。這個代理的結構如下：

工作 1：建立可以搜尋油漆產品資訊的 Agent Search 應用程式

在這項工作，您會部署 Agent Search 資料儲存庫。這個資料儲存庫會匯入說明 Cymbal Shops 油漆的資料表 (您可以在無痕視窗開啟分頁來預覽這些資料，網址為 https://storage.cloud.google.com/-bucket/Cymbal_Shops_Paint_Datasheets.pdf)。這份資料表將做為基準資料來源，使用者查詢油漆產品時，系統就會以此為依據。

資料儲存庫和搜尋應用程式可讓代理快速找到貴公司的內容，然後根據該資訊，向使用提供適當的回覆。

1. 前往 Google Cloud 控制台，依序點選「Agent Platform」>「代理」>「搜尋」。

2. 按照下列設定建立 Agent Search 應用程式：

   欄位	值
   應用程式類型	自訂搜尋 (一般)
   應用程式名稱	Paint Search
   公司名稱	Cymbal Shops
   位置	全域

3. 按照下列設定建立 Agent Search 資料儲存庫：

   欄位	值
   資料來源	Cloud Storage
   資料類型	文件
   資料夾或檔案	檔案
   要匯入的檔案	-bucket/Cymbal_Shops_Paint_Datasheets.pdf
   位置	全域
   資料儲存庫名稱	Cymbal Paint
   文件剖析器	版面配置剖析器
   啟用表格註解功能	已啟用
   在分塊中納入祖系標題	已啟用

4. 應用程式和資料儲存庫的「計價模式」都選「一般」。

點選「Check my progress」，確認目標已達成。 建立資料儲存庫和搜尋應用程式。

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

本實驗室環境已預先啟用 Agent Platform API。如要在自己的專案執行這些步驟，請前往 Agent Platform 並按照提示啟用。

準備 Cloud Shell 編輯器分頁

1. 在 Google Cloud 控制台標題列，點按「啟用 Cloud Shell」圖示 ()。

   注意：您也可以選取控制台瀏覽器分頁，然後依序按下 G 和 S 鍵，開啟 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_challenge_lab . 2> /dev/null
2. gcloud storage cp -r gs://{{{project_0.project_id| YOUR_GCP_PROJECT_ID}}}-bucket/adk_challenge_lab . 2> /dev/null
   export PATH=$PATH:"/home/${USER}/.local/bin" python3 -m pip install -r adk_challenge_lab/requirements.txt python3 -m pip install chainlit==2.11.1
3. 在 Cloud Shell 終端機執行下列指令，更新 PATH 環境變數，並安裝 ADK 和實驗室所需的其他項目。

   export PATH=$PATH:"/home/${USER}/.local/bin" python3 -m pip install -r adk_challenge_lab/requirements.txt python3 -m pip install chainlit==2.11.1

   cd ~/adk_challenge_lab cat << EOF > .env GOOGLE_GENAI_USE_VERTEXAI=TRUE GOOGLE_CLOUD_PROJECT={{{project_0.project_id| YOUR_GCP_PROJECT_ID}}} GOOGLE_CLOUD_LOCATION={{{project_0.default_region| GCP_LOCATION}}} RESOURCES_BUCKET={{{project_0.project_id| YOUR_GCP_PROJECT_ID}}}-bucket MODEL={{{project_0.startup_script.gemini_flash_model_id | gemini_flash_model_id}}} SEARCH_ENGINE_ID=YOUR_ID EOF

4. 將下列指令複製到文字檔，並將 SEARCH_ENGINE_ID 的值從 YOUR_ID 改為剛才建立的搜尋引擎 ID (格式為 paint-search_1756...)。只要依序前往「Agent Platform」>「代理」>「搜尋」，就能在「應用程式」清單中找到這組 ID：

5. cd ~/adk_challenge_lab cat << EOF > .env GOOGLE_GENAI_USE_VERTEXAI=TRUE GOOGLE_CLOUD_PROJECT={{{project_0.project_id| YOUR_GCP_PROJECT_ID}}} GOOGLE_CLOUD_LOCATION={{{project_0.default_region| GCP_LOCATION}}} RESOURCES_BUCKET={{{project_0.project_id| YOUR_GCP_PROJECT_ID}}}-bucket MODEL={{{project_0.startup_script.gemini_flash_model_id | gemini_flash_model_id}}} SEARCH_ENGINE_ID=YOUR_ID EOF
   cp .env paint_agent/.env
在 Cloud Shell 終端機執行編輯後的指令，建立包含模型驗證和設定變數的 .env 檔案。[注意：如要查看隱藏的檔案 (檔名開頭為半形句點)，只需在 Cloud Shell 編輯器選單依序點選「View」>「Toggle Hidden Files」，系統就會顯示這類檔案]

將 .env 檔案複製到代理目錄，讓代理在部署完成後取得所需驗證設定：

cp .env paint_agent/.env

工作 3：為 Paint Agent 偵錯

adk run paint_agent
6. 同事已開始開發 Paint Agent，但中途卡關，您必須接手對方未完成的工作 (包括修正先前留下的錯誤)，完成該代理的開發作業並加以部署。
   hello
   yes

   在 Cloud Shell 終端機執行下列指令，執行該代理目前的版本：

   ... google.genai.errors.ClientError: 400 INVALID_ARGUMENT. {'error': {'code': 400, 'message': 'Multiple tools are supported only when they are all search tools.', 'status': 'INVALID_ARGUMENT'}}

   adk run paint_agent

7. [user]: 提示出現時，請輸入以下內容：

8. 如果代理接著又問您是否想進一步瞭解 Cymbal Shops 的油漆，請回覆：

   yes

   ... google.genai.errors.ClientError: 400 INVALID_ARGUMENT. {'error': {'code': 400, 'message': 'Multiple tools are supported only when they are all search tools.', 'status': 'INVALID_ARGUMENT'}}

   您將在後續步驟中解決這個錯誤。

9. 開啟 adk_challenge_lab/paint_agent/agent.py 檔案，並查看 root_agent 使用的子代理和工具清單。請注意，root_agent 包含子代理。將工作轉交給子代理時，系統會叫用隱式 transfer_to_agent 工具。

   由於 root_agent 的工具不是搜尋工具，因此至少須有一個代理叫用搜尋工具。請查看
   sub_agents 目錄中的子代理，找出實際使用的搜尋工具 (本例用的是 VertexAiSearchTool)：
   • https://github.com/google/adk-python/blob/main/src/google/adk/tools/vertex_ai_search_tool.py
   • 隨堂測驗 (答案會在後續步驟中揭曉)：

10. 雖然搜尋工具無法與代理中的其他非搜尋工具一起使用 (即使如本例所示，透過子代理使用也不行)，但 ADK 有一個名為 AgentTool 的工具，可將使用搜尋工具的獨立代理包裝起來，接著該代理便能以工具形式，與其他工具搭配使用。

11. https://github.com/google/adk-python/blob/main/src/google/adk/tools/agent_tool.py

    請回到 root_agent 的檔案 adk_challenge_lab/paint_agent/agent.py，在 root_agent 的工具清單中新增 AgentTool()，並為 AgentTool() 提供下列引數：

    agent 應設為 search_agent (也就是您在上方找到、會使用搜尋工具的子代理)。

    skip_summarization 應設為 False，因為您希望代理回報搜尋工具傳回的結果。

12. 將該子代理從 sub_agents 清單中移除。

    adk run paint_agent

13. 儲存檔案。
    注意：請在資料儲存庫建立完畢且文件編入索引之後，再繼續操作。您可以依序點選「Agent Platform」>「代理」>「搜尋」>「資料儲存庫」>「Cymbal Paint」資料儲存庫，然後前往「文件」分頁確認這個狀態。

    實際上，狀態顯示為「就緒」後，過幾分鐘再查詢代理，輸出結果會更可靠。

14. 在 Cloud Shell 終端機，透過下列指令再次執行代理：

    adk run paint_agent

現在您應該可以與該代理對話，並取得 Cymbal Shops 油漆的相關資訊。

請代理告訴您 EcoGreens 和 Forever Paint 的價格。

1. 價格應分別為 €35 歐元和 €40 歐元。

   
   

2. 點選「Check my progress」，確認目標已達成。 為代理偵錯。

3. 在指令列介面與代理對話完畢之後，輸入 exit 即可結束對話。

4. 工作 4：儲存及使用共用狀態

   root_agent 會從 adk_challenge_lab/paint_agent/tools.py 匯入並使用 set_session_value 工具，目的是向使用者收集 SELECTED_PAINT 和 COVERAGE_RATE 等資訊，然後將這些資訊儲存在工作階段中，並在多輪對話中使用。不過，這項工具尚未完整實作。

5. 更新 adk_challenge_lab/paint_agent/tools.py 檔案中的 set_session_value 函式，將鍵/值組合儲存在 ToolContext 的狀態字典中。

   adk web --allow_origins "regex:https://.*\.cloudshell\.dev"

6. 更新函式的回應，傳回 f"stored '{value}' in '{key}'" 這個狀態訊息。

7. 開啟與 coverage_calculator_agent 相關聯的 agent.py 檔案。coverage_calculator_agent 是 room_planner 的子代理，而 room_planner 則是 root_agent 的子代理。

   您現在應該可以與代理進行以下對話：代理回覆[表示願意提供 Cymbal Shops 油漆的相關資訊][分享 Project Paint、EcoGreens、SureCoverage、Forever Paint 等油漆產品的相關資訊。][「State」分頁應會顯示更新後的狀態值。詢問房間數量和各房間的名稱。][請您挑選辦公室要使用的顏色。]

   請注意，該代理的指令內容並未正確載入狀態字典中的值。請更新指令，將全大寫的字詞改為使用 ADK 的鍵範本，將狀態值載入指令中。建議您使用選用語法 (例如 {SELECTED_PAINT?})，避免因在狀態鍵填入值之前叫用代理，而導致代理當機。	https://google.github.io/adk-docs/sessions/state/#using-key-templating	執行下列指令來測試代理：	adk web --allow_origins "regex:https://.*\.cloudshell\.dev"	選取「paint_agent」。
   您
   你好
   好
   我想使用 EcoGreens
   只有一間，我的辦公室

8. Deep Ocean

   [詢問房間尺寸。]

9. 3 公尺 x 4 公尺，高 3 公尺，有 1 扇門、2 扇窗。

   [確認要刷幾層。]

兩層。

[計算出需要可以覆蓋 74 平方公尺的油漆。]

注意：為確保產品圖片正確顯示，請在瀏覽器設定中為這個網域啟用第三方 Cookie，然後重新整理頁面。

cd ~/adk_challenge_lab

11. 與代理對話完畢之後，即可關閉開發人員 UI 瀏覽器分頁。

    點選「Check my progress」，確認目標已達成。 設定及使用工作階段狀態

    	選取 Cloud Shell 終端機面板，然後按下 CTRL+C 鍵來關閉伺服器。

工作 5：部署至 Agent Runtime 在 Cloud Shell 終端機中，確認所在目錄為 adk_challenge_lab：
15. cd ~/adk_challenge_lab

16. 使用 adk deploy agent_engine 指令，將代理部署至 Agent Runtime，且務必將代理目錄加入指令，做為最後一個位置引數 (例如，如果您目前就位於該目錄，就直接使用 .)。請使用下列引數：

    參數

引數
--display_name
17. "Paint Agent"
    agent = client.agent_engines.get(name='YOUR_AGENT_RESOURCE_NAME')
18. 注意：部署指令可能需要 5 到 10 分鐘才會執行完畢。
    cd ~/adk_challenge_lab/chainlit_ui chainlit run app.py

    在代理部署期間，將 Agent Platform 使用者和 Discovery Engine 使用者 IAM 角色授予 服務帳戶。

    2025-08-25 12:30:00 - Your app is available at http://localhost:8000

19. 請注意，部署作業完成後，部署的代理資源名稱會顯示在控制台中。

20. 點選「Check my progress」，確認目標已達成。 部署至 Agent Runtime

工作 6：向部署的代理查詢資訊在 adk_challenge_lab/chainlit_ui/app.py 檔案，找出並更新下列這行程式碼，將 YOUR_AGENT_RESOURCE_NAME 改為已部署的代理資源名稱，以便載入遠端代理：使用下列指令來執行 UI： 2025-08-25 12:30:00 - Your app is available at http://localhost:8000 您你好好我想使用 Forever Paint兩間，客廳和嬰兒房。嬰兒房用「Sunlight through a canvas tent」，客廳用「Coffee Cream」。

		agent = client.agent_engines.get(name='YOUR_AGENT_RESOURCE_NAME')		cd ~/adk_challenge_lab/chainlit_ui chainlit run app.py	預期的輸出內容：		點按 http://localhost:8000 的連結，在新的瀏覽器分頁中開啟。	與部署的代理進行以下對話：
代理回覆
[表示願意提供 Cymbal Shops 油漆的相關資訊]
[分享 Project Paint、EcoGreens、SureCoverage、Forever Paint 等油漆產品的相關資訊]
[詢問房間數量和各房間的名稱]
[請您挑選客廳和嬰兒房要使用的顏色。]

[詢問房間尺寸]

客廳為 5 公尺 x 4 公尺，高 2.5 公尺，有 1 扇門、3 扇窗。

[詢問要刷幾層油漆。]

兩層。

[要求提供嬰兒房尺寸。]

嬰兒房為 3 公尺 x 3 公尺，高 2.5 公尺，有 1 扇門、1 扇窗。

[提供單層估算結果，並確認要刷幾層。]

一律刷兩層。

[計算出客廳需要可以覆蓋 77 平方公尺的油漆，嬰兒房則為 53 平方公尺。]

如要與代理展開新的對話，點選左上角的圖示即可。