Créer un sommelier de durian multimodal avec ADK et Antigravity

1. Présentation

Choisir un bon durian sur un étal de bord de route est un véritable casse-tête sensoriel. Les acheteurs doivent distinguer un véritable Musang King (D197) d'un fruit qui lui ressemble, déterminer si le fruit est tombé ce matin ou il y a plusieurs jours, et deviner s'ils vont apprécier son goût.

Dans cet atelier de programmation, vous allez créer et tester un système multi-agent multimodal Sommelier de durians avec l'Agent Development Kit (ADK) et Agents CLI, et éventuellement le déployer sur Cloud Run avec Antigravity CLI (les étapes principales prennent environ 45 minutes, et les deux étapes Antigravity facultatives ajoutent environ 20 minutes). Le choix d'un durian montre où s'arrête la perception de l'IA et où commencent les sens humains :

  • Ce que l'IA peut voir : Gemini peut inspecter une photo de la coque et repérer les marqueurs de cultivar, comme l'étoile à cinq branches à la base d'un Musang King, la pointe sombre et enfoncée d'un Black Thorn (D200), l'anneau de la taille d'une pièce de monnaie d'un D24 ou une tige sèche et flétrie.
  • Ce que seul un humain peut percevoir : un modèle ne peut pas sentir la couture pour détecter une note alcoolisée, tapoter sur la coque pour entendre un son creux ou appuyer sur deux épines pour voir si elles reprennent leur forme.
  • Ce dont l'agent doit se souvenir : deux durians parfaitement mûrs divisent toujours les acheteurs. Certains aiment le goût amer et alcoolisé d'un XO D24 d'un vieil arbre, tandis que d'autres préfèrent la crème sucrée et sans amertume d'un Red Prawn (D175).

La frontière sensorielle du durian : vision de l'IA et sens humains

Ce que vous allez faire

  • Étape 1 : Agent de vision unique : un agent ADK, échafaudé avec Agents CLI, qui identifie le cultivar et la fraîcheur d'un durian à partir d'une photo.
  • Étape 2 : Sens humains et mémoire du palais : outils qui évaluent ce que l'acheteur sent, entend et ressent, ainsi qu'un outil qui enregistre son profil gustatif d'une session à l'autre.
  • Étape 3 : Coordinateur et spécialistes : un coordinateur durian_advisor qui appelle un inspecteur visuel et un sommelier sensoriel, puis rend un verdict clair.
  • Étape 4 – Service d'agent Cloud Run : dans une étape facultative, la CLI Antigravity déploie votre agent avec les compétences de la CLI Agents.
  • Étape 5 : Chatbot Web Cloud Run : dans une autre étape facultative, la CLI Antigravity crée et déploie une application de chat adaptée aux mobiles qui communique avec votre agent.

Architecture

Architecture du sommelier de durians : un chatbot Web Cloud Run appelle le coordinateur durian_advisor sur Cloud Run, qui appelle des spécialistes visuels et sensoriels, et conserve les préférences de l'acheteur dans l'état de session ADK

Les deux services Cloud Run proviennent des étapes Antigravity facultatives. Sans eux, vous exécutez les mêmes agents dans l'environnement de test ADK dans Cloud Shell.

Prérequis

  • Maîtriser les bases de la programmation Python
  • Connaissance des outils de ligne de commande et des concepts d'IA générative
  • Aucune expérience préalable avec l'ADK, Agents CLI ou Antigravity CLI n'est requise.

Points abordés

  • Comment créer un projet ADK avec agents-cli create et créer un agent multimodal qui lit des photos
  • Où s'arrête la perception de l'IA (odeur, son, toucher et goût personnel) et comment concevoir des outils human-in-the-loop (avec intervention humaine) pour ces sens
  • Mémoriser les préférences de chaque utilisateur d'une session à l'autre avec l'état ADK de portée user:
  • Comment diviser un agent en un coordinateur et des agents spécialisés à un seul tour qu'il appelle comme des outils
  • (Facultatif) Comment donner à la CLI Antigravity les compétences de la CLI Agents pour qu'elle puisse déployer votre agent et un chatbot Web sur Cloud Run

