使用 ADK 构建 AI 智能体：基础知识

1. 准备工作

欢迎学习“使用 ADK 构建 AI 智能体”系列的第一部分！在此实践 Codelab 系列中，您将踏上激动人心的旅程，使用 Google 的智能体开发套件 (ADK) 创建自己的智能 AI 智能体。

我们将从最基本的知识入手，引导您设置开发环境并打造基础的对话代理。完成本 Codelab 后，您将构建出自己的第一个互动式 AI，并可在本系列的后续部分中对其进行扩展，将其转换为复杂的多代理系统 (MAS)。

您可以在本地环境或 Google Cloud 上完成此 Codelab。为了获得最一致的体验，我们建议您使用 Google Cloud 环境中的 Cloud Shell。Cloud Shell 还会在 $HOME 目录中提供 5 GB 的永久性存储空间。这对于存储脚本、配置文件或克隆的代码库非常有用。

前提条件

学习内容

  • 如何设置 Python 环境
  • 如何使用 ADK 创建简单的个人助理智能体
  • 如何运行、测试和调试代理

所需条件

  • 一台可正常运行的计算机和稳定的 Wi-Fi 连接
  • 浏览器（例如 Chrome），用于访问 Google Cloud 控制台
  • 启用了结算功能的 Google Cloud 项目
  • 好奇心和学习热情

2. 简介

生成式 AI (GenAI) 领域正在快速发展，而 AI 智能体目前是一个热门话题。AI 代理是一种智能计算机程序，旨在代表您执行操作，就像个人助理一样。它无需直接的人工控制，即可感知数字环境、做出决策并采取行动来实现特定目标。您可以将其视为一种主动的自主实体，能够通过学习和适应来完成任务。

从根本上讲，AI 智能体使用大语言模型 (LLM) 作为其“大脑”来理解和推理。这使得它能够处理来自各种来源的信息，例如文本、图片和声音。然后，智能体利用这种理解来制定计划并执行一系列任务，以实现预定义的目标。

现在，即使您没有深厚的专业知识，也可以轻松构建自己的 AI 智能体，这得益于智能体开发套件 (ADK) 等现成可用的框架。我们将从构建一个可帮助您完成任务的个人助理代理开始这段旅程。我们开始吧！

3. 设置 Google Cloud 服务

创建 Google Cloud 项目

此 Codelab 假设您已创建一个启用了结算功能的 Google Cloud 项目。如果您还没有项目，请按照以下步骤创建一个：

选择或创建 Google Cloud 项目

  • 前往 Google Cloud 控制台。
  • 点击顶部的项目选择器下拉列表（位于 Google Cloud 徽标旁边）
  • 选择现有项目或创建新项目。

启用结算功能

  • 确保您选择的 Google Cloud 项目已启用结算功能。
  • 您可以按照 Google Cloud 结算文档中的说明了解如何检查项目是否已启用结算功能。

配置 Cloud Shell

现在，我们来确保您已在 Cloud Shell（Google Cloud 控制台中直接提供的便捷命令行界面）中正确设置。

启动 Cloud Shell

在 Google Cloud 控制台的右上角，您会看到一个看起来像终端的图标 (>_)。点击该图标即可激活 Cloud Shell。

8e234ad9973e49d4.png

授予访问权限

如果系统提示，请点击授权，以向 Cloud Shell 授予与您的 Google Cloud 项目互动的必要权限。

d5e271ec814f5769.png

验证您的账号：

Cloud Shell 加载完毕后，我们来确认您使用的是正确的 Google Cloud 账号。运行以下命令：

gcloud auth list

您应该会在终端中看到类似的命令输出：

Credentialed Accounts

ACTIVE: *
ACCOUNT: current_account@example.com

To set the active account, run:
    $ gcloud config set account `ACCOUNT`

切换账号（如有必要）：

如果当前账号不是您打算用于此 Codelab 的账号，请使用以下命令切换到正确的账号，并将 <your_desired_account@example.com> 替换为实际的电子邮件地址（您将在此实验中使用该地址）：

gcloud config set account <your_desired_account@example.com

确认项目

接下来，我们验证 Cloud Shell 是否已配置为使用正确的 Google Cloud 项目。运行以下命令：

gcloud config list project

系统会显示配置列表。找到 [core] 部分，并确保项目值与您要用于此 Codelab 的 Google Cloud 项目的 ID 相匹配：

[core]
project = <current-project-id>

设置项目（如有必要）

如果 project ID 值不正确，请使用以下命令将其设置为所需项目：

gcloud config set project <your-desired-project-id>

启用必需的 API

如需使用 Google Cloud 服务，您必须先为项目启用其各自的 API。在 Cloud Shell 终端中运行以下命令可启用本 Codelab 所需的所有服务：

gcloud services enable aiplatform.googleapis.com

如果操作成功，您会在终端中看到 Operation/... finished successfully。

4. 创建 Python 虚拟环境

