Crea un sommelier multimodale di durian con ADK e Antigravity

1. Panoramica

Scegliere un buon durian in una bancarella lungo la strada è un rompicapo sensoriale. Gli acquirenti devono distinguere un vero Musang King (D197) da un frutto simile, capire se il frutto è caduto questa mattina o giorni fa e indovinare se ne apprezzeranno il sapore.

In questo codelab, creerai e testerai un sistema multi-agente multimodale Durian Sommelier con l'Agent Development Kit (ADK) e l'Agents CLI ed, eventualmente, ne eseguirai il deployment in Cloud Run con l'Antigravity CLI (i passaggi principali richiedono circa 45 minuti; i due passaggi facoltativi di Antigravity aggiungono circa 20 minuti). La scelta di un durian mostra dove finisce la percezione dell'AI e iniziano i sensi umani:

  • Cosa può vedere l'AI: Gemini può esaminare una foto del guscio e individuare i segni distintivi della varietà, come la stella a cinque punte alla base di un Musang King, la punta scura e incavata di un Black Thorn (D200), l'anello delle dimensioni di una moneta di un D24 o un gambo secco e raggrinzito.
  • Cosa può percepire solo un essere umano: un modello non può annusare la fessura per sentire una nota alcolica, toccare il guscio per sentire un suono vuoto o premere due spine per sentire se tornano indietro.
  • Cosa deve ricordare l'agente: due durian perfettamente maturi dividono ancora gli acquirenti. C'è chi ama il sapore amaro e alcolico di un XO D24 di un albero antico e chi invece preferisce la crema dolce e priva di amaro di un Red Prawn (D175).

Il confine sensoriale del durian: visione dell'AI e sensi umani

Cosa creerai

  • Fase 1 - Agente di visione singola: un agente ADK, creato con l'interfaccia a riga di comando degli agenti, che identifica la varietà e la freschezza di un durian da una foto.
  • Fase 2 - Sensi umani e memoria del palato: strumenti che valutano ciò che l'acquirente annusa, sente e percepisce, oltre a uno strumento che salva il suo profilo di gusto tra le sessioni.
  • Fase 3 - Coordinatore e specialisti: un coordinatore durian_advisor che chiama un ispettore visivo e un sommelier sensoriale, quindi emette un verdetto chiaro.
  • Fase 4 - Servizio agente Cloud Run: in un passaggio facoltativo, Antigravity CLI esegue il deployment dell'agente con le skill di Agents CLI.
  • Fase 5 - Chatbot web Cloud Run: in un altro passaggio facoltativo, Antigravity CLI crea ed esegue il deployment di un'app di chat ottimizzata per il mobile che comunica con l'agente.

Architettura

Architettura di Durian Sommelier: un chatbot web di Cloud Run chiama il coordinatore durian_advisor su Cloud Run, che chiama gli specialisti visivi e sensoriali e mantiene il palato dell'acquirente nello stato della sessione ADK

I due servizi Cloud Run provengono dai passaggi facoltativi di Antigravity. Senza, esegui gli stessi agenti nel playground ADK in Cloud Shell.

Prerequisiti

  • Conoscenza di base della programmazione in Python
  • Familiarità con gli strumenti a riga di comando e i concetti di AI generativa
  • Non è richiesta alcuna esperienza precedente con ADK, Agents CLI o Antigravity CLI

Obiettivi didattici

  • Come creare un'impalcatura di un progetto ADK con agents-cli create e creare un agente multimodale che legge le foto
  • Dove si ferma la percezione dell'AI (olfatto, suono, tatto e gusto personale) e come progettare strumenti human-in-the-loop per questi sensi
  • Come ricordare le preferenze di ogni utente nelle varie sessioni con lo stato ADK con ambito user:
  • Come suddividere un agente in un coordinatore e in agenti specializzati single-turn che chiama come strumenti
  • Facoltativamente, come fornire ad Antigravity CLI le competenze di Agents CLI in modo che possa eseguire il deployment dell'agente e di un chatbot web su Cloud Run