Prérequis

  • Un compte Google (utilisez un compte @gmail.com personnel si vous demandez des crédits pour l'atelier)
  • Un lien de crédit d'atelier fourni par votre formateur (ainsi que l'appareil photo d'un téléphone pour scanner le QR code) ou un compte de facturation Cloud actif
  • Google Chrome (nous vous recommandons d'utiliser une fenêtre de navigation privée pour éviter de mélanger vos comptes personnel et professionnel)

2. Profiter de crédits Google Cloud (facultatif)

Si vous suivez cet atelier de programmation par vous-même et que vous êtes éligible, utilisez la bannière de crédits du Google Developer Program sur cette page pour demander des crédits sans carte de crédit. Si vous participez à un atelier avec un lien de crédit d'événement fourni par votre formateur, suivez les étapes de la section "Crédit d'événement".

Demander votre crédit pour l'événement

Vous pouvez demander des crédits pour les ateliers via Google Builders Hub (qui fait partie du Google Developer Program).

Pour demander votre crédit d'événement, procédez comme suit :

  1. Ouvrez le lien de crédit de l'atelier dans une fenêtre de navigation privée, puis connectez-vous avec votre compte @gmail.com personnel.
  2. Sur la fiche Réclamer votre avantage, cliquez sur Réclamer le crédit.

Carte "Profitez de votre avantage" du Google Builders Hub affichant le bouton "Profiter de l'avoir".

  1. Facultatif : Si vous êtes invité à créer un profil Google Developer Program, remplissez le formulaire.
  2. Lorsque la boîte de dialogue Scannez pour confirmer que vous êtes un humain s'affiche, scannez le QR code avec votre téléphone et effectuez la validation. Si le QR code ne s'affiche pas, actualisez la page et cliquez à nouveau sur Réclamer un crédit.
  3. Vérifiez que le message Votre demande de crédit pour l'événement a bien été validée ! s'affiche, puis cliquez sur Ouvrir le compte de facturation.

Carte de confirmation Google Builders Hub indiquant que votre demande de crédit pour l'événement a bien été validée et le bouton "Ouvrir le compte de facturation".

🔍 Vérifiez votre travail

Le provisionnement du compte de facturation peut prendre jusqu'à cinq minutes. Pour vérifier que votre crédit est actif, procédez comme suit :

  1. Si la page Gestion du compte de facturation n'est pas déjà ouverte, ouvrez Google Cloud Billing (ou copiez l'URL dans votre fenêtre de navigation privée) :
https://console.cloud.google.com/billing
  1. Cliquez sur l'onglet Vos comptes de facturation et actualisez la page jusqu'à ce qu'un compte contenant Crédit GDP affiche Actif dans la colonne État.

Page de gestion des comptes de facturation Google Cloud affichant un compte de facturation actif avec des crédits GDP.

3. Créer un projet Google Cloud (facultatif)

Créez un projet Google Cloud dédié pour isoler toutes les ressources de cet atelier de programmation afin de pouvoir les supprimer proprement lorsque vous aurez terminé.

Pour créer un projet Google Cloud, procédez comme suit :

  1. Ouvrez Créer un projet (ou copiez l'URL dans votre fenêtre de navigation privée) :
https://console.cloud.google.com/projectcreate
  1. Saisissez les détails de votre projet :
    • Nom du projet : saisissez un nom descriptif, par exemple google-cloud-workshop.
    • Compte de facturation (si affiché) : sélectionnez votre compte Crédit GDP (ou votre compte de facturation actif).
    • Ressource parente : laissez l'option Aucune organisation sélectionnée (ou sélectionnez votre organisation si nécessaire).
  2. Notez l'ID du projet généré, puis cliquez sur Créer.

Formulaire "Créer un projet Google Cloud" affichant le nom du projet, l'ID du projet généré, la ressource parente et le bouton "Créer".

🔍 Vérifiez votre travail

Une fois le projet créé, ouvrez Notifications dans la barre d'outils de la console Google Cloud, puis cliquez sur Sélectionner un projet.

Menu "Notifications" de la console Google Cloud affichant "Créer un projet" et le lien "Sélectionner un projet".

4. Configurer votre environnement

Dans cette section, vous allez configurer Google Cloud Shell, activer l'API Agent Platform et installer Agents CLI avec uv.

Configurer Cloud Shell

Lancer Cloud Shell

Ouvrez Google Cloud Shell avec l'éditeur de code et la vue du terminal activés (ou copiez l'URL dans votre fenêtre de navigation privée), puis cliquez sur Autoriser si vous y êtes invité :

https://shell.cloud.google.com/?show=ide,terminal

Boîte de dialogue "Autoriser Cloud Shell"

Définir l'ID de votre projet Google Cloud

Copiez et collez l'extrait de code suivant dans votre terminal Cloud Shell. Il affiche un menu numéroté de vos projets Google Cloud disponibles. Saisissez le numéro à côté de votre projet (par exemple, 1), puis appuyez sur Entrée :

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

Prompt attendu :

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.

L'ID de projet que vous avez sélectionné doit maintenant s'afficher en jaune dans l'invite du terminal Cloud Shell :

Terminal Cloud Shell affichant l'ID du projet sélectionné en jaune

Activer l'API Agent Platform

Activez l'API Agent Platform, que vos agents utilisent pour appeler Gemini :

gcloud services enable aiplatform.googleapis.com

🔍 Vérifiez votre travail

Un résultat semblable à celui-ci s'affiche :

Operation "operations/acat.p2-..." finished successfully.

Installer Agents CLI

Assurez-vous que uv est disponible et que son dossier d'outils se trouve sur votre PATH :

which uv || curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"

Installez la CLI Agents en tant qu'outil uv :

uv tool install google-agents-cli==1.7.0

uv installe chaque outil dans son propre environnement isolé et n'ajoute que la commande agents-cli à votre PATH. Votre système Python reste donc intact. Vous n'avez pas non plus besoin d'installer ADK vous-même. Chaque projet créé par Agents CLI dispose de son propre environnement virtuel avec une version d'ADK sur laquelle le modèle a été testé.

🔍 Vérifiez votre travail

Vérifiez qu'Agents CLI est prêt :

agents-cli --version

Un résultat semblable à celui-ci s'affiche :

agents-cli, version 1.7.0

5. Créer un agent de vision multimodal

Commencez petit : utilisez Agents CLI pour générer un projet ADK, puis transformez son exemple d'agent en classificateur de vision de durians.

Générer le projet

Générez le projet durian-advisor. --agent adk_python sélectionne le modèle ADK Python, --deployment-target cloud_run et --region us-central1 le préparent pour Cloud Run, --prototype ignore la configuration CI/CD et --yes accepte les valeurs par défaut :

cd ~ && agents-cli create durian-advisor \
  --agent adk_python \
  --deployment-target cloud_run \
  --region us-central1 \
  --prototype \
  --yes

Un résultat semblable à celui-ci s'affiche :

> Verifying GCP credentials...
> ✓ Connected to project: your-project-id

✅ Success! Your agent project is ready.

Ouvrez le projet dans l'éditeur Cloud Shell. La fenêtre est alors actualisée et le terminal redémarre :

cloudshell workspace ~/durian-advisor

Installez les dépendances du projet dans son propre dossier .venv :

cd ~/durian-advisor && agents-cli install

Vérifier le fichier d'environnement

Agents CLI a également écrit un fichier .env qui indique à l'ADK d'appeler Gemini via votre projet Google Cloud :

grep GOOGLE_ ~/durian-advisor/.env

Un résultat semblable à celui-ci s'affiche :

GOOGLE_GENAI_USE_VERTEXAI=true
GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_CLOUD_LOCATION=global

Conserver GOOGLE_CLOUD_LOCATION=global. Gemini 3.8 Flash est diffusé à partir du point de terminaison global, et non à partir de points de terminaison régionaux tels que us-central1, même si vos services Cloud Run s'exécutent dans us-central1.

Si GOOGLE_CLOUD_PROJECT affiche your-gcp-project-id, Agents CLI n'a pas pu détecter votre projet. Définissez-la avec :

sed -i "s/your-gcp-project-id/$(gcloud config get-value project)/" ~/durian-advisor/.env

Écrire le classificateur de vision

Chaque cultivar possède des marqueurs de coquille que Gemini peut repérer sur une photo :

Guide visuel des cultivars de durian montrant les marqueurs de base et d'épine de Musang King, Black Thorn, Red Prawn et D24

Ouvrez app/agent.py :

cloudshell edit ~/durian-advisor/app/agent.py

Remplacez son contenu par le code suivant :

"""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")

Voici quelques détails importants :

  • MODEL est le seul endroit où l'ID du modèle apparaît. Chaque agent que vous ajouterez par la suite en héritera. Changer de modèle ne nécessite donc qu'une seule ligne de code.
  • retry_options relance les erreurs temporaires, telles que les limites de débit, jusqu'à trois fois.
  • app = App(...) encapsule l'agent pour le playground et le serveur Cloud Run. Conservez le nom de l'application app et le nom de l'agent durian_advisor, qui correspondent au serveur généré et à agents-cli-manifest.yaml.

Tester l'agent dans le simulateur

Démarrez le playground ADK :

cd ~/durian-advisor && agents-cli playground

Un résultat semblable à celui-ci s'affiche :

INFO:     Uvicorn running on http://127.0.0.1:8080 (Press CTRL+C to quit)

Cliquez sur Aperçu sur le Web dans la barre d'outils Cloud Shell, puis sélectionnez Prévisualiser sur le port 8080. Si l'UI de développement ADK vous demande de choisir un agent, sélectionnez app. Envoyez ensuite ce prompt ou joignez votre propre photo de durian à l'aide du bouton d'importation :

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?

🔍 Vérifiez votre travail

L'agent identifie Musang King (D197) et attribue un score de fraîcheur élevé pour la tige verte humide. Ensuite, il admet ce qu'une photo ne peut pas lui dire : l'arôme, le son du tapotement, l'élasticité des épines et si vous allez aimer le goût.

Appuyez sur Ctrl + C dans le terminal pour arrêter le playground avant de continuer.

6. Ajoutez les sens humains et la mémoire du palais

Une caméra ne peut pas sentir, entendre ni toucher. Vous allez donc créer des outils qui demandent à l'acheteur de le faire. Vous allez également donner à l'agent une mémoire à long terme des goûts de chaque acheteur. Dans cette étape, vous allez écrire les outils. Dans l'étape suivante, vous les intégrerez aux agents.

Ajouter le catalogue de cultivars

Créez app/durian_data.py :

cloudshell edit ~/durian-advisor/app/durian_data.py

Collez ce catalogue de référence. En conservant les données dans leur propre module, le code de l'agent reste court :

"""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",
    },
}

