GENAI124

總覽

本實驗室將介紹 Model Context Protocol (MCP)，這項開放標準可完美整合外部服務、資料來源、工具和應用程式。您將瞭解如何使用現有 MCP 伺服器提供的工具，將 MCP 整合至 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 代理與外部工具。
• 使用 Model Context Protocol，讓大型語言模型與工具順暢互動。

設定和需求

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

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

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

需求條件

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

• 可以使用標準的網際網路瀏覽器 (Chrome 瀏覽器為佳)。
• 已預留充足時間可完成實驗室。

注意：如果您擁有個人 Google Cloud 或專案，請勿用於本實驗室。

注意：如果您使用的是 Pixelbook，請在無痕視窗執行本實驗室。

如何開始研究室及登入 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 控制台視窗，然後在鍵盤上依序按下 G 和 S 鍵，開啟 Cloud Shell。或者點選 Cloud 控制台右上方的「啟用 Cloud Shell」按鈕 ()。

2. 按一下「繼續」。

3. 看到授權 Cloud Shell 的提示時，點選「授權」。

4. 在 Cloud Shell 終端機面板的右上角，按一下「在新視窗中開啟」按鈕 。

5. 在 Cloud Shell 終端機中輸入下列指令，開啟 Cloud Shell 編輯器並前往主目錄：

   cloudshell workspace ~

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

7. 操作本實驗室剩餘步驟時，您可以全程將這個視窗當成 IDE 使用，搭配 Cloud Shell 編輯器和 Cloud Shell 終端機作業。

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

1. 在 Cloud Shell 終端機中執行下列指令，安裝 ADK。

   注意：您需要指定版本，確保安裝的 ADK 版本與本實驗室所用者相符。您可以在 adk-python 存放區中查看最新版本號碼和版本資訊。 sudo python3 -m pip install google-adk==1.5.0

2. 將下列指令貼到 Cloud Shell 終端機，從 Cloud Storage bucket 複製檔案並解壓縮，建立本實驗室所需的程式碼專案目錄：

   gcloud storage cp gs://{{{project_0.project_id| YOUR_GCP_PROJECT_ID}}}-bucket/adk_mcp_tools.zip . unzip adk_mcp_tools.zip

3. 使用下列指令安裝其他實驗室所需項目：

   python3 -m pip install -r adk_mcp_tools/requirements.txt

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

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

本節說明如何將外部 Google 地圖 MCP 伺服器的工具整合至 ADK 代理。如果 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_MAPS_API_KEY 的新 API 金鑰。

1. 開啟顯示 Google Cloud 控制台的瀏覽器分頁 (而非 Cloud Shell 編輯器)。

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

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

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

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

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

   新建立的金鑰名稱預設為 API Key 1。請選取金鑰，將其重新命名為 GOOGLE_MAPS_API_KEY，然後按一下「儲存」。

   

使用 Google 地圖的 MCPToolset 定義代理

在本小節中，您要將代理設為使用 Google 地圖的 MCPToolset，順暢提供路線和地點專屬資訊。

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

2. 前往 adk_mcp_tools/google_maps_mcp_agent 目錄。

3. 將下列指令貼到純文字檔中，然後將 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={{{ project_0.default_region | Region}}} GOOGLE_MAPS_API_KEY="YOUR_ACTUAL_API_KEY" MODEL={{{project_0.startup_script.gemini_flash_model_id | gemini_flash_model_id}}} EOF

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

5. 執行下列指令，將 .env 檔案複製到您將在本實驗室使用的其他代理目錄：

   cp google_maps_mcp_agent/.env adk_mcp_server/.env

6. 接著，在 agent.py 檔案中加入下列程式碼，將 Google 地圖工具新增至代理。這樣一來，代理就能使用 Google 地圖的 MCPToolset 提供路線或位置資訊。

   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. 在 adk_mcp_tools 專案目錄中，使用下列指令啟動 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)

8. 點按終端機輸出內容中的 http://127.0.0.1:8000 連結，即可在新分頁中查看網頁介面。

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

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

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

    輸出內容：

    

11. 按一下代理圖示，也就是代理的聊天泡泡旁的閃電符號，代表函式呼叫。這麼做會開啟該事件的「事件」檢查器：

    

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

    

13. 您可以在「Request」分頁中查看要求結構，並使用事件檢查器頂端的箭頭，瀏覽代理的想法、函式呼叫和回應。

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

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

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

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

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

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

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

2. 系統已為您準備名為 adk_server.py 的 Python 檔案，並加上註解。請花點時間查看該檔案及閱讀註解，瞭解程式碼如何包裝工具，並將其做為 MCP 伺服器來提供。留意該檔案如何讓 MCP 用戶端列出可用工具，並以非同步方式叫用 ADK 工具，依符合 MCP 的格式處理要求和回應。

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

3. 點選 adk_mcp_server 目錄中的 agent.py 檔案。

4. 更新 adk_server.py 檔案的路徑。

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

5. 接著，在 agent.py 檔案中加入下列程式碼，將 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 ) ],

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

   python3 ~/adk_mcp_tools/adk_mcp_server/adk_server.py

   輸出內容：

   

7. 點選 Cloud Shell 終端機視窗頂端的 按鈕，開啟新的 Cloud Shell 終端機分頁。

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

   cd ~/adk_mcp_tools adk web

9. 點按終端機輸出內容中的 http://127.0.0.1:8000 連結，即可在新分頁中查看網頁介面。

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

11. 使用下列內容查詢代理：

    Load the content from https://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) 工具整合至 ADK 代理。您已瞭解如何連線至 MCP 伺服器、在代理中使用伺服器工具，以及透過自訂 MCP 伺服器公開 load_web_page 等 ADK 工具。這些技能可幫助您透過強大的外部服務擴充 ADK 代理，提高網頁程式開發工作流程效率。

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

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

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