使用 ADK 从原型设计过渡到代理

使用 ADK 从原型设计过渡到代理

关于此 Codelab

subject上次更新时间:6月 12, 2025
account_circleAuthor: Abirami Sukumaran 编写

1. 概览

现在,如何开始使用 AI 构建应用?对大多数人来说,这通常始于一个简单的问题:“该模型能否真正帮助解决我一直在思考的问题?”这正是 Google AI Studio 的用武之地。您可以在此快速设计任何类型的原型。我一直想翻新厨房,我相信 Gemini 可以提供帮助,但我只是一名工程师,不是总包商。我甚至不确定该提出什么要求,因为需要考虑的因素太多了:法规、固定装置等。因此,我们先将问题拆解一下,让 Gemini 为我们生成超详细的问题,然后生成完整的装修计划,并直观呈现改造效果!不过请等一下。接下来,我该如何帮助企业扩大规模?输入 AGENTS!!!

智能体是一种自主程序,可与 AI 模型交互,使用其拥有的工具和上下文执行基于目标的操作,并且能够基于事实做出自主决策!

Agent Development Kit (ADK)

智能体开发套件 (ADK) 是一个灵活的模块化框架,用于开发和部署 AI 智能体。ADK 支持将多个不同的代理实例组合到多智能体系统 (MAS) 中,从而构建复杂的应用。

在 ADK 中,多智能体系统是一种应用,其中不同的智能体(通常会形成层次结构)协作或协调以实现更大的目标。以这种方式构建应用具有显著优势,包括增强的模块化、专业化、可重用性和可维护性,以及能够使用专用工作流代理定义结构化控制流。

构建内容

准备好从我们的原型问题转到构建智能客服了吗?我们将创建一个代理来帮助生成厨房装修项目的提案文档。在本实验中,您将执行以下操作:

  1. 构建一个简单的智能体,使用 ADK 生成装修提案文档
  2. 将生成的翻新提案文档存储在 Cloud Storage 存储分区中
  3. 在 Cloud Shell 和代理 Web 输出中测试代理

要求

  • 一个浏览器,例如 ChromeFirefox
  • 启用了结算功能的 Google Cloud 项目。

2. 准备工作

创建项目

  1. Google Cloud Console 的项目选择器页面上,选择或创建一个 Google Cloud 项目
  2. 确保您的 Cloud 项目已启用结算功能。了解如何检查项目是否已启用结算功能
  3. 此外,如果您正在阅读本文,并希望获得一些赠金来帮助您开始使用 Google Cloud 和 ADK,请使用此链接 兑换赠金
  4. 您可以按照此处兑换说明进行兑换。请注意,此链接的兑换期限仅截止 2025 年 7 月 15 日。
  5. 点击此链接激活 Cloud Shell。您可以点击 Cloud Shell 中的相应按钮,在 Cloud Shell 终端(用于运行云端命令)和编辑器(用于构建项目)之间切换。
  6. 连接到 Cloud Shell 后,您可以使用以下命令检查自己是否已通过身份验证,以及项目是否已设置为您的项目 ID:
gcloud auth list
  1. 在 Cloud Shell 中运行以下命令,以确认 gcloud 命令了解您的项目。
gcloud config list project
  1. 如果项目未设置,请使用以下命令进行设置:
gcloud config set project <YOUR_PROJECT_ID>
  1. 确保安装了 Python 3.9 或更高版本

如需了解其他 gcloud 命令和用法,请参阅文档

3. 原型

前往 Google AI Studio。开始在提示中输入内容。我的提示是:

I want to renovate my kitchen, basically just remodel it. I don't know where to start. So I want to use Gemini to generate a plan. For that I need a good prompt. Give me a short yet detailed prompt that I can use.

调整和配置右侧的参数,以获得最佳回答。

根据这个简单的描述,Gemini 为我提供了非常详细的提示,帮助我开始装修!实际上,我们使用 Gemini 来从 AI Studio 和我们的模型中获取更优质的回答。您还可以根据自己的应用场景选择要使用的不同模型。

我们选择了 Gemini 2.5 Pro。这是思考型模型,这意味着我们可以获得更多输出令牌(在本例中,最多可达 65,000 个令牌),以便进行长篇幅分析和生成详细文档。启用 Gemini 2.5 Pro 后,系统会显示 Gemini 思考框。Gemini 2.5 Pro 具有原生推理功能,可以接收长上下文请求。