Ajouter les outils sensoriels

Créez app/sensory_tools.py :

cloudshell edit ~/durian-advisor/app/sensory_tools.py

Collez le code suivant :

"""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}

Comment fonctionnent ces outils ?

  • ADK transforme chaque fonction en un outil que le modèle peut appeler. La docstring devient la description de l'outil, et la section Args explique chaque paramètre.
  • Les indications de type Literal[...] deviennent des choix fixes dans le schéma de l'outil. Gemini doit donc mapper "sent un peu l'alcool" à une seule valeur autorisée, telle que boozy_fermented.
  • get_cultivar_profile renvoie un état NOT_FOUND explicite avec les clés compatibles au lieu d'inventer un cultivar.

Ajouter l'outil de mémorisation des goûts

Créez app/memory_tools.py :

cloudshell edit ~/durian-advisor/app/memory_tools.py

Collez le code suivant :

"""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}

Fonctionnement de la mémoire gustative :

  • ADK transmet automatiquement tool_context et le masque du modèle, de sorte que Gemini ne voit que les deux paramètres de goût.
  • Le préfixe user: limite la clé d'état à l'utilisateur au lieu de la session en cours. Ainsi, le profil suit l'acheteur dans chaque nouvelle conversation.
  • Vous n'avez pas besoin d'un outil "get" distinct. Les agents lisent le profil directement dans leurs instructions avec l'espace réservé {user:palate_profile?}. ? vide l'espace réservé lorsqu'aucun profil n'existe encore, au lieu de générer une erreur.

