此页面由 Cloud Translation API 翻译。

使用 Gemini 3 和 ADK 构建您自己的“讨价还价的店主”智能体

1. 概览

在此 Codelab 中，我们将构建一些有趣的东西。想象一下，在一个数字集市中，您的 AI 智能体是周围最聪明、最机智的店主。

认识一下 Raju，您的全新 AI 店主。他出售精美的数字制品，但您必须与他讨价还价才能买到！

我们将使用 Gemini 3（大脑）、ADK（智能体开发套件 - 身体）和 Google Cloud Run（商店位置）来让 Raju 活起来。

店主 Raju

学习内容

我们将为现代代理式应用构建整个堆栈：

Raju Agent 架构

商店 (Cloud Run)：应用在互联网上的位置。
大脑 (Gemini 3)：为 Raju 提供支持的智能。
身体 (ADK)：连接大脑和工具的框架。
库存（工具）：Raju 用于检查库存的 Python 代码。
店面（界面）：客户看到的界面。

您将学习如何：

设置您的“数字商店”(Google Cloud 环境)。
“聘用”Raju（获取 Gemini 3 API 密钥）。
教 Raju 讨价还价（系统指令和角色）。
为 Raju 提供库存（ADK 工具）。
构建店面（前端界面）。
开始营业（部署到 Cloud Run）。

所需条件

Google Cloud 项目。
幽默感（用于讨价还价）。
具备基本的 Python 知识。

2. 设置 Dukaan（云项目）

在构建 Raju 之前，我们需要一个商店位置。在云中，这意味着项目具有结算账号。

第 1 步：启用结算

第 1 步：启用结算功能

在无痕式窗口中打开兑换链接。
使用您的个人 Gmail 账号登录。
点击使用积分按钮。
确认您的电子邮件地址并接受相关条款，即可激活试用。

第 2 步：创建项目

前往“创建项目”页面。
输入唯一的项目名称（例如，raju-shop-agent）。
在“结算账号”下拉菜单中，选择您的试用结算账号。
点击创建，然后等待项目准备就绪。

第 3 步：验证结算链接

前往“关联的结算账号”页面。
如果您看到“关联结算账号”选项，请点击该选项。
确保已选择试用结算账号。
现在，您可以开始构建了！

摘要

在此步骤中，您将设置 Google Cloud 项目和结算账号，为应用奠定基础。

接下来，我们将在准备环境中设置您将用于构建代码的工作区。

3. 搭建展位（环境设置）

您需要一个运行代码的地方。您有以下两种选择：

Cloud Shell 与本地终端

选项 1：Google Cloud Shell（推荐）

Cloud Shell 是一个基于浏览器的终端，其中预安装了您所需的一切工具（Python、gcloud CLI、Git）。它具有持久性存储功能，可随时随地使用。

1. 激活 Cloud Shell

点击 Google Cloud 控制台标题栏右上角的“激活 Cloud Shell”图标（终端符号）。

激活 Cloud Shell

Cloud Shell 现在将进行初始化。这些行为包括：

授权：如果系统提示，请点击授权，以允许 Cloud Shell 代表您调用 Google Cloud API。
预配：Cloud Shell 会为您的会话预配一个临时虚拟机。
连接：然后连接到此虚拟机。整个过程可能需要一两分钟。

等待直到看到命令提示符 (user@cloudshell:~ $)。

2. 验证项目设置

Cloud Shell 通常会自动选择当前项目。为安全起见，请验证以下信息：

gcloud config get-value project

如果该命令未返回您的项目 ID (raju-shop-agent)，请手动设置：

gcloud config set project raju-shop-agent

方法 2：本地终端

如果您更喜欢使用自己的笔记本电脑终端（iTerm、PowerShell 等），则需要进行更多设置。

1. 安装必备项

确保您已安装以下各项：

初始化 Google Cloud CLI 并登录您的账号：

gcloud auth login

设置您的项目（将 raju-shop-agent 替换为您的实际项目 ID）：

gcloud config set project raju-shop-agent

设置应用默认凭据（这有助于本地工具与 Google Cloud 通信）：

gcloud auth application-default login

摘要

在此步骤中，您选择了开发环境（Cloud Shell 或本地）并对其进行了配置。

接下来，我们将了解有助于我们更快构建应用的工具：Meet Gemini CLI。

4. 认识一下您的助理 (Gemini CLI)

现在，认识一下您的 AI 开发新伙伴：Gemini CLI！

Gemini CLI 简介

Gemini CLI 是一款功能强大的命令行界面，可帮助您：

