GENAI104

概览：智能体开发套件的优势

对于构建代理式应用的开发者，智能体开发套件具有以下几项关键优势：

1. 多智能体系统：通过分层组合多个专业智能体来构建模块化且可伸缩的应用，实现复杂的协调和委托。
2. 丰富的工具生态系统：赋予智能体多种功能，包括使用预构建工具（搜索、代码执行等）、创建自定义函数、整合第三方智能体框架的工具（LangChain、CrewAI），甚至调用其他智能体作为工具。
3. 灵活的编排：使用工作流智能体（SequentialAgent、ParallelAgent 和 LoopAgent）为可预测的流水线定义工作流，或利用 LLM 驱动的动态路由（LlmAgent 转移）实现自适应行为。
4. 集成式开发者体验：使用强大的 CLI 和交互式开发者界面，在本地开发、测试和调试，并分步检查事件、状态及智能体执行情况。
5. 内置评估：通过将最终回答质量和分步执行轨迹与预定义测试用例对比，系统地评估智能体性能。
6. 可随时部署：将智能体容器化并部署至任意环境 - 本地运行、使用 Vertex AI Agent Engine 扩缩，或通过 Cloud Run 或Docker 集成到自定义基础设施。

虽然其他生成式 AI SDK 或智能体框架也允许您查询模型，甚至为模型添加工具功能，但在多个模型之间实现动态协调仍需您完成大量工作。

智能体开发套件提供了比这些工具更高级的框架，使您可以轻松地将多个智能体互相连接，从而实现复杂但易维护的工作流。

此外，您可以将这些复杂的智能体系统部署到 Agent Engine 中的全托管式端点，以便专注于智能体逻辑，而系统会负责基础设施的分配与扩缩。

目标

在本实验中，您将创建一个可以使用搜索工具的单智能体，并通过 ADK 的浏览器界面、CLI 聊天界面以及从脚本中以编程方式进行测试。

您将学习以下内容：

• 智能体开发套件的主要功能
• ADK 的核心概念
• 如何为 ADK 构建项目目录结构
• ADK 中智能体的最基本参数，包括如何指定模型名称和工具
• ADK 浏览器界面的一些功能
• 如何控制智能体的输出架构
• 如何以三种方式（通过浏览器界面、以编程方式和通过 CLI 聊天界面）运行智能体

设置和要求

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

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

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 并设置环境

注意：对于大多数 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。注意：您需要指定版本，以确保您安装的 ADK 版本与本实验中使用的版本一致：

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

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

   gcloud storage cp gs://{{{project_0.project_id| YOUR_GCP_PROJECT_ID}}}-bucket/adk_project.zip ./adk_project.zip unzip adk_project.zip

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

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

智能体开发套件的核心概念

Google ADK 基于以下几个核心概念构建，因此功能强大且灵活：

• 智能体：智能体是旨在完成特定任务的核心智能模块，可通过 LLM 提供推理、规划和利用工具实现目标的能力，甚至可协作完成复杂项目。
• 工具：工具可让智能体执行对话之外的操作，例如与外部 API 互动、搜索信息、运行代码或调用其他服务。
• 会话服务：会话服务处理单个对话 (Session) 的上下文，包括其历史记录 (Events) 和智能体在该对话中的工作内存 (State)。
• 回调：您提供的自定义代码段，可在智能体流程中的特定时间点运行，从而实现检查、日志记录或行为修改。
• 制品管理：制品允许智能体保存、加载和管理与会话或用户关联的文件或二进制数据（例如图片或 PDF）。
• Runner：负责管理执行流程、根据事件编排智能体互动并与后端服务协调的引擎。

任务 2. 查看智能体开发套件项目目录的结构

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

2. 此目录包含另外三个目录：my_google_search_agent、app_agent 和 llm_auditor。每个目录都代表一个单独的智能体。将智能体分别放置在项目目录中各自相应的目录内有助于整理项目，并让智能体开发套件了解存在哪些智能体。

3. 点击 my_google_search_agent 即可浏览智能体目录。

4. 请注意，该目录包含 __init__.py 文件和 agent.py 文件。__init__.py 文件通常用于将目录标识为可供其他 Python 代码导入的 Python 软件包。点击 init.py 文件查看其内容。

5. 请注意，__init__.py 文件包含一行从 agent.py 文件中导入的代码。ADK 用它将此目录标识为智能体软件包：

   from . import agent

6. 现在，点击 agent.py 文件。此文件包含一个简单的智能体。您将为它添加一个强大的工具：使用 Google 搜索在网络上进行搜索。此文件有几点需要注意：

   • 注意从 google.adk 导入的内容：Agent 类和 tools 模块中的 google_search 工具
   • 阅读代码注释，了解配置此简单智能体所用的参数。