🔍 Vérifiez votre travail

Notez un durian qui sent l'alcool, qui sonne creux et qui a des épines élastiques :

cd ~/durian-advisor && uv run python -c "from app.sensory_tools import evaluate_human_sensory_clues as score; print(score('boozy_fermented', 'hollow', 'springy'))"

Un résultat semblable à celui-ci s'affiche :

{'status': 'OK', 'ripeness_score': 9, 'max_score': 10, 'verdict': 'RIPE'}

7. Coordonner les agents spécialisés

Un seul agent qui jongle avec les règles visuelles, l'évaluation sensorielle et l'association des saveurs dans un seul prompt s'embrouille souvent. Au lieu de cela, vous allez confier chaque tâche à un spécialiste dédié et laisser un coordinateur combiner leurs réponses :

  • vision_inspector_agent lit le cultivar et la fraîcheur à partir de la photo, puis renvoie un rapport structuré.
  • sensory_sommelier_agent note ce que l'acheteur a senti, entendu et ressenti, et vérifie le cultivar par rapport à son palais.
  • durian_advisor parle à l'acheteur, enregistre ses préférences, appelle chaque spécialiste et rédige le verdict final.

Créer l'inspecteur de vision

Créez app/vision_agent.py :

cloudshell edit ~/durian-advisor/app/vision_agent.py

