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 实现 LLM 与工具之间的无缝交互。

设置和要求

点击“开始实验”按钮前的注意事项

请阅读以下说明。实验会以定时的方式进行，且您无法暂停实验。定时器（点击“开始实验”即可启动）会显示云资源可供您使用的时间。

Qwiklabs 实操实验可让您在真实的云环境中开展实验活动，免受模拟或演示环境的局限。为此，我们会向您提供新的临时凭据，您可以在该实验的规定时间内通过此凭据登录和访问 Google Cloud Platform。

要求

要完成此实验，您需要：

• 能够使用标准的互联网浏览器（建议使用 Chrome 浏览器）。
• 为完成实验留出时间。

注意：如果您已拥有个人 GCP 帐号或项目，请不要使用其进行此实验。

如何开始实验并登录 Google Cloud 控制台

1. 点击开始实验按钮。如果该实验需要付费，系统会打开一个对话框供您选择支付方式。左侧是“实验详细信息”窗格，其中包含以下各项：

   • “打开 Google Cloud 控制台”按钮
   • 剩余时间
   • 进行该实验时必须使用的临时凭据
   • 帮助您逐步完成本实验所需的其他信息（如果需要）

2. 点击打开 Google Cloud 控制台（如果您使用的是 Chrome 浏览器，请右键点击并选择在无痕式窗口中打开链接）。

   该实验会启动资源并打开另一个标签页，显示“登录”页面。

   提示：将这些标签页安排在不同的窗口中，并排显示。

   注意：如果您看见选择账号对话框，请点击使用其他账号。

3. 如有必要，请复制下方的用户名，然后将其粘贴到登录对话框中。

   {{{user_0.username | "<用户名>"}}}

   您也可以在“实验详细信息”窗格中找到“用户名”。

4. 点击下一步。

