GSP1350

概览

在本实验中，您将重点练习使用智能体开发套件 (ADK) 实现和部署客户端智能体服务，以构建使用 MCP 服务器等远程工具的 AI 智能体。本实验中体现的关键架构原则是关注点分离，即通过安全的 API，让不同的推理层（智能体）与不同的工具层（MCP 服务器）进行通信。

在本实验中，我们为您预部署了一个 MCP 服务器，该服务器可为 LLM 提供有关虚构动物园中动物的数据，例如当您使用 Gemini CLI 时就会用到它。在本实验中，您将为虚构的动物园构建一个导游智能体，该智能体由一个 Python 应用组成。该智能体使用 MCP 服务器访问有关动物园内动物的详细信息，并使用维基百科来为游客打造优秀的游玩体验。

这个导游智能体不只是在本地运行，为了让动物园的所有游客都可以访问，您最后要把它部署到 Google Cloud Run。

前提条件

• 在 Cloud Run 上运行的 MCP 服务器或关联的服务网址。
• 启用了结算功能的 Google Cloud 项目。

学习内容

在本实验中，您将学习如何执行以下任务：

• 构建一个 Python 项目，用于部署 ADK。
• 使用 google-adk 实现一个使用工具的智能体。
• 将智能体连接到远程 MCP 服务器以获取其工具集。
• 将 Python 应用作为无服务器容器部署到 Cloud Run。
• 使用 IAM 角色配置安全的服务间身份验证。
• 删除 Cloud 资源，避免以后产生费用。

所需条件

• Google Cloud 账号和 Google Cloud 项目
• 网络浏览器，例如 Chrome

为何要部署到 Cloud Run？

Cloud Run 是托管 ADK 智能体的绝佳选择，因为它是一个无服务器平台，这意味着您可以专注于代码，而无需亲自管理底层基础设施。Cloud Run 会为您处理运维工作。

您可以将其想象成一家快闪店：只在客户（请求）上门时开门营业并使用资源。没有顾客时，它会完全关闭，您无需为空店支付费用。

Cloud Run 的主要功能

在任何地方运行容器

• 您需要提供一个包含应用的容器（Docker 映像）。
• Cloud Run 会在 Google 的基础设施上运行该容器。
• 不用负责为操作系统打补丁、设置虚拟机或扩缩。

自动扩缩

• 如果没有人在使用您的应用 → 运行 0 个实例（空闲时，您无需支付任何费用）。
• 如果有 1,000 个请求发送到该服务 → 它会根据需要启动相应数量的副本。

默认为无状态

• 每个请求都可以发送到不同的实例。
• 如果需要存储状态，请使用 Cloud SQL、Firestore 或 Redis 等外部服务。

支持任何编程语言或框架

• 只要能在 Linux 容器中运行，Cloud Run 就不在乎它是 Python、Go、Node.js、Java 还是 .Net。

用多少，付多少

• 按请求次数 + 计算时间（精确到 100 毫秒）结算。
• 您无需像使用传统虚拟机那样为闲置资源付费。

设置和要求

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

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

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

为完成此实验，您需要：

• 能够使用标准的互联网浏览器（建议使用 Chrome 浏览器）。

注意：请使用无痕模式（推荐）或无痕浏览器窗口运行此实验。这可以避免您的个人账号与学生账号之间发生冲突，这种冲突可能导致您的个人账号产生额外费用。

• 完成实验的时间 - 请注意，实验开始后无法暂停。

注意：请仅使用学生账号完成本实验。如果您使用其他 Google Cloud 账号，则可能会向该账号收取费用。

激活 Cloud Shell

Cloud Shell 是一种装有开发者工具的虚拟机。它提供了一个永久性的 5GB 主目录，并且在 Google Cloud 上运行。Cloud Shell 提供可用于访问您的 Google Cloud 资源的命令行工具。

1. 点击 Google Cloud 控制台顶部的激活 Cloud Shell 。

2. 在弹出的窗口中执行以下操作：

   • 继续完成 Cloud Shell 信息窗口中的设置。
   • 授权 Cloud Shell 使用您的凭据进行 Google Cloud API 调用。