Collez le code suivant :

"""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 permet au spécialiste de renvoyer des données structurées sur lesquelles le coordinateur peut s'appuyer.
  • include_contents="default" permet à ce spécialiste de voir la conversation, y compris la photo importée. Sans cela, un spécialiste à tour unique ne voit que la requête transmise par le coordinateur.
  • disallow_transfer_to_parent et disallow_transfer_to_peers suppriment l'outil transfer_to_agent que l'ADK fournirait autrement à ce sous-agent. Un spécialiste qui voit l'intégralité de la conversation est tenté de renvoyer le chat au coordinateur au lieu de renvoyer son rapport.

Créer le sommelier sensoriel

Créez app/sensory_agent.py :

cloudshell edit ~/durian-advisor/app/sensory_agent.py

Collez le code suivant :

"""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 définit ce que le coordinateur doit transmettre : le cultivar et les trois rapports sensoriels de l'acheteur, avec ses propres mots. Le spécialiste mappe ces mots aux valeurs autorisées de l'outil.
  • {user:palate_profile?} insère les préférences enregistrées de l'acheteur dans l'instruction, afin que le spécialiste puisse juger de la pertinence sans avoir à rechercher dans sa mémoire.
  • Aucun spécialiste ne définit model. Les deux héritent de la valeur MODEL du coordinateur.
  • Les deux spécialistes utilisent les deux mêmes indicateurs de transfert, de sorte que chacun d'eux rend toujours compte au coordinateur.

Connecter le coordinateur

Ouvrez app/agent.py :

cloudshell edit ~/durian-advisor/app/agent.py

Remplacez son contenu par le coordinateur :

