使用 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 控制台
  • 好奇心和学习热情

兑换试用结算账号

如需完成此 Codelab，您还需要有效的 Google Cloud 结算账号。如果您还没有试用结算账号，请按以下步骤兑换：

  1. 在浏览器中打开无痕式窗口
  2. 前往此兑换门户
  3. 使用您的个人 Gmail 账号登录
  4. 按照门户网站中的分步说明操作

2. 简介

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

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

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

3. 配置 Google Cloud 服务

创建 Google Cloud 项目

首先，创建一个新的 Google Cloud 项目，以便将此 Codelab 中的活动仅隔离在此新项目中。

  1. 前往 console.cloud.google.com/projectcreate
  2. 输入所需信息：
  • 项目名称 - 您可以输入所需的任何名称（例如 genai-workshop）
  • 位置 - 将其保留为无组织
  • 结算账号 - 如果看到此选项，请选择 Google Cloud Platform 试用结算账号。如果您没有看到此选项，请不必担心。只需继续执行下一步即可。
  1. 记下生成的项目 ID，稍后您将需要用到它。

c3988d2f9ea7b7c3.png

  1. 如果一切正常，请点击创建按钮

配置 Cloud Shell

成功创建项目后，请按以下步骤设置 Cloud Shell。

1. 启动 Cloud Shell

前往 shell.cloud.google.com，如果看到要求您授权的弹出式窗口，请点击授权。

d5e271ec814f5769.png

2. 设置项目 ID

在 Cloud Shell 终端中执行以下命令，以设置正确的项目 ID。将 <your-project-id> 替换为从上述项目创建步骤中复制的实际项目 ID。

gcloud config set project <your-project-id>

现在，您应该会在 Cloud Shell 终端中看到已选择正确的项目。所选项目 ID 会以黄色突出显示。

a596b7d3cb052d07.png

3. 启用必需的 API

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

gcloud services enable aiplatform.googleapis.com

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

4. 创建 Python 虚拟环境

在开始任何 Python 项目之前，最好先创建一个虚拟环境。这样可以隔离项目的依赖项，防止与其他项目或系统的全局 Python 软件包发生冲突。

1. 创建项目目录并导航至该目录：

mkdir ai-agents-adk
cd ai-agents-adk

2. 创建并激活虚拟环境：

uv venv --python 3.12
source .venv/bin/activate

您会看到终端提示符带有 (ai-agents-adk) 前缀，表明虚拟环境处于有效状态。

aa915af1d8379132.png

3. 安装 ADK 页面

uv pip install google-adk

5. 创建代理

环境准备就绪后，就可以开始创建 AI 代理的基础了。ADK 需要一些文件来定义代理的逻辑和配置：

  • agent.py：包含代理的主要 Python 代码，用于定义代理的名称、使用的 LLM 和核心指令。
  • __init__.py：将目录标记为 Python 软件包，帮助 ADK 发现并加载您的代理定义。
  • .env：存储敏感信息和配置变量，例如 API 密钥、项目 ID 和位置。

此命令将创建一个名为 personal_assistant 的新目录，其中包含三个必需的文件。

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

之后，您需要验证方括号 [...] 中显示的项目 ID 是否设置正确。如果确实如此，请按 Enter 键。如果不是，请在以下提示中输入正确的项目 ID：

Enter Google Cloud project ID [your-project-id]:

最后，在下一个问题中按 Enter 键，以使用 us-central1 作为此 Codelab 的区域。

Enter Google Cloud region [us-central1]:

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

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

6. 探索代理代码

如需查看创建的文件，请在 Cloud Shell Editor 中打开 ai-agents-adk 文件夹。

  • 在顶部菜单中，依次点击文件 > 打开文件夹...。
  • 找到并选择 ai-agents-adk 文件夹
  • 点击确定。

如果您没有看到顶部菜单栏，也可以点击文件夹图标，然后选择打开文件夹。

733f215484b2ee7d.png

编辑器窗口完全加载后，前往 personal-assistant 文件夹。您将看到上述必要文件（agent.py、__init__.py 和 .env）。

.env 文件通常默认处于隐藏状态。如需在 Cloud Shell 编辑器中显示该文件，请执行以下操作：

  • 前往顶部的菜单栏，
  • 点击查看，然后
  • 选择切换隐藏文件。

a3a4e5587e8ed302.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="root_agent"：智能体的唯一标识符。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 服务有效通信。

7. 在终端上运行代理

有了这三个文件，您就可以直接从终端运行代理了。为此，请在终端中运行以下 adk run 命令：

adk run personal_assistant

如果一切设置正确，您会在终端中看到类似的输出。暂时不用担心警告，只要看到 [user]:，就可以继续操作。

...
Running agent personal_assistant, type exit to exit.
[user]: 
...

快来与智能体聊天吧！输入类似 “你好。What can you do for me?”，然后您应该会收到回复。

...
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 格式，这在终端中可能难以阅读。在下一步中，我们将使用开发界面来获得更丰富的聊天应用体验。

问题排查

此 API 方法要求启用结算功能

如果您收到一条消息，指出“{‘message': ‘This API method requires billing to be enabled'}”，请执行以下操作：

  1. 检查您是否在 .env 文件中使用了正确的项目 ID
  2. 前往关联的结算账号页面，查看结算账号是否已关联
  3. 如果不是，请从选项中选择 Google Cloud Platform 试用结算账号

ac71beafc7f645e.png

61c3fca79c772230.png

项目未使用过 Vertex AI API

如果您收到包含 {'message': 'Vertex AI API has not been used in project...'} 的错误消息，请在终端中输入以下内容以启用 Vertex AI API：

gcloud services enable aiplatform.googleapis.com

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

其他错误

如果您收到上述未提及的任何其他错误，请尝试重新加载浏览器中的 Cloud Shell 标签页（如果系统提示，请重新授权）。

8. 在开发 Web 界面中运行代理

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

如果您的终端仍在运行 adk run，请先输入 exit 以将其关闭，然后再输入以下命令：

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

9. 清理（可选）

由于本 Codelab 不涉及任何长时间运行的产品，因此只需在终端中按 Ctrl + C 或 Cmd + 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 项目，请参阅官方指南，了解详细说明。

10. 总结

恭喜！您已成功使用智能体开发套件 (ADK) 构建了一个简单的个人助理智能体。现在，您已经对 ADK 代理的核心组件有了扎实的基础和了解。

接下来，您可以为智能体提供工具，使其能够访问实时信息并与外部服务互动，从而大幅扩展智能体的功能。如果您想继续学习，本系列中的下一个 Codelab 使用 ADK 构建 AI 代理：利用工具赋能将引导您完成此流程。