如果您连接成功，即表示您已通过身份验证，且项目 ID 会被设为您的 Project_ID 。输出内容中有一行说明了此会话的 Project_ID：

Your Cloud Platform project in this session is set to {{{project_0.project_id | "PROJECT_ID"}}}

gcloud 是 Google Cloud 的命令行工具。它已预先安装在 Cloud Shell 上，且支持 Tab 自动补全功能。

3. （可选）您可以通过此命令列出活跃账号名称：

gcloud auth list

4. 点击授权。

输出：

ACTIVE: * ACCOUNT: {{{user_0.username | "ACCOUNT"}}} To set the active account, run: $ gcloud config set account `ACCOUNT`

5. （可选）您可以通过此命令列出项目 ID：

gcloud config list project

输出：

[core] project = {{{project_0.project_id | "PROJECT_ID"}}} 注意：如需查看在 Google Cloud 中使用 gcloud 的完整文档，请参阅 gcloud CLI 概览指南。

任务 1. 下载并安装 ADK，然后创建项目文件夹

在此任务中，您将启用相关 API 并创建一个项目文件夹，用于存储 Python 项目部署的源代码。

启用 API 并设置环境变量

1. 在 Cloud Shell 中，点击 Open Editor（打开编辑器），以打开 Cloud Shell Editor 并进入主目录。
2. 在 Cloud Shell Editor 操作栏中，点击 View（查看）> Terminal（终端）。

注意：您可能需要拉长浏览器窗口才能看到“View”（视图）菜单选项。

在本实验的后续操作中，您可将此窗口作为集成了 Cloud Shell Editor（顶部）和 Cloud Shell 终端（底部）的 IDE 使用。

关闭屏幕右侧显示的其他教程或 Gemini 面板，以便为代码编辑器留出更大的窗口空间。

3. 在终端中输入以下命令来设置项目：

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

   预期输出： 您应该会收到一条输出消息，确认属性已更新。

注意：如果 Cloud Shell 超时或重启，您需要重新设置项目。

4. 运行以下命令以启用所有必需的服务。

   gcloud services enable \ run.googleapis.com \ artifactregistry.googleapis.com \ cloudbuild.googleapis.com \ aiplatform.googleapis.com \ compute.googleapis.com

   预期输出： 您应该会收到一条输出消息，确认操作已成功。

点击检查我的进度以验证是否完成了以下目标： 启用 API

创建项目目录

1. 执行以下命令，在实验中创建一个用于存放智能体源代码的主文件夹：

   mkdir zoo_guide_agent && cd zoo_guide_agent

2. 接下来，运行以下命令来创建虚拟环境：

   uv venv

3. 运行以下命令来激活虚拟环境：

   source .venv/bin/activate

现在，您可以创建 requirements.txt 文件了。此文件列出了动物园导游智能体需要使用的 Python 库。

4. 运行以下命令，在 zoo_guide_agent 目录中创建该文件，并在 Cloud Shell Editor 中启动该文件，以便进行编辑：

   cloudshell edit requirements.txt

5. 将以下内容添加到 requirements.txt 文件，然后按 CTRL+S 保存更改：

   google-adk==1.12.0 langchain-community wikipedia

6. 在终端中运行以下命令，让 uv 软件包管理器安装 Python 软件包：

   uv pip install -r requirements.txt

7. 使用以下命令为当前项目、区域和用户设置变量：

   export PROJECT_ID=$(gcloud config get-value project) export REGION=$(gcloud compute project-info describe \ --format="value(commonInstanceMetadata.items[google-compute-default-region])") export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)") export SERVICE_ACCOUNT="${PROJECT_NUMBER}-compute@developer.gserviceaccount.com"

注意：如果 Cloud Shell 超时或重启，您需要重新初始化上述变量。

8. 运行以下命令，在 zoo_guide_agent 目录中创建并打开 .env 文件，用于对智能体进行身份验证：

   cloudshell edit .env

Cloud Shell Editor 中会打开包含 .env 文件的目录。