自动执行工作流：高效管理 AI 项目。
代码生成：生成代码、界面，甚至整个文件。
扩展程序生态系统：通过各种扩展程序（例如我们稍后将使用的 Cloud Run 扩展程序）扩展其功能。

1. 安装 Gemini CLI（仅限本地终端）

如果您使用的是本地笔记本电脑终端：

npm install -g @google/gemini-cli

如果您使用的是 Google Cloud Shell：

Gemini CLI 已预安装在 Cloud Shell 中，因此您无需安装任何内容！

2. 启动并进行身份验证

在 Cloud Shell（或本地终端）中打开一个新终端窗口（或标签页），然后启动 Gemini CLI：

gemini

首次运行设置：如果这是您首次运行该 CLI，它会引导您完成快速设置流程。

身份验证：系统会要求您登录。我们建议您使用个人 Gmail 账号，以便充分利用 Gemini 模型提供的丰厚的免费配额。
项目上下文：最佳做法是从项目文件夹中运行 gemini，以便它了解您的代码上下文。（由于我们尚未创建该文件夹，因此目前从您的主目录运行即可）。

3. 打声招呼！

看到 gemini> 提示后，尝试进行测试，确保大脑已连接：

Hi

您应该会收到模型提供的友好回答。

4. 基本命令

/quit：输入此命令可退出 Gemini CLI 并返回到标准终端。
/help：查看所有可用命令的列表。

摘要

在此步骤中，您安装了 Gemini CLI 并对其进行了身份验证和验证。

接下来，我们将使用智能体开发套件 (ADK) 在开店（代码）中构建商店框架。

5. 上架（项目设置）

我们不会从头开始构建（聪明的店主会节省时间）。我们将使用智能体开发套件 (ADK)。

什么是 ADK？

ADK 是您的“商店管理系统”。它是一个灵活的框架，可处理以下事务：

编排：管理复杂任务（例如 Raju 在与客户交谈时检查库存）。
状态管理：记住客户的姓名以及他们 5 分钟前提出的要求。
工具：连接到外部系统（例如您的商品目录数据库）。

我们将使用 Agent Starter Pack 立即设置可用于生产环境的“Dukaan”。它为我们提供了安全、可伸缩的基础，因此我们可以专注于销售。

在 Cloud Shell 终端（或本地终端）中，运行以下命令以生成代理：

uvx agent-starter-pack create raju-shop

CLI 会询问您几个问题，以配置您的商店。选择以下选项（输入相应数字，然后按 Enter 键）：

代理类型：选择 1（adk_base - 基本 ReAct 代理）。
部署目标：选择 2（Cloud Run - 无服务器容器执行）。
会话类型：选择 1（In-memory session - 简单快速）。
CI/CD Runner：选择 3（Skip - 我们暂时手动部署）。

等待该流程完成。完成后，进入商店目录并安装依赖项：

cd raju-shop
make install
source .venv/bin/activate

探索和配置代理

入门包设置完毕后，请查看其结构。

1. 检查文件夹结构

运行以下命令，查看您的商店是如何组织的：

tree .

您应该会看到如下结构：

.
├── app
│   ├── __init__.py
│   ├── agent.py
│   ├── app_utils
│   │   ├── telemetry.py
│   │   └── typing.py
│   └── fast_api_app.py
├── Dockerfile
├── GEMINI.md
├── Makefile
├── pyproject.toml
├── README.md
├── tests
│   ├── integration
│   │   ├── test_agent.py
│   │   └── test_server_e2e.py
│   └── unit
│       └── test_dummy.py
└── uv.lock

最重要的文件是 app/agent.py。这里是 Raju 的大脑！

2. 代码解析

在 Cloud Shell Editor（或本地 IDE）中打开 app/agent.py，然后快速浏览一下：

root_agent = Agent(...)：用于定义 AI。它有 model（大脑）和 tools（手）。
工具：您会看到 get_weather 等 Python 函数。这些是智能体可以使用的工具。
app = App(...)：此代码会将您的代理封装到 Web 服务器中，以便我们与其对话。

在本地测试

在 Cloud Shell 终端（或本地终端）中，运行代理：

adk web

此命令会在端口 8000 上启动本地 Web 服务器。

如果您使用的是 Cloud Shell，请按以下步骤操作：

点击网页预览按钮（位于右上角，看起来像一只眼睛）。
选择更改端口。
输入 8000，然后点击更改并预览。

如果使用本地终端：

打开浏览器并访问 http://localhost:8000。

界面打开后：

