GSP532

挑戰總覽

在挑戰研究室中，您會在特定情境下完成一系列任務。挑戰研究室不會提供逐步說明，您將運用從課程研究室學到的技巧，自行找出方法完成任務！自動評分系統 (如本頁所示) 將根據您是否正確完成任務來提供意見回饋。

在您完成任務的期間，挑戰研究室不會介紹新的 Google Cloud 概念。您須靈活運用所學技巧，例如變更預設值或詳讀並研究錯誤訊息，解決遇到的問題。

若想滿分達標，就必須在時限內成功完成所有任務！

這個實驗室適合已參加「透過直覺式程式開發方法建構智慧雲端應用程式」課程的學員。準備好迎接挑戰了嗎？

測驗主題

• 啟用 API 並設定環境變數。
• 執行 IAM 政策繫結。
• 在本機部署及測試 MCP 伺服器，然後部署至 Cloud Run。
• 使用 Agent Development Kit (ADK) 更新 Python 應用程式，改用 MCP。
• 將 MCP 伺服器和 ADK 代理 Docker 化，並部署至 Cloud Run。

設定和需求

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

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

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

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

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

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

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

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

挑戰情境

Cloud Creek 動物園委託 Cymbal Group 的「數位體驗」諮詢部門導入最先進的遊客互動系統，最終目標是打造出準確度高、生動有趣，且能根據情境深入回答遊客問題的 AI 導覽員。系統升級的核心是導入並升級「動物園導覽員」AI 代理，讓代理能透過稱為「動物園伺服器」的遠端 Model Context Protocol (MCP) 伺服器查詢動物資訊。

除了使用維基百科提供的背景資訊回答遊客問題，「動物園導覽員」代理必須能透過專用的 Google 搜尋 MCP 伺服器工具，即時取得廣泛的資訊，以便回答「請提供有關獅子保育的最新消息」等問題。

一名初級顧問在升級現有的「動物園伺服器」時犯了一些錯誤，導致 Python 伺服器無法正常運作。此外，專案架構尚不符合 Cymbal Group 嚴格的 IAM 政策。

您的任務就是解決這些問題。

您的挑戰

在本實驗室，您將擔任 Cymbal Group 的資深 AI 整合專家，完成以下任務：

• 設定專案並啟用必要的 API 和服務。
• 強制執行公司 IAM 政策。
• 修正損毀的 MCP 伺服器程式碼，並將伺服器部署至 Cloud Run 進行測試。
• 整合並升級「動物園導覽員」ADK AI 代理的功能和工作流程，以支援 Google 搜尋。
• 將 ADK 代理套件 Docker 化，並部署至 Cloud Run，以便用於正式環境。

工作 1：設定環境並啟用必要的 API

在這項工作，您會在 Google Cloud 建立專案專屬的基礎架構，以支援大規模 AI 部署作業。

請務必正確設定 Google Cloud 專案，確保必要服務能正常運作及有效通訊。

下載程式碼檔案

1. 在 Cloud Shell 點選「開啟編輯器」，開啟 Cloud Shell 編輯器並前往主目錄。

2. 在 Cloud Shell 編輯器的動作列，依序點選「View」>「Terminal」。

   注意：您可能需要拉寬瀏覽器視窗，或點選「更多選項」圖示 ，才能看到「View」選單選項。

在本實驗室的後續步驟，請將這個視窗做為 IDE，搭配使用上方的 Cloud Shell 編輯器和下方的 Cloud Shell 終端機。

關閉畫面右側顯示的其他教學課程或 Gemini 面板，為程式碼編輯器保留更多視窗空間。

3. 在終端機輸入下列指令，設定專案：

   gcloud config set project {{{primary_project.project_id | filled in at lab start}}}

   預期輸出內容： 輸出訊息應會顯示屬性已更新。

4. 在終端機執行下列指令，下載並解壓縮樣板程式碼檔案：

   gcloud storage cp gs://{{{primary_project.project_id | filled in at lab start}}}-labconfig-bucket/labs_code.zip . unzip labs_code.zip

