使用 Google ADK 构建 AI 智能体

1. 简介

在此 Codelab 中，您将使用 Google 的智能体开发套件 (ADK) 和 Gemini 逐步构建您的首个 AI 智能体。您将创建一个基本的博客写作代理，用于规划和撰写内容，展示推理和行动的核心概念。

您将执行的操作

• 设置 ADK 开发环境。
• 创建包含规划器和撰写器的多智能体系统。
• 在本地运行智能体，并通过 ADK 网页界面与之互动。

所需条件

• 网络浏览器，例如 Chrome。
• 您的机器上安装了 Python 3.10 或更高版本。
• Google AI Studio API 密钥。

本 Codelab 适合各种水平的开发者，包括新手。

预计时长：30 分钟。

2. 可视化指南：什么是 AI 智能体？

在开始构建之前，我们先快速了解一下什么是 AI 代理以及它们遵循的常见模式。

什么是 AI 智能体？

从最简单的层面来说，智能体是一种不仅能回答问题，还能做出决策并采取行动的软件。与生成单个回答的传统聊天机器人不同，智能体会查看您的请求，确定要采取的步骤，可能会调用 API、运行代码、查看结果，然后决定下一步行动。

最清晰的解释之一来自研究论文 ReAct：在语言模型中协同推理和行动。该论文中的想法简单但强大：语言模型不应只生成文本。它们实际上可以逐步推理，采取行动（例如调用工具或 API），观察结果，然后决定下一步该怎么做。

推理、行动、观察和调整的循环是现代 AI 智能体运作的基础。这与 Google Cloud 对 AI 智能体的定义相符：具有推理、规划和记忆能力，并且具有足够的自主性来代表用户进行调整和做出决策的系统。

三种智能体行为模式

并非所有智能体的行为方式都相同。您可以从以下三种大致模式来考虑它们：

1. 顺序代理：这些代理像流水线一样按步骤运行：先运行第 1 步，然后运行第 2 步，再运行第 3 步。它们具有可预测性，但比较死板。
2. 反应式智能体：这类智能体会在当下做出决策。他们会查看当前状态，然后问：“接下来我该怎么做？”也许这次是工具 A，下次是工具 B。他们很灵活，但不会提前规划。
3. 审慎型或规划型智能体：这类智能体会暂停以制定计划，然后执行。以预订旅行为例，您不会随意购买机票，而是会选择日期、酒店、安排步骤，然后按部就班地完成预订。

哪个是“正确”的？这取决于问题。对于简单、可预测的流程，顺序执行即可。对于动态任务，反应式代理效果更好。对于具有依赖关系的多步骤目标，您需要规划代理。

在本实验中，我们将构建一个审慎/规划代理，该代理会先创建大纲，然后再撰写博文！

3. 准备工作

创建 Google Cloud 账号和项目

如需在本实验中将代理部署到 Google Cloud Run，您需要拥有 Google Cloud 账号和启用了结算功能的项目。

1. 登录 Google Cloud 控制台。创建新项目或重复使用现有项目。如果您还没有 Google 账号，则必须先创建一个。
2. 接下来，您需要在 Cloud 控制台中启用结算功能，才能使用 Cloud 资源。完成此 Codelab 的费用应该不到几美分。Google Cloud 新用户可能还符合参与 300 美元免费试用计划的条件。
3. 记下您的项目 ID（在所有 Google Cloud 项目中都是唯一的名称）。您需要此 ID 来配置和部署代理。

获取 Google AI Studio API 密钥

如需使用 Gemini 模型，您需要从 Google AI Studio 获取 API 密钥。

1. 前往 Google AI Studio。
2. 点击 Get API Key。
3. 创建新密钥或使用现有密钥。复制密钥以供日后使用。

4. 创建博客撰写智能体项目结构

在此步骤中，您将在本地机器上设置用于存放博客写作代理代码的目录和文件。

1. 创建博客撰写代理工作区