Che cosa ti serve

  • Un Account Google (utilizza un account @gmail.com personale se richiedi i crediti per il workshop)
  • Un link per i crediti del workshop fornito dall'insegnante (oltre alla fotocamera dello smartphone per scansionare il codice QR) o un account di fatturazione Cloud attivo
  • Google Chrome (è consigliata una finestra Incognito per evitare di combinare account personali e account di lavoro)

2. (Facoltativo) Richiedi crediti Google Cloud

Se stai completando questo codelab in autonomia e hai i requisiti, utilizza il banner dei crediti del Google Developer Program in questa pagina per richiedere i crediti senza carta di credito. Se stai partecipando a un workshop con un link ai crediti per l'evento fornito dall'istruttore, segui i passaggi per i crediti per l'evento in questa sezione.

Richiedi il tuo credito per l'evento

Puoi richiedere i crediti per gli eventi dei workshop tramite Google Builders Hub (parte del Google Developer Program).

Per richiedere il credito per l'evento, segui questi passaggi:

  1. Apri il link dei crediti del workshop in una finestra Incognito e accedi con il tuo account @gmail.com personale.
  2. Nella scheda Richiedi il tuo vantaggio, fai clic su Richiedi credito.

Scheda Richiedi il tuo vantaggio di Google Builders Hub che mostra il pulsante Richiedi credito.

  1. (Facoltativo) Se vedi un messaggio che ti chiede di creare un profilo Google Developer Program, compila il modulo.
  2. Quando viene visualizzata la finestra di dialogo Scansiona per verificare che sei una persona fisica, scansiona il codice QR con lo smartphone e completa la verifica. Se il codice QR non viene visualizzato, aggiorna la pagina e fai di nuovo clic su Richiedi credito.
  3. Verifica che venga visualizzato il messaggio Hai richiesto correttamente il credito per l'evento, quindi fai clic su Apri account di fatturazione.

Scheda di conferma di Google Builders Hub che mostra il messaggio "Hai richiesto correttamente il tuo credito per l'evento" e il pulsante Apri account di fatturazione.

🔍 Controlla il tuo lavoro

