正在加载…
未找到任何结果。

在 Google Cloud 控制台中运用您的技能

Install the ADK and set up your environment

检查我的进度

/ 50

Create the API key and deploy the ADK agent

检查我的进度

/ 50

此实验可能会提供 AI 工具来支持您学习。
注意：为了确保一致且高性能的体验，此实验可能会针对某些模型请求提供缓存的响应。

GENAI124

Google Cloud 自学实验

概览

在本实验中，您将探索 Model Context Protocol (MCP)，这是一种开放标准，可实现外部服务、数据源、工具和应用之间的无缝集成。您将了解如何将 MCP 集成到智能体开发套件 (ADK) 智能体中，借助现有 MCP 服务器提供的工具来增强您的 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 与工具之间的无缝交互。

设置和要求

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

请阅读以下说明。实验是计时的，并且您无法暂停实验。计时器在您点击开始实验后即开始计时，显示 Google Cloud 资源可供您使用多长时间。

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

为完成此实验，您需要：

  • 能够使用标准的互联网浏览器（建议使用 Chrome 浏览器）。
注意：请使用无痕模式（推荐）或无痕浏览器窗口运行此实验。这可以避免您的个人账号与学生账号之间发生冲突，这种冲突可能导致您的个人账号产生额外费用。
  • 完成实验的时间 - 请注意，实验开始后无法暂停。
注意：请仅使用学生账号完成本实验。如果您使用其他 Google Cloud 账号，则可能会向该账号收取费用。

如何开始实验并登录 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 控制台中，点击右上角的激活 Cloud Shell 按钮 (激活 Cloud Shell)。
  2. 点击继续。
  3. 如果系统提示您为 Cloud Shell 授权，请点击授权。
  4. 在 Cloud Shell 终端面板的右上角，点击在新窗口中打开按钮 (“在新窗口中打开”按钮)。
  5. 点击窗格顶部的打开编辑器图标 (“修改”铅笔图标) 即可查看文件。
  6. 在左侧导航菜单顶部，点击探索器图标 (“探索器”图标) 即可打开文件资源管理器。
  7. 点击打开文件夹按钮。
  8. 在出现的“打开文件夹”对话框中，点击确定，选择学员账号的主文件夹。
  9. 关闭屏幕右侧显示的任何其他教程或 Gemini 面板，为代码编辑器留出更多窗口空间。
  10. 在本实验的其余部分，您可以在此窗口中将 Cloud Shell 编辑器和 Cloud Shell 终端用作 IDE。

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

在本部分中，您将在 Cloud Shell 终端中运行以下命令。

  1. 在 Cloud Shell 终端中运行以下命令，以便从 Cloud Storage 复制项目目录：

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

  2. 运行以下命令，安装智能体开发套件 (ADK) 以及运行示例应用所需的其他依赖项：

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

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

任务 2. 在 ADK 开发者界面中将 Google 地图 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 地图 MCP 服务器需要使用 API 密钥才能与 Google 地图服务通信。在此步骤中，您将生成一个名为 GOOGLE_MAPS_API_KEY 的新 API 密钥，并将其限制为仅可用于 Directions API 和 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 地图密钥

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

现在，您将配置智能体以使用 Google 地图工具。通过添加 MCPToolset，您可以让智能体在需要时动态发现和调用地图 API。

  1. 将以下命令粘贴到您电脑上的纯文本文件中，然后将 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=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 项目目录中，执行以下命令启动智能体开发套件开发者界面：

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

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

    Get directions from GooglePlex to SFO. 注意：如果您首次调用 API 时遇到超时问题，请点击 ADK 开发者界面右上角的 + 新建会话，然后重试。 What's the route from Paris, France to Berlin, Germany?

    输出：

    智能体回答

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

    ADK 工具调用

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

    智能体图显示了多种工具

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

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

  14. 返回 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 服务器的逻辑。查看代码，了解它是如何封装 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 服务器的客户端。此 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 ) ],

  4. 保存文件。

  5. 如需运行 MCP 服务器，请在 Cloud Shell 终端中运行以下命令，以启动 adk_server.py 脚本：

    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 项目目录中使用以下命令启动智能体开发套件开发者界面：

    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 智能体会传达此信息。您应该会在运行 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 开发工作流。

上次更新手册的时间：2026 年 4 月 21 日

上次测试实验的时间：2026 年 4 月 21 日

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

准备工作

  1. 实验会创建一个 Google Cloud 项目和一些资源，供您使用限定的一段时间
  2. 实验有时间限制，并且没有暂停功能。如果您中途结束实验，则必须重新开始。
  3. 在屏幕左上角，点击开始实验即可开始

使用无痕浏览模式

  1. 复制系统为实验提供的用户名和密码
  2. 在无痕浏览模式下，点击打开控制台

登录控制台

  1. 使用您的实验凭证登录。使用其他凭证可能会导致错误或产生费用。
  2. 接受条款，并跳过恢复资源页面
  3. 除非您已完成此实验或想要重新开始，否则请勿点击结束实验，因为点击后系统会清除您的工作并移除该项目

此内容目前不可用

一旦可用，我们会通过电子邮件告知您

太好了！

一旦可用，我们会通过电子邮件告知您

一次一个实验

确认结束所有现有实验并开始此实验

使用无痕浏览模式运行实验

使用无痕模式或无痕浏览器窗口是运行此实验的最佳方式。这可以避免您的个人账号与学生账号之间发生冲突，这种冲突可能导致您的个人账号产生额外费用。

完成此快速步骤即可开始实验。