9. 将以下内容添加到 .env 文件并保存更改：

   MODEL="{{{ project_0.startup_script.gemini_flash_model_id | filled in at lab start }}}" SERVICE_ACCOUNT="${PROJECT_NUMBER}-compute@developer.gserviceaccount.com"

连接到安全的 MCP 服务器端点

在本部分中，您将与远程 MCP 服务器建立连接。

1. 返回 Cloud Shell 终端，运行以下命令，为 Cloud Run 服务授予调用远程 MCP 服务器的权限：

   gcloud projects add-iam-policy-binding $PROJECT_ID \ --member="serviceAccount:$SERVICE_ACCOUNT" \ --role="roles/run.invoker"

2. 运行以下命令，将 MCP 服务器网址保存到环境变量中：

   echo -e "\nMCP_SERVER_URL=https://zoo-mcp-server-${PROJECT_NUMBER}.${REGION}.run.app/mcp/" >> .env

3. 接下来，创建 __init__.py 文件。这个文件会告诉 Python，zoo_guide_agent 目录是一个软件包：

   cloudshell edit __init__.py

4. 在打开的 Cloud Shell Editor 中，将以下代码添加到 __init__.py 并保存更改：

   from . import agent

任务 2. 创建智能体工作流

在此任务中，您将配置动物园导游智能体的工作流。首先，您需要导入相关库以进行初始设置。然后，您定义动物园智能体的功能（它使用的工具），并定义专业智能体。然后，您定义工作流智能体，最后组合主工作流。

创建主 agent.py 文件

• 返回 Cloud Shell 终端，运行以下命令来创建主 agent.py 文件。该文件会在 Cloud Shell Editor 中打开，以便您在后续步骤中粘贴多智能体系统的完整代码：

  cloudshell edit agent.py

第 1 步：导入库并执行初始设置

第一个代码块会引入 ADK 和 Google Cloud 中的所有必要库。它还会设置日志记录，并从 .env 文件加载环境变量，这对于访问模型和服务器网址至关重要。

• 将以下代码添加到 agent.py 文件中：

  import os import logging import google.cloud.logging from dotenv import load_dotenv from google.adk import Agent from google.adk.agents import SequentialAgent from google.adk.tools.mcp_tool.mcp_toolset import MCPToolset, StreamableHTTPConnectionParams from google.adk.tools.tool_context import ToolContext from google.adk.tools.langchain_tool import LangchainTool from langchain_community.tools import WikipediaQueryRun from langchain_community.utilities import WikipediaAPIWrapper import google.auth import google.auth.transport.requests import google.oauth2.id_token # --- Setup Logging and Environment --- cloud_logging_client = google.cloud.logging.Client() cloud_logging_client.setup_logging() load_dotenv() model_name = os.getenv("MODEL")

第 2 步：定义工具（智能体的功能）

智能体是否优秀取决于它能使用的工具。在本部分中，您将定义智能体的所有功能，包括用于保存数据的自定义函数、连接到安全 MCP 服务器的 MCP 工具，以及维基百科工具。

• 将以下代码添加到 agent.py 的底部：

  # Greet user and save their prompt def add_prompt_to_state( tool_context: ToolContext, prompt: str ) -> dict[str, str]: """Saves the user's initial prompt to the state.""" tool_context.state["PROMPT"] = prompt logging.info(f"[State updated] Added to PROMPT: {prompt}") return {"status": "success"} # Configuring the MCP Tool to connect to the Zoo MCP server mcp_server_url = os.getenv("MCP_SERVER_URL") if not mcp_server_url: raise ValueError("The environment variable MCP_SERVER_URL is not set.") def get_id_token(): """Get an ID token to authenticate with the MCP server.""" target_url = os.getenv("MCP_SERVER_URL") audience = target_url.split('/mcp/')[0] request = google.auth.transport.requests.Request() id_token = google.oauth2.id_token.fetch_id_token(request, audience) return id_token """ # Use this code if you are using the public MCP Server and comment out the code below defining mcp_tools mcp_tools = MCPToolset( connection_params=StreamableHTTPConnectionParams( url=mcp_server_url ) ) """ mcp_tools = MCPToolset( connection_params=StreamableHTTPConnectionParams( url=mcp_server_url, headers={ "Authorization": f"Bearer {get_id_token()}", }, ), ) # Configuring the Wikipedia Tool wikipedia_tool = LangchainTool( tool=WikipediaQueryRun(api_wrapper=WikipediaAPIWrapper()) )

