GENAI129

得分：您必须获得 80% 或更高的分数，才能通过此实验室挑战赛。

概览

在本实验中，您需要展示以下能力：使用智能体开发套件 (ADK) 编写智能体、将其部署到 Agent Engine，并最终在 Web 应用中调用这些智能体。

目标

在本实验中，您将执行以下操作：

• 使用智能体开发套件 (ADK) 构建由根智能体和子智能体组成的智能体
• 使用 Vertex AI Search 工具和自定义函数工具为智能体赋能
• 将智能体输出存储在会话状态中，并从会话状态中检索值以用于后续智能体指令
• 将智能体部署到 Agent Engine
• 向部署到 Agent Engine 的智能体发出查询请求

相关学习资料

如果您正在寻找资源来掌握顺利完成本实验所需的技能，建议参考以下内容的相关部分：

类别	资源
课程	- 使用智能体开发套件 (ADK) 和 Agent Engine 部署多智能体系统
学习实验室	- 智能体开发套件 (ADK) 入门 - 为 ADK 智能体配备工具 - 使用 ADK 构建多智能体系统 - 将 ADK 智能体部署到 Agent Engine - 使用 AI Applications 构建 Vertex AI Search 应用

设置和要求

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

请阅读以下说明。实验是计时的，并且您无法暂停实验。计时器在您点击开始实验后即开始计时，显示 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 产品和服务，请点击导航菜单，或在搜索字段中输入服务或产品的名称。

挑战场景

Cymbal Shops 是一家总部位于明尼阿波利斯的美国连锁零售店，经营范围涵盖家居用品、电子产品和服装。

Cymbal Shops 已将业务拓展到欧洲，并增设了油漆部门。该公司计划利用其全新的在线平台，简化 DIY 家装项目的油漆选购流程。

您的一位同事已经开始开发一个名为 Paint Agent 的智能体，旨在帮助用户：

• 根据 Cymbal Shops 的油漆产品数据表选择油漆产品
• 从所选产品线中选择颜色
• 根据房间尺寸确定所需油漆用量
• 根据所选选项计算价格

然而，您的一位同事在处理一个 bug 时遇到了瓶颈，且现已离职。

现在，您是 Cymbal Shops 的新任机器学习工程师。您的任务是完成 Paint Agent 的部署工作。该智能体的结构如下所示：

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

在本实验环境中，我们已为您启用了 Vertex AI API。如果您在自己的项目中操作，则可前往 Vertex AI 页面，然后按照提示启用该 API。

准备 Cloud Shell 编辑器标签页

1. 点击 Google Cloud 控制台标题栏中的激活 Cloud Shell ()。

   注意：您也可以选择控制台浏览器标签页，然后按 G 键再按 S 键，打开 Cloud Shell 终端。

2. 点击继续。

3. 如果系统提示您为 Cloud Shell 授权，请点击授权。

4. 在 Cloud Shell 终端面板的右上角，点击在新窗口中打开按钮 。

5. 点击窗格顶部的打开编辑器铅笔图标 () 即可查看文件。

6. 在左侧导航菜单顶部，点击“资源管理器”图标 () 即可打开文件资源管理器。

7. 点击打开文件夹按钮。

8. 在出现的“打开文件夹”对话框中，点击确定，选择 Qwiklab 学员账号的主文件夹。

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

10. 在本实验的其余部分，您可以在此窗口中将 Cloud Shell 编辑器和 Cloud Shell 终端用作 IDE。

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

1. 将以下命令粘贴到 Cloud Shell 终端中，以从 Cloud Storage 存储桶中复制文件，从而创建一个包含本实验代码的项目目录：

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

2. 在 Cloud Shell 终端中运行以下命令，以更新 PATH 环境变量并安装 ADK 和其他实验依赖项。

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

任务 2. 创建 AI Applications 搜索应用，用于搜索油漆产品信息

在此任务中，您需要部署 AI Applications 数据存储区。此数据存储区将导入一个描述 Cymbal Shops 油漆产品的数据表（您可以开启无痕式窗口，在新的标签页中预览该文件，网址为 https://storage.cloud.google.com/-bucket/Cymbal_Shops_Paint_Datasheets.pdf）。回应用户的油漆相关查询时，该数据表将用作接地数据源。

1. 按照以下配置创建一个 AI Applications 数据存储区：

   字段	值
   数据源	Cloud Storage
   数据类型	文档
   文件夹或文件	文件
   要导入的文件	-bucket/Cymbal_Shops_Paint_Datasheets.pdf
   位置	全局
   数据存储区名称	Cymbal Paint
   文档解析器	布局解析器
   启用表格注解	已启用
   将祖先标题纳入分块中	已启用