"""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")

Comme les deux spécialistes utilisent mode="single_turn", ADK fournit au coordinateur deux outils supplémentaires nommés vision_inspector_agent et sensory_sommelier_agent. L'instruction les désigne par ces noms.

Tester le coordinateur dans Playground

Redémarrez le playground :

cd ~/durian-advisor && agents-cli playground

Ouvrez l'aperçu sur le Web sur le port 8080 et discutez brièvement avec l'agent.

Faites-lui découvrir vos goûts :

Hi! Please remember my taste: I love sweet, creamy custard durians and I can't stand bitterness.

Ouvrez l'onglet État. Votre profil enregistré devrait s'afficher, comme suit :

{
  "user:palate_profile": {
    "favorite_flavors": "sweet, creamy custard",
    "bitterness_tolerance": "none"
  }
}

Montrez-lui un durian (décrivez-le ou joignez une photo) :

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?

Le coordinateur appelle vision_inspector_agent, qui identifie un XO D24. Ensuite, il vous demande de sentir la couture, de tapoter la cosse et de presser deux épines l'une contre l'autre.

Signalez ce que vous avez ressenti :

It smells a bit boozy, the knock sounds hollow, and the thorns spring back when I press them.

Pour repartir de zéro, cliquez sur Nouvelle session et demandez :

Which durian should I pick today?

🔍 Vérifiez votre travail

  • Une fois que vous avez décrit vos sensations, le coordinateur appelle sensory_sommelier_agent et rend un verdict : le XO D24 est mûr (9 sur 10), mais son amertume prononcée ne convient pas à votre palais. Demandez plutôt un Red Prawn (D175) ou un Black Thorn (D200).
  • Dans l'onglet Événements, vous pouvez voir durian_advisor appeler chaque spécialiste, et sensory_sommelier_agent appeler evaluate_human_sensory_clues et get_cultivar_profile.
  • Dans la nouvelle session, l'agent connaît déjà vos goûts et vous recommande un cultivar doux et sans amertume sans vous poser de questions.

Appuyez sur Ctrl + C dans le terminal pour arrêter le playground.

8. Déployer avec Antigravity (facultatif)

Vous avez créé et testé l'agent manuellement. Vous allez maintenant laisser Antigravity CLI (agy), l'agent de codage IA de Google pour le terminal, le déployer. Les compétences de la CLI Agents apprennent à Antigravity comment déployer correctement un agent ADK.

Activer les API de déploiement

Activez les API Cloud Run, Cloud Build et Artifact Registry, qu'Agents CLI utilise pour créer et héberger votre agent :

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

Un résultat semblable à celui-ci s'affiche :

Operation "operations/acat.p2-..." finished successfully.

Installer les compétences de la CLI Agents

Installez les sept compétences Agents CLI dans le dossier de votre projet, où Antigravity les détecte automatiquement :

cd ~/durian-advisor && agents-cli setup --workspace

🔍 Vérifiez votre travail

ls -1 ~/durian-advisor/.agents/skills

Un résultat semblable à celui-ci s'affiche :

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

Démarrer la CLI Antigravity

La CLI Antigravity est préinstallée dans Cloud Shell. Démarrez-le à partir du dossier de votre projet :

cd ~/durian-advisor && agy --dangerously-skip-permissions

Lors de la première exécution, Antigravity vous demande de vous connecter avec votre compte Google, de choisir un thème de couleurs, d'accepter les conditions d'utilisation et de faire confiance au dossier actuel.

Demander à Antigravity de déployer

Collez ce prompt dans 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 lit la compétence et peut d'abord exécuter les tests du projet. Ensuite, il exécute agents-cli deploy, qui crée le conteneur avec Cloud Build, déploie le service durian-advisor et envoie un message de test au service actif. L'exécution complète prend environ cinq à huit minutes.

Lorsque l'antigravité est terminée, quittez-la en appuyant deux fois sur Ctrl + D.

🔍 Vérifiez votre travail

Envoyez un message à l'agent déployé en utilisant l'URL enregistrée par Antigravity :

cd ~/durian-advisor && source .env && agents-cli run --url "$AGENT_BASE_URL" --mode adk "Which durian suits a beginner?"

Un résultat semblable à celui-ci s'affiche :

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...

Vérifiez maintenant que le service rejette les appels sans jeton :

curl -s -o /dev/null -w "%{http_code}\n" "$AGENT_BASE_URL"

Un résultat semblable à celui-ci s'affiche :

403

9. Vibe coder le chatbot Web (facultatif)

Votre agent est en ligne, mais privé. Vous allez maintenant reprendre la conversation avec Antigravity, qui connaît déjà votre agent, ses clés d'état et son URL, et lui demander de créer et de déployer un chatbot Web pour les acheteurs de durians.

Reprendre Antigravity

cd ~/durian-advisor && agy --dangerously-skip-permissions

Dans Antigravity, exécutez la commande à barre oblique suivante et sélectionnez votre conversation de déploiement dans la liste :

/resume

Demander à Antigravity de créer le chatbot

Collez ce prompt :

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 écrit l'application, crée le compte de service, lui attribue le rôle Demandeur Cloud Run sur durian-advisor et déploie l'application avec Cloud Build. Il teste généralement le point de terminaison de chat avant de se terminer. L'exécution complète prend environ 10 minutes. Lorsque l'URL s'affiche, quittez en appuyant deux fois sur Ctrl + D.

🔍 Vérifiez votre travail

Ouvrez l'URL https://durian-sommelier-web-....run.app affichée par Antigravity, puis :

  1. Appuyez sur un bouton de saveur, par exemple "Doux et crémeux". L'agent confirme qu'il a enregistré votre palais.
  2. Importez une photo de durian ou saisissez une brève description de la coque. L'agent identifie le cultivar et vous demande d'effectuer des contrôles sensoriels.
  3. Appuyez sur les chips sensorielles qui correspondent à votre durian. L'agent répond par un verdict unique qui couvre la maturité et l'adéquation au palais.

10. Effectuer un nettoyage

Supprimez les ressources que vous avez créées pour éviter que des frais ne vous soient facturés.

Supprimer les services Cloud Run

Supprimez le chatbot Web :

gcloud run services delete durian-sommelier-web --region us-central1 --quiet

Supprimez le service de l'agent :

gcloud run services delete durian-advisor --region us-central1 --quiet

Supprimer le compte de service

Supprimez le compte de service sous lequel le chatbot Web s'est exécuté :

gcloud iam service-accounts delete "durian-sommelier-web@$(gcloud config get-value project).iam.gserviceaccount.com" --quiet

Supprimer les images de conteneurs

Les déploiements de sources Cloud Run transfèrent l'image de conteneur de chaque service vers un dépôt Artifact Registry nommé cloud-run-source-deploy, que d'autres déploiements de votre projet peuvent partager. Supprimez uniquement les deux images de cet atelier de programmation et conservez le dépôt.

Supprimez l'image de l'agent :

gcloud artifacts packages delete durian-advisor --repository cloud-run-source-deploy --location us-central1 --quiet

Supprimez l'image du chatbot Web :

gcloud artifacts packages delete durian-sommelier-web --repository cloud-run-source-deploy --location us-central1 --quiet

🔍 Vérifiez votre travail

gcloud run services list --region us-central1

Un résultat semblable à celui-ci s'affiche :

Listed 0 items.

Supprimer les fichiers locaux

Supprimez le dossier du projet, y compris ses compétences et son environnement virtuel :

rm -rf ~/durian-advisor

Vous pouvez également désinstaller Agents CLI :

uv tool uninstall google-agents-cli

Supprimer l'intégralité du projet Google Cloud (facultatif)

PROJECT_ID=$(gcloud config get-value project)
gcloud projects delete "$PROJECT_ID" --quiet

11. Félicitations

Félicitations ! Vous avez créé et testé un système multi-agent multimodal Durian Sommelier avec ADK et Agents CLI. Si vous avez suivi les étapes facultatives, vous l'avez également déployée sur Cloud Run avec la CLI Antigravity.

Bilan de vos réalisations

  • Vous avez échafaudé un projet ADK avec agents-cli create et créé un agent de vision multimodal avec un seul paramètre MODEL.
  • Création d'outils human-in-the-loop (avec intervention humaine) pour l'odorat, l'ouïe et le toucher, ainsi qu'une mémoire du palais stockée dans l'état ADK limité à user:
  • Divisez l'agent en un coordinateur durian_advisor et deux spécialistes single_turn qu'il appelle comme des outils.
  • (Facultatif) Vous avez utilisé la CLI Antigravity avec les compétences Agents CLI pour déployer l'agent et un chatbot Web sur Cloud Run.

Étapes suivantes