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

1. 准备工作

欢迎学习“使用 ADK 构建 AI 智能体”系列的第一部分！在本实操 Codelab 系列中，您将开启精彩的学习之旅，使用 Google 的智能体开发套件 (ADK) 创建自己的智能 AI 智能体。

我们将从最基本的内容开始，指导您设置开发环境并构建基础对话智能体。完成本 Codelab 后，您将构建出自己的第一个交互式 AI，并准备好在本系列的后续部分中对其进行扩展，将其转换为复杂的多智能体系统 (MAS)。

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

您还可以通过此缩短的网址访问此 Codelab： goo.gle/adk-foundation。

前提条件

学习内容

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

所需条件

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

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），这是 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 Editor 中可见，请执行以下操作：

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

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]: 
...

继续与智能体聊天吧！输入类似 "你好。你能为我做些什么？” 的内容，您应该会收到回复。

...
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 预览 打开
  • 点击 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 智能体：使用工具赋能将指导您完成此过程。