5. 執行下列指令，建立環境變數：

   cd ~/zoo_guide_agent cat <<EOF > .env MODEL="{{{primary_project.startup_script.gemini_flash_model_id |filled in at lab start}}}" SERVICE_ACCOUNT="{{{primary_project.startup_script.project_number | filled in at lab start}}}-compute@developer.gserviceaccount.com" MCP_SERVER_URL="https://{{{primary_project.startup_script.mcp_server_name | filled in at lab start}}}-{{{primary_project.startup_script.project_number | filled in at lab start}}}.{{{primary_project.default_region | filled in at lab start}}}.run.app/mcp/" GOOGLE_GENAI_USE_ENTERPRISE=1 GOOGLE_CLOUD_PROJECT={{{primary_project.project_id | filled in at lab start}}} PROJECT_NUMBER={{{primary_project.startup_script.project_number | filled in at lab start}}} GOOGLE_CLOUD_LOCATION={{{primary_project.default_region | filled in at lab start}}} EOF

   最終的目錄結構應類似下方所示。

   輸出內容：

   . ├── mcp-on-cloudrun │ ├── Dockerfile │ ├── local_mcp_call.py │ ├── pyproject.toml │ ├── server.py │ └── uv.lock └── zoo_guide_agent ├── agent.py ├── __init__.py ├── .env └── requirements.txt

6. 最後，啟用必要的 API：Agent Platform API、Artifact Registry API、Compute Engine API、Cloud Build API 和 Cloud Run Admin API。

點選「Check my progress」，確認目標已達成。 啟用必要的 API

工作 2：執行必要的政策繫結 (IAM 設定)

自動化服務 Cloud Build 和 Cloud Run 需要特定權限，才能互相搭配運作並與 AI 平台互動。

在這項工作，您必須執行必要的政策繫結，授予使用者/服務帳戶權限，以便叫用 Cloud Run 並使用 AI 平台。

您需要將下列 IAM 角色授予對應的服務帳戶：

• 將 Cloud Run 管理員和 Agent Platform 使用者角色授予 使用者，允許該使用者將服務部署至 Cloud Run。

點選「Check my progress」，確認目標已達成。 執行必要的政策繫結

工作 3：修正 MCP 伺服器並部署至 Cloud Run

在這項工作，您必須使用 Gemini CLI 排解錯誤並修復 MCP 伺服器。MCP 伺服器是應用程式的核心，負責協調 AI 工具的使用。

修正程式碼問題後，請務必在 Gemini CLI 使用相關的 Cloud Build 整合指令，將現有的遠端 MCP 伺服器部署至 Gemini CLI 存放區進行測試。

在本機部署及測試

1. 在終端機執行下列指令，執行 ~/mcp-on-cloudrun/server.py：

   cd ~/mcp-on-cloudrun uv run server.py

   系統會傳回錯誤訊息；您需要在 Cloud Shell 中使用 Gemini 修正錯誤。

   注意：Gemini CLI 需要一些時間來更新及變更實際 Python 檔案中的程式碼。如果 Gemini CLI 要求您授權執行修正後的 Python 檔案，請按下 ESC 鍵取消，然後退出 Gemini CLI 並返回終端機。接著按照後續實驗室步驟操作。

2. 修正錯誤後，請重新執行先前的指令。系統應會在本機啟動 MCP 伺服器，並顯示確認訊息。

3. 開啟另一個 terminal 執行個體，然後執行 ~/mcp-on-cloudrun/local_mcp_call.py，測試部署在本機的代理：

   注意：如果收到 google.logging.v2.WriteLogEntriesPartialErrors 錯誤，請使用 gcloud config set project 指令設定專案。 cd ~/mcp-on-cloudrun uv run local_mcp_call.py

   預期輸出內容：結果應以 CallToolResult 形式呈現，顯示已成功擷取海象物種的結構化資料。

點選「Check my progress」，確認目標已達成。 在本機部署及測試 MCP

部署至 Cloud Run

注意：部署期間，系統可能會提示您授權 Cloud Shell。

• 執行下列 gcloud 指令，將應用程式部署至 Cloud Run：

  cd ~/mcp-on-cloudrun gcloud run deploy {{{primary_project.startup_script.mcp_server_name | filled in at lab start}}} \ --no-allow-unauthenticated \ --region={{{primary_project.default_region | filled in at lab start}}} \ --source=. \ --min=1 \ --project={{{primary_project.project_id | filled in at lab start}}} \ --labels=lab-dev=mcp-zoo-cloud-run-service