打开终端并运行以下命令，为博客撰写代理创建一个专用目录，然后进入该目录：

mkdir bloggeragent
cd bloggeragent

2. 初始化代理文件

Google ADK 框架直接从项目目录加载智能体工作流。直接在 bloggeragent 的根目录中创建必要的文件：

touch requirements.txt .env __init__.py agent.py

5. 安装依赖项并设置环境

在此步骤中，您将设置 Python 虚拟环境、安装 Google ADK 框架，并配置环境变量以使用 Gemini 模型对您的博客智能体进行身份验证。

1. 配置代理要求

打开 bloggeragent 目录中的 requirements.txt 文件，然后向其中添加以下内容，以指定博客写作代理所需的软件包：

google-adk==2.2.0
python-dotenv

2. 为代理创建虚拟环境

在 bloggeragent 目录中，创建并激活 Python 虚拟环境，以隔离代理的软件包：

python3 -m venv .venv
source .venv/bin/activate

3. 安装 ADK 框架

安装 requirements.txt 中定义的依赖项，以便为本地工作区配备 Google ADK：

pip install -r requirements.txt

4. 配置代理 API 凭据

打开您在项目根目录中创建的 .env 文件，然后添加您的 Gemini API 密钥：

GOOGLE_API_KEY=your_api_key

将 your_api_key 替换为您从 Google AI Studio 复制的密钥。

关于模型名称和端点的注意事项：

模型选择：agent.py 中的代理代码默认使用 gemini-flash-latest。如 Google ADK 文档的“使用入门”部分中所述，此选择器别名允许您的应用自动使用最新的稳定版 Gemini Flash 模型。如果您想使用其他模型（例如 Pro 模型或特定版本的模型），可以在终端或容器设置中设置 MODEL 环境变量来替换此默认设置（无需在 .env 文件中设置，因为代码会直接读取系统环境变量）。

端点和延迟时间：默认情况下，此设置使用全球 Google AI Studio 端点。对于延迟至关重要的生产工作负载，您应通过更靠近工作负载的区域性 Gemini Enterprise 端点（例如 us-east1 或 us-west1）来路由生成式 AI 调用。如需详细了解区域可用性和特定模型的托管位置，请参阅 Gemini Enterprise Agent Platform 模型指南。

6. 构建多智能体博客撰写工具

在此步骤中，您将实现博客撰写代理系统的核心工作流。

您将构建一个复杂的多智能体系统，该系统使用自我校正循环和大纲验证来撰写高质量的技术文章，而不是简单的单提示聊天机器人。这遵循了我们之前讨论的审慎/规划模式。

架构概览

以下是系统中的专家代理的互动方式：

配置 init.py

在文本编辑器中打开 __init__.py，并添加以下导入，以向 Runner 公开代理工作流：

from . import agent

编写博客写作代理工作流

在代码编辑器中打开 agent.py，然后添加以下代码，以定义 Planner、Writer、Validation Checkers 和主要的 Blogger 代理：

import os
import sys
from pathlib import Path
import datetime

from dotenv import load_dotenv
from google.adk.agents import Agent, LoopAgent
from google.adk.tools import agent_tool

# env config
load_dotenv()

MODEL = os.getenv("MODEL", "gemini-flash-latest")

# Sub-Agent: Planner
blog_planner = Agent(
   name="BlogPlanner",
   model=MODEL,
   description="Creates a practical, skimmable outline in Markdown.",
   instruction="""
You are a technical content strategist. Produce a clear Markdown outline with:
- Title
- Short intro
- 4–6 main sections (each with 2–3 bullets)
- Conclusion

If `codebase_context` exists in state, weave in specific sections/snippets.
Return only the outline in Markdown.
""",
   output_key="blog_outline",
)

class OutlineValidationChecker(Agent):
   def __init__(self):
       super().__init__(
           name="OutlineValidationChecker",
           model=MODEL,
           description="Validates that the outline is usable.",
           instruction="""
Check the outline in state `blog_outline`. If it has a title, intro, 4–6 sections, and a conclusion, respond exactly "ok".
Otherwise respond exactly "retry" and list missing pieces.
""",
           output_key="validation_result",
       )