7. 若要使用导入的 google_search 工具，需要将其传递给智能体。为此，请将以下代码行粘贴到 agent.py 文件中 Agent 对象创建完毕时所指示的位置：

   tools=[google_search]

8. 保存文件。

借助工具，智能体可以执行生成文本以外的操作。在本例中，google_search 工具可让智能体自己判断什么时候需要更多信息，而不是只依赖它已有的训练数据。然后，它可以撰写搜索查询，使用 Google 搜索来搜索网络内容，并根据搜索结果向用户提供回答。当模型根据检索到的额外信息生成回答时，这称为“接地”，而整个过程称为“检索增强生成”，简称“RAG”。

如需详细了解如何在 ADK 中使用工具，请参考实验“为 ADK 智能体配备工具”。

任务 3. 使用 ADK 的开发者界面运行智能体

ADK 包含一个旨在本地运行的开发者界面，可帮助您开发和测试智能体。它有助于您直观地了解每个智能体在做什么，以及多个智能体之间的互动情况。在此任务中，您将探索这个界面。

当您运行智能体时，ADK 需要知道是谁在请求模型 API 调用。您可以通过以下两种方式之一提供此信息。您可以：

1. 提供 Gemini API 密钥。
2. 使用 Google Cloud 凭证对环境进行身份验证，并将模型 API 调用与 Vertex AI 项目和位置相关联。

在本实验中，您将采用 Vertex AI 方法。

1. 在 Cloud Shell 编辑器菜单中，选择 View > Toggle Hidden Files，以查看或隐藏您的隐藏文件（在大多数文件系统中，文件名开头带有英文句点的文件默认处于隐藏状态）。您可能需要在该菜单中向下滚动才能找到“Toggle Hidden Files”选项。

2. 在 Cloud Shell 编辑器的文件资源管理器窗格中，前往 adk_project/my_google_search_agent 目录。

3. 选择 my_google_search_agent 目录中的 .env 文件。

4. 用这些值覆盖文件中的现有内容，以更新文件并包含您的项目 ID：

   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

5. 保存文件。

这些变量的作用如下：

• GOOGLE_GENAI_USE_VERTEXAI=TRUE 表示您将使用 Vertex AI 进行身份验证，而不是使用 Gemini API 密钥进行身份验证。
• GOOGLE_CLOUD_PROJECT 和 GOOGLE_CLOUD_LOCATION 提供模型调用关联的项目和位置。
• MODEL 不是必需项，但存储在此处可作为另一个环境变量加载。这为在不同部署环境中尝试不同模型提供了便利。

当您使用 ADK 的开发者界面或命令行聊天界面测试智能体时，它们会加载并使用智能体的 .env 文件（如有），否则会查找与此处设置的名称相同的环境变量。

6. 在 Cloud Shell 终端中，运行以下命令，确保您位于智能体子目录所在的 adk_project 目录中：

   cd ~/adk_project

7. 使用以下命令启动智能体开发套件开发者界面：

   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 链接，该链接会通过代理将您链接到在 Cloud Shell 实例上本地运行的此应用。

9. 系统随即会打开一个新的浏览器标签页，其中包含 ADK 开发者界面。

10. 在左侧的 Select an agent 下拉菜单中，选择 my_google_search_agent。

    

11. 为了鼓励智能体使用其 Google 搜索工具，请输入以下问题：

    What is some recent global news?

12. 从结果中可以看出，智能体能够使用 Google 搜索获取最新信息，而不是仅限于其模型训练日期之前的信息。

    使用“依托 Google 搜索进行接地”的回答包含可直接显示的 HTML“搜索建议”，就像您在智能体的回答底部看到的那样。使用“依托 Google 搜索进行接地”时，您必须显示这些建议，以便用户跟进模型用于生成回答的信息。

13. 请注意，在左侧边栏中，您默认位于 Trace 标签页中。点击您上次的查询文本 (What is some recent global news?)，查看查询不同部分执行耗时的跟踪信息。您可以利用这些信息调试涉及工具调用的更复杂执行过程，从而了解各环节对回答延迟的影响。

    

14. 点击智能体的回答（或 Events 标签页上列表中的事件）旁边的智能体图标 ()，即可检查智能体返回的事件，其中包括返回给用户的 content 以及详细说明回答所依据的搜索结果的 groundingMetadata。

15. 浏览完开发者界面后，关闭此浏览器标签页，然后返回到包含 Cloud Shell 终端的浏览器标签页，点击终端的窗格，然后按 Ctrl + C 以停止 Web 服务器。

点击检查我的进度以验证是否完成了以下目标：使用 ADK 的网页界面运行智能体。

任务 4. 以编程方式运行智能体

虽然开发者界面非常适合测试和调试，但并不适合在生产环境中向多位用户展示智能体。