在开始任何 Python 项目之前，最好先创建一个虚拟环境。这样可以隔离项目的依赖项，防止与其他项目或系统的全局 Python 软件包发生冲突。由于代理开发套件 (ADK) 需要 Python 3.9 或更高版本，我们将使用 uv 等工具来管理虚拟环境并确保使用正确的 Python 版本。

uv 是一款现代、快速且高效的工具，用于管理 Python 项目和环境，它结合了 pip、venv、pip-tools 和 pipx 等工具中传统的功能。它采用 Rust 编写，以实现快速运行。

Cloud Shell 已提供 uv，因此我们可以立即开始。

验证 uv 是否已正确安装

uv --version

为 AI 智能体创建新的项目文件夹

uv init ai-agents-adk
cd ai-agents-adk

使用 Python 3.12 创建虚拟环境

uv venv --python 3.12

在虚拟环境中安装 Google ADK 库

uv add google-adk

检查您是否已成功安装 google-adk 软件包

uv pip list | grep google-adk

如果您看到包含 google-adk 及其版本的输出行，则可以继续执行下一步。

5. 创建代理

现在，您的开发环境已设置完毕并准备就绪，接下来该为 AI 代理奠定基础了。智能体开发套件 (ADK) 简化了此流程，只需几个基本文件即可定义智能体的核心逻辑和配置。

以下三个文件协同工作，使您的代理可被发现、可运行和可配置：

  • agent.py：这是代理的核心。它包含定义代理行为的主要 Python 代码，包括代理的名称、用作“大脑”的大语言模型 (LLM) 以及指导其回答的核心指令。
  • __init__.py：在 Python 中，__init__.py 文件用于将目录标记为 Python 软件包。对于 ADK，这一点至关重要，因为它可以帮助框架从 agent.py 中发现并加载您的代理定义。在简单的 ADK 项目中，它通常包含一行用于导入 agent 模块的代码，使 ADK 运行程序可以访问您的代理。
  • .env：此文件（简称“环境”）用于存储代理所需的敏感信息和配置变量，例如 API 密钥、项目 ID 和地理位置。将这些详细信息保存在单独的 .env 文件中是确保安全性和可移植性的最佳做法，因为这样可以防止将敏感数据直接硬编码到代码中。您还可以轻松更改配置，而无需修改主代理逻辑。

使用以下命令在个人助理代理的专用文件夹中创建这些文件：

uv run adk create personal_assistant

执行命令后，系统会要求您选择一些选项来配置代理。在第一步中，选择选项 1 以使用 gemini-2.5-flash 模型，该模型快速高效，非常适合对话任务。

Choose a model for the root agent:
1. gemini-2.5-flash
2. Other models (fill later)
Choose model (1, 2): 1

在第二步中，选择 Vertex AI（选项 2）作为后端服务提供商。Vertex AI 是 Google Cloud 提供的功能强大的托管式 AI 平台。

1. Google AI
2. Vertex AI
Choose a backend (1, 2): 2

最后，系统会要求您确认 Google Cloud 项目 ID 和区域。如果预填充的值（current-project-id 和 current-region）是您打算使用的值，只需针对每个问题按 Enter 键即可。

Enter Google Cloud project ID [current-project-id]: 
Enter Google Cloud region [current-region]:

您应该会在终端中看到类似的输出。

Agent created in /home/<your-username>/ai-agent-adk/personal_assistant:
- .env
- __init__.py
- agent.py

现在，点击 Cloud Shell 窗口顶部的打开编辑器按钮。点击该按钮会打开编辑器窗口，让您更轻松地探索文件内容。切换可能需要一段时间；如果您在加载屏幕上停留的时间超过几分钟，请尝试刷新浏览器。

331da4cf37a1e8a4.png

编辑器窗口完全加载后，前往 personal-assistant 文件夹。您将看到上述必要的文件（agent.py、__init__.py 和 .env）。接下来，我们来探索一下这些文件的内容。

如果您在相应文件夹中没有看到 .env 文件，请前往顶部菜单栏，点击“查看”，然后选择切换隐藏文件。这是一项常见设置，因为 .env 文件通常默认处于隐藏状态，以防意外泄露。

ad3a52aebdae6142.png

我们来了解一下每个文件的内容。

agent.py

此文件使用 google.adk.agents 库中的 Agent 类实例化代理。

from google.adk.agents import Agent

root_agent = Agent(
    model='gemini-2.5-flash',
    name='root_agent',
    description='A helpful assistant for user questions.',
    instruction='Answer user questions to the best of your knowledge',
)
  • from google.adk.agents import Agent：此行从 ADK 库导入必需的 Agent 类。
  • root_agent = Agent(...)：您可以在此处创建 AI 智能体的实例。
  • name="personal_assistant"：代理的唯一标识符。这是 ADK 识别和指代您的代理的方式。
  • model="gemini-2.5-flash"：此关键参数用于指定智能体将使用哪个大语言模型 (LLM) 作为其底层“大脑”来理解、推理和生成回答。gemini-2.5-flash 是一款快速高效的模型，适合用于对话任务。
  • description="..."：简要总结代理的用途或功能。说明更侧重于让人类理解或让多代理系统中的其他代理了解此特定代理的功能。它通常用于日志记录、调试或显示有关代理的信息。
  • instruction="..."：这是引导代理行为并定义其角色的系统提示。它会告知 LLM 应该如何行动以及其主要用途。在本例中，它将代理确立为“有用的助理”。此指令对于塑造智能体的对话风格和能力至关重要。