注意：部署作業會在 10 分鐘內完成。如果在 Cloud Run 部署期間遇到 Quota exceeded for total allowable CPU per project per region 錯誤，請稍候片刻，再重試指令。

點選「Check my progress」，確認目標已達成。 將 MCP 部署至 Cloud Run

工作 4：更新代理以使用 MCP

在這項工作，您將部署 Python Agent 程式碼，並連結至新部署的 MCP 伺服器。

請在 Gemini CLI 使用 ADK 指令，部署已更新的本機 agent.py 檔案；接著設定部署作業，指定使用在工作 3 部署的 MCP 伺服器，讓「動物園導覽員」在本機 CLI 環境運作。

產生權杖並設定 settings.json 檔案

1. 將 Google Cloud 憑證和專案編號儲存至環境變數，供 Gemini 設定檔使用：

   export PROJECT_NUMBER=$(gcloud projects describe $GOOGLE_CLOUD_PROJECT --format="value(projectNumber)") export ID_TOKEN=$(gcloud auth print-identity-token)

注意：如果在 Gemini CLI 收到驗證錯誤，可能是 ID_TOKEN 已過期。輸入 /quit 來退出，然後使用 gcloud config set project 指令設定專案。

2. 在 Cloud Shell 編輯器，依序選取「View」>「Toggle hidden files」，然後開啟或建立 ~/.gemini/settings.json 檔案來進行更新。填入下列 Gemini CLI 設定，將 Cloud Run MCP 伺服器新增至檔案：

   { "mcpServers": { "zoo-remote": { "httpUrl": "https://{{{primary_project.startup_script.mcp_server_name | filled in at lab start}}}-{{{primary_project.startup_script.project_number | filled in at lab start}}}.{{{primary_project.default_region | filled in at lab start}}}.run.app/mcp/", "headers": { "Authorization": "Bearer $ID_TOKEN" } } }, "selectedAuthType": "cloud-shell", "hasSeenIdeIntegrationNudge": true }

開啟 Gemini CLI

請按照下列步驟開啟 Gemini CLI。

1. 在終端機執行指令，啟動 Gemini CLI。

   您可能需要按下 Enter 鍵來接受部分預設設定。

2. 使用相關的斜線指令，讓 Gemini 列出在目前環境中可用的 MCP 工具。

3. 請 Gemini 找出動物園中的某種動物：

   Where can I find penguins?

   Gemini CLI 會判斷需使用 zoo-remote MCP 伺服器，並詢問您是否允許執行 MCP 工具。

4. 選擇「always allow all tools」，一律允許使用 zoo-remote MCP 伺服器中的所有工具。

   預期輸出內容：輸出內容應會顯示正確答案，以及表示已使用 MCP 伺服器的顯示方塊。

5. 按照以下格式提示 Gemini CLI，測試您建立的新自訂指令：

   /find --animal="lion"

   預期輸出內容：Gemini CLI 應會呼叫 fetch_animals_by_species 工具，並按照 MCP 提示詞的指示格式化回覆。

6. 使用相關指令或鍵盤快速鍵退出 Gemini CLI，即可結束工作階段。

驗證伺服器記錄

• 在終端機輸入下列內容，驗證伺服器記錄：

  gcloud run services logs read {{{primary_project.startup_script.mcp_server_name | filled in at lab start}}} --region {{{primary_project.default_region| filled in at lab start}}} --limit=5

  預期輸出內容：系統應會傳回確認已呼叫工具的輸出記錄。🛠️

點選「Check my progress」，確認目標已達成。 更新代理以使用 MCP 並進行驗證

工作 5：將 ADK 代理 Docker 化並部署至 Cloud Run

最後一項工作是將整個系統從本機測試環境，移至可擴充的無伺服器正式環境。

您需要將完整的 ADK 應用程式(包括 MCP 伺服器和整合 Google 搜尋功能的「動物園導覽員」代理) 容器化，然後將產生的容器映像檔部署至 Google Cloud Run。請務必將服務設為公開叫用，並確認代理在其公開網址上可正常回應。

在本機部署及測試

1. 開啟 ~/zoo_guide_agent/agent.py，查看 TODO 註解，並根據註解內容更新程式碼，完成代理設定。

2. 執行下列指令，安裝 zoo_guide_agent 套件：

   gcloud config set project {{{primary_project.project_id | filled in at lab start}}} cd ~/zoo_guide_agent python -m venv .venv source .venv/bin/activate pip install --no-cache-dir -r requirements.txt