如需将智能体作为较大应用的一部分运行，您需要在 agent.py 脚本中加入一些额外组件，而这些组件在之前的任务中由 Web 应用为您处理。请继续执行以下步骤，打开包含这些组件的脚本进行查看。

1. 在 Cloud Shell 终端中，运行以下命令以导出环境变量。如果智能体目录中没有 .env 文件，您可以使用此方法设置环境变量供所有智能体使用：

   export GOOGLE_GENAI_USE_VERTEXAI=TRUE export GOOGLE_CLOUD_PROJECT={{{project_0.project_id| YOUR_GCP_PROJECT_ID}}} export GOOGLE_CLOUD_LOCATION={{{project_0.default_region| GCP_LOCATION}}} export MODEL=gemini-2.5-flash

2. 在 Cloud Shell 编辑器文件浏览器中，选择 adk_project/app_agent 目录。

3. 选择此目录中的 agent.py 文件。

4. 此智能体旨在作为应用的一部分运行。阅读 agent.py 中的注释代码，并特别注意代码中的以下组件：

   组件	功能	说明
   InMemoryRunner()	监督智能体执行	Runner 代码负责接收用户查询、将其传递给相应智能体、接收智能体的回答事件并将其传回调用应用或界面，然后触发后续事件。如需了解详情，请参阅关于事件循环的 ADK 文档。
   runner.session_service.create_session()	对话记录和共享状态	会话可让智能体保留状态，并记住一系列内容、任务的当前状态或其他“当前”信息。此类会创建一个本地会话服务以简化操作，但在生产环境中，这可以由数据库来处理。
   types.Content() 和 types.Part()	结构化多模态消息	智能体接收的不再是简单字符串，而是 Content 对象，该对象可包含多个 PARTS。这样就可以按特定顺序将复杂的消息（包括文本和多模态内容）传递给智能体。

当您在开发者界面中运行智能体时，它会为您创建会话服务、制品服务和 Runner。如果您编写自己的智能体并以编程方式部署，建议您将这些组件作为外部服务提供，而不是依赖于内存版本。

5. 请注意，该脚本包含一个硬编码查询，询问智能体："What is the capital of France?"

6. 在 Cloud Shell 终端中运行以下命令，以编程方式运行此智能体：

   python3 app_agent/agent.py

   所选输出结果：

   trivia_agent: The capital of France is Paris.

7. 您还可以为智能体定义特定的输入和/或输出架构。

   现在，您将为 Pydantic 架构类 BaseModel 和 Field 添加导入项，并使用它们定义一个仅包含一个字段的架构类，该字段的键为“capital”，值为字符串，用于存储国家/地区的首都/首府名称。您可以将这些行粘贴到 app_agent/agent.py 文件中，紧跟在其他导入项之后：

   from pydantic import BaseModel, Field class CountryCapital(BaseModel): capital: str = Field(description="A country's capital.") 重要提示：定义输出架构时，不能使用工具或智能体转移。

8. 在 root_agent 的 Agent 定义中，添加以下参数以停用转移（使用输出架构时必须这样做），并将输出设置为根据您在上面定义的 CountryCapital 架构生成：

   disallow_transfer_to_parent=True, disallow_transfer_to_peers=True, output_schema=CountryCapital,

9. 再次运行智能体脚本，查看 output_schema 之后的回答：

   python3 app_agent/agent.py

   所选输出结果：

   ** User says: {'parts': [{'text': 'What is the capital of France?'}], 'role': 'user'} ** trivia_agent: {"capital": "Paris"}

点击检查我的进度以验证是否完成了以下目标：以编程方式运行智能体。

任务 5. 通过命令行界面与智能体对话

您还可以使用命令行界面在本地开发环境中与智能体对话。这对于在开发智能体时快速调试和测试智能体非常方便。

与网页界面一样，命令行界面也会处理智能体的会话服务、制品服务和 Runner 的创建。

如需使用命令行界面运行交互式会话，请执行以下操作：

1. 在 Cloud Shell 终端中运行以下命令：

   adk run my_google_search_agent

   输出结果：

   Log setup complete: /tmp/agents_log/agent.20250322_010300.log To access latest log: tail -F /tmp/agents_log/agent.latest.log Running agent basic_search_agent, type exit to exit. user:

2. 输入以下消息：

   what are some new movies that have been released in the past month in India?

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

   [google_search_agent]: Here are some movies that have been released in India in the past month (August-September 2025): * **Param Sundari** Released on 29 August 2025. * **Ek Chatur Naar** Released on 12 September 2025. * **Jolly LLB 3** Released on 19 September 2025. * **Ajey: The Untold Story of a Yogi** Released on 19 September 2025. * **Antha 7 Naatkal** Released on Sep 25 2025.