robust_blog_planner = LoopAgent(
   name="RobustBlogPlanner",
   description="Retries planning if validation fails.",
   sub_agents=[blog_planner, OutlineValidationChecker()],
   max_iterations=3,
)

# Sub-Agent: Writer
blog_writer = Agent(
   name="BlogWriter",
   model=MODEL,
   description="Writes a technical blog post from the outline.",
   instruction="""
Write a complete Markdown article from the outline in `blog_outline`.

Guidelines:
- Audience: software engineers; skip basics and focus on practical insight.
- Explain both the 'how' and 'why'.
- Include concise code snippets when helpful.
- Follow the outline's structure (H2/H3).
- Output only the final article in Markdown (no fence around the whole post).
""",
   output_key="blog_post",
)

class BlogPostValidationChecker(Agent):
   def __init__(self):
       super().__init__(
           name="BlogPostValidationChecker",
           model=MODEL,
           description="Validates the final post.",
           instruction="""
Check `blog_post` for: intro, clear sections matching the outline, conclusion, and technical clarity.
If passes, respond "ok". Else respond "retry" with the specific fixes.
""",
           output_key="validation_result",
       )

robust_blog_writer = LoopAgent(
   name="RobustBlogWriter",
   description="Retries writing if validation fails.",
   sub_agents=[blog_writer, BlogPostValidationChecker()],
   max_iterations=3,
)

# Expose planner/writer as tools so the root agent can call them explicitly
planner_tool = agent_tool.AgentTool(agent=robust_blog_planner)
writer_tool  = agent_tool.AgentTool(agent=robust_blog_writer)

# Root Agent: Plan → Write 
root_agent = Agent(
   name="Blogger",
   model=MODEL,
   description="Minimal multi-agent blogger that plans and writes.",
   instruction=f"""
If the user gives a topic:
1) Call the planner tool to generate the outline.
2) Call the writer tool to produce the full draft.
3) End with 3 alternate titles and 2 tweet-length hooks.

Date: {datetime.datetime.now().strftime("%Y-%m-%d")}
""",
   tools=[
       planner_tool, # calls RobustBlogPlanner
       writer_tool,  # calls RobustBlogWriter
   ],
)

了解代理架构

我们来详细了解您刚刚在 agent.py 中添加的代码的主要组成部分，以便了解它如何实现多智能体规划和写作工作流：

1. BlogPlanner 子代理

blog_planner 代理负责内容规划。它会获取用户提供的主题，并以 Markdown 格式生成结构化的大纲（包含标题、简介、4-6 个部分和结论）。大纲会保存到共享状态字典中，并存储在 "blog_outline" 键下。

2. OutlineValidationChecker

OutlineValidationChecker 代理充当质量门。它会检查状态中的生成 "blog_outline"。如果大纲有效，则返回 "ok"。否则，系统会返回 "retry" 以及缺少的内容列表。

3. RobustBlogPlanner Loop

为防止代理生成不良大纲，我们将规划器和验证检查器封装在名为 robust_blog_planner 的 LoopAgent 中。如果验证失败并返回 "retry"，循环会自动再次运行规划器，最多运行 3 次，确保在进入下一阶段之前进行自我修正。

4. BlogWriter 子代理

大纲确定后，blog_writer 代理会从状态中读取 "blog_outline"，并生成完整的 Markdown 技术文章，该文章与大纲的结构相符，并针对软件工程师进行了量身定制。

5. BlogPostValidationChecker 和 RobustBlogWriter 循环

与大纲一样，最终文章会经过 BlogPostValidationChecker 的验证，以确保所有关键部分都存在且清晰明了。编写器和检查器封装在 robust_blog_writer 循环中，如果检查器发现问题，该循环最多可进行 3 次自我更正。