3. 執行下列指令，在本機部署 ADK 代理：

   cd ~ adk web

4. 在 Cloud Shell 中，按住 Ctrl 鍵並點按 http://localhost:8000 或 http://127.0.0.1:8000 連結，在新瀏覽器分頁開啟 ADK 開發 UI。

5. 在 ADK 開發 UI 中，選取 zoo_guide_agent，並輸入下列查詢內容：

   Where can I find bears?

   預期輸出內容： 您應該會看到所有函式呼叫的事件記錄，以及結合所有來源資訊的查詢結果。此外，代理應會提供全球現存物種數量的估計值。

注意：彙整代理的實際回覆可能需要一些時間。

點選「Check my progress」，確認目標已達成。 在本機部署 ADK 代理

部署至 Cloud Run

• 在終端機開啟另一個終端機執行個體，然後執行下列指令來部署代理：

  cd ~/zoo_guide_agent uvx --from google-adk \ adk deploy cloud_run \ --project={{{primary_project.project_id | filled in at lab start}}} \ --region={{{primary_project.default_region| filled in at lab start}}} \ --service_name={{{primary_project.startup_script.adk_server_name | filled in at lab start}}} \ --with_ui \ . \ -- \ --labels=lab-dev=cloud-zoo-run-adk-service

uvx 指令可讓您執行以 Python 套件形式發布的指令列工具，而不需在全域安裝這些工具。

注意：部署作業平均需要 15 分鐘。如果系統詢問是否允許未經驗證的叫用，請輸入 y 來繼續操作。

點選「Check my progress」，確認目標已達成。 在 Cloud Run 部署 ADK 代理

驗證已部署的 ADK 代理

現在您的代理已在 Cloud Run 運作，請執行測試來確認是否部署成功，並驗證代理能否正常運作。請使用公開服務網址存取 ADK 的網頁介面，並與代理互動。

1. 代理成功部署至 Cloud Run 後，按住 Ctrl 鍵並點選輸出內容中的服務網址，在新瀏覽器分頁開啟。

格式應如下所示。

輸出的服務網址：

https://{{{primary_project.startup_script.adk_server_name | filled in at lab start}}}-{{{primary_project.startup_script.project_number | filled in at lab start}}}.{{{primary_project.default_region | filled in at lab start}}}.run.app/

由於您在部署至 Cloud Run 時使用了 --with_ui 旗標，因此應該會看到 ADK 開發 UI。

2. 將右上角的「詞源串流」切換為「開啟」。

3. 與動物園代理互動。輸入下列查詢，發起新對話：

   Where can I find elephants?

   預期輸出內容： 您應該會看到所有函式呼叫的事件記錄，以及結合所有來源資訊的查詢結果。此外，代理應會提供全球現存物種數量的估計值。

注意：彙整代理的實際回覆可能需要一些時間。

點選「Check my progress」，確認目標已達成。 驗證已部署的 ADK 代理

恭喜！

在本實驗室，您展現運用 Gemini CLI、Google Cloud Run 和 Cloud Build 的能力，順利設定、測試及部署了具備更強大功能的「動物園導覽員」ADK 代理。透過讓代理與專屬 MCP 伺服器和內建工具互動，您大幅提升了回應動物園遊客查詢和搜尋動物的效率，為 Cloud Creek 動物園順利完成數位轉型計畫的一環。

後續步驟/瞭解詳情

歡迎參考下列資源，進一步瞭解生成式 AI 和 Gemini Enterprise Agent Platform：

• 請參閱 Google DeepMind Gemini 模型總覽，瞭解核心模型功能。
• 如需設計、擴充及部署指南，請參閱官方 Agent Platform 說明文件。
• 請參閱 Agent Platform 的代理總覽，瞭解如何建構及管理自訂代理。
• YouTube 上的生成式 AI 播放清單提供教學影片和產品示範，歡迎多加利用。
• 前往 Google Cloud 生成式 AI 存放區，查看其他筆記本和範例。
• 如需自訂代理範本，請瀏覽 Google Agent Development Kit (ADK) 範例存放區。

Google Cloud 教育訓練與認證

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

使用手冊上次更新日期：2025 年 10 月 16 日

實驗室上次測試日期：2025 年 10 月 16 日

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