1. 概览
在路边摊挑选一个好榴莲,就像是在解一道感官谜题。买家需要从外观相似的榴莲中辨别出真正的猫山王 (D197),判断果实是今天早上掉落的还是几天前掉落的,并猜测自己是否会喜欢它的味道。
在此 Codelab 中,您将使用智能体开发套件 (ADK) 和 Agents CLI 构建并测试多模态榴莲侍酒师多智能体系统,并可选择使用 Antigravity CLI 将其部署到 Cloud Run(核心步骤大约需要 45 分钟;两个可选的 Antigravity 步骤大约需要 20 分钟)。选择榴莲,可以展示 AI 感知的局限性和人类感官的优势:
- AI 能看到什么:Gemini 可以检查外壳照片并识别品种特征,例如猫山王底部的五角星、黑刺 (D200) 顶部的深色凹陷、D24 的硬币大小圆环,或干燥萎缩的果柄。
- 只有人类才能感知到的特征:模型无法通过嗅闻接缝来判断是否有酒香,无法通过敲击外壳来听是否有空洞的声音,也无法通过按压两根刺来感受它们是否会回弹。
- 智能体必须记住的内容:两个完全成熟的榴莲仍然让买家意见不一。有人喜欢老树 XO D24 的苦涩和酒香,有人则喜欢红虾 (D175) 的甜美和无苦味。

构建内容
- 第 1 阶段 - 单一视觉智能体:一个使用 Agents CLI 构建的 ADK 智能体,可根据照片识别榴莲的品种和新鲜度。
- 第 2 阶段 - 人类感官和味觉记忆:这些工具可对买家闻到、听到和感受到的内容进行评分,并可跨会话保存买家的口味偏好。
- 第 3 阶段 - 协调员和专家:
durian_advisor协调员会调用视觉检查员和感官侍酒师,然后给出一个明确的结论。 - 第 4 阶段 - Cloud Run 智能体服务:在可选步骤中,Antigravity CLI 会使用 Agents CLI 技能部署智能体。
- 第 5 阶段 - Cloud Run Web 聊天机器人:在另一个可选步骤中,Antigravity CLI 会构建并部署一个适合移动设备的聊天应用,该应用可与您的智能体对话。
架构

这两个 Cloud Run 服务来自可选的 Antigravity 步骤。如果没有这些,您可以在 Cloud Shell 的 ADK Playground 中运行相同的智能体。
前提条件
- 基本掌握 Python 编程
- 熟悉命令行工具和生成式 AI 概念
- 无需具备 ADK、Agents CLI 或 Antigravity CLI 的使用经验
学习内容
- 如何使用
agents-cli create搭建 ADK 项目,并构建一个可读取照片的多模态智能体 - AI 感知的局限性(嗅觉、听觉、触觉和个人品味),以及如何针对这些感官设计人机协同工具
- 如何通过
user:范围的 ADK 状态在多轮会话中记住每位用户的偏好设置 - 如何将一个智能体拆分为一个协调器和多个单轮专家智能体,并像调用工具一样调用这些专家智能体
- (可选)如何为 Antigravity CLI 赋予 Agents CLI 技能,以便其将您的智能体和 Web 聊天机器人部署到 Cloud Run
所需条件
- Google 账号(如果需要领取研讨会赠金,请使用个人
@gmail.com账号) - 讲师提供的研讨会赠金链接(以及用于扫描二维码的手机摄像头)或有效的 Cloud Billing 账号
- Google Chrome(建议使用无痕式窗口,以免混淆个人账号和工作账号)
2. 领取 Google Cloud 赠金(可选)
如果您是自行完成此 Codelab 且符合条件,请使用本页上的 Google 开发者计划赠金横幅,无需信用卡即可领取赠金。如果您参加的研讨会提供了讲师提供的活动赠金链接,请按照本部分中的活动赠金步骤操作。
领取活动赠金
您可以通过 Google Builders Hub(Google 开发者计划的一部分)领取研讨会活动赠金。
如需领取活动赠金,请按以下步骤操作:
- 在无痕式窗口中打开研讨会赠金链接,然后使用您的个人
@gmail.com账号登录。 - 在领取福利卡片上,点击领取赠金。