Il provisioning dell'account di fatturazione può richiedere fino a cinque minuti. Per verificare che il credito sia attivo, completa i seguenti passaggi:

  1. Se la pagina Gestione account di fatturazione non è già aperta, apri Fatturazione Google Cloud (o copia l'URL nella finestra di navigazione in incognito):
https://console.cloud.google.com/billing
  1. Fai clic sulla scheda I tuoi account di fatturazione e aggiorna la pagina finché un account contenente Credito GDP non mostra Attivo nella colonna Stato.

Pagina di gestione dell'account di fatturazione Google Cloud che mostra un account di fatturazione con credito GDP attivo.

3. Crea un progetto Google Cloud (facoltativo)

Crea un progetto Google Cloud dedicato per mantenere isolate tutte le risorse di questo codelab, in modo da poterle rimuovere facilmente al termine.

Per creare un progetto Google Cloud:

  1. Apri Crea un progetto (o copia l'URL nella finestra Incognito):
https://console.cloud.google.com/projectcreate
  1. Inserisci i dettagli del progetto:
    • Nome progetto: inserisci un nome descrittivo, ad esempio google-cloud-workshop.
    • Account di fatturazione (se visualizzato): seleziona il tuo account GDP Credit (o il tuo account di fatturazione attivo).
    • Risorsa principale: lascia selezionata l'opzione Nessuna organizzazione (o seleziona la tua organizzazione, se necessario).
  2. Prendi nota dell'ID progetto generato, quindi fai clic su Crea.

Modulo Crea un progetto Google Cloud che mostra il nome del progetto, l'ID progetto generato, la risorsa principale e il pulsante Crea.

🔍 Controlla il tuo lavoro

Al termine della creazione del progetto, apri Notifiche nella barra degli strumenti della console Google Cloud, quindi fai clic su Seleziona progetto.

Menu Notifiche della console Google Cloud che mostra Crea progetto e il link Seleziona progetto.

4. Configura l'ambiente

In questa sezione configurerai Google Cloud Shell, abiliterai l'API Agent Platform e installerai Agents CLI con uv.

Configura Cloud Shell

Avvia Cloud Shell

Apri Google Cloud Shell con l'editor di codice e la visualizzazione del terminale abilitati (o copia l'URL nella finestra Incognito) e fai clic su Autorizza se richiesto:

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

Finestra di dialogo Autorizza Cloud Shell

Imposta l'ID progetto Google Cloud

Copia e incolla lo snippet seguente nel terminale Cloud Shell. Viene visualizzato un menu numerato dei progetti Google Cloud disponibili. Digita il numero accanto al progetto (ad esempio 1) e premi Invio:

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 previsto:

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.

Ora dovresti vedere l'ID progetto selezionato evidenziato in giallo nel prompt del terminale Cloud Shell:

Terminale Cloud Shell che mostra l'ID progetto selezionato evidenziato in giallo

Abilita l'API Agent Platform

Abilita l'API Agent Platform, utilizzata dagli agenti per chiamare Gemini:

gcloud services enable aiplatform.googleapis.com

🔍 Controlla il tuo lavoro

Dovresti visualizzare un output simile al seguente:

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

Installa l'interfaccia a riga di comando degli agenti

Assicurati che uv sia disponibile e che la relativa cartella degli strumenti si trovi nel tuo PATH:

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

Installa Agents CLI come strumento uv:

uv tool install google-agents-cli==1.7.0

uv installa ogni strumento nel proprio ambiente isolato e aggiunge solo il comando agents-cli al tuo PATH, in modo che l'installazione Python del sistema rimanga invariata. Non è necessario installare ADK manualmente. Ogni progetto creato dall'interfaccia a riga di comando degli agenti riceve il proprio ambiente virtuale con una versione dell'ADK con cui è stato testato il template.

🔍 Controlla il tuo lavoro

Verifica che l'interfaccia a riga di comando degli agenti sia pronta:

agents-cli --version

Dovresti visualizzare un output simile al seguente:

agents-cli, version 1.7.0

5. Crea lo scaffold di un agente di visione multimodale

Inizia con poco: utilizza l'interfaccia a riga di comando degli agenti per generare un progetto ADK, quindi trasforma l'agente di esempio in un classificatore di immagini di durian.

Crea l'impalcatura del progetto

Genera il progetto durian-advisor. --agent adk_python sceglie il template ADK Python, --deployment-target cloud_run e --region us-central1 lo preparano per Cloud Run, --prototype salta la configurazione CI/CD e --yes accetta i valori predefiniti:

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

Dovresti visualizzare un output simile al seguente:

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

✅ Success! Your agent project is ready.

Apri il progetto nell'editor di Cloud Shell. In questo modo, la finestra viene ricaricata e il terminale viene riavviato:

cloudshell workspace ~/durian-advisor

Installa le dipendenze del progetto nella relativa cartella .venv:

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

Controlla il file dell'ambiente

Agents CLI ha anche scritto un file .env che indica ad ADK di chiamare Gemini tramite il tuo progetto Google Cloud:

grep GOOGLE_ ~/durian-advisor/.env

Dovresti visualizzare un output simile al seguente:

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

Conserva GOOGLE_CLOUD_LOCATION=global. Gemini 3.8 Flash viene fornito dall'endpoint global, non da endpoint regionali come us-central1, anche se i tuoi servizi Cloud Run vengono eseguiti in us-central1.

Se GOOGLE_CLOUD_PROJECT mostra your-gcp-project-id, l'interfaccia a riga di comando degli agenti non è riuscita a rilevare il tuo progetto. Impostalo con:

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

Scrivi il classificatore di immagini

Ogni cultivar ha dei segni sul guscio che Gemini può individuare in una foto:

Guida visiva alle cultivar di durian che mostra gli indicatori della base e delle spine di Musang King, Black Thorn, Red Prawn e D24

Apri app/agent.py:

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

Sostituisci i contenuti con il seguente codice:

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

Ecco alcuni dettagli importanti:

  • MODEL è l'unico punto in cui viene visualizzato l'ID modello. Ogni agente aggiunto in un secondo momento lo eredita, quindi il passaggio da un modello all'altro richiede una sola riga di codice.
  • retry_options riprova a risolvere gli errori temporanei, come i limiti di frequenza, fino a tre volte.
  • app = App(...) esegue il wrapping dell'agente sia per il playground sia per il server Cloud Run. Mantieni il nome dell'app app e il nome dell'agente durian_advisor, che corrispondono al server generato e a agents-cli-manifest.yaml.

Testa l'agente nel playground

Avvia il playground ADK:

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

Dovresti visualizzare un output simile al seguente:

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

Fai clic su Anteprima web nella barra degli strumenti di Cloud Shell e seleziona Anteprima sulla porta 8080. Se la UI di sviluppo ADK ti chiede di scegliere un agente, seleziona app. Poi invia questo prompt o allega la tua foto di un durian con il pulsante di caricamento:

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?

🔍 Controlla il tuo lavoro

L'agente identifica il Musang King (D197) e assegna un punteggio di freschezza elevato per il gambo verde umido. Poi ammette ciò che una foto non può dirgli: l'aroma, il suono del tocco, l'elasticità delle spine e se il sapore ti piacerà.

Premi Ctrl + C nel terminale per interrompere il playground prima di procedere.

6. Aggiungi i sensi umani e la memoria del palato

Una fotocamera non può annusare, sentire o toccare, quindi creerai strumenti che chiedono all'acquirente di farlo. Inoltre, l'agente avrà una memoria a lungo termine dei gusti di ogni acquirente. In questo passaggio scriverai gli strumenti, mentre nel passaggio successivo li collegherai agli agenti.

Aggiungi il catalogo delle cultivar

Crea app/durian_data.py:

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

Incolla questo catalogo di riferimento. La conservazione dei dati nel proprio modulo mantiene breve il codice dell'agente:

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

Aggiungi gli strumenti sensoriali

Crea app/sensory_tools.py:

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

Incolla il seguente codice:

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

Come funzionano questi strumenti:

  • ADK trasforma ogni funzione in uno strumento che il modello può chiamare. La docstring diventa la descrizione dello strumento e la sezione Args spiega ogni parametro.
  • I suggerimenti di tipo Literal[...] diventano scelte fisse nello schema dello strumento, quindi Gemini deve mappare "ha un odore un po' alcolico" esattamente a un valore consentito, ad esempio boozy_fermented.
  • get_cultivar_profile restituisce uno stato NOT_FOUND esplicito con le chiavi supportate anziché inventare una cultivar.

Aggiungi lo strumento per la memoria del palato

Crea app/memory_tools.py:

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

Incolla il seguente codice:

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

Come funziona la memoria del palato:

  • ADK passa automaticamente tool_context e lo nasconde al modello, in modo che Gemini veda solo i due parametri di gusto.
  • Il prefisso user: limita la chiave di stato all'utente anziché alla sessione corrente, in modo che il profilo segua l'acquirente in ogni nuova conversazione.
  • Non è necessario uno strumento "get" separato. Gli agenti leggono il profilo direttamente nelle loro istruzioni con il segnaposto {user:palate_profile?}. ? rende vuoto il segnaposto quando non esiste ancora un profilo, anziché generare un errore.

🔍 Controlla il tuo lavoro

Scegli un durian che abbia un odore alcolico, un suono vuoto quando lo colpisci e spine elastiche:

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

Dovresti visualizzare un output simile al seguente:

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

7. Coordinare gli agenti specializzati

Un singolo agente che gestisce regole visive, punteggi sensoriali e abbinamenti di sapori in un unico prompt spesso si confonde. Invece, assegnerai ogni attività a uno specialista dedicato e lascerai che un coordinatore combini le risposte:

  • vision_inspector_agent legge la varietà e la freschezza dalla foto e restituisce un report strutturato.
  • sensory_sommelier_agent valuta l'odore, il suono e la sensazione al tatto, oltre a verificare la cultivar in base al suo palato.
  • durian_advisor parla con l'acquirente, salva il suo palato, chiama ogni specialista e scrive il verdetto finale.

Crea l'ispettore visivo

Crea app/vision_agent.py:

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

Incolla il seguente codice:

"""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 fa sì che lo specialista restituisca dati strutturati su cui il coordinatore può fare affidamento.
  • include_contents="default" consente a questo esperto di visualizzare la conversazione, inclusa la foto caricata. Senza, uno specialista single-turn vede solo la richiesta passata dal coordinatore.
  • disallow_transfer_to_parent e disallow_transfer_to_peers rimuovono lo strumento transfer_to_agent che l'ADK altrimenti darebbe a questo subagente. Un esperto che vede l'intera conversazione è tentato di restituire la chat al coordinatore anziché restituire il suo report.

Crea il sommelier sensoriale

Crea app/sensory_agent.py:

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

Incolla il seguente codice:

"""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 definisce ciò che il coordinatore deve trasmettere: la cultivar e i tre report sensoriali dell'acquirente, con parole sue. L'esperto mappa queste parole ai valori consentiti dello strumento.
  • {user:palate_profile?} inserisce il palato salvato dell'acquirente nell'istruzione, in modo che lo specialista possa valutare l'idoneità senza dover consultare la memoria.
  • Nessun set di esperti model. Entrambi ereditano l'elemento MODEL del coordinatore.
  • Entrambi gli specialisti utilizzano gli stessi due flag di trasferimento, quindi ognuno di loro riferisce sempre al coordinatore.

Cablare il coordinatore

Apri app/agent.py:

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

Sostituisci i contenuti con il coordinatore:

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

Poiché entrambi gli specialisti utilizzano mode="single_turn", ADK fornisce al coordinatore due strumenti aggiuntivi denominati vision_inspector_agent e sensory_sommelier_agent. L'istruzione fa riferimento a questi nomi.

Testa il coordinator nel playground

Avvia di nuovo il playground:

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

Apri l'Anteprima web sulla porta 8080 e avvia questa breve conversazione con l'agente.

Insegna a Gemini i tuoi gusti:

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

Apri la scheda Stato. Dovresti vedere il tuo profilo salvato, simile a:

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

Mostragli un durian (descrivilo o allega una foto):

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?

Il coordinatore chiama vision_inspector_agent, che identifica un XO D24. Poi ti chiede di annusare la cucitura, toccare il guscio e premere due spine insieme.

Segnala ciò che hai percepito:

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

Inizia da zero: fai clic su Nuova sessione e chiedi:

Which durian should I pick today?

🔍 Controlla il tuo lavoro

  • Dopo aver riferito le tue sensazioni, il coordinatore chiama sensory_sommelier_agent e dà un verdetto: l'XO D24 è maturo (9 su 10), ma la sua elevata amarezza si scontra con il tuo palato, quindi chiedi invece un Red Prawn (D175) o un Black Thorn (D200).
  • Nella scheda Eventi, puoi vedere durian_advisor chiamare ogni specialista e sensory_sommelier_agent chiamare evaluate_human_sensory_clues e get_cultivar_profile.
  • Nella nuova sessione, l'agente conosce già i tuoi gusti e ti consiglia una varietà dolce e non amara senza chiederti di nuovo.

Premi Ctrl + C nel terminale per interrompere il playground.

8. (Facoltativo) Esegui il deployment con Antigravity

Hai creato e testato l'agente manualmente. Ora consentirai ad Antigravity CLI (agy), l'agente di programmazione AI di Google per il terminale, di eseguirne il deployment. Le competenze di Agents CLI insegnano ad Antigravity come eseguire il deployment di un agente ADK in modo corretto.

Abilita le API di deployment

Abilita le API Cloud Run, Cloud Build e Artifact Registry, utilizzate dall'interfaccia a riga di comando degli agenti per creare e ospitare l'agente:

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

Dovresti visualizzare un output simile al seguente:

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

Installa le skill di Agents CLI

Installa le sette skill di Agents CLI nella cartella del progetto, dove Antigravity le rileva automaticamente:

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

🔍 Controlla il tuo lavoro

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

Dovresti visualizzare un output simile al seguente:

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

Avvia Antigravity CLI

Antigravity CLI è preinstallato in Cloud Shell. Avviala dalla cartella del progetto:

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

Alla prima esecuzione, Antigravity ti chiede di accedere con il tuo Account Google, scegliere un tema cromatico, accettare i Termini di servizio e considerare attendibile la cartella corrente.

Chiedi ad Antigravity di eseguire il deployment

Incolla questo prompt in 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 legge la skill e potrebbe eseguire prima i test del progetto. Poi esegue agents-cli deploy, che crea il container con Cloud Build ed esegue il deployment del servizio durian-advisor, quindi invia un messaggio di test al servizio live. L'intera esecuzione richiede dai 5 agli 8 minuti.

Al termine di Antigravity, esci premendo Ctrl + D due volte.

🔍 Controlla il tuo lavoro

Invia un messaggio all'agente di cui è stato eseguito il deployment utilizzando l'URL salvato da Antigravity:

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

Dovresti visualizzare un output simile al seguente:

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

Ora verifica che il servizio rifiuti le chiamate senza token:

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

Dovresti visualizzare un output simile al seguente:

403

9. (Facoltativo) Crea il chatbot web in vibe coding

L'agente è attivo, ma privato. Ora riprenderai la conversazione con Antigravity, che conosce già il tuo agente, le sue chiavi di stato e il suo URL, e gli chiederai di creare ed eseguire il deployment di un chatbot web per gli acquirenti di durian.

Riprendi Antigravity

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

All'interno di Antigravity, esegui il seguente comando slash e seleziona la conversazione di deployment dall'elenco:

/resume

Chiedi ad Antigravity di creare il chatbot

Incolla questo 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 scrive l'app, crea il service account, gli concede il ruolo Cloud Run Invoker su durian-advisor ed esegue il deployment dell'app con Cloud Build. In genere, testa l'endpoint della chat prima di terminare. L'intera esecuzione richiede circa dieci minuti. Quando viene stampato l'URL, esci premendo due volte Ctrl + D.

🔍 Controlla il tuo lavoro

Apri l'URL https://durian-sommelier-web-....run.app stampato da Antigravity, quindi:

  1. Tocca un pulsante del palato, ad esempio quello dolce e cremoso. L'agente conferma di aver salvato il tuo palato.
  2. Carica una foto del durian o digita una breve descrizione del guscio. L'agente identifica la cultivar e ti chiede di eseguire i controlli sensoriali.
  3. Tocca i chip sensoriali corrispondenti al tuo durian. L'agente risponde con un unico verdetto che copre la maturazione e l'idoneità al palato.

10. Esegui la pulizia

Elimina le risorse che hai creato per interrompere gli addebiti.

Elimina i servizi Cloud Run

Elimina il chatbot web:

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

Elimina il servizio dell'agente:

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

Elimina l'account di servizio

Elimina il service account con cui è stato eseguito il chatbot web:

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

Elimina le immagini container

I deployment dall'origine di Cloud Run eseguono il push dell'immagine container di ogni servizio in un repository Artifact Registry denominato cloud-run-source-deploy, che può essere condiviso da altri deployment nel progetto. Elimina solo le due immagini di questo codelab e conserva il repository.

Elimina l'immagine dell'agente:

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

Elimina l'immagine del chatbot web:

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

🔍 Controlla il tuo lavoro

gcloud run services list --region us-central1

Dovresti visualizzare un output simile al seguente:

Listed 0 items.

Elimina i file locali

Rimuovi la cartella del progetto, incluse le skill e l'ambiente virtuale:

rm -rf ~/durian-advisor

Facoltativamente, disinstalla Agents CLI:

uv tool uninstall google-agents-cli

(Facoltativo) Elimina l'intero progetto Google Cloud

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

11. Complimenti

Complimenti! Hai creato e testato un sistema multi-agente multimodale Durian Sommelier con ADK e Agents CLI. Se hai seguito i passaggi facoltativi, hai anche eseguito il deployment in Cloud Run con l'interfaccia a riga di comando Antigravity.

Risultati ottenuti

  • Hai creato un'impalcatura di un progetto ADK con agents-cli create e un agente di visione multimodale con una singola impostazione MODEL
  • Strumenti human-in-the-loop integrati per odore, suono e tatto, oltre a una memoria del palato archiviata nello stato ADK con ambito user:
  • Suddividi l'agente in un coordinatore durian_advisor e due specialisti single_turn che chiama come strumenti
  • (Facoltativo) Utilizzato Antigravity CLI con le competenze di Agents CLI per eseguire il deployment dell'agente e di un chatbot web in Cloud Run

Passaggi successivi