2. 按照以下配置创建一个 AI Applications 搜索应用：

   字段	值
   应用类型	自定义搜索（常规）
   应用名称	Paint Search
   公司名称	Cymbal Shops
   位置	全局
   数据存储区	Cymbal Paint

3. 将以下命令复制到文本文件中。将 SEARCH_ENGINE_ID 的值从 YOUR_ID 更新为您刚刚创建的搜索引擎的 ID（其格式类似于：paint-search_1756...，可在 AI Applications 的应用列表中找到）：

   cd ~/adk_challenge_lab 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}}} RESOURCES_BUCKET={{{project_0.project_id| YOUR_GCP_PROJECT_ID}}}-bucket MODEL={{{project_0.startup_script.gemini_flash_model_id | gemini_flash_model_id}}} SEARCH_ENGINE_ID=YOUR_ID EOF

4. 在 Cloud Shell 终端中运行您修改后的命令，以创建包含模型身份验证和配置变量的 .env 文件。[注意：若要查看隐藏文件（以英文句点开头的文件），您可以使用 Cloud Shell 编辑器菜单启用 View > Toggle Hidden Files（查看 > 显示/不显示隐藏文件）]

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

   cp .env paint_agent/.env

点击检查我的进度以验证是否完成了以下目标： 创建数据存储区和搜索应用。

任务 3. 调试 Paint Agent

您的一位同事已经开始开发 Paint Agent，但遇到了瓶颈。您需要接手同事未完成的工作，包括修复其遗留的 bug，从而完成并部署该智能体。

1. 在 Cloud Shell 终端中，使用以下命令来运行当前版本的智能体：

   adk run paint_agent

2. 当出现 [user]: 提示时，输入：

   hello

   如果智能体接着询问您是否想进一步了解 Cymbal Shops 的油漆产品，请回复：

   yes

   输出内容的结尾应为：

   ... google.genai.errors.ClientError: 400 INVALID_ARGUMENT. {'error': {'code': 400, 'message': 'Multiple tools are supported only when they are all search tools.', 'status': 'INVALID_ARGUMENT'}}

   在接下来的步骤中，您需要解决这个错误。

3. 打开 adk_challenge_lab/paint_agent/agent.py 文件，检查 root_agent 所用子智能体和工具的列表。请注意，其中包含子智能体。转移到子智能体时，会调用隐式 transfer_to_agent 工具。

4. 由于 root_agent 本身并未配备搜索工具，因此必须由至少一个子智能体来调用搜索工具。探索 sub_agents 目录中的子智能体，找到所使用的搜索工具（在本例中为 VertexAiSearchTool）：

5. 虽然智能体不支持将搜索工具与其他非搜索工具结合使用（即便像本例这样在子智能体中嵌套使用也不行），但 ADK 提供了一个名为 AgentTool 的工具，它可以将使用搜索工具的独立智能体封装起来。这样一来，这个“智能体即工具”便可以与其他工具协同使用了。

   返回到 root_agent 的文件 adk_challenge_lab/paint_agent/agent.py，将 AgentTool() 添加到 root_agent 的工具列表中。为 AgentTool() 提供以下参数：

   • agent 应设置为使用您在上面发现的搜索工具的子智能体。
   • skip_summarization 应设置为 False，因为您希望智能体报告搜索工具返回的内容。

6. 从 sub_agents 列表中移除该子智能体。

7. 保存文件。

注意：只有在创建数据存储区并将文档编入索引后，才能继续执行后续操作。您可以进入 AI Applications > 数据存储区 > Cymbal Paint 数据存储区，在文档标签页中监控此状态。

在实际应用中，如果在其状态显示为“就绪”后再多等待几分钟，然后再查询智能体，您将能获得更可靠的输出结果。

8. 在 Cloud Shell 终端中，使用以下命令再次运行智能体：

   adk run paint_agent

   现在，您应该可以与该智能体聊天并获取有关 Cymbal Shops 油漆的信息了。

9. 让智能体告诉您 EcoGreens 和 Forever Paint 油漆的价格。

   点击检查我的进度，验证已完成了以下目标： 调试智能体。

10. 通过命令行界面与智能体完成对话后，输入 exit 结束对话。

任务 4. 保存并利用共享状态

您的 root_agent 从 adk_challenge_lab/paint_agent/tools.py 导入并使用 set_session_value 工具，但该工具尚未完全实现。

1. 更新 adk_challenge_lab/paint_agent/tools.py 文件中的 set_session_value 函数，以将 key-value 键值对存储在 ToolContext 的 state 状态字典中。