6. 将 Loop 公开为工具

我们使用 AgentTool 将规划器循环 (robust_blog_planner) 和写入器循环 (robust_blog_writer) 封装为工具（planner_tool 和 writer_tool）。这样一来，其他智能体就可以像调用简单工具一样调用这些复杂的工作流。

7. Blogger 根智能体

root_agent（命名为 Blogger）可编排整个工作流。当给定一个主题时，指令会引导模型执行以下操作：

1. 调用 planner_tool 以生成经过验证的大纲。
2. 调用 writer_tool 以根据该大纲撰写草稿。
3. 最后，生成 3 个备选标题和 2 个推文钩子。

这种多智能体循环架构可在向用户显示输出之前捕获并纠正 LLM 格式或结构错误，从而确保可靠性！

7. 运行和测试智能体

现在，让我们看看代理的实际应用！

1. 启动 ADK 网页界面

确保您位于终端中的 bloggeragent 项目根目录中，并且虚拟环境处于活跃状态 (source .venv/bin/activate)，然后启动 Web 界面：

adk web

如果端口 8000 已在使用，您可以使用 --port 8001 指定其他端口。如果找不到 adk 命令，请确保您的虚拟环境已激活，并且软件包已正确安装。

2. 与代理互动

1. 打开浏览器，然后前往 http://127.0.0.1:8000（或您指定的端口）。
2. 您应该会看到 ADK 网页界面，其中Blogger已加载智能体及其图文并茂布局（显示指向 RobustBlogPlanner 和 RobustBlogWriter 工具的博主根智能体）：
3. 在消息框中输入技术主题，然后按 Enter 键。以下是一些有趣的测试提示，可用于评估您的智能体：
   • How to build an AI agent using planning loops
   • Explain the difference between REST and gRPC in microservices
   • A guide to using Python's asyncio for backend concurrency
   • Why developers should use Docker for local database setups
4. 在界面中观看执行轨迹。您将看到 BlogPlanner 创建大纲，OutlineValidationChecker 验证大纲，以及 BlogWriter 根据大纲撰写最终草稿：

8. 部署到 Cloud Run

现在，您已验证代理在本地正常运行，接下来将其部署到 Google Cloud Run，以便其他人可以使用！

Google Cloud Run 是一款代管式计算平台，供您运行可通过 Web 请求或 Pub/Sub 事件调用的无状态容器。

1. 部署的前提条件

如需将博客撰写代理部署到 Cloud Run，您需要在本地机器上安装 Google Cloud CLI (gcloud) 并进行身份验证：

1. 安装 Google Cloud CLI：如果您尚未安装 Google Cloud CLI，请按照您所用操作系统（macOS、Windows 或 Linux）的 Google Cloud CLI 安装指南进行安装。
2. 对本地终端进行身份验证：安装完成后，在终端中运行以下命令，登录您的 Google Cloud 账号：

   gcloud auth login
   

3. 验证身份验证：确认您的账号已成功登录，并且您可以访问 Google Cloud 资源：

   gcloud auth list
   

此部署步骤需要一个启用了结算功能的 Google Cloud 项目。如果您只想在本地运行和测试博客撰写代理，可以跳过本部分的其余内容。

2. 设置 Google Cloud 项目

在终端中设置有效项目：

gcloud config set project <YOUR_PROJECT_ID>

启用构建和部署容器化代理所需的必要 Google Cloud 服务：

gcloud services enable \
  run.googleapis.com \
  artifactregistry.googleapis.com \
  cloudbuild.googleapis.com

由于 ADK 部署命令使用 Google Cloud Build 来自动执行 build 流程，因此您必须向默认的 Compute 服务账号授予使用 Cloud Build 的权限。

运行以下命令查找您的项目编号：

gcloud projects describe <YOUR_PROJECT_ID> --format="value(projectNumber)"

运行以下命令以绑定所需的 IAM 角色（将 替换为您的项目 ID，并将 替换为上述命令返回的编号）。