请参阅下面的响应代码段:

a80d4bad4b3864f7.png

AI Studio 分析了我的数据,并生成了橱柜、厨房台面、后挡板、地板、水槽、协调性、调色板和材料选择等所有内容。Gemini 甚至会注明信息来源!

现在,尝试使用其他提示,看看能否让这个想法变为现实。

  1. 复制此提示并将其粘贴到提示编辑器中:
Add flat and circular light accessories above the island area for my current kitchen in the attached image.
  1. 请附上您当前厨房的图片(或使用我的厨房示例图片)。
  2. 将模型更改为“Gemini 2.0 Flash 预览图片生成”,以便您可以生成图片。

我得到了以下输出

b5b1e83fcada28f5.png

这就是 Gemini 的强大之处!

从理解视频、生成原生图片,到利用 Google 搜索建立真实信息依据,有些功能只有借助 Gemini 才能实现。

在 AI Studio 中,您可以获取此原型、获取 API 密钥,并使用 Vertex AI ADK 的强大功能将其扩展为完整的代理应用。

4. ADK 设置

现在,我们前往在“准备工作”部分中激活的 Cloud Shell 终端:

  1. 创建并激活虚拟环境(推荐)

在 Cloud Shell 终端中,创建一个虚拟环境:

python -m venv .venv

激活虚拟环境:

source .venv/bin/activate
  1. 安装 ADK
pip install google-adk

5. 项目结构

  1. 在 Cloud Shell 终端中,在所需的项目位置为代理应用创建一个根目录:
mkdir agentic-apps
  1. 在主目录中,创建一个专门用于当前项目的文件夹:
mkdir renovation-agent
  1. 前往 Cloud Shell 编辑器,通过创建文件(一开始为空)来创建以下项目结构:
renovation-agent/
        __init__
.py
        agent
.py
        requirements
.txt
       
.env

6. 源代码

  1. 前往“init.py”,并使用以下内容进行更新:
from . import agent
  1. 前往 agent.py,然后使用以下路径中的以下内容更新该文件:
https://github.com/AbiramiSukumaran/adk-renovation-single-agent/blob/main/agent.py

在 agent.py 中,我们会导入必要的依赖项,从 .env 文件检索配置参数,并定义 root_agent,用于生成提案文档并将其存储在 Cloud Storage 存储分区中。如需执行 Cloud Storage 步骤,我们使用一个名为 store_pdf 的工具。

  1. 确保您拥有 Cloud Storage 存储分区

用于存储代理生成的提案文档。创建该集群并预配访问权限,以便我们使用 Vertex AI 创建的代理系统可以访问该集群。具体方法如下:

https://cloud.google.com/storage/docs/creating-buckets#console