2. 更新函数的响应，以返回状态消息 f"stored '{value}' in '{key}'"。

3. 打开与 coverage_calculator_agent（room_planner 的子智能体，而 room_planner 是 root_agent 的子智能体）关联的 agent.py 文件。

4. 请注意，其指令没有从状态字典中正确加载值。更新指令，将全部大写的术语替换为使用 ADK 的键模板将状态值加载到指令中。

5. 使用以下命令测试智能体：

   adk web --allow_origins "regex:https://.*\.cloudshell\.dev"

6. 选择 paint_agent。

7. 现在，您应该可以与智能体进行以下对话了：

   您	智能体回答
   hello	[主动表示愿意分享 Cymbal Shops 油漆的相关信息]
   yes	[分享油漆产品信息，例如 Project Paint、EcoGreens、SureCoverage、Forever Paint。]
   I'd like to use EcoGreens	[状态标签页应显示更新后的状态值。询问房间数量以及每个房间的名称。]
   Just one room, my office	[让您为办公室选择颜色。]
   Deep Ocean	[询问房间尺寸。]
   3m by 4m. 3m high. 1 door, 2 windows.	[确认涂层数量。]
   Two coats.	[计算得出，您需要覆盖 74 平方米的面积。]

8. 与智能体完成对话后，您可以关闭开发者界面浏览器标签页。

   点击检查我的进度，验证已完成了以下目标： 设置和利用会话状态

9. 选择 Cloud Shell 终端面板，然后按 Ctrl+C 关闭服务器。

任务 5. 部署到 Agent Engine

1. 在 Cloud Shell 终端中，确保您位于 adk_challenge_lab 目录中：

   cd ~/adk_challenge_lab

2. 使用以下参数，以适当的部署命令将 paint_agent 部署到 Agent Engine：

   参数	参数值
   --display_name	"Paint Agent"
   --staging_bucket	gs://-bucket

3. 在智能体部署过程中，向 Vertex AI Reasoning Engine Service Agent 授予 Vertex AI User 和 Discovery Engine User IAM 角色。

4. 请注意，部署完成后，已部署智能体的资源名称会输出到控制台。

   点击检查我的进度以验证是否完成了以下目标： 部署到 Agent Engine

任务 6. 向已部署的智能体发出查询请求

1. 在 adk_challenge_lab/chainlit_ui/app.py 文件中，找到以下行并将其更新为已部署智能体的资源名称，以加载您的远程智能体：

   agent = client.agent_engines.get(name='YOUR_AGENT_RESOURCE_NAME')

2. 使用以下命令来运行界面：

   cd ~/adk_challenge_lab/chainlit_ui chainlit run app.py

   预期输出：

   2025-08-25 12:30:00 - Your app is available at http://localhost:8000

3. 点击 http://localhost:8000 链接，在新的浏览器标签页中打开它。

4. 与已部署的智能体进行以下对话：

   您	智能体回答
   hello	[主动表示愿意分享 Cymbal Shops 油漆的相关信息]
   yes	[分享油漆产品信息，例如 Project Paint、EcoGreens、SureCoverage、Forever Paint]
   I'd like to use Forever Paint	[询问房间数量以及每个房间的名称]
   Two rooms. The living room and a baby's room.	[让您为各个房间选择颜色。]
   "Sunlight through a canvas tent" for the baby's room and "Coffee Cream" for the living room.	[询问房间尺寸]
   The living room is 5m by 4m. 2.5m high. 1 door, 3 windows.	[询问涂层数量。]
   Two coats.	[请求提供婴儿房的尺寸。]
   The baby's room is 3m by 3m. 2.5m high. 1 door, 1 window.	[提供单涂层的估算用量，并确认涂层数量。]
   Always two coats.	[计算得出，您需要覆盖 77 平方米的客厅面积和 53 平方米的婴儿房面积。]

5. 如果您想与智能体开始新的对话，可以点击左上角的图标创建新对话。

   点击检查我的进度以验证是否完成了以下目标： 配置前端以向智能体发出查询请求

恭喜！

在本实验中，您已：

• 使用智能体开发套件 (ADK) 构建了一个由根智能体和子智能体组成的智能体
• 使用 Vertex AI Search 工具和自定义函数工具为智能体赋能
• 将智能体输出存储在会话状态字典中，并从会话状态字典中检索值以用于后续智能体指令
• 将智能体部署到 Agent Engine
• 向部署到 Agent Engine 的智能体发出查询请求

Google Cloud 培训和认证

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

上次更新手册的时间：2026 年 2 月 26 日

上次测试实验的时间：2026 年 2 月 26 日

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