GENAI107

概览

在本实验中，您将学习如何将 ADK 智能体部署到 Agent Engine，以便为智能体工作流打造可伸缩的全托管式环境。

这样一来，您就可以专注于智能体的逻辑，让系统来负责基础设施的分配和伸缩。

目标

在本实验中，您将学习以下内容：

• 将智能体部署到 Agent Engine 的优势
• 如何向 Reasoning Engine Service Agent 授予所需的角色
• 如何使用 ADK 命令行界面将智能体部署到 Agent Engine
• 如何向部署到 Agent Engine 的智能体发出查询
• 如何监控已部署的智能体
• 如何删除智能体

设置和要求

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

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

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 产品和服务，请点击导航菜单，或在搜索字段中输入服务或产品的名称。

Agent Engine

Vertex AI Agent Engine（以前称为 LangChain on Vertex AI 或 Vertex AI Reasoning Engine）是一项全托管式 Google Cloud 服务，可让开发者在生产环境中部署、管理和伸缩 AI 智能体。

如需详细了解其优势，请参阅 Vertex AI Agent Engine 文档。

任务 1. 安装 ADK 并设置环境

注意：对于大多数 Qwiklabs 实验，建议使用无痕式浏览器窗口，以避免您的 Qwiklabs 学员账号与登录 Google Cloud 的其他账号出现混淆。如果您使用的是 Chrome，最简单的实现方法是关闭所有无痕式窗口，然后右键点击本实验顶部的打开 Google Cloud 控制台按钮，并选择在无痕式窗口中打开链接。

启用 Vertex AI 推荐的 API

1. 在本实验环境中，系统已为您启用 Vertex AI API。如果您要在自己的项目中执行这些步骤，则需要前往 Vertex AI，然后按照提示进行启用。

准备 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 终端中运行以下命令，更新 PATH 环境变量并安装 ADK。

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

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

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

3. 使用以下命令安装实验所需的其他组件/依赖项：

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

4. 运行以下命令，在 adk_to_agent_engine 目录中创建 .env 文件（注意：若要查看以英文句点开头的隐藏文件，您可以使用 Cloud Shell 编辑器菜单启用 View > Toggle Hidden Files [查看 > 显示/不显示隐藏文件]）：

   cd ~/adk_to_agent_engine cat << EOF > .env GOOGLE_GENAI_USE_VERTEXAI=TRUE GOOGLE_CLOUD_PROJECT={{{project_0.project_id| YOUR_GCP_PROJECT_ID}}} GOOGLE_CLOUD_LOCATION={{{project_0.default_region| GCP_LOCATION}}} MODEL=gemini-2.5-flash EOF

5. 将 .env 文件复制到智能体目录，以便在部署智能体后为其提供必要的身份验证配置：

   cp .env transcript_summarization_agent/.env

任务 2. 使用命令行部署方法部署到 Agent Engine

ADK 的命令行界面提供快捷方式，可让您轻松将智能体部署到 Agent Engine、Cloud Run 和 Google Kubernetes Engine (GKE)。您可以使用以下基本命令，将智能体部署到上述各项服务：

• adk deploy agent_engine（命令行参数请参阅 @deploy.command("agent_engine") 修饰器部分）
• adk deploy cloud_run（命令行参数请参阅 @deploy.command("cloud_run") 修饰器部分）
• adk deploy gke（命令行参数请参阅 @deploy.command("gke") 修饰器部分）

adk deploy agent_engine 命令会将智能体封装在 reasoning_engines.AdkApp 类中，并将此应用部署到 Agent Engine 的托管式运行时，使其做好接收智能体查询的准备。

将 AdkApp 部署到 Agent Engine 后，它会自动使用 VertexAiSessionService 来提供持久的托管式会话状态。这样一来，无需进行任何额外配置即可实现多轮对话记忆。对于本地测试，应用默认使用临时 InMemorySessionService。

