Loading...
No results found.

Apply your skills in Google Cloud console

Install the ADK and set up your environment

Check my progress

/ 50

Create the API key and deploy the ADK agent

Check my progress

/ 50

This lab may incorporate AI tools to support your learning.
注意：為了確保一致且高效能的體驗，本實驗室可能會針對某些模型要求提供快取的回應。

GENAI124

Google Cloud 自學實驗室

總覽

本實驗室介紹 Model Context Protocol (MCP)，這項開放標準可完美整合外部服務、資料來源、工具和應用程式。課程內容包括如何使用現有 MCP 伺服器提供的工具，將 MCP 整合至 Agent Development Kit (ADK) 代理，強化 ADK 工作流程。此外，您也會學到如何透過自建 MCP 伺服器，公開 load_web_page 等 ADK 工具，進一步整合 MCP 用戶端。

什麼是 Model Context Protocol (MCP)？

Model Context Protocol (MCP) 是一項開放標準，可將 Gemini 和 Claude 等大型語言模型 (LLM) 與外部應用程式、資料來源和工具的通訊方式標準化。這項機制就像通用連結機制，可簡化 LLM 取得內容、執行動作，以及與各種系統互動的方式。

MCP 採用用戶端/伺服器架構，定義 MCP 伺服器如何公開資料 (資源)、互動式範本 (提示) 和可執行的函式 (工具)，以及 MCP 用戶端 (可能是 LLM 主機應用程式或 AI 代理) 如何使用這些項目。

本實驗室將介紹兩種主要整合模式：

  • 在 ADK 中使用現有的 MCP 伺服器：使用 ADK 代理做為 MCP 用戶端，運用外部 MCP 伺服器提供的工具。
  • 透過 MCP 伺服器公開 ADK 工具：建構 MCP 伺服器來包裝 ADK 工具，讓任何 MCP 用戶端都能存取。

目標

在本實驗室中，您將瞭解如何執行下列工作：

  • 使用 ADK 代理做為 MCP 用戶端，與現有 MCP 伺服器的工具互動。
  • 設定及部署您的 MCP 伺服器，向其他用戶端公開 ADK 工具。
  • 透過標準化 MCP 通訊連結 ADK 代理與外部工具。
  • 使用 MCP 讓 LLM 與工具順暢互動。

設定和需求

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

請詳閱以下操作說明。實驗室活動會計時，且中途無法暫停。點選「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 產品和服務，請點選「導覽選單」，或在「搜尋」欄位輸入服務或產品名稱。「導覽選單」圖示和搜尋欄位

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

本實驗室環境已預先為您啟用 Vertex AI API、Routes API 和 Directions API。

準備 Cloud Shell 編輯器分頁

  1. 點選 Google Cloud 控制台右上方的「啟用 Cloud Shell」按鈕圖示 啟用 Cloud Shell。
  2. 按一下「繼續」。
  3. 系統提示您授權 Cloud Shell 時，點按「授權」。
  4. 點選 Cloud Shell 終端機面板右上角的「在新視窗中開啟」按鈕 「在新視窗中開啟」按鈕。
  5. 點選窗格頂端的「開啟編輯器」圖示 「編輯」鉛筆圖示，即可查看檔案。
  6. 點選左側導覽選單頂端的「Explorer」圖示 「探索工具」圖示，開啟檔案總管。
  7. 點選「Open Folder」按鈕。
  8. 在隨即開啟的「Open Folder」對話方塊，點選「OK」，選取學員帳戶的主資料夾。
  9. 關閉畫面右側顯示的其他教學課程或 Gemini 面板，為程式碼編輯器騰出更多視窗空間。
  10. 操作這個實驗室其餘步驟時，您可以全程將這個視窗當成 IDE 使用，搭配 Cloud Shell 編輯器和 Cloud Shell 終端機作業。

下載並安裝本實驗室所需的 ADK 和程式碼範例

在本節中，您將在 Cloud Shell 終端機執行指令。

  1. 在 Cloud Shell 終端機執行以下指令，從 Cloud Storage 複製專案目錄：

    gcloud storage cp -r gs://{{{project_0.project_id| YOUR_GCP_PROJECT_ID}}}-bucket/* .

  2. 執行下列指令，安裝 Agent Development Kit (ADK)，以及執行範例應用程式所需的其他依附元件：

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