1. 向 Cloud Build 授予构建容器的权限：

gcloud projects add-iam-policy-binding <YOUR_PROJECT_ID> \
  --member="serviceAccount:<PROJECT_NUMBER>[e-mail]" \
  --role="roles/cloudbuild.builds.builder"

2. 授予 Gemini Enterprise 访问权限，以便部署的代理无需 API 密钥即可调用 Gemini 模型：

gcloud projects add-iam-policy-binding <YOUR_PROJECT_ID> \
  --member="serviceAccount:<PROJECT_NUMBER>[e-mail]" \
  --role="roles/aiplatform.user"

3. 设置本地环境变量

为简化部署命令并防止出现拼写错误，请在终端会话中将项目 ID 设置为环境变量：

export PROJECT_ID="<YOUR_PROJECT_ID>"

4. 使用 ADK CLI 进行部署

ADK CLI 提供了一个简化的命令，用于将代理部署到 Cloud Run。

确保虚拟环境处于活跃状态，并且您位于 bloggeragent 项目目录中，然后运行部署命令：

# Deploy using ADK
adk deploy cloud_run \
  --project=$PROJECT_ID \
  --region=us-east1 \
  --service_name=bloggeragent \
  --with_ui \
  . \
  -- \
  --set-env-vars GOOGLE_GENAI_USE_VERTEXAI=TRUE,MODEL=gemini-3.5-flash,GOOGLE_CLOUD_LOCATION=global

在部署过程中，系统会在终端中提示您回答以下两个问题：

1. 确认代码库创建：

   Deploying from source requires an Artifact Registry Docker repository to store built containers. A repository named [cloud-run-source-deploy] in region [us-east1] will be created.
   
   Do you want to continue (Y/n)?
   

   输入 Y，然后按 Enter 键。
2. 允许未经身份验证的访问：

   Allow unauthenticated invocations to [bloggeragent] (y/N)?
   

   输入 y 并按 Enter 键（这样一来，您就可以在浏览器中公开访问 ADK Web 界面）。

为 Cloud Run 设置环境变量

在本地运行代理时，您使用 .env 文件来管理环境变量。不过，在部署期间，系统会自动忽略本地 .env 文件（使用 .gcloudignore），以防止上传本地密钥或配置。相反，--set-env-vars 参数（而非标志）用于将环境变量（例如 MODEL 和 GOOGLE_CLOUD_LOCATION）显式注入 Cloud Run 服务环境中。身份验证由 Cloud Run 服务账号使用应用默认凭据 (ADC) 自动处理，因此您无需配置或上传 API 密钥。

5. 访问已部署的代理

部署完成后，该命令将输出一个网址。在浏览器中打开该网址，即可访问公开可访问的 ADK Web 界面！

9. 清理

为避免系统向您的 Google Cloud 账号持续收取费用，请删除在此 Codelab 中创建的资源。

1. 删除 Cloud Run 服务

删除已部署的 bloggeragent 服务：

gcloud run services delete bloggeragent --region=us-east1 --quiet

2. 删除 Artifact Registry 代码库

删除为存储构建的容器映像而创建的 Docker 代码库：

gcloud artifacts repositories delete cloud-run-source-deploy --location=us-east1 --quiet

3. 停止本地服务器

如需停止本地 ADK 服务器，请在运行该服务器的终端中按 CTRL+C，然后停用虚拟环境：

deactivate

10. 恭喜

恭喜！您已使用 Google 的 ADK 和 Gemini 构建了首个 AI 智能体。

您学到的内容

• AI 智能体的核心概念（推理和行动）。
• 如何使用 Google ADK 构建多智能体系统。
• 如何使用 Web 界面运行和测试智能体。

后续步骤

• 尝试向智能体添加工具（例如网页搜索或 API 调用）。
• 请继续观看视频 2，我们将在其中集成 MCP 服务器！

参考文档

• Google ADK 文档
• Gemini 文档