3. 在命令行界面中完成对话后，在下一个用户提示符处输入 exit 以结束对话。

点击检查我的进度以验证是否完成了以下目标：通过命令行界面与智能体对话。

任务 6. 预览多智能体示例

您将在实验“使用 ADK 构建多智能体系统”中详细了解如何构建多智能体系统，但由于多智能体功能是智能体开发套件体验的核心，因此您可以立即探索一个多智能体系统。

此智能体系统可评估和改进 LLM 生成的回答的事实依据。它包括：- critic_agent，用作自动事实核查工具 - reviser_agent，用于根据经过验证的发现结果在需要时重写回答，以纠正不准确之处

如需探索此智能体，请执行以下操作：

1. 如需探索此多智能体系统的代码，请使用 Cloud Shell 编辑器的文件资源管理器进入 adk_project/llm_auditor 目录。

2. 在 llm_auditor 目录中，选择 agent.py 文件。

3. 以下是有关此多智能体示例的一些注意事项：

   • 注意 SequentialAgent 类的导入和使用。这是一个工作流类示例，它按顺序将对话控制权从一个智能体传递到下一个智能体，而无需等待用户在中间进行额外的输入。运行智能体时，您会看到 critic_agent 和 reviser_agent（按此顺序）的回答，而无需等待用户输入。
   • 请注意，这些子智能体分别是从 sub_agents 目录中各自的相应目录导入的。
   • 在子智能体的目录中，您会看到 __init__.py 和 agent.py 文件（与您之前在目录结构中浏览的文件类似），以及一个 prompt.py 文件。prompt.py 文件提供了一个专用位置，用来存储和修改完整而结构清晰的提示，然后再将其导入到 agent.py 文件中。

4. 为此智能体创建 .env 文件，然后在 Cloud Shell 终端中运行以下命令，再次启动开发者界面：

   cd ~/adk_project cat << EOF > llm_auditor/.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 adk web 注意：如果您未关闭之前的 adk web 会话，默认端口 8000 将被屏蔽，但您可以通过新端口启动开发者界面，例如使用 adk web --port 8001。

5. 点击终端输出中的 http://127.0.0.1:8000 链接。系统随即会打开一个新的浏览器标签页，其中包含 ADK 开发者界面。

6. 从左侧的 Select an agent 下拉菜单中，选择 llm_auditor。

7. 以下面的虚假陈述开始对话：

   Double check this: Earth is further away from the Sun than Mars.

8. 您应该会在对话区域中看到智能体的两个回答：

   • 首先，critic_agent 会给出详细的回答，对用户提供的陈述进行事实核查，并基于 Google 搜索结果判断其真实性。
   • 其次，reviser_agent 会返回一个简短的修正版本，用以纠正之前的错误陈述，例如“Earth is closer to the Sun than Mars”。

9. 在每个回答旁边，点击智能体图标 () 可打开相应回答的事件面板（或者在“事件”面板中找到相应编号的事件并选择它）。事件视图顶部有一个图表，直观显示了此多智能体系统中各智能体和工具之间的关系。负责生成此回答的智能体将被突出显示。

10. 您可以随意进一步探索代码，也可以在开发者界面中尝试其他事实核查示例。比如，您可以尝试以下示例：

    Q: Why is the sky blue? A: Because the sky reflects the color of the ocean.

11. 如果您想重置对话，请使用 ADK 开发者界面右上角的 + New Session 链接重新开始对话。

12. 完成与此智能体的对话后，关闭浏览器标签页，然后在终端中按 Ctrl+C 以停止服务器。

人机协同 (human-in-the-loop) 模式

虽然此示例使用了 SequentialAgent 工作流智能体，但您可以将此模式理解为人机协同 (human-in-the-loop) 模式。当 SequentialAgent 结束其序列时，对话会返回到其父级（在本例中为 llm_auditor），以获取用户的新输入，然后再将对话传回其他智能体继续处理。

点击检查我的进度以验证是否完成了以下目标：预览多智能体示例。

恭喜！

在本实验中，您学习了：

• 智能体开发套件的主要功能
• ADK 的核心概念
• 如何为 ADK 构建项目目录结构
• ADK 中智能体的最基本参数，包括如何指定模型名称和工具
• ADK 浏览器界面的一些功能
• 如何控制智能体的输出架构
• 如何以三种方式（通过浏览器界面、以编程方式和通过 CLI 聊天界面）运行智能体

后续步骤

如需详细了解如何使用智能体开发套件构建和部署智能体，请查看以下实验：

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

如需详细了解 ADK，请参阅以下文档和 GitHub 代码库：

• 智能体开发套件文档智能体开发套件
• adk-docs GitHub 代码库 adk-docs

Google Cloud 培训和认证

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

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

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

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