若要使用 adk deploy agent_engine 部署 Agent Engine 应用，请完成以下步骤：

1. 在 adk_to_agent_engine/transcript_summarization_agent 目录中，点击 agent.py 文件，查看这个简单摘要智能体的指令。

2. 若要部署智能体，您必须提供相关要求。在 Cloud Shell 编辑器中，右键点击 transcript_summarization_agent 目录（您可能需要点击 Allow [允许]，才能启用右键菜单）。

3. 选择 New File...（新文件…）

4. 将文件命名为标准的 Python 要求文件，例如：requirements.txt

5. 将以下内容粘贴到文件中：

   google-cloud-aiplatform[adk,agent_engines]==1.110.0

6. 保存文件。

7. 在 Cloud Shell 终端中，运行部署命令：

   adk deploy agent_engine transcript_summarization_agent \ --display_name "Transcript Summarizer" \ --staging_bucket gs://{{{project_0.project_id| YOUR_GCP_PROJECT_ID}}}-bucket

   您可以通过命令输出中提供的日志文件链接来跟踪状态。在部署期间，系统会执行以下步骤：

   1. 在本地生成制品包，其中包含：
      • *.pkl：与 local_agent 对应的 pickle 文件。
      • requirements.txt：智能体文件夹中的此文件用于定义软件包要求。
      • dependencies.tar.gz：包含任何额外软件包的 tar 文件。
   2. 将制品包上传到 Cloud Storage（如果已指定目录，则使用定义的目录），以便暂存制品。
   3. 各个制品的 Cloud Storage URI 在 PackageSpec 中指定。
   4. Vertex AI Agent Engine 服务接收请求后，将在后端构建容器，并启动 HTTP 服务器。

   注意：部署过程大约需要 10 分钟，但您可以在部署期间继续进行本实验。

   智能体部署期间的测验

   每个 adk deploy ... 命令都需要设置某些参数。如需了解最新参数，请点击本任务顶部列表中链接的命令，然后查找标有“Required”的参数。

   某些必需的参数（例如 adk deploy agent_engine 部署中的 --project 和 --region）可以从智能体的 .env 文件（如果存在）中加载其值。

   根据 adk deploy agent_engine 的参数，回答以下问题：

   预期输出亮点：

   复制智能体源代码... 智能体源代码复制完成。 初始化 Vertex AI... [...] 创建 AgentEngine 创建支持 LRO 的 AgentEngine: projects/430282503153/locations/us-central1/reasoningEngines/2902138951282196480/operations/2777364189918789632 前往 https://console.cloud.google.com/logs/query?project=qwiklabs-gcp-04-f71a2270bd79 查看进度和日志 AgentEngine 已创建。 资源名称: projects/430282503153/locations/us-central1/reasoningEngines/2902138951282196480 如需在其他会话中使用此 AgentEngine: agent_engine = vertexai.agent_engines.get('projects/430282503153/locations/us-central1/reasoningEngines/2902138951282196480') 清理临时文件夹: /tmp/agent_engine_deploy_src/20250813_175223

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

任务 3. 获取部署到 Agent Engine 的智能体并向它发出查询

若要向智能体发出查询，您必须先授予它通过 Vertex AI 调用模型的权限。

1. 若要查看服务代理及其获分的角色，请前往控制台中的 IAM。

2. 勾选包括 Google 提供的角色授权复选框。

3. 找到 AI Platform Reasoning Engine Service Agent (service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com)，然后点击此服务代理所在行中的“修改”（铅笔）图标。

4. 点击 + 添加其他角色。

5. 在选择角色字段中，输入 Vertex AI User。如果您部署的智能体会使用工具访问其他数据，您还需要向此服务代理授予访问这些系统的权限。

6. 保存更改。

7. 回到 Cloud Shell 编辑器，在 adk_to_agent_engine 目录中，打开 query_agent_engine.py 文件。