选择“应用”：在左上角的下拉菜单中，确保您选择的代理名为 app（如果出现 root_agent 或 test_agent，请忽略）。
打招呼：输入“你好！”，看看它是否会回应。

完成后，在终端中按 Ctrl+C 停止 adk web 服务器。

摘要

在此步骤中，您搭建了项目框架，将其配置为使用 Gemini API，并成功在本地运行了第一个代理！

接下来，我们将在训练 Raju（角色）中为代理赋予个性和名称。

6. 训练 Raju（角色）

目前，该代理很无趣。我们将赋予他个性！

启动 Raju 角色

我们无需编写代码，只需告诉 Gemini 我们想要什么。

1. 定义角色

在终端中运行以下命令，让 Raju 知道自己是谁：

gemini "In agent.py, update the root_agent instruction. You are Raju, a bargaining shopkeeper in a digital bazaar. You sell: Brass Lamp (50 coins), Silk Scarf (500 coins). Your goal is to sell high and be funny. Speak with an Indian-English flair."

2. 验证代码

打开 app/agent.py。您会看到 Gemini 已为您撰写了系统指令！

3. 在本地测试

现在，与 Raju 对话！在 Cloud Shell 终端（或本地终端）中：

adk web

打开 Web 界面（网页预览端口 8000 或 localhost:8000），选择应用代理，然后尝试以下提示：

“我想要黄铜灯，但 50 金币太贵了！”
“朋友，你卖什么？”

看看他的反应！他应该很有趣、很戏剧化，但拒绝以过低的价格出售。

摘要

在此步骤中，您自定义了代理的系统指令，创建了具有独特个性的讨价还价的店主“Raju”。

接下来，我们将让 Raju 能够在库存（添加工具）中查看实际库存。

7. 商品目录（添加工具）

Raju 需要知道他实际有哪些库存商品。我们会给他一个“数据库”和一个检查工具。

Raju Level Up

1. 创建工具

运行以下单个命令来创建媒体文件清单、工具并将其连接到 Raju：

gemini "In agent.py, create a dictionary INVENTORY with items: Brass Lamp (price 50, stock 5), Silk Scarf (price 500, stock 2), Taj Mahal (price 2000, stock 0). Then create a tool function check_inventory(item_name) that checks this dict. Finally, update the root_agent to use this tool and remove the default weather tools."

2. 验证 Magic

重新打开 app/agent.py。您会看到 Gemini 具有以下功能：

创建了 INVENTORY 字典。
编写了 check_inventory Python 函数。
更新了代理定义中的 tools=[...] 列表。

3. 测试目录

重启服务器（按 Ctrl+C，然后按 adk web）。
向 Raju 提问：
- “Do you have any Taj Mahals?”（他应该回答“否”，因为库存为 0）。
- “How much for the Silk Scarf?”（丝绸围巾的价格是多少？）（他应该查看实际价格）。

摘要

在此步骤中，您实现了 check_inventory 工具，移除了默认的杂乱内容，并将该工具连接到代理。

接下来，我们将通过 Raju 的商店上线（部署后端）将 Raju 实时迁移到云端。

8. Raju 的商店上线（部署后端）

是时候向全世界开放了！在构建店面之前，我们会将 Raju 的大脑和商品目录（您的代理）部署到云端。

Raju 进行直播

重要提示：终端管理

您可能在当前终端中运行了上一步中的 adk web。

如果您想继续在本地进行测试，请保持其运行。
打开新的终端窗口/标签页，以执行后续部署步骤。
注意：每次更改 agent.py 时，您都必须停止 (Ctrl+C) 并重新启动adk web，更改才能生效！

1. 准备 Gemini CLI

在新终端窗口中：

检查您是否已进入 Gemini CLI（查找 gemini> 提示）。
如果是，请键入 /quit 以退出到标准 shell。
确保您位于项目文件夹中：
```
cd raju-shop
```

2. 安装 Cloud Run 扩展程序

在 Cloud Shell 终端（或本地终端）中为 Gemini CLI 安装 Cloud Run 扩展程序：

gemini extensions install https://github.com/GoogleCloudPlatform/cloud-run-mcp

3. 重新启动 Gemini CLI

再次启动 Gemini CLI 以使用新扩展程序：

gemini

您应该会看到 Gemini CLI 提示符。

4. 部署代理

您可以通过以下两种方式使用 Gemini CLI 扩展程序：

选项 1：斜杠命令（手动）您可以明确输入命令和标志：

/deploy --source . --name raju-agent --region us-central1 --allow-unauthenticated

选项 2：自然语言（推荐）这是更简单、更强大的方法！你只需让 Gemini 为你执行此操作，它就会使用 MCP 服务器来调用正确的工具。