5. 复制下面的密码，然后将其粘贴到欢迎对话框中。

   {{{user_0.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. 在本实验的其余部分，您可以在此窗口中将 Cloud Shell 编辑器和 Cloud Shell 终端用作 IDE。

下载并安装本实验所需的 ADK 和代码示例

1. 在 Cloud Shell 终端中运行以下命令，以安装 ADK。

   注意：您需要指定版本，以确保您安装的 ADK 版本与本实验中使用的版本一致。您可以在 adk-python 代码库中查看最新版本号和版本说明。 sudo python3 -m pip install google-adk==1.5.0

2. 将以下命令粘贴到 Cloud Shell 终端中，以便从 Cloud Storage 存储桶中复制文件并将其解压缩，从而创建包含本实验代码的项目目录：

   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

点击检查我的进度，验证已完成以下目标： 安装 ADK 并设置环境

任务 2. 在 ADK 网页界面中将 Google Maps MCP 服务器与 ADK 智能体结合使用（将 ADK 作为 MCP 客户端）

本部分展示了如何将外部 Google Maps MCP 服务器中的工具集成到 ADK 智能体中。当 ADK 智能体需要使用由公开 MCP 接口的现有服务提供的功能时，这是最常见的集成模式。您将看到如何将 MCPToolset 类直接添加到智能体的 tools 列表中，从而无缝连接 MCP 服务器、发现其工具，并让这些工具可供智能体使用。这些示例主要侧重于 adk web 开发环境中的交互。

MCPToolset

MCPToolset 类是 ADK 用于集成 MCP 服务器工具的主要机制。当您将 MCPToolset 实例添加到智能体的 tools 列表时，它会自动处理与指定 MCP 服务器的交互。其工作原理如下：

• 连接管理：在初始化时，MCPToolset 会建立并管理与 MCP 服务器的连接。这可以是本地服务器进程（使用 StdioServerParameters 通过标准输入/输出进行通信），也可以是远程服务器（将 SseServerParams 用于服务器发送的事件）。当智能体或应用终止时，MCPToolset 还会处理此连接的安全关停。
• 工具发现和适配：连接后，MCPToolset 会通过 list_tools MCP 方法向 MCP 服务器查询有哪些工具可用。然后，它会将这些发现的 MCP 工具的架构转换为与 ADK 兼容的 BaseTool 实例。
• 向智能体公开：这些经过调整的工具随后会提供给您的 LlmAgent，就像它们是原生 ADK 工具一样。
• 智能体工具调用：当 LlmAgent 决定使用其中一种工具时，MCPToolset 会通过 MCP 的 call_tool 方法将调用透明地代理到 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，然后点击保存。

   

使用 MCPToolset 为 Google 地图定义智能体

在这个子部分中，您会将智能体配置为针对 Google 地图使用 MCPToolset，从而使智能体能够无缝提供路线和基于位置的信息。

1. 在 Cloud Shell 编辑器的文件资源管理器窗格中，找到 adk_mcp_tools 文件夹。点击将其打开。

2. 前往 adk_mcp_tools/google_maps_mcp_agent 目录。

3. 将以下命令粘贴到纯文本文件中，然后将 YOUR_ACTUAL_API_KEY 值更新为您在上一步中生成并保存的 Google 地图 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 项目目录中，使用以下命令启动智能体开发套件开发者界面：

   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 开发者界面。从左侧的选择智能体下拉菜单中，选择 google_maps_mcp_agent。

10. 开始与智能体对话，并运行以下提示：

    获取从 Google 总部到旧金山国际机场的路线。 注意：如果您首次调用 API 时遇到超时问题，请点击 ADK 开发者界面右上角的 + 新建会话，然后重试。 从法国巴黎到德国柏林要走什么路线？

    输出：

    

11. 点击带有闪电符号（表示函数调用）的智能体对话气泡旁的智能体图标。系统随即会打开相应事件的“事件”检查器：

    

12. 请注意，这张智能体图中显示了多个不同的工具，这些工具由扳手表情符号 (🔧) 标识。虽然您只导入了一个 MCPToolset，但该工具集附带了您在此处看到的各种工具，例如 maps_place_details 和 maps_directions。

    

13. 在请求标签页中，您可以看到该请求的结构。您可以使用事件检查器顶部的箭头来浏览智能体的思路、函数调用和回答。

14. 当您完成对该智能体的提问后，关闭开发者界面浏览器标签页。

15. 返回 Cloud Shell 终端面板，然后按 Ctrl+C 停止服务器。

点击检查我的进度以验证是否完成了以下目标： 创建 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 服务器的客户端。此 ADK 智能体将使用 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. 如需运行 MCP 服务器，请在 Cloud Shell 终端中运行以下命令，以启动 adk_server.py 脚本：

   python3 ~/adk_mcp_tools/adk_mcp_server/adk_server.py

   输出：

   

7. 点击 Cloud Shell 终端窗口顶部的 按钮，打开一个新的 Cloud Shell 终端标签页。

8. 在 Cloud Shell 终端中，从 adk_mcp_tools 项目目录中，使用以下命令启动智能体开发套件开发者界面：

   cd ~/adk_mcp_tools adk web

9. 如需在新标签页中查看网页界面，请点击终端输出中的 http://127.0.0.1:8000 链接。

10. 从左侧的选择智能体下拉菜单中，选择 adk_mcp_server。

11. 向智能体查询：

    从 https://example.com 加载内容。

    输出：

    

    具体过程：

    • ADK 智能体 (web_reader_mcp_client_agent) 使用 MCPToolset 连接到 adk_server.py。
    • MCP 服务器将收到 call_tool 请求，执行 ADK load_web_page 工具，然后返回结果。
    • 然后，ADK 智能体会中继此信息。您应该会在运行 adk_server.py 的 Cloud Shell 终端标签页中，看到来自 ADK 网页界面（及其终端）和 adk_server.py 终端的日志。

    这表明 ADK 工具可以封装在 MCP 服务器中，供各种符合 MCP 规范的客户端（包括 ADK 智能体）访问。

恭喜！

本实验结束时，您将了解如何使用 MCPToolset 类将外部 Model Context Protocol (MCP) 工具集成到 ADK 智能体中。您已了解如何连接到 MCP 服务器、在智能体中使用其工具，以及通过自定义 MCP 服务器公开 load_web_page 等 ADK 工具。借助这些技能，您可以利用强大的外部服务来扩展 ADK 智能体，从而改进 Web 开发工作流。

上次更新手册的时间：2025 年 10 月 6 日

上次测试实验的时间：2025 年 10 月 6 日

版权所有 2020 Google LLC 保留所有权利。Google 和 Google 徽标是 Google LLC 的商标。其他所有公司名和产品名可能是其各自相关公司的商标。