这三种工具的说明

• add_prompt_to_state：📝此工具用于记录动物园游客提出的问题。当访客问“狮子在哪里？”时，此工具会将这个问题保存到智能体的记忆中，以便工作流中的其他智能体知道要研究的对象。

  运作方式：这是一个 Python 函数，用于将游客的提示写入共享的 tool_context.state 目录。此工具上下文表示智能体在单次对话中的短期记忆。一个智能体保存到状态的数据可以被工作流中的下一个智能体读取。

• MCPToolset：🦁用于将导游智能体连接到本实验中预先部署的动物园 MCP 服务器。该服务器提供了一些专门的工具，可用于查找动物园内动物的特定信息，例如名称、年龄和位置。

  运作方式：它能安全地连接到动物园的专用服务器网址。它使用 get_id_token 自动获取安全的“钥匙卡”（服务账号 ID 令牌），以证明其身份并获得访问权限。

• LangchainTool：🌍它为导游智能体提供了常识信息。如果访客提出的问题不在动物园的数据库中，例如“狮子在野外吃什么？”，此工具可让智能体在维基百科上查找答案。

  运作方式：它充当适配器，让您的智能体可以使用 LangChain 库中预构建的 WikipediaQueryRun 工具。

资源：

• MCP 工具集
• 函数工具
• 状态

第 3 步：定义专业智能体

在本部分中，您将定义两个专业智能体：研究智能体和回答格式化智能体。研究智能体相当于整套操作的“大脑”。此智能体从共享的 State 中获取用户提示，检查其强大的工具（Zoo 的 MCP 服务器工具和维基百科工具），并决定使用哪些工具来查找答案。

回答格式化智能体的作用是呈现回答。它不使用任何工具来查找新信息，而是接收研究智能体收集的原始数据（通过状态传递），并利用 LLM 的语言技能将其转换为方便用户理解的对话式回答。

• 将以下代码添加到 agent.py 的底部：

  # 1. Researcher Agent comprehensive_researcher = Agent( name="comprehensive_researcher", model=model_name, description="The primary researcher that can access both internal zoo data and external knowledge from Wikipedia.", instruction=""" You are a helpful research assistant. Your goal is to fully answer the user's PROMPT. You have access to two tools: 1. A tool for getting specific data about animals AT OUR ZOO (names, ages, locations). 2. A tool for searching Wikipedia for general knowledge (facts, lifespan, diet, habitat). First, analyze the user's PROMPT. - If the prompt can be answered by only one tool, use that tool. - If the prompt is complex and requires information from both the zoo's database AND Wikipedia, you MUST use both tools to gather all necessary information. - Synthesize the results from the tool(s) you use into preliminary data outputs. PROMPT: {{ PROMPT }} """, tools=[ mcp_tools, wikipedia_tool ], output_key="research_data" # A key to store the combined findings ) # 2. Response Formatter Agent response_formatter = Agent( name="response_formatter", model=model_name, description="Synthesizes all information into a friendly, readable response.", instruction=""" You are the friendly voice of the Zoo Tour Guide. Your task is to take the RESEARCH_DATA and present it to the user in a complete and helpful answer. - First, present the specific information from the zoo (like names, ages, and where to find them). - Then, add the interesting general facts from the research. - If some information is missing, just present the information you have. - Be conversational and engaging. RESEARCH_DATA: {{ research_data }} """ )

第 4 步：定义工作流智能体

工作流智能体充当动物园导游的“后台”管理员。它会接收研究请求，并确保您在第 3 步中定义的两个智能体按正确的顺序各司其职：先研究，再给出格式化回答。它为回答动物园游客的问题制定了一个可预测且可靠的过程。