8. 查看代码和注释，了解代码的作用。

9. 查看传递给智能体的转写文稿，以便评估智能体生成的摘要是否合适。

10. 在 Cloud Shell 终端中，使用以下命令从 adk_to_agent_engine 目录运行文件：

    cd ~/adk_to_agent_engine/transcript_summarization_agent python3 query_agent_engine.py

    输出示例（您的结果可能略有不同）：

    [远程回答] 用户想买一艘船，在被问及尺寸后，询问 5 万美元能买到多大的船。虚拟客服回答说 5 万美元可以买到“非常不错的船”，用户随即同意继续。

点击检查我的进度以验证是否完成了以下目标： 向智能体发出查询。

任务 4. 查看和删除已部署到 Agent Engine 的智能体

1. 智能体完成部署后，返回到显示 Cloud 控制台的浏览器标签页，在控制台顶部搜索并选择 Agent Engine，然后前往相应页面。

2. 在 Region（区域）下拉菜单中，确保已选择本实验指定的位置 ()。

3. 您将看到已部署智能体的显示名称。点击它即可进入其监控信息中心。

4. 请注意 Metrics（指标）和 Session（会话）这两个标签页，它们可帮助您深入了解智能体的使用情况。

5. 准备好删除智能体后，从其监控信息中心的顶部选择 Deployment details（部署详情）。

6. 返回到运行 Cloud Shell 终端的浏览器标签页，粘贴以下命令，但暂时不要运行：

   cd ~/adk_to_agent_engine python3 agent_engine_utils.py delete REPLACE_WITH_AE_ID

7. 在 Agent Engine 的 Deployment info（部署信息）面板中，复制 Name（名称）字段中的内容，其格式如下：projects/qwiklabs-gcp-02-76ce2eed15a5/locations/us-central1/reasoningEngines/1467742469964693504.

8. 返回到 Cloud Shell 终端，将命令末尾的 REPLACE_WITH_AE_ID 替换为您复制的资源名称。

9. 按 Return 键运行删除命令。

   输出示例：

   Deleting AgentEngine resource: projects/1029886909158/locations/us-central1/reasoningEngines/1456078850617245696 Delete AgentEngine backing LRO: projects/1029886909158/locations/us-central1/operations/2884525977596067840 AgentEngine resource deleted: projects/1029886909158/locations/us-central1/reasoningEngines/1456078850617245696

10. 在 Cloud 控制台中，返回到 Agent Engine 信息中心，确认智能体已删除。

11. 若要查看用于列出和删除智能体的简单 Python SDK 代码，请查看 adk_to_agent_engine/agent_engine_utils.py 文件的内容。

点击检查我的进度以验证是否完成了以下目标： 列出和删除智能体。

恭喜！

在本实验中，您学习了以下内容：

• 将智能体部署到 Agent Engine 的优势
• 如何向 Reasoning Engine Service Agent 授予所需的角色
• 如何使用 ADK 命令行界面将智能体部署到 Agent Engine
• 如何向部署到 Agent Engine 的智能体发出查询
• 如何监控已部署的智能体
• 如何删除智能体

后续步骤

如需详细了解如何使用智能体开发套件构建智能体，可以前往本系列的其他实验学习：

• 为 ADK 智能体配备工具
• 使用 ADK 构建多智能体系统
• 将 ADK 智能体部署到 Agent Engine

Google Cloud 培训和认证

…可帮助您充分利用 Google Cloud 技术。我们的课程会讲解各项技能与最佳实践，可帮助您迅速上手使用并继续学习更深入的知识。我们提供从基础到高级的全方位培训，并有点播、直播和虚拟三种方式选择，让您可以按照自己的日程安排学习时间。各项认证可以帮助您核实并证明您在 Google Cloud 技术方面的技能与专业知识。

本手册的最后更新时间：2025 年 8 月 19 日

本实验的最后测试时间：2025 年 8 月 19 日

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