使用 ADK 和 Antigravity 构建多模态榴莲品鉴师

1. 概览

在路边摊挑选一个好榴莲,就像是在解一道感官谜题。买家需要从外观相似的榴莲中辨别出真正的猫山王 (D197),判断果实是今天早上掉落的还是几天前掉落的,并猜测自己是否会喜欢它的味道。

在此 Codelab 中,您将使用智能体开发套件 (ADK) 和 Agents CLI 构建并测试多模态榴莲侍酒师多智能体系统,并可选择使用 Antigravity CLI 将其部署到 Cloud Run(核心步骤大约需要 45 分钟;两个可选的 Antigravity 步骤大约需要 20 分钟)。选择榴莲,可以展示 AI 感知的局限性和人类感官的优势:

  • AI 能看到什么:Gemini 可以检查外壳照片并识别品种特征,例如猫山王底部的五角星、黑刺 (D200) 顶部的深色凹陷、D24 的硬币大小圆环,或干燥萎缩的果柄。
  • 只有人类才能感知到的特征:模型无法通过嗅闻接缝来判断是否有酒香,无法通过敲击外壳来听是否有空洞的声音,也无法通过按压两根刺来感受它们是否会回弹。
  • 智能体必须记住的内容:两个完全成熟的榴莲仍然让买家意见不一。有人喜欢老树 XO D24 的苦涩和酒香,有人则喜欢红虾 (D175) 的甜美和无苦味。

榴莲感官边界:AI 视觉与人类感官

构建内容

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

架构

榴莲侍酒师架构:Cloud Run Web 聊天机器人调用 Cloud Run 上的 durian_advisor 协调器,后者调用视觉和感官专家,并将买家的口味偏好保存在 ADK 会话状态中

这两个 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 开发者计划的一部分)领取研讨会活动赠金。

如需领取活动赠金,请按以下步骤操作:

  1. 在无痕式窗口中打开研讨会赠金链接,然后使用您的个人 @gmail.com 账号登录。
  2. 在领取福利卡片上,点击领取赠金。

Google Builders Hub 的“领取福利”卡片,其中显示了“领取赠金”按钮。

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

Google Builders Hub 确认卡,显示“已成功领取活动赠金”和“打开结算账号”按钮。

🔍 检查您的工作

结算账号预配最多可能需要 5 分钟。如需确认您的赠金是否有效,请完成以下步骤:

  1. 如果结算账号管理页面尚未打开,请打开 Google Cloud Billing(或将网址复制到无痕式窗口中):
https://console.cloud.google.com/billing
  1. 点击您的结算账号标签页,然后刷新页面,直到包含 GDP 赠金的账号在状态列中显示有效。

Google Cloud Billing 账号管理页面,其中显示了一个有效的 GDP 赠金结算账号。

3. 创建 Google Cloud 项目(可选)

创建一个专用的 Google Cloud 项目,以便将此 Codelab 中的所有资源隔离开来,这样您就可以在完成后将其彻底移除。

如需创建 Google Cloud 项目,请按照以下步骤操作:

  1. 打开创建项目(或将网址复制到无痕式窗口中):
https://console.cloud.google.com/projectcreate
  1. 输入项目详细信息:
    • 项目名称:输入一个描述性名称,例如 google-cloud-workshop。
    • 结算账号(如果显示):选择您的 GDP 赠金账号(或您的有效结算账号)。
    • 父级资源:保留无组织选项(或根据需要选择您的组织)。
  2. 记下生成的项目 ID,然后点击创建。

“创建 Google Cloud 项目”表单,其中显示了“项目名称”、生成的“项目 ID”、“父级资源”和“创建”按钮。

🔍 检查您的工作

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

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

“为 Cloud Shell 提供授权”对话框

设置 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 以黄色突出显示:

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 可以在照片中识别出的壳体特征:

榴莲品种视觉指南,展示了猫山王、黑刺、红虾和 D24 的底部和刺部特征

打开 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 网址,然后:

  1. 点按一个口味按钮,例如“甜美丝滑”。代理会确认它已保存您的口味。
  2. 上传一张榴莲照片,或输入对榴莲壳的简短描述。智能体识别出该品种,并要求您进行感官检查。
  3. 点按与您的榴莲相符的感官标签。智能体回复一个结论,涵盖成熟度和口味契合度。

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

后续步骤