- 可选:如果您看到创建 Google 开发者计划资料的提示,请填写表单。
- 当扫描以验证您是真人对话框出现时,请使用手机扫描二维码并完成验证。如果未显示二维码,请刷新页面,然后再次点击领取赠金。
- 确认系统显示已成功领取活动赠金!消息,然后点击打开结算账号。

🔍 检查您的工作
结算账号预配最多可能需要 5 分钟。如需确认您的赠金是否有效,请完成以下步骤:
- 如果结算账号管理页面尚未打开,请打开 Google Cloud Billing(或将网址复制到无痕式窗口中):
https://console.cloud.google.com/billing
- 点击您的结算账号标签页,然后刷新页面,直到包含 GDP 赠金的账号在状态列中显示有效。

3. 创建 Google Cloud 项目(可选)
创建一个专用的 Google Cloud 项目,以便将此 Codelab 中的所有资源隔离开来,这样您就可以在完成后将其彻底移除。
如需创建 Google Cloud 项目,请按照以下步骤操作:
- 打开创建项目(或将网址复制到无痕式窗口中):
https://console.cloud.google.com/projectcreate
- 输入项目详细信息:
- 项目名称:输入一个描述性名称,例如
google-cloud-workshop。 - 结算账号(如果显示):选择您的 GDP 赠金账号(或您的有效结算账号)。
- 父级资源:保留无组织选项(或根据需要选择您的组织)。
- 项目名称:输入一个描述性名称,例如
- 记下生成的项目 ID,然后点击创建。

🔍 检查您的工作
项目创建完成后,打开 Google Cloud 控制台工具栏上的通知,然后点击选择项目。

4. 设置您的环境
在本部分中,您将设置 Google Cloud Shell、启用 Agent Platform API,并使用 uv 安装 Agents CLI。
配置 Cloud Shell
启动 Cloud Shell
打开 Google Cloud Shell,同时启用代码编辑器和终端视图(或将网址复制到无痕式窗口中),然后点击授权(如果出现提示):
https://shell.cloud.google.com/?show=ide,terminal

设置 Google Cloud 项目 ID
复制以下代码段并将其粘贴到 Cloud Shell 终端中。它会显示一个带编号的菜单,其中列出了您可用的 Google Cloud 项目。输入项目旁边的编号(例如 1),然后按 Enter 键:
unset CLOUDSDK_CORE_PROJECT
PS3="Select your project (e.g. 1): "
select PROJECT_ID in $(gcloud projects list --format="value(projectId)"); do
[ -n "$PROJECT_ID" ] && gcloud config set project "$PROJECT_ID" && break
done
预期提示:
1) durian-sommelier-workshop-4210 2) my-cloud-project-8812 Select your project (e.g. 1): 1 Updated property [core/project]. [environment: untagged] Read more to tag: g.co/cloud/project-env-tag.
现在,您应该会在 Cloud Shell 终端提示中看到所选的项目 ID 以黄色突出显示:

启用 Agent Platform API
启用 Agent Platform API,您的智能体将使用该 API 调用 Gemini:
gcloud services enable aiplatform.googleapis.com
🔍 检查您的工作
您看到的输出结果应该类似于以下内容:
Operation "operations/acat.p2-..." finished successfully.
安装 Agents CLI
确保 uv 可用,并且其工具文件夹位于 PATH 中:
which uv || curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
将 Agents CLI 作为 uv 工具安装:
uv tool install google-agents-cli==1.7.0
uv 会在各自的隔离环境中安装每个工具,并且只会将 agents-cli 命令添加到 PATH,因此系统 Python 不会受到影响。您也无需自行安装 ADK。Agents CLI 创建的每个项目都有自己的虚拟环境,其中包含模板测试所用的 ADK 版本。
🔍 检查您的工作
确认 Agents CLI 已准备就绪:
agents-cli --version
您看到的输出结果应该类似于以下内容:
agents-cli, version 1.7.0
5. 搭建多模态视觉智能体
从小处着手:使用 Agents CLI 生成 ADK 项目,然后将其示例智能体转换为榴莲视觉分类器。
搭建项目脚手架
生成 durian-advisor 项目。--agent adk_python 选择 Python ADK 模板,--deployment-target cloud_run 和 --region us-central1 为 Cloud Run 做好准备,--prototype 跳过 CI/CD 设置,--yes 接受默认设置:
cd ~ && agents-cli create durian-advisor \
--agent adk_python \
--deployment-target cloud_run \
--region us-central1 \
--prototype \
--yes
您看到的输出结果应该类似于以下内容:
> Verifying GCP credentials... > ✓ Connected to project: your-project-id ✅ Success! Your agent project is ready.
在 Cloud Shell 编辑器中打开项目。这会重新加载窗口并重启终端:
cloudshell workspace ~/durian-advisor
将项目的依赖项安装到其自己的 .venv 文件夹中:
cd ~/durian-advisor && agents-cli install
检查环境文件
Agents CLI 还编写了一个 .env 文件,用于指示 ADK 通过您的 Google Cloud 项目调用 Gemini:
grep GOOGLE_ ~/durian-advisor/.env
您看到的输出结果应该类似于以下内容:
GOOGLE_GENAI_USE_VERTEXAI=true GOOGLE_CLOUD_PROJECT=your-project-id GOOGLE_CLOUD_LOCATION=global
保留 GOOGLE_CLOUD_LOCATION=global。Gemini 3.8 Flash 通过 global 端点提供,而不是通过 us-central1 等区域级端点提供,即使您的 Cloud Run 服务在 us-central1 中运行也是如此。
如果 GOOGLE_CLOUD_PROJECT 显示 your-gcp-project-id,则表示 Agents CLI 无法检测到您的项目。使用以下命令进行设置:
sed -i "s/your-gcp-project-id/$(gcloud config get-value project)/" ~/durian-advisor/.env
编写视觉分类器
每个品种都有 Gemini 可以在照片中识别出的壳体特征:

打开 app/agent.py:
cloudshell edit ~/durian-advisor/app/agent.py
将其内容替换为以下代码:
"""A single multimodal agent that inspects durian photos."""
from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.models import Gemini
from google.genai import types
MODEL = "gemini-3.8-flash"
INSTRUCTION = """You are a durian visual classifier. Inspect the durian photo or shell description.
1. Base seam: a 5-point star means Musang King (D197). A dark sunken tip means Black Thorn (D200). A coin-sized brown ring means D24. An oval body with widely spaced, hooked thorns means Red Prawn (D175).
2. Stem: plump, moist, and greenish means it fell within about 12 hours. Dry and shriveled means it is days old.
3. Husk: closed seams mean natural ripening. Wide splits or mold mean it is past its best.
Give the likely cultivar and a visual freshness score from 1 to 10. Then list what a photo cannot tell you: the aroma, the tap sound, the thorn springiness, and whether the buyer will enjoy the taste."""
root_agent = Agent(
name="durian_advisor",
model=Gemini(model=MODEL, retry_options=types.HttpRetryOptions(attempts=3)),
description="Classifies durian cultivars and visual freshness from photos.",
instruction=INSTRUCTION,
)
app = App(root_agent=root_agent, name="app")
这里有几个细节需要注意:
MODEL是模型 ID 唯一出现的位置。之后添加的每个智能体都会继承该模型,因此切换模型只需更改一行代码。retry_options会针对临时性错误(例如速率限制)重试最多三次。app = App(...)会封装 Playground 和 Cloud Run 服务器的智能体。保留应用名称app和代理名称durian_advisor,它们与生成的服务器和agents-cli-manifest.yaml匹配。
在 Playground 中测试智能体
启动 ADK 实验园地:
cd ~/durian-advisor && agents-cli playground
您看到的输出结果应该类似于以下内容:
INFO: Uvicorn running on http://127.0.0.1:8080 (Press CTRL+C to quit)
点击 Cloud Shell 工具栏中的网页预览,然后选择在端口 8080 上预览。如果 ADK 开发者界面要求您选择智能体,请选择 app。然后发送此提示,或使用上传按钮附上您自己的榴莲照片:
I'm at a stall looking at a round durian with pyramid-shaped thorns and a 5-point star at the base. The stem is green and moist. What cultivar is this, and will it taste sweet?
🔍 检查您的工作
智能体识别出猫山王 (D197),并根据湿润的绿色果柄给出了较高的鲜度评分。然后,它会坦承照片无法传达的信息:香气、敲击声、刺的弹性,以及你是否会喜欢它的味道。
在继续操作之前,请在终端中按 Ctrl + C 停止 Playground。
6. 添加人类感官和味觉记忆
摄像头无法闻、听或感知,因此您需要构建工具,让买家来完成这些操作。您还将让智能体长期记住每位买家的喜好。在此步骤中,您将编写工具;在下一步中,您将把这些工具连接到智能体。
添加品种目录
创建 app/durian_data.py:
cloudshell edit ~/durian-advisor/app/durian_data.py
粘贴此参考目录。将数据保留在自己的模块中可使智能体代码保持简短:
"""Reference catalog of durian cultivars."""
CULTIVAR_CATALOG = {
"musang_king": {
"code": "D197",
"name": "Musang King (Mao Shan Wang)",
"visual_markers": "5-point star seam at the base, pyramid-shaped thorns",
"flavor": "rich, bittersweet, buttery custard",
"bitterness": "medium",
},
"black_thorn": {
"code": "D200",
"name": "Black Thorn (Ochee)",
"visual_markers": "Dark sunken tip at the base, round pumpkin-like body",
"flavor": "sweet, creamy, slightly winey",
"bitterness": "low",
},
"red_prawn": {
"code": "D175",
"name": "Red Prawn (Udang Merah)",
"visual_markers": "Oval body, widely spaced and slightly hooked thorns",
"flavor": "sweet, floral, soft and sticky",
"bitterness": "none",
},
"xo_d24": {
"code": "D24",
"name": "XO D24 (Sultan, old tree)",
"visual_markers": "Coin-sized brown ring at the base, dense sharp thorns",
"flavor": "intense, bitter, with a boozy finish",
"bitterness": "high",
},
}
添加感官工具
创建 app/sensory_tools.py:
cloudshell edit ~/durian-advisor/app/sensory_tools.py
粘贴以下代码:
"""Tools for cultivar lookup and human-in-the-loop sensory checks."""
from typing import Any, Literal
from .durian_data import CULTIVAR_CATALOG
AROMA_POINTS = {"sweet_fragrant": 4, "boozy_fermented": 3, "faint_grassy": 0, "sour_rotten": 0}
TAP_POINTS = {"hollow": 3, "solid": 0}
THORN_POINTS = {"springy": 3, "rigid": 0}
def get_cultivar_profile(cultivar_key: str) -> dict[str, Any]:
"""Looks up the visual markers, flavor, and bitterness of a durian cultivar.
Args:
cultivar_key: One of 'musang_king', 'black_thorn', 'red_prawn', or 'xo_d24'.
"""
key = cultivar_key.strip().lower().replace(" ", "_").replace("-", "_")
if key not in CULTIVAR_CATALOG:
return {"status": "NOT_FOUND", "supported": list(CULTIVAR_CATALOG)}
return {"status": "OK", "cultivar": CULTIVAR_CATALOG[key]}
def evaluate_human_sensory_clues(
aroma: Literal["sweet_fragrant", "boozy_fermented", "faint_grassy", "sour_rotten"],
tap_sound: Literal["hollow", "solid"],
thorn_feel: Literal["springy", "rigid"],
) -> dict[str, Any]:
"""Scores the ripeness clues that only a human buyer can smell, hear, and feel.
Args:
aroma: What the buyer smells at the seam of the husk.
tap_sound: What the buyer hears when tapping the husk.
thorn_feel: How two thorns feel when the buyer presses them together.
"""
score = AROMA_POINTS[aroma] + TAP_POINTS[tap_sound] + THORN_POINTS[thorn_feel]
if aroma == "sour_rotten":
verdict = "SPOILED"
elif score >= 7:
verdict = "RIPE"
elif score >= 4:
verdict = "NOT_QUITE_READY"
else:
verdict = "UNRIPE"
return {"status": "OK", "ripeness_score": score, "max_score": 10, "verdict": verdict}
这些工具的工作原理:
- ADK 会将每个函数转换为模型可以调用的工具。文档字符串会成为工具说明,
Args部分会解释每个参数。 Literal[...]类型提示会成为工具架构中的固定选项,因此 Gemini 必须将“闻起来有点酒味”映射到恰好一个允许的值,例如boozy_fermented。get_cultivar_profile会返回包含受支持键的显式NOT_FOUND状态,而不是创建品种。
添加味觉记忆工具
创建 app/memory_tools.py:
cloudshell edit ~/durian-advisor/app/memory_tools.py
粘贴以下代码:
"""Tool that remembers each buyer's durian palate across sessions."""
from typing import Any, Literal
from google.adk.tools import ToolContext
def save_palate_preference(
favorite_flavors: str,
bitterness_tolerance: Literal["none", "low", "medium", "high"],
tool_context: ToolContext,
) -> dict[str, Any]:
"""Saves the buyer's durian taste preferences to their long-term profile.
Args:
favorite_flavors: Flavors and textures the buyer enjoys, such as
'sweet, creamy custard'.
bitterness_tolerance: How much bitterness the buyer enjoys.
"""
profile = {
"favorite_flavors": favorite_flavors,
"bitterness_tolerance": bitterness_tolerance,
}
# The "user:" prefix scopes this key to the buyer, so it follows them
# into every future session of this app.
tool_context.state["user:palate_profile"] = profile
return {"status": "SAVED", "palate_profile": profile}
味觉记忆的工作原理:
- ADK 会自动传入
tool_context,并对模型隐藏该参数,因此 Gemini 只会看到两个口味参数。 user:前缀会将状态键的作用域限定为用户,而不是当前会话,因此买家在每次新对话中都会沿用该个人资料。- 您无需使用单独的“get”工具。智能体会使用占位符
{user:palate_profile?}直接将个人资料读取到其指令中。当尚无配置文件时,?会使占位符留空,而不是引发错误。
🔍 检查您的工作
为闻起来有酒味、敲击声空洞且刺有弹性的榴莲评分:
cd ~/durian-advisor && uv run python -c "from app.sensory_tools import evaluate_human_sensory_clues as score; print(score('boozy_fermented', 'hollow', 'springy'))"
您看到的输出结果应该类似于以下内容:
{'status': 'OK', 'ripeness_score': 9, 'max_score': 10, 'verdict': 'RIPE'}
7. 协调专业智能体
如果一个智能体在单个提示中同时处理视觉规则、感官评分和口味匹配,往往会感到困惑。相反,您需要将每项工作交给专门的专家,并让协调员整合他们的答案:
vision_inspector_agent会从照片中读取品种和新鲜度,并返回结构化报告。sensory_sommelier_agent会对买家闻到、听到和感受到的内容进行评分,并根据买家的口味检查品种。durian_advisor会与买家沟通,保存其口味偏好,调用每位专家,并撰写最终结论。
创建视觉检查器
创建 app/vision_agent.py:
cloudshell edit ~/durian-advisor/app/vision_agent.py
粘贴以下代码:
"""Vision inspector: reads the cultivar and freshness from a durian photo."""
from google.adk.agents import Agent
from pydantic import BaseModel, Field
class VisionReport(BaseModel):
cultivar_key: str = Field(
description="musang_king, black_thorn, red_prawn, xo_d24, or unknown"
)
visual_freshness: int = Field(description="1 (stale) to 10 (freshly fallen)")
evidence: str = Field(description="The visual markers behind your answer")
vision_inspector_agent = Agent(
name="vision_inspector_agent",
description="Identifies a durian's cultivar and visual freshness from the buyer's photo or shell description.",
mode="single_turn",
# Specialists only see their tool-call input by default. Opt in to the
# conversation history so this agent can see the uploaded photo.
include_contents="default",
# Report back to the coordinator instead of taking over the conversation.
disallow_transfer_to_parent=True,
disallow_transfer_to_peers=True,
output_schema=VisionReport,
instruction="""You are a durian vision inspector. Examine the durian photo or shell description in the conversation.
Cultivar markers:
- 5-point star seam at the base: musang_king
- Dark sunken tip at the base: black_thorn
- Oval body with widely spaced, slightly hooked thorns: red_prawn
- Coin-sized brown ring at the base and dense, sharp thorns: xo_d24
Freshness: a plump, moist, greenish stem and closed seams score high. A dry, shriveled stem or a split, moldy husk scores low.
If the markers are unclear, use 'unknown'.""",
)
output_schema=VisionReport会让专家返回协调器可以依赖的结构化数据。include_contents="default"让这位专家可以看到对话内容,包括上传的照片。如果没有它,单轮专家只会看到协调器传入的请求。disallow_transfer_to_parent和disallow_transfer_to_peers会移除 ADK 本来会为此子智能体提供的transfer_to_agent工具。看到完整对话的专家可能会倾向于将对话交还给协调员,而不是返回其报告。
创建感官侍酒师
创建 app/sensory_agent.py:
cloudshell edit ~/durian-advisor/app/sensory_agent.py
粘贴以下代码:
"""Sensory sommelier: scores the buyer's senses and checks palate fit."""
from google.adk.agents import Agent
from pydantic import BaseModel, Field
from .sensory_tools import evaluate_human_sensory_clues, get_cultivar_profile
class SensoryClues(BaseModel):
cultivar_key: str = Field(description="Cultivar from the vision inspector")
aroma: str = Field(description="What the buyer smelled at the seam")
tap_sound: str = Field(description="What the buyer heard when tapping the husk")
thorn_feel: str = Field(description="How the thorns felt when pressed together")
sensory_sommelier_agent = Agent(
name="sensory_sommelier_agent",
description="Scores the smell, sound, and touch clues the buyer reports, and checks the cultivar against their palate.",
mode="single_turn",
# Report back to the coordinator instead of taking over the conversation.
disallow_transfer_to_parent=True,
disallow_transfer_to_peers=True,
input_schema=SensoryClues,
instruction="""You are a durian sensory sommelier.
Buyer palate profile: {user:palate_profile?}
1. Call evaluate_human_sensory_clues with the buyer's aroma, tap sound, and thorn feel.
2. Call get_cultivar_profile for the cultivar.
3. Compare the cultivar's bitterness with the buyer's bitterness tolerance.
Report the ripeness verdict, the palate fit, and one sentence of advice.""",
tools=[evaluate_human_sensory_clues, get_cultivar_profile],
)
input_schema=SensoryClues定义了协调员必须传入的内容:品种和买家的三份感官报告(用他们自己的话描述)。专家会将这些字词映射到工具的允许值。{user:palate_profile?}会将买家保存的口味偏好放入指令中,这样专家无需查找记忆即可判断是否合适。- 两个专家集均未设置
model。两者都继承了协调器的MODEL。 - 两位专家使用相同的两个转移标志,因此每位专家始终会向协调员报告。
连接协调器
打开 app/agent.py:
cloudshell edit ~/durian-advisor/app/agent.py
将其内容替换为协调器:
"""Durian advisor: a concierge that coordinates vision and sensory specialists."""
from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.models import Gemini
from google.genai import types
from .memory_tools import save_palate_preference
from .sensory_agent import sensory_sommelier_agent
from .vision_agent import vision_inspector_agent
MODEL = "gemini-3.8-flash"
root_agent = Agent(
name="durian_advisor",
model=Gemini(model=MODEL, retry_options=types.HttpRetryOptions(attempts=3)),
description="Durian concierge that combines what the camera sees with what the buyer senses.",
instruction="""You are a friendly durian concierge helping a buyer at a fruit stall.
Buyer palate profile: {user:palate_profile?}
1. When the buyer shares taste preferences, call save_palate_preference.
2. When the buyer shows or describes a durian, call vision_inspector_agent.
3. A camera cannot smell, hear, or feel. Unless the buyer already reported the seam aroma, tap sound, and thorn feel, ask them to check. Then call sensory_sommelier_agent.
4. Call one specialist at a time. Finish with ONE verdict covering the cultivar, ripeness, and palate fit. If the durian does not suit their palate, suggest a cultivar that does.""",
tools=[save_palate_preference],
sub_agents=[vision_inspector_agent, sensory_sommelier_agent],
)
app = App(root_agent=root_agent, name="app")
由于两位专家都使用 mode="single_turn",ADK 为协调器提供了两个名为 vision_inspector_agent 和 sensory_sommelier_agent 的额外工具。指令会通过这些名称引用它们。
在 Playground 中测试协调器
再次启动 Playground:
cd ~/durian-advisor && agents-cli playground
在端口 8080 上打开网页预览,并与代理进行以下简短对话。
让它了解你的口味:
Hi! Please remember my taste: I love sweet, creamy custard durians and I can't stand bitterness.
打开状态标签页。您应该会看到已保存的配置文件,如下所示:
{
"user:palate_profile": {
"favorite_flavors": "sweet, creamy custard",
"bitterness_tolerance": "none"
}
}
向它展示榴莲(描述榴莲或附上榴莲照片):
The vendor is showing me a round durian with a coin-sized brown ring at the base and dense, sharp thorns. The stem is green and moist. Should I buy it?
协调器会调用 vision_inspector_agent,以标识 XO D24。然后,它会要求你闻一闻接缝、敲一敲外壳,并把两根刺压在一起。
报告您感知到的情况:
It smells a bit boozy, the knock sounds hollow, and the thorns spring back when I press them.
重新开始:点击新会话,然后询问:
Which durian should I pick today?
🔍 检查您的工作
- 在您报告感官体验后,协调员会致电
sensory_sommelier_agent并给出一个结论:XO D24 已经成熟(10 分中得 9 分),但其浓郁的苦味与您的口味不符,因此建议您选择红虾 (D175) 或黑刺 (D200)。 - 在事件标签页中,您可以看到
durian_advisor调用每个专家,sensory_sommelier_agent调用evaluate_human_sensory_clues和get_cultivar_profile。 - 在新的会话中,智能体已经了解您的口味,无需再次询问即可推荐一种甜而不苦的品种。
在终端中按 Ctrl + C 即可停止 Playground。
8. 使用 Antigravity 进行部署(可选)
您手动构建并测试了智能体。现在,您将让 Google 的终端 AI 编码智能体 Antigravity CLI (agy) 来部署它。Agents CLI 技能会指导 Antigravity 如何正确部署 ADK 智能体。
启用部署 API
启用 Cloud Run、Cloud Build 和 Artifact Registry API,Agents CLI 会使用这些 API 来构建和托管您的代理:
gcloud services enable \
run.googleapis.com \
cloudbuild.googleapis.com \
artifactregistry.googleapis.com
您看到的输出结果应该类似于以下内容:
Operation "operations/acat.p2-..." finished successfully.
安装 Agents CLI 技能
将 7 个 Agents CLI 技能安装到项目文件夹中,Antigravity 会自动发现这些技能:
cd ~/durian-advisor && agents-cli setup --workspace
🔍 检查您的工作
ls -1 ~/durian-advisor/.agents/skills
您看到的输出结果应该类似于以下内容:
google-agents-cli-adk-code google-agents-cli-deploy google-agents-cli-eval google-agents-cli-observability google-agents-cli-publish google-agents-cli-scaffold google-agents-cli-workflow
启动 Antigravity CLI
Antigravity CLI 已预安装在 Cloud Shell 中。从项目文件夹中启动它:
cd ~/durian-advisor && agy --dangerously-skip-permissions
首次运行时,Antigravity 会要求您使用 Google 账号登录、选择色彩主题、接受服务条款,并信任当前文件夹。
让 Antigravity 部署
将以下提示粘贴到 Antigravity 中:
Use the google-agents-cli-deploy skill to deploy this ADK agent to Cloud Run in us-central1 as a private service. Keep GOOGLE_CLOUD_LOCATION=global so Gemini keeps working, save the exact service URL to .env as AGENT_BASE_URL, and smoke-test the deployed agent with agents-cli run.
Antigravity 会读取该技能,并可能会先运行项目的测试。然后,它会运行 agents-cli deploy,该脚本会使用 Cloud Build 构建容器并部署 durian-advisor 服务,然后向实时服务发送测试消息。整个运行过程大约需要 5 到 8 分钟。
Antigravity 运行完毕后,按两次 Ctrl + D 即可退出。
🔍 检查您的工作
使用 Antigravity 保存的网址向已部署的智能体发送消息:
cd ~/durian-advisor && source .env && agents-cli run --url "$AGENT_BASE_URL" --mode adk "Which durian suits a beginner?"
您看到的输出结果应该类似于以下内容:
Querying remote agent: https://durian-advisor-123456789012.us-central1.run.app (mode: adk) [user]: Which durian suits a beginner? [durian_advisor]: For beginners, you want a durian that is sweet, creamy, and gentle on the palate, with little to no bitterness...
现在,确认该服务会拒绝不带令牌的调用:
curl -s -o /dev/null -w "%{http_code}\n" "$AGENT_BASE_URL"
您看到的输出结果应该类似于以下内容:
403
9. 以氛围编程方式开发 Web 聊天机器人(可选)
您的代理已发布,但处于私密状态。现在,您将继续与 Antigravity 对话,它已经知道您的代理、其状态密钥和网址,并要求它为榴莲买家构建和部署一个网页聊天机器人。
恢复 Antigravity
cd ~/durian-advisor && agy --dangerously-skip-permissions
在 Antigravity 中,运行以下斜杠命令,然后从列表中选择您的部署对话:
/resume
让 Antigravity 构建聊天机器人
粘贴以下提示:
Build a mobile-friendly "Durian Sommelier" web chatbot in a new web/ folder that talks to our deployed agent at AGENT_BASE_URL (ADK app name "app").
- Add palate quick-set buttons, a photo upload, and one-tap sensory chips: Smells sweet, Smells boozy, Hollow knock, Solid knock, Thorns spring back, Thorns feel stiff.
- Use a small FastAPI server that proxies chat requests to the agent with a Google ID token, because the agent service is private.
- Show only durian_advisor's replies in the chat, not the specialists' intermediate output.
- Keep a stable user ID per browser and reuse one ADK session, creating a new one if it is missing.
Deploy it to Cloud Run as durian-sommelier-web in us-central1 with public access. Run it as a new service account named durian-sommelier-web that can invoke durian-advisor, and print the URL.
Antigravity 编写应用,创建服务账号,向其授予 durian-advisor 的 Cloud Run Invoker 角色,并使用 Cloud Build 部署应用。它通常会在完成之前测试聊天端点。整个运行过程大约需要 10 分钟。当系统输出网址时,按两次 Ctrl + D 退出。
🔍 检查您的工作
打开 Antigravity 输出的 https://durian-sommelier-web-....run.app 网址,然后:
- 点按一个口味按钮,例如“甜美丝滑”。代理会确认它已保存您的口味。
- 上传一张榴莲照片,或输入对榴莲壳的简短描述。智能体识别出该品种,并要求您进行感官检查。
- 点按与您的榴莲相符的感官标签。智能体回复一个结论,涵盖成熟度和口味契合度。
10. 清理
删除您创建的资源,以免继续产生费用。
删除 Cloud Run 服务
删除网页聊天机器人:
gcloud run services delete durian-sommelier-web --region us-central1 --quiet
删除代理服务:
gcloud run services delete durian-advisor --region us-central1 --quiet
删除服务账号
删除网页聊天机器人运行时所用的服务账号:
gcloud iam service-accounts delete "durian-sommelier-web@$(gcloud config get-value project).iam.gserviceaccount.com" --quiet
删除容器映像
Cloud Run 源代码部署会将每个服务的容器映像推送到名为 cloud-run-source-deploy 的 Artifact Registry 代码库,该代码库可供项目中的其他部署共享。仅删除此 Codelab 的两个映像,并保留代码库。
删除智能体的图片:
gcloud artifacts packages delete durian-advisor --repository cloud-run-source-deploy --location us-central1 --quiet
删除 Web 聊天机器人的映像:
gcloud artifacts packages delete durian-sommelier-web --repository cloud-run-source-deploy --location us-central1 --quiet
🔍 检查您的工作
gcloud run services list --region us-central1
您看到的输出结果应该类似于以下内容:
Listed 0 items.
删除本地文件
移除项目文件夹,包括其技能和虚拟环境:
rm -rf ~/durian-advisor
(可选)卸载 Agents CLI:
uv tool uninstall google-agents-cli
删除整个 Google Cloud 项目(可选)
PROJECT_ID=$(gcloud config get-value project)
gcloud projects delete "$PROJECT_ID" --quiet
11. 恭喜
恭喜!您使用 ADK 和 Agents CLI 构建并测试了多模态榴莲侍酒师多智能体系统。如果您执行了可选步骤,那么您还使用 Antigravity CLI 将其部署到了 Cloud Run。
您完成的任务
- 使用
agents-cli create搭建了 ADK 项目,并通过单个MODEL设置构建了多模态视觉智能体 - 构建了人机协同工具,用于处理气味、声音和触觉,并利用
user:范围内的 ADK 状态存储味觉记忆 - 将智能体拆分为一个
durian_advisor协调器和两个single_turn专家,协调器会像调用工具一样调用专家 - (可选)使用 Antigravity CLI 和 Agents CLI 技能将智能体和 Web 聊天机器人部署到 Cloud Run
后续步骤
- 如果您跳过了这些步骤,请返回到可选的 Antigravity 步骤,将智能体和 Web 聊天机器人部署到 Cloud Run
- 利用数据库支持的会话服务,让味觉记忆持久留存
- 使用
agents-cli eval衡量回答质量 - 探索智能体开发套件 (ADK) 文档
- 详细了解 Agents CLI
- 浏览 Cloud Run 文档
- 加入 GEAR(Gemini Enterprise Agent Ready)计划,参加研讨会并学习相关课程