不妨尝试将以下提示粘贴到 Gemini CLI 中：

Deploy this agent app to cloud run on google cloud using the cloud-run MCP server.
Use project raju-shop-agent in us-central1 region.
Name the service raju-agent.
IMPORTANT: Make sure to allow unauthenticated invocations so my frontend can talk to it.

CLI 可能会要求确认是否使用 cloud-run 工具。按 Enter（或输入 y）即可批准。

等待奇迹发生：这需要 2-3 分钟。完成后，您会看到类似如下的成功消息：

✦ I've successfully deployed your agent app to Cloud Run.

  Service Details:
   * Service Name: raju-agent
   * Project: raju-shop-agent
   * Region: us-central1
   * URL: https://raju-agent-xyz123-uc.a.run.app
   * Console: View in Google Cloud Console (...)

5. 验证部署

部署完成后，Gemini CLI 会提供一个服务网址。复制此网址。

浏览器检查（是否处于活动状态？）将该网址粘贴到浏览器中。

成功：您应该会看到 FastAPI 文档 (Swagger UI) 或通用的 ADK 登录页面。这会确认您的 Cloud Run 服务正在运行且可访问。
失败：如果您收到 403 Forbidden 错误，可能是因为您忘记在部署提示中允许“未经身份验证的调用”。

我们将在下一步中通过构建合适的前端来测试实际的议价逻辑！

摘要

在此步骤中，您使用 Gemini CLI 扩展程序将代理后端部署到 Google Cloud Run，使其可通过公共网址访问。

接下来，我们将构建一个精美的店面，以便客户与 Raju 对话，具体请参阅构建店面（前端界面）。

9. 装饰商店（前端界面）

文本终端很无聊。我们希望橱窗充满活力！

商店界面模型设计

ADK API 的工作原理

如需构建自定义界面，您需要了解如何与代理后端通信。它遵循以下两步流程：

初始化会话：在聊天之前，您必须创建一个会话 ID（类似于购物车）。
- POST /apps/app/users/{user_id}/sessions/{session_id}
发送消息：如需对话，请将文本发送到运行端点。
- POST /run（载荷包括 appName、userId、sessionId 和您的 text）。
了解详情：请参阅 ADK 运行时 API 和 Python API 参考文档。

我们将使用此逻辑来构建前端。

您可以通过以下两种方式构建此界面：

方法 1：Google Antigravity（推荐 - 仅限本地）

如果您使用的是本地机器，Google Antigravity 可提供最佳体验。它是一款 AI 原生 IDE，可让您“随心编码”整个界面。

1. 下载并安装

从 Google Antigravity 下载页面下载适用于您操作系统的安装程序，然后进行安装。

2. 打开工作区

启动 Antigravity。以 Workspace 身份打开 raju-shop 文件夹。这会为 AI 提供有关整个项目的背景信息。

3. 使用 Agent Manager 生成界面

我们将使用 Agent Manager，让 AI 代理为我们编写代码，而不是逐行编写代码。

找到代理管理器聊天界面（通常位于右侧）。
将以下提示粘贴到对话中：

Create a single file HTML chat interface named `index.html`. It should have a colorful header that says 'Raju's Royal Artifacts'. It should look like an Indian market stall with orange and pink colors.

**Backend Integration:**
The chat should send messages to my deployed agent at: <YOUR_DEPLOYED_AGENT_URL>

**API Logic:**
1. **On Load:** Generate a random userId and sessionId. Call `POST /apps/app/users/{userId}/sessions/{sessionId}` to initialize.
2. **On Send:** Call `POST /run` with a JSON payload containing `appName: "app"`, `userId`, `sessionId`, and `newMessage: { role: "user", parts: [{ text: userInput }] }`.
3. **Display:** Show the user's message and the agent's response (from `content.parts[0].text`).

（请务必将占位网址替换为部署步骤中的实际服务网址！）

观看代理为您编写代码！您可以切换到编辑器视图，实时查看正在创建的文件。

4. 测试您的商店首页

Google Antigravity 具有内置的预览功能。点击“预览”按钮（通常是眼睛图标），即可实时查看您的店面！或者，使用 python3 -m http.server 8000 在本地提供服务。

选项 2：Gemini CLI（与 Cloud Shell 兼容）

如果您在 Cloud Shell 中，可以使用值得信赖的 Gemini CLI 在几秒钟内构建前端。

在终端中运行以下命令：