运作方式：这是一个 SequentialAgent，是一种不会独立思考的特殊代理。它唯一的任务就是按固定顺序运行 sub_agents（研究智能体和回答格式化智能体）列表，并自动将共享内存从一个智能体传递到下一个智能体。

• 将以下代码块添加到 agent.py 的底部：

  tour_guide_workflow = SequentialAgent( name="tour_guide_workflow", description="The main workflow for handling a user's request about an animal.", sub_agents=[ comprehensive_researcher, # Step 1: Gather all data response_formatter, # Step 2: Format the final response ] )

第 5 步：组合主工作流

主工作流通过 root_agent 指定，ADK 框架会将其用作所有新对话的起点。这个智能体的首要角色是编排整个流程。它充当初始控制器，管理第一轮对话。

• 将下面的最后一段代码添加到 agent.py 的底部，并保存更改：

  root_agent = Agent( name="greeter", model=model_name, description="The main entry point for the Zoo Tour Guide.", instruction=""" - Let the user know you will help them learn about the animals we have in the zoo. - When the user responds, use the 'add_prompt_to_state' tool to save their response. After using the tool, transfer control to the 'tour_guide_workflow' agent. """, tools=[add_prompt_to_state], sub_agents=[tour_guide_workflow] )

您的 agent.py 文件现已完成！

通过以这种方式构建智能体，您可以了解每个组件（工具、工作器智能体和管理器智能体）在创建最终智能系统中的具体作用。接下来是部署！

任务 3. 准备应用以进行部署

本地环境准备就绪后，下一步是为动物园导游智能体的部署准备 Google Cloud 项目。

您需要对智能体的文件结构进行最后检查，以确保其与部署命令兼容。更重要的是，您配置要一项关键的 IAM 权限，允许已部署的 Cloud Run 服务代表您调用 Vertex AI 模型。完成此步骤可确保云环境已准备好成功运行您的智能体。

1. 返回 Cloud Shell 终端，运行以下命令，将变量加载到 shell 会话中：

   source .env

2. 运行以下命令，向服务账号授予 Vertex AI User 角色，使其有权进行预测并调用 Google 的模型：

   # Grant the "Vertex AI User" role to your service account gcloud projects add-iam-policy-binding $PROJECT_ID \ --member="serviceAccount:$SERVICE_ACCOUNT" \ --role="roles/aiplatform.user"

任务 4. 使用 ADK CLI 部署智能体

本地代码已准备就绪，Google Cloud 项目也已准备好，现在可以部署智能体了。

在此任务中，您将使用 adk deploy cloud_run 命令，这是一个方便的工具，可自动执行整个部署工作流。只需一个命令，它就能打包代码、构建容器映像、将其推送到 Artifact Registry，并在 Cloud Run 上启动服务，使其可通过网络访问。

部署智能体

1. 运行以下命令以部署智能体：

   # Run the deployment command adk deploy cloud_run \ --project=$PROJECT_ID \ --region=$REGION \ --service_name=zoo-tour-guide \ --with_ui \ .

2. 如果看到提示，询问您是否继续，和/或是否允许未经身份验证就调用 [zoo-tour-guide]，请输入 Y，然后按 Enter 键。

注意：此部署命令可能需要 5–10 分钟才能完成运行。

3. 运行以下命令来修改现有 Cloud Run 服务的配置设置：

   gcloud run services update zoo-tour-guide \ --region=$REGION \ --update-labels=dev-tutorial=codelab-adk

获取部署链接

• 成功将代理部署到 Cloud Run 后，按住 Ctrl 键并点击输出中的服务网址，在新的浏览器标签页中打开该网址。

  网址格式应该与下面的网址相似。 服务网址输出：

  https://zoo-tour-guide-{{{project_0.startup_script.project_number | filled in at lab start}}}.{{{project_0.default_region | filled in at lab start}}}.run.app

由于您在部署到 Cloud Run 时使用了 --with_ui 标志，因此您应该会看到 ADK 开发者界面。

注意：获取到该网址的任何人都可以访问此智能体，因此建议只将这种方法用于测试目的。

点击检查我的进度以验证是否完成了以下目标： 部署智能体

任务 5. 测试已部署的智能体

现在，您的智能体已在 Cloud Run 上运行。在此任务中，您将执行一项测试，以确认部署成功且智能体按预期工作。您需要使用公开的服务网址来访问 ADK 的 Web 界面并与智能体互动。

1. 在 Web 浏览器中打开上一个任务中输出的公开 Cloud Run 服务网址，或点击输出中的网址（该网址应在新浏览器标签页中打开）。这样就可以进入 ADK 开发者界面。

2. 在 ADK 工具栏的右上角，将 Token Streaming（令牌流式传输）切换为 On（开启）。

现在，您可以与动物园导游智能体互动了。

3. 在提示框中输入 hello，然后按 Enter 键开始新对话。

   观察结果。智能体应快速回复标准问候语：

   "Hello! I'm your Zoo Tour Guide. I can help you learn about the amazing animals we have here. What would you like to know or explore today?"

4. 现在，与动物园导游智能体互动。输入以下查询，开始新对话：

   Where can I find penguins?

   您应该会看到如下所示的回答：

   

智能体工作流详解

您的系统可以像一个睿智的多智能体团队一样运作。整个过程由清晰的顺序管理，确保从用户提问到得到最终详细回答的整个流程顺畅高效。

1. 动物园接待员（接待处）

整个过程的第一步是接待员智能体。

任务：开始与游客对话。它要向游客问好，并询问游客想要了解哪种动物。

工具：当用户回复时，接待员智能体使用 add_prompt_to_state 工具来采集用户的确切措辞（例如 “tell me about the lions”（给我介绍一下狮子）并将其保存在系统内存中。

移交：保存提示后，它会立即将控制权移交给其子智能体 tour_guide_workflow。

2. 综合研究智能体（超级研究员智能体）

这是主工作流中的第一步，也是整个操作的“大脑”。现在，您不再需要庞大的团队，只需一个能够访问所有相关信息的专业智能体。

任务：分析用户的问题并确定回答问题的方案。它利用语言模型强大的工具使用功能来决定是否需要：

• 来自动物园记录的内部数据（通过 MCP 服务器）。
• 来自网络（通过 Wikipedia API）的一般性知识。
• 或者，对于复杂的问题，两者都使用。

操作：执行必要的工具，以收集所有必需的原始数据。例如，如果游客问到“动物园里的狮子几岁了？它们在野外吃什么？”，它会调用 MCP 服务器来获取狮子的年龄信息，并调用维基百科工具来获取狮子的进食习性信息。

3. 回答格式化智能体（演示者）

在综合研究智能体收集完所有事实后，回答格式化智能体是要运行的最后一个智能体。

工作：充当动物园导游。它会获取原始数据（可能来自一个或两个来源）并进行优化。

行动：它将所有信息整合到一个连贯且有趣的回答中。按照提示，它首先介绍动物园的具体信息，然后添加一些有趣的事实。

最终结果：这个智能体生成的文本就是用户在聊天窗口中看到的完整且详细的答案。

后续步骤/了解详情

如果您有兴趣详细了解如何构建智能体，请查看以下资源：

• ADK 文档
• 为 ADK 智能体构建自定义工具

任务 6. 清理环境

在此任务中，您将删除在本实验中创建的 Cloud 资源，以避免以后产生费用。

• 返回 Cloud Shell 终端标签页并运行以下命令：

  gcloud run services delete zoo-tour-guide --region=$REGION --quiet gcloud artifacts repositories delete cloud-run-source-deploy --location=$REGION --quiet

恭喜！

在本实验中，您探索了如何使用 ADK 命令行界面构建要部署的 Python 项目，实现了多智能体工作流，连接了远程 MCP 服务器（目的是使用其工具），集成了 Wikipedia API 等外部工具（作为对内部数据的补充），并将智能体作为无服务器容器部署到了 Cloud Run。

本手册的最后更新时间：2025 年 10 月 13 日

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

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