點選「Check my progress」，確認目標已達成。 安裝 ADK 並設定環境

工作 2：在 ADK 開發 UI 中，透過 ADK 代理 (ADK 做為 MCP 用戶端)，使用 Google 地圖 MCP 伺服器

本節說明如何在 ADK 代理中，整合外部 Google 地圖 MCP 伺服器的工具。如果 ADK 代理要使用現有服務提供的功能 (會公開 MCP 介面)，這就是最常見的整合模式。您會瞭解如何將 MCPToolset 類別直接新增至代理的 tools 清單，進而順暢連線至 MCP 伺服器、探索其中工具並讓代理使用。這些範例以 adk web 開發環境中的互動為主。

MCPToolset

MCPToolset 類別是 ADK 的主要機制，用於整合 MCP 伺服器的工具。在代理的 tools 清單中加入 MCPToolset 執行個體時，系統會自動處理與指定 MCP 伺服器的互動。運作方式如下：

  • 連線管理：初始化時，MCPToolset 會建立及管理與 MCP 伺服器的連線。這可以是本機伺服器程序 (使用 StdioServerParameters，透過標準輸入/輸出內容進行通訊)，也可以是遠端伺服器 (使用 SseServerParams 處理伺服器傳送事件)。當代理或應用程式終止，工具集也會安全關閉這個連線。
  • 工具探索與調整：連線後，MCPToolset 會透過 list_tools MCP 方法，向 MCP 伺服器查詢可用工具，接著將找到的 MCP 工具結構定義，轉換為與 ADK 相容的 BaseTool 執行個體。
  • 向代理公開：這些調整後的工具隨後會提供給 LlmAgent，就像是原生 ADK 工具一樣。
  • 代理工具呼叫：當 LlmAgent 決定使用其中某個工具時，MCPToolset 會透過 call_tool MCP 方法，以公開方式代理對 MCP 伺服器的呼叫作業、傳送必要引數，並將伺服器的回應傳回給代理。
  • 篩選 (選用)：建立 MCPToolset 時，您可以使用 tool_filter 參數，從 MCP 伺服器選取特定工具子集，而非向代理公開所有工具。

取得 API 金鑰並啟用 API

Google 地圖 MCP 伺服器需要 API 金鑰，才能與 Google 地圖服務通訊。在本步驟中，您將產生名為 GOOGLE_MAPS_API_KEY 的新 API 金鑰，並限制該金鑰只能用於 Directions 和 Routes API，維護安全。

  1. 前往「Google Cloud 控制台」瀏覽器分頁 (而非 Cloud Shell 編輯器)。

  2. 您可以關閉此瀏覽器分頁的 Cloud Shell 終端機窗格，騰出更多空間顯示控制台區域。

  3. 在頁面頂端的搜尋列中搜尋「憑證」，然後從搜尋結果中選取所需項目。

  4. 在「憑證」頁面上，按一下頁面頂端的「建立憑證」，然後選取「API 金鑰」。

  5. 在「名稱」部分輸入 GOOGLE_MAPS_API_KEY

  6. 在「可透過這個金鑰存取的 API」部分，選取下列 API：

    • Directions API
    • Routes API

  7. 點選「建立」。

    「已建立 API 金鑰」對話方塊會顯示新建立的 API 金鑰。請務必複製此金鑰並儲存在本機，實驗室的後續步驟會用到。

  8. 按一下對話方塊中的「關閉」。

    Google 地圖金鑰

使用 Google 地圖的 MCPToolset 定義代理