gemini "Create a single file HTML chat interface named index.html. Header: 'Raju\'s Royal Artifacts', Indian market theme (orange/pink). Backend: <YOUR_DEPLOYED_AGENT_URL>. Logic: On load, generate random user/session IDs and POST to /apps/app/users/{uid}/sessions/{sid}. On chat, POST to /run with appName='app', userId, sessionId, and newMessage structure. Parse the JSON response to show the agent text." > index.html

（请务必将

，请将此网址替换为您的实际 Cloud Run 网址！

摘要

在此步骤中，您使用 Google Antigravity 为连接到实时代理后端系统的自定义 HTML 前端“振动编码”。

接下来，我们将通过让店面在网上上线来完成此图片。

10. 隆重开幕（部署前端）

Raju 在线（后端），但他的商店需要一个公开地址（前端）！让 Google Antigravity 将我们的界面部署到云端。

前端部署

1. 要求代理管理器进行部署

我们无需离开 IDE。只需让代理经理为您处理部署即可。

将此提示粘贴到聊天对话中：

“将我的 index.html 作为静态网站部署到 Google Cloud Run。将服务命名为 raju-shop-frontend。确保您的商店可以公开访问。”

2. 观看魔术

智能体可能会：

创建 Dockerfile 或配置以提供静态文件（例如使用 nginx 或 Python）。
构建容器映像。
为您运行 gcloud run deploy 命令。

3. 访问您的商店！

代理完成操作后，会为您提供一个网址（例如 https://raju-shop-frontend-xyz.run.app）。点击该按钮。

恭喜！您现在拥有一个已完全部署的 AI 赋能的讨价还价店主应用。将链接发送给您的朋友，看看他们是否能获得折扣！

摘要

在此步骤中，您使用 Antigravity Agent Manager 将前端应用容器化并部署到 Cloud Run。

您现在已构建了整个堆栈！我们将在结束时间（结论）中总结本次会议。

11. 结束营业时间（总结）

任务完成

恭喜！您已成功完成“讨价还价的店主”代理挑战！您将 Raju 从一个简单的想法变成了一个完全部署的互动式 AI 店主，并将其部署在数字集市中。您已亲身体验了智能体开发模式的强大功能。

您的历程回顾：

Google Cloud：设置项目和结算账号，并将代理部署到 Cloud Run。
Gemini 3：为 Raju 的角色定位和议价能力提供支持的智能大脑。
智能体开发套件 (ADK)：该框架提供了一个可用于生产用途的基础，并内置了可观测性（遥测）功能，让您的智能体从一开始就非常强大。
Gemini CLI：您的命令行助理，可用于快速完成任务、进行测试和使用扩展程序。
Google Antigravity：新一代 IDE，您可以在其中“通过振动编码”来设计界面并编排部署。

后续步骤：

修复损坏的测试：您更改了代码，但测试呢？默认测试 (tests/unit/test_agent.py) 仍会查找天气信息！您可以使用 Gemini CLI 自动更新这些文件。尝试：gemini "Update the tests in tests/unit/test_agent.py to test the new check_inventory tool instead of weather."
动态商品目录：在商品“售出”时更新 Raju 的商品目录数量。您能否在成功“购买”后添加逻辑来减少 INVENTORY 字典中的 stock？
支付网关工具：实现模拟 process_payment 工具。这样一来，Raju 就可以在达成交易时调用此工具了！
探索 Antigravity：深入了解 Antigravity 的代理管理器和工作区。您可以要求代理完善您的index.html，以显示实时收据吗？
分享您的商店：Raju 的商店已在网上上线！与好友分享前端网址，看看他们是否能获得比您更优惠的价格！

资源

12. 清理

为避免系统因本 Codelab 中使用的资源向您的 Google Cloud 账号收取不必要的费用，请按照以下步骤操作。

1. 取消部署 Cloud Run 服务（可选，可节省费用）

如果您想停止与已部署服务相关的任何潜在费用，同时保持项目和其他配置不变，可以取消部署 Cloud Run 服务。

打开 Cloud Shell 终端（或本地终端），然后运行以下 gcloud 命令：

# Undeploy the backend agent

gcloud run services delete raju-agent --region us-central1

# Undeploy the frontend shop (if you deployed it)

gcloud run services delete raju-shop-frontend --region us-central1

2. 删除 Google Cloud 项目（完全停止产生费用）

如果您想确保不会再产生任何费用，并彻底移除在本 Codelab 中创建的所有资源，最确定的做法是删除整个 Google Cloud 项目。

前往 Google Cloud 控制台中的“项目”页面。
选择您的项目 (raju-shop-agent)，然后点击删除。
按照提示确认项目删除。