将存储分区命名为“next-demo-store”。如果您使用其他名称,请务必更新 .env 文件中的 STORAGE_BUCKET 的值(在“环境变量设置”步骤中)。

  1. 如需设置对存储分区的访问权限,请前往 Cloud Storage 控制台,然后前往您的存储分区(在本例中,存储分区名称为“next-demo-storage”:https://console.cloud.google.com/storage/browser/next-demo-storage

依次前往“权限”->“查看主账号”->“授予访问权限”。将“Principals”(正文)选择为“allUsers”,将“Role”(角色)选择为“Storage Object User”(存储对象用户)。

Make sure to not enable "prevent public access". Since this is a demo/study application we are going with a public bucket. Remember to configure permission settings appropriately when you are building your application.
  1. 创建依赖项列表

requirements.txt 中列出所有依赖项。您可以从代码库中复制此代码。

单个代理系统源代码说明

agent.py 文件使用智能体开发套件 (ADK) 定义厨房装修多智能体系统的结构和行为。我们来逐一了解关键组成部分:

代理定义

根代理(编排器):proposal_agent

root_agent 充当此单代理系统的编排器。它会接收初始装修请求,并根据请求的需求确定要调用哪些工具。

然后,root_agent 会收集这些工具的回答,并将其合并起来,以便向用户提供全面的回答。在本例中,我们只有一个工具“store_pdf”。

7. 数据流和关键概念

用户通过 ADK 界面(终端或 Web 界面)发起请求。

  1. root_agent 会收到请求。
  2. root_agent 会分析请求,并在需要时将其路由到相应工具。
  3. 工具“store_pdf”旨在将经过改进的文本内容写入 PDF 文件,然后将其上传到 Google Cloud Storage。
  4. 然后,它会将响应返回给 root_agent。
  5. root_agent 会合并这些响应,并向用户提供最终输出。

LLM(大语言模型)

智能客服非常依赖 LLM 来生成文本、回答问题和执行推理任务。LLM 是支持客服助理理解和响应用户请求的“大脑”。我们在此应用中使用的是 Gemini 2.5。

Google Cloud Storage

用于存储生成的装修方案文档。您需要创建一个存储分区,并向代理授予访问该存储分区的必要权限。

Cloud Run(可选)

OrderingAgent 使用 Cloud Run 函数与 AlloyDB 交互。Cloud Run 提供无服务器环境,以便在响应 HTTP 请求时执行代码。

AlloyDB

如果您使用的是 OrderingAgent,则需要设置 AlloyDB 数据库来存储订单信息。

.env 文件

.env 文件存储 API 密钥、数据库凭据和存储分区名称等敏感信息。请务必确保此文件的安全,并勿将其提交到代码库。它还会存储代理和 Google Cloud 项目的配置设置。root_agent 或支持函数通常会从此文件中读取值。确保已在 .env 文件中正确设置所有必需的变量。包括 Cloud Storage 存储分区名称

8. 模型设置

智能客服助理的理解用户请求和生成回答的能力依托于大语言模型 (LLM)。您的代理需要对此外部 LLM 服务进行安全调用,而这需要身份验证凭据。如果没有有效的身份验证,LLM 服务将拒绝代理的请求,代理将无法正常运行。

  1. Google AI Studio 获取 API 密钥。
  2. 在设置 .env 文件的下一步中,将 <<your API KEY>> 替换为您的实际 API 密钥值。

9. 环境变量设置

  1. 在本 repo 的模板 .env 文件中为参数设置值。在我的情况下,.env 包含以下变量:
GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=<<your API KEY>>
GOOGLE_CLOUD_LOCATION = us-central1 <<or your region>>
GOOGLE_CLOUD_PROJECT = <<your project id>>
PROJECT_ID = <<your project id>>
GOOGLE_CLOUD_REGION=us-central1 <<or your region>>
STORAGE_BUCKET = next-demo-store <<or your storage bucket name>>

将占位符替换为您的值。

10. 运行代理

  1. 使用终端,前往代理项目的父级目录:
cd agentic-apps/renovation-agent
  1. 安装所有依赖项
pip install -r requirements.txt
  1. 您可以在 Cloud Shell 终端中运行以下命令来执行代理:
adk run .
  1. 您可以运行以下命令,在 ADK 预配的 Web 界面中运行它:
adk web
  1. 使用以下提示进行测试:
user>> 

Hello. Generate Proposal Document for the kitchen remodel requirement in a proper format that applies to a renovation contract. Remember this text will eventually be stored as a pdf file so make sure to have the formatting appropriate. I have no other specification.

11. 结果

对于 adk run . 命令result is as follows"

ae50e6f6b2bab0a0.png

38a2c34667a8fd05.png

a8a39e8323d3ceb9.png

您可以验证翻新方案文档是否已在 Cloud Storage 存储分区中创建。

12. 清理

为避免系统因本博文中使用的资源向您的 Google Cloud 账号收取费用,请按照以下步骤操作:

  1. 在 Google Cloud 控制台中,前往管理资源页面。
  2. 在项目列表中,选择要删除的项目,然后点击删除
  3. 在对话框中输入项目 ID,然后点击关停以删除项目。

13. 恭喜

恭喜!您已成功使用 ADK 创建多智能体应用并与其互动!该多代理系统旨在通过自动执行提案生成、许可检查和订单状态跟踪等任务,简化厨房装修流程。每个代理都有特定的角色,root_agent 会协调各个代理的活动,以提供全面的解决方案。该系统利用 LLM、Google Cloud 服务以及可能的外部 API 来提供其功能。点击此处可前往产品文档。