init.py

此文件对于 Python 将 personal-assistant 识别为软件包是必需的，这样 ADK 才能正确导入您的 agent.py 文件。

from . import agent
  • from . import agent：此行执行相对导入，告知 Python 在当前软件包 (personal-assistant) 中查找名为 agent（对应于 agent.py）的模块。这行简单的代码可确保当 ADK 尝试加载您的 personal-assistant 代理时，它能够找到并初始化 agent.py 中定义的 root_agent。即使为空，__init__.py 的存在也会使相应目录成为 Python 软件包。

.env

此文件包含特定于环境的配置和敏感凭据。

GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_PROJECT_LOCATION
  • GOOGLE_GENAI_USE_VERTEXAI：此参数用于告知 ADK 您打算使用 Google 的 Vertex AI 服务进行生成式 AI 操作。这对于利用 Google Cloud 的托管服务和高级模型至关重要。
  • GOOGLE_CLOUD_PROJECT：此变量将保存 Google Cloud 项目的唯一标识符。ADK 需要此信息才能正确地将代理与云资源相关联，并启用结算功能。
  • GOOGLE_CLOUD_LOCATION：用于指定 Vertex AI 资源所在的 Google Cloud 区域（例如 us-central1）。使用正确的位置可确保您的代理能够与相应区域中的 Vertex AI 服务有效通信。

6. 在终端上运行代理

有了这三个文件，您就可以直接从终端运行代理了。为此，您需要打开终端窗口。点击菜单栏中的终端，然后选择新建终端即可！

77e87c904f45d1b2.png

终端可用后，您可以使用 adk run 命令启动代理。由于这是一个新的终端窗口，并且我们使用的是 uv，因此您需要先进入 ai-agent-adk 文件夹，然后在 adk run 命令前添加 uv run。

在终端中输入以下命令：

cd ai-agents-adk
uv run adk run personal_assistant

如果一切设置正确，您会在终端中看到类似的输出。

...
Running agent personal_assistant, type exit to exit.
[user]: hello. What can you do for me?
[personal_assistant]: Hello! I am a large language model, trained by Google. I can do many things to help you, such as:
...

快来与智能体聊天吧！您会注意到，输出有时会采用 Markdown 格式，这在终端中可能难以阅读。在下一步中，我们将使用开发界面来获得更丰富的聊天应用体验。

7. 在开发界面上运行代理

智能体开发套件还提供了一种便捷的方式，让您可以使用其开发界面将智能体作为聊天应用启动。只需使用 adk web 命令，而不是 adk run.

如果您仍处于之前的会话中，只需在终端中输入 exit 即可将其关闭。关闭上一个会话后，在终端中输入以下命令：

uv run adk web

您应该会在终端中看到类似的输出：

...
INFO:     Started server process [4978]
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)

您可以通过以下两种方式访问开发界面：

  1. 通过终端打开
  • 按住 Ctrl 键并点击或按住 Cmd 键并点击相应网址（例如 http://localhost:8000）从终端运行。
  1. 通过 Web 预览打开
  • 点击网页预览按钮，
  • 选择更改端口。
  • 输入端口号（例如 8000）
  • 点击更改并预览

9af437bf60562635.png

然后，您会在浏览器中看到类似聊天应用的界面。快来通过此界面与您的个人助理聊天吧！您会发现，Markdown 格式现在可以正确显示，并且此界面还可让您调试和调查每个消息传递事件、代理的状态、用户请求等。祝您聊天愉快！

7b779b9601941a12.png

8. 清理

由于本 Codelab 不涉及任何长时间运行的产品，因此只需在终端中按 Ctrl + C 停止活跃的代理会话（例如终端中的 adk web 实例）即可。

删除代理项目文件夹和文件

如果您只想从 Cloud Shell 环境中移除代码，请使用以下命令：

cd ~
rm -rf ai-agents-adk

停用 Vertex AI API

如需停用之前启用的 Vertex AI API，请运行以下命令：

gcloud services disable aiplatform.googleapis.com

关停整个 Google Cloud 项目

如果您希望完全关停 Google Cloud 项目，请参阅官方指南，了解详细说明。

9. 总结

恭喜！您已成功使用智能体开发套件 (ADK) 构建了一个简单的个人助理智能体。

您可能已经注意到，这个个人助理代理的性能还不是很强大（例如，它无法访问互联网以获取最新信息）。在本“使用 ADK 构建 AI 智能体”系列 的下一个 Codelab 中，您将学习如何使用函数和工具增强个人助理智能体的功能。到时候见！