現在要設定代理來使用 Google 地圖工具。您只需新增 MCPToolset，代理就能在需要時自動探索及呼叫 Maps API。

  1. 將以下指令貼到電腦上的純文字文件中，然後將 YOUR_ACTUAL_API_KEY 值更新為您在上個步驟產生並儲存的 Google Maps API 金鑰：

    cd ~/adk_mcp_tools cat << EOF > google_maps_mcp_agent/.env GOOGLE_GENAI_USE_VERTEXAI=TRUE GOOGLE_CLOUD_PROJECT={{{project_0.project_id | Project }}} GOOGLE_CLOUD_LOCATION=global GOOGLE_MAPS_API_KEY="YOUR_ACTUAL_API_KEY" MODEL={{{project_0.startup_script.gemini_flash_model_id | gemini_flash_model_id}}} EOF

  2. 複製更新後的指令並貼到 Cloud Shell 終端機，然後執行指令來寫入 .env 檔案，提供這個代理目錄所需的驗證詳細資料。

  3. 執行下列指令，將 .env 檔案複製到本實驗室之後會用到的其他代理目錄：

    cp google_maps_mcp_agent/.env adk_mcp_server/.env

  4. 在 Cloud Shell 編輯器的檔案總管窗格中，找出 adk_mcp_tools 資料夾，然後點選並開啟資料夾。

  5. 前往 adk_mcp_tools/google_maps_mcp_agent 目錄。

  6. 開啟 agent.py，在註解 ## Add the MCPToolset (第 53 行) 後方建立新的一行，並新增以下程式碼來設定代理與 Google 地圖 MCP 伺服器的連結：

    tools=[ MCPToolset( connection_params=StdioConnectionParams( server_params=StdioServerParameters( command='npx', args=[ "-y", "@modelcontextprotocol/server-google-maps", ], env={ "GOOGLE_MAPS_API_KEY": google_maps_api_key } ), timeout=15, ), ) ],

  7. 儲存檔案。

  8. 在 adk_mcp_tools 專案目錄中，使用下列指令啟動 Agent Development Kit 開發 UI：

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

    輸出內容：

    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)

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

  10. 新的瀏覽器分頁會隨即開啟，顯示 ADK 開發 UI。在左側的「選取代理」下拉式選單中，選取「google_maps_mcp_agent」。

  11. 與代理展開對話，並執行下列提示詞：

    取得從 GooglePlex 到 SFO 的路線。 注意：如果第一次使用 API 呼叫時發生逾時，請按一下 ADK 開發 UI 右上方的「+ New Session」，然後再試一次。 從法國巴黎到德國柏林的路線為何？

    輸出內容：

    代理回覆

  12. 按一下代理圖示，這個閃電符號位於代理的聊天泡泡旁邊，代表函式呼叫。這會開啟此事件的「事件」檢查工具。

    ADK 工具呼叫

    請注意，代理圖表會顯示多種工具，並以扳手表情符號 (🔧) 標示。即使您只匯入一個 MCPToolset，該工具集也會附上您在此處看到的各種工具，例如 maps_place_details 和 maps_directions。

    代理圖表會顯示多種工具

    您可以在「事件」分頁查看要求結構，並使用「事件」檢查工具頂端的箭頭，瀏覽代理的思路、函式呼叫和回覆。

  13. 向這個代理提問完畢後，關閉開發 UI 瀏覽器分頁。

  14. 返回 Cloud Shell 終端機面板，按下 CTRL + C 鍵停止伺服器。

點選「Check my progress」，確認目標已達成。 建立 API 金鑰並部署 ADK 代理

工作 3：使用 ADK 工具建構 MCP 伺服器 (用於公開 ADK)

本節說明如何透過自建 MCP 伺服器，公開 ADK load_web_page 工具。您可以透過這個模式包裝現有的 ADK 工具，讓任何標準 MCP 用戶端應用程式都能存取。

建立 MCP 伺服器指令碼並實作伺服器邏輯

  1. 返回 Cloud Shell 編輯器分頁，然後選取 adk_mcp_tools/adk_mcp_server 目錄。

  2. 開啟名為 adk_server.py 的 Python 檔案。該檔案包含自訂 MCP 伺服器的邏輯。查看程式碼，瞭解如何包裝並提供 ADK 工具。

    請花點時間查看該檔案及閱讀註解，瞭解程式碼如何包裝工具，並以 MCP 伺服器的形式提供。留意該檔案如何讓 MCP 用戶端列出可用工具，並以非同步方式叫用 ADK 工具，依符合 MCP 的格式處理要求和回應。

使用 ADK 代理測試自訂 MCP 伺服器

  1. 開啟 adk_mcp_server 目錄中的 agent.py。

  2. 將第 31 行 PATH_TO_YOUR_MCP_SERVER_SCRIPT 的值更新為下列路徑，確保代理能連結至自訂伺服器指令碼：

    /home/{{{project_0.startup_script.updated_lab_username | Username}}}/adk_mcp_tools/adk_mcp_server/adk_server.py

  3. 接著在 agent.py 檔案中，於 第 55 行的 ## Add the MCPToolset below: 後方新增下列程式碼，將 MCPToolset 新增至代理。ADK 代理會做為 MCP 伺服器的用戶端，並使用 MCPToolset 連結至 adk_server.py 指令碼。

    tools=[ MCPToolset( connection_params=StdioConnectionParams( server_params=StdioServerParameters( command="python3", # Command to run your MCP server script args=[PATH_TO_YOUR_MCP_SERVER_SCRIPT], # Argument is the path to the script ), timeout=15, ), tool_filter=['load_web_page'] # Optional: ensure only specific tools are loaded ) ],

  4. 儲存檔案。

  5. 在 Cloud Shell 終端機執行下列指令，啟動 adk_server.py 指令碼來執行 MCP 伺服器：

    python3 ~/adk_mcp_tools/adk_mcp_server/adk_server.py

    輸出內容：

    MCP 伺服器

  6. 點選 Cloud Shell 終端機視窗頂端的 add-session-button 按鈕，開啟新的 Cloud Shell 終端機分頁。

  7. 在 Cloud Shell 終端機中執行下列指令，從 adk_mcp_tools 專案目錄啟動 Agent Development Kit 開發 UI：

    export PATH=$PATH:"/home/${USER}/.local/bin" cd ~/adk_mcp_tools adk web --allow_origins "regex:https://.*.cloudshell.dev" --otel_to_cloud --reload_agents 注意：這段指令加入 `PATH` 以重設路徑。如果直接執行其餘指令而未包含此部分內容，新的 Cloud Shell 終端機可能傳回錯誤訊息，通常會是找不到 `adk web` 錯誤。

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

  9. 在左側的「選取代理」下拉式選單中，選取「adk_mcp_server」。

  10. 對代理下達以下提示詞：

    Load the content from http://example.com.

    輸出內容：

    代理回覆

    後續情形：

    • ADK 代理 (web_reader_mcp_client_agent) 會使用 MCPToolset 連結至 adk_server.py。
    • MCP 伺服器會收到 call_tool 要求、執行 ADK load_web_page 工具，並傳回結果。
    • 接著 ADK 代理會轉發這項資訊。您應會在執行工具的 Cloud Shell 終端機分頁中，看到 ADK 網頁 UI (和其終端機)，以及 adk_server.py 終端機的記錄。

    這表示 ADK 工具可封裝在 MCP 伺服器中，供各種符合 MCP 的用戶端 (包括 ADK 代理) 存取。

恭喜！

在本實驗室中，您學到如何使用 MCPToolset 類別，將外部 Model Context Protocol (MCP) 工具整合至 Agent Development Kit (ADK) 代理。此外，您還瞭解了如何連線至 MCP 伺服器、在代理中使用伺服器工具，以及透過自訂 MCP 伺服器公開 load_web_page 等 ADK 工具。這些技能可幫助您透過強大的外部服務擴充 ADK 代理，提高網頁程式開發工作流程效率。

使用手冊上次更新日期：2026 年 4 月 21 日

實驗室上次測試日期：2026 年 4 月 21 日

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

Before you begin

  1. Labs create a Google Cloud project and resources for a fixed time
  2. Labs have a time limit and no pause feature. If you end the lab, you'll have to restart from the beginning.
  3. On the top left of your screen, click Start lab to begin

Use private browsing

  1. Copy the provided Username and Password for the lab
  2. Click Open console in private mode

Sign in to the Console

  1. Sign in using your lab credentials. Using other credentials might cause errors or incur charges.
  2. Accept the terms, and skip the recovery resource page
  3. Don't click End lab unless you've finished the lab or want to restart it, as it will clear your work and remove the project

This content is not currently available

We will notify you via email when it becomes available

Great!

We will contact you via email if it becomes available

One lab at a time

Confirm to end all existing labs and start this one

Use private browsing to run the lab

Using an Incognito or private browser window is the best way to run this lab. This prevents any conflicts between your personal account and the Student account, which may cause extra charges incurred to your personal account.

Complete this quick step to start your lab.