Multimodalen Durian-Sommelier mit ADK und Antigravity erstellen

1. Übersicht

An einem Straßenstand eine gute Durian auszuwählen, ist eine Herausforderung für die Sinne. Käufer müssen eine echte Musang King (D197) von einer ähnlich aussehenden Frucht unterscheiden, beurteilen, ob die Frucht heute Morgen oder vor Tagen gefallen ist, und erraten, ob sie ihnen überhaupt schmecken wird.

In diesem Codelab erstellen und testen Sie ein multimodales Multi-Agenten-System für einen Durian-Sommelier mit dem Agent Development Kit (ADK) und der Agents CLI. Optional können Sie es mit der Antigravity CLI in Cloud Run bereitstellen. Die Hauptschritte dauern etwa 45 Minuten, die beiden optionalen Antigravity-Schritte etwa 20 Minuten. Die Wahl einer Durian zeigt, wo die KI-Wahrnehmung endet und die menschlichen Sinne beginnen:

  • Was die KI sehen kann: Gemini kann ein Foto der Schale analysieren und Merkmale der Sorte erkennen, z. B. den fünfzackigen Stern an der Basis einer Musang King, die dunkle, eingefallene Spitze einer Black Thorn (D200), den münzgroßen Ring einer D24 oder einen trockenen, schrumpeligen Stiel.
  • Was nur ein Mensch wahrnehmen kann: Ein Modell kann nicht an der Naht riechen, um eine alkoholische Note zu erkennen, auf die Schale klopfen, um ein hohles Geräusch zu hören, oder zwei Dornen zusammendrücken, um zu fühlen, ob sie zurückfedern.
  • Was sich der Agent merken muss: Zwei perfekt reife Durianfrüchte spalten die Käufer immer noch. Eine Person liebt den bitteren, alkoholischen Geschmack einer XO D24 von einem alten Baum, während eine andere den süßen, bitterfreien Geschmack einer Red Prawn (D175) bevorzugt.

Die sensorische Grenze der Durian: KI-Vision im Vergleich zu menschlichen Sinnen

Aufgaben

  • Phase 1 – KI-Agent für die Bilderkennung: Ein ADK-KI-Agent, der mit der Agents CLI erstellt wurde und die Sorte und Frische einer Durian anhand eines Fotos erkennt.
  • Phase 2 – Menschliche Sinne und Geschmackserinnerung: Tools, die bewerten, was der Käufer riecht, hört und fühlt, sowie ein Tool, das sein Geschmacksprofil sitzungsübergreifend speichert.
  • Phase 3 – Koordinator und Spezialisten: Ein durian_advisor-Koordinator, der einen Vision Inspector und einen Sensory Sommelier aufruft und dann ein klares Urteil abgibt.
  • Phase 4 – Cloud Run-Agentendienst: In einem optionalen Schritt stellt die Antigravity CLI Ihren Agenten mit den Agents CLI-Skills bereit.
  • Phase 5 – Cloud Run-Web-Chatbot: In einem weiteren optionalen Schritt erstellt und stellt die Antigravity CLI eine für Mobilgeräte optimierte Chat-App bereit, die mit Ihrem Agenten kommuniziert.

Architektur

Durian Sommelier-Architektur: Ein Cloud Run-Web-Chatbot ruft den durian_advisor-Koordinator in Cloud Run auf, der wiederum Vision- und Sensorikspezialisten aufruft und die Vorlieben des Käufers im ADK-Sitzungsstatus speichert.

Die beiden Cloud Run-Dienste stammen aus den optionalen Antigravity-Schritten. Ohne sie führen Sie dieselben Agents im ADK-Playground in Cloud Shell aus.

Vorbereitung

  • Grundlegende Kenntnisse in der Programmierung mit Python
  • Kenntnisse über Befehlszeilentools und Konzepte der generativen KI
  • Es sind keine Vorkenntnisse mit ADK, Agents CLI oder Antigravity CLI erforderlich.

Lerninhalte

  • ADK-Projekt mit agents-cli create erstellen und einen multimodalen Agenten entwickeln, der Fotos liest
  • Wo die KI-Wahrnehmung aufhört (Geruch, Klang, Berührung und persönlicher Geschmack) und wie Human-in-the-Loop-Tools für diese Sinne entwickelt werden können
  • Wie Sie die Einstellungen der einzelnen Nutzer über Sitzungen hinweg mit dem ADK-Zustand im Bereich user: speichern
  • Wie Sie einen KI-Agenten in einen Koordinator und Spezialisten-KI-Agenten für einzelne Turns aufteilen, die er wie Tools aufruft
  • Optional: Wie Sie der Antigravity CLI die Agents CLI-Fähigkeiten verleihen, damit sie Ihren Agenten und einen Web-Chatbot in Cloud Run bereitstellen kann

Voraussetzungen

  • Ein Google-Konto (verwenden Sie ein privates @gmail.com-Konto, wenn Sie Workshop-Guthaben einlösen möchten)
  • Einen Link für Workshop-Guthaben von Ihrem Kursleiter (plus eine Smartphone-Kamera zum Scannen des QR-Codes) oder ein aktives Cloud-Rechnungskonto
  • Google Chrome (ein Inkognitofenster wird empfohlen, um eine Vermischung von privaten und geschäftlichen Konten zu vermeiden)

2. Google Cloud-Guthaben einlösen (optional)

Wenn Sie dieses Codelab selbstständig absolvieren und die Voraussetzungen erfüllen, können Sie über das Banner für das Google Developer Program auf dieser Seite Guthaben ohne Kreditkarte anfordern. Wenn Sie an einem Workshop mit einem Link für Event-Guthaben von Ihrem Kursleiter teilnehmen, folgen Sie der Anleitung für Event-Guthaben in diesem Abschnitt.

Event-Guthaben einlösen

Sie können Guthaben für Workshop-Veranstaltungen über den Google Builders Hub (Teil des Google Developer Program) beantragen.

So lösen Sie Ihr Event-Guthaben ein:

  1. Öffnen Sie den Link für das Workshop-Guthaben in einem Inkognitofenster und melden Sie sich mit Ihrem privaten @gmail.com-Konto an.
  2. Klicken Sie auf der Karte Vorteil einlösen auf Guthaben einlösen.

Karte „Vorteil einlösen“ im Google Builders Hub mit der Schaltfläche „Guthaben einlösen“

  1. Optional: Wenn Sie aufgefordert werden, ein Google Developer Program-Profil zu erstellen, füllen Sie das Formular aus.
  2. Wenn das Dialogfeld Scannen, um zu bestätigen, dass du ein Mensch bist angezeigt wird, scannen Sie den QR-Code mit Ihrem Smartphone und schließen Sie die Bestätigung ab. Wenn der QR-Code nicht angezeigt wird, aktualisieren Sie die Seite und klicken Sie noch einmal auf Guthaben einlösen.
  3. Prüfen Sie, ob die Meldung Sie haben Ihr Event-Guthaben erhalten. angezeigt wird, und klicken Sie dann auf Rechnungskonto öffnen.

Bestätigungskarte im Google Builders Hub mit der Meldung „Sie haben Ihr Event-Guthaben erhalten“ und der Schaltfläche „Rechnungskonto öffnen“.

🔍 Arbeit überprüfen lassen

Die Bereitstellung des Rechnungskontos kann bis zu fünf Minuten dauern. So prüfen Sie, ob Ihr Guthaben aktiv ist:

  1. Wenn die Seite Verwaltung des Rechnungskontos noch nicht geöffnet ist, öffnen Sie Google Cloud Billing (oder kopieren Sie die URL in Ihr Inkognitofenster):
https://console.cloud.google.com/billing
  1. Klicken Sie auf den Tab Meine Rechnungskonten und aktualisieren Sie die Seite, bis ein Konto mit GDP-Guthaben in der Spalte Status als Aktiv angezeigt wird.

Seite „Kontoverwaltung“ in Google Cloud Billing mit einem aktiven Cloud-Rechnungskonto für GDP-Guthaben.

3. Google Cloud-Projekt erstellen (optional)

Erstellen Sie ein dediziertes Google Cloud-Projekt, um alle Ressourcen aus diesem Codelab isoliert zu halten, damit Sie sie nach Abschluss des Codelabs sauber entfernen können.

So erstellen Sie ein Google Cloud-Projekt:

  1. Öffnen Sie Projekt erstellen oder kopieren Sie die URL in Ihr Inkognitofenster:
https://console.cloud.google.com/projectcreate
  1. Geben Sie die Projektdetails ein:
    • Projektname: Geben Sie einen aussagekräftigen Namen ein, z. B. google-cloud-workshop.
    • Rechnungskonto (falls angezeigt): Wählen Sie Ihr GDP-Guthabenkonto (oder Ihr aktives Rechnungskonto) aus.
    • Übergeordnete Ressource: Lassen Sie Keine Organisation ausgewählt (oder wählen Sie bei Bedarf Ihre Organisation aus).
  2. Notieren Sie sich die generierte Projekt-ID und klicken Sie dann auf Erstellen.

Formular „Google Cloud-Projekt erstellen“ mit dem Projektnamen, der generierten Projekt-ID, der übergeordneten Ressource und der Schaltfläche „Erstellen“

🔍 Arbeit überprüfen lassen

Öffnen Sie nach Abschluss der Projekterstellung in der Symbolleiste der Google Cloud Console die Benachrichtigungen und klicken Sie dann auf Projekt auswählen.

Menü „Benachrichtigungen“ in der Google Cloud Console mit „Projekt erstellen“ und dem Link „Projekt auswählen“.

4. Umgebung einrichten

In diesem Abschnitt richten Sie die Google Cloud Shell ein, aktivieren die Agent Platform API und installieren die Agents CLI mit uv.

Cloud Shell konfigurieren

Cloud Shell starten

Öffnen Sie die Google Cloud Shell mit aktiviertem Code-Editor und aktivierter Terminalansicht (oder kopieren Sie die URL in Ihr Inkognitofenster) und klicken Sie auf Autorisieren, wenn Sie dazu aufgefordert werden:

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

Dialogfeld „Cloud Shell autorisieren“

Google Cloud-Projekt-ID festlegen

Kopieren Sie das folgende Snippet und fügen Sie es in Ihr Cloud Shell-Terminal ein. Es wird ein nummeriertes Menü Ihrer verfügbaren Google Cloud-Projekte angezeigt. Geben Sie die Nummer neben Ihrem Projekt ein (z. B. 1) und drücken Sie die Eingabetaste:

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

Erwarteter Prompt:

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.

Die ausgewählte Projekt-ID sollte jetzt in der Cloud Shell-Terminal-Eingabeaufforderung gelb hervorgehoben sein:

Cloud Shell-Terminal mit gelb hervorgehobener ausgewählter Projekt-ID

Agent Platform API aktivieren

Aktivieren Sie die Agent Platform API, die Ihre Agenten zum Aufrufen von Gemini verwenden:

gcloud services enable aiplatform.googleapis.com

🔍 Arbeit überprüfen lassen

Die Ausgabe sollte etwa so aussehen:

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

Agents CLI installieren

Prüfen Sie, ob uv verfügbar ist und sich der Toolordner in Ihrem PATH befindet:

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

Installieren Sie die Agents CLI als uv-Tool:

uv tool install google-agents-cli==1.7.0

uv installiert jedes Tool in einer eigenen isolierten Umgebung und fügt nur den Befehl agents-cli zu Ihrer PATH hinzu, sodass die Python-Installation Ihres Systems unberührt bleibt. Sie müssen das ADK auch nicht selbst installieren. Jedes Projekt, das von Agents CLI erstellt wird, erhält eine eigene virtuelle Umgebung mit einer ADK-Version, mit der die Vorlage getestet wurde.

🔍 Arbeit überprüfen lassen

Prüfen Sie, ob die Agents CLI bereit ist:

agents-cli --version

Die Ausgabe sollte etwa so aussehen:

agents-cli, version 1.7.0

5. Multimodalen Vision-Agenten erstellen

Fangen Sie klein an: Erstellen Sie mit der Agents CLI ein ADK-Projekt und wandeln Sie den Beispiel-Agenten in einen Durian-Vision-Klassifikator um.

Projektstruktur erstellen

Generieren Sie das Projekt durian-advisor. --agent adk_python wählt die Python-ADK-Vorlage aus, --deployment-target cloud_run und --region us-central1 bereiten sie für Cloud Run vor, --prototype überspringt die CI/CD-Einrichtung und --yes akzeptiert die Standardeinstellungen:

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

Die Ausgabe sollte etwa so aussehen:

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

✅ Success! Your agent project is ready.

Öffnen Sie das Projekt im Cloud Shell-Editor. Dadurch wird das Fenster neu geladen und das Terminal neu gestartet:

cloudshell workspace ~/durian-advisor

Installieren Sie die Projektabhängigkeiten in einem eigenen .venv-Ordner:

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

Umgebungsdatei prüfen

Die Agents CLI hat außerdem eine .env-Datei geschrieben, die das ADK anweist, Gemini über Ihr Google Cloud-Projekt aufzurufen:

grep GOOGLE_ ~/durian-advisor/.env

Die Ausgabe sollte etwa so aussehen:

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

GOOGLE_CLOUD_LOCATION=global behalten. Gemini 3.8 Flash wird über den Endpunkt global bereitgestellt, nicht über regionale Endpunkte wie us-central1, obwohl Ihre Cloud Run-Dienste in us-central1 ausgeführt werden.

Wenn für GOOGLE_CLOUD_PROJECT der Wert your-gcp-project-id angezeigt wird, konnte die Agents CLI Ihr Projekt nicht erkennen. Legen Sie sie so fest:

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

Vision-Klassifikator schreiben

Jede Sorte hat Schalenmerkmale, die Gemini auf einem Foto erkennen kann:

Visueller Leitfaden für Durian-Sorten, der die Basis- und Dornenmerkmale von Musang King, Black Thorn, Red Prawn und D24 zeigt

Rufen Sie app/agent.py auf:

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

Ersetzen Sie den Inhalt durch den folgenden Code:

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

Hier sind einige Details wichtig:

  • MODEL ist die einzige Stelle, an der die Modell-ID angezeigt wird. Jeder Agent, den Sie später hinzufügen, übernimmt diese Einstellung. Ein Modellwechsel ist also mit einer einzigen Zeile erledigt.
  • retry_options wiederholt vorübergehende Fehler wie Ratenbegrenzungen bis zu dreimal.
  • app = App(...) umschließt den KI-Agenten sowohl für den Playground als auch für den Cloud Run-Server. Behalten Sie den App-Namen app und den Agent-Namen durian_advisor bei, die mit dem generierten Server und agents-cli-manifest.yaml übereinstimmen.

KI-Agenten im Playground testen

Starten Sie den ADK-Playground:

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

Die Ausgabe sollte etwa so aussehen:

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

Klicken Sie in der Cloud Shell-Symbolleiste auf Webvorschau und wählen Sie Vorschau auf Port 8080 aus. Wenn Sie in der ADK-Entwicklungsoberfläche aufgefordert werden, einen KI-Agenten auszuwählen, wählen Sie app aus. Senden Sie dann diesen Prompt oder hängen Sie über die Schaltfläche zum Hochladen ein eigenes Foto einer Durian an:

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?

🔍 Arbeit überprüfen lassen

Der Agent identifiziert Musang King (D197) und gibt eine hohe Frischebewertung für den feuchten grünen Stiel. Dann gibt es zu, was es anhand eines Fotos nicht erkennen kann: das Aroma, das Klopfgeräusch, die Elastizität der Dornen und ob dir der Geschmack gefallen wird.

Drücken Sie im Terminal Ctrl + C, um den Playground zu beenden, bevor Sie fortfahren.

6. Menschliche Sinne und Geschmackserinnerung hinzufügen

Eine Kamera kann nicht riechen, hören oder fühlen. Deshalb entwickeln Sie Tools, die den Käufer dazu auffordern, dies zu tun. Außerdem geben Sie dem KI-Agenten ein Langzeitgedächtnis für den Geschmack der einzelnen Käufer. In diesem Schritt schreiben Sie die Tools. Im nächsten Schritt binden Sie sie in Agenten ein.

Katalog der Sorten hinzufügen

app/durian_data.py erstellen:

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

Fügen Sie diesen Referenzkatalog ein. Wenn Sie Daten in einem eigenen Modul speichern, bleibt der KI-Agentencode kurz:

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

Sensorische Tools hinzufügen

app/sensory_tools.py erstellen:

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

Fügen Sie den folgenden Code ein:

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

So funktionieren diese Tools:

  • Das ADK wandelt jede Funktion in ein Tool um, das vom Modell aufgerufen werden kann. Der Docstring wird zur Toolbeschreibung und im Abschnitt Args werden die einzelnen Parameter erläutert.
  • Die Literal[...]-Typhinweise werden zu festen Auswahlmöglichkeiten im Toolschema. Gemini muss also „riecht ein bisschen nach Alkohol“ genau einem zulässigen Wert zuordnen, z. B. boozy_fermented.
  • get_cultivar_profile gibt einen expliziten NOT_FOUND-Status mit den unterstützten Schlüsseln zurück, anstatt eine Sorte zu erfinden.

Tool „Palate Memory“ hinzufügen

app/memory_tools.py erstellen:

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

Fügen Sie den folgenden Code ein:

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

So funktioniert das Geschmacksgedächtnis:

  • Das ADK übergibt tool_context automatisch und verbirgt es vor dem Modell, sodass Gemini nur die beiden Geschmacksparameter sieht.
  • Das Präfix user: beschränkt den Zustandsschlüssel auf den Nutzer und nicht auf die aktuelle Sitzung. Das Profil folgt dem Käufer also in jede neue Unterhaltung.
  • Sie benötigen kein separates „get“-Tool. KI-Agenten lesen das Profil mit dem Platzhalter {user:palate_profile?} direkt in ihre Anweisungen ein. Mit ? wird der Platzhalter leer gelassen, wenn noch kein Profil vorhanden ist, anstatt einen Fehler auszugeben.

🔍 Arbeit überprüfen lassen

Finde eine Durian, die nach Alkohol riecht, hohl klingt und elastische Dornen hat:

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

Die Ausgabe sollte etwa so aussehen:

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

7. Spezial-KI-Agenten koordinieren

Ein einzelner Agent, der visuelle Regeln, sensorische Bewertungen und die Abstimmung auf den Geschmack in einem einzigen Prompt verarbeiten muss, ist oft überfordert. Stattdessen weisen Sie jede Aufgabe einem spezialisierten Agenten zu und lassen einen Koordinator die Antworten zusammenfassen:

  • vision_inspector_agent liest die Sorte und Frische aus dem Foto und gibt einen strukturierten Bericht zurück.
  • sensory_sommelier_agent bewertet, was der Käufer gerochen, gehört und gefühlt hat, und prüft die Sorte auf seinen Geschmack.
  • durian_advisor spricht mit dem Käufer, speichert seine Vorlieben, ruft die einzelnen Spezialisten an und schreibt das endgültige Urteil.

Vision Inspector erstellen

app/vision_agent.py erstellen:

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

Fügen Sie den folgenden Code ein:

"""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 sorgt dafür, dass der Spezialist strukturierte Daten zurückgibt, auf die sich der Koordinator verlassen kann.
  • include_contents="default" kann die Unterhaltung, einschließlich des hochgeladenen Fotos, sehen. Ohne diesen Kontext sieht ein Single-Turn-Spezialist nur die Anfrage, die der Koordinator weitergibt.
  • disallow_transfer_to_parent und disallow_transfer_to_peers entfernen das Tool transfer_to_agent, das das ADK diesem Sub-Agenten sonst zur Verfügung stellen würde. Ein Spezialist, der die gesamte Unterhaltung sieht, ist versucht, den Chat an den Koordinator zurückzugeben, anstatt seinen Bericht zurückzugeben.

Sensorischen Sommelier erstellen

app/sensory_agent.py erstellen:

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

Fügen Sie den folgenden Code ein:

"""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 definiert, was der Koordinator übergeben muss: die Sorte und die drei sensorischen Berichte des Käufers in seinen eigenen Worten. Der Spezialist ordnet diese Wörter den zulässigen Werten des Tools zu.
  • {user:palate_profile?} fügt die gespeicherten Vorlieben des Käufers in die Anweisung ein, damit der Spezialist die Passform beurteilen kann, ohne die gemerkten Informationen abrufen zu müssen.
  • Keiner der Spezialisten legt model fest. Beide übernehmen die MODEL des Koordinators.
  • Beide Spezialisten verwenden dieselben zwei Transfer-Flags, sodass jeder immer an den Koordinator zurückmeldet.

Koordinator verbinden

Rufen Sie app/agent.py auf:

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

Ersetzen Sie den Inhalt durch den Koordinator:

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

Da beide Spezialisten mode="single_turn" verwenden, stellt das ADK dem Koordinator zwei zusätzliche Tools namens vision_inspector_agent und sensory_sommelier_agent zur Verfügung. In der Anweisung werden sie mit diesen Namen referenziert.

Koordinator im Playground testen

Starten Sie den Playground noch einmal:

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

Öffnen Sie die Webvorschau auf Port 8080 und führen Sie die folgende kurze Unterhaltung mit dem Agenten.

Lerne deinen Geschmack kennen:

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

Öffnen Sie den Tab Status. Sie sollten Ihr gespeichertes Profil sehen, ähnlich wie:

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

Zeige ihm eine Durian (beschreibe sie oder hänge ein Foto an):

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?

Der Koordinator ruft vision_inspector_agent auf, wodurch ein XO D24 identifiziert wird. Dann werden Sie aufgefordert, an der Naht zu riechen, auf die Schale zu klopfen und zwei Dornen zusammenzudrücken.

Berichte, was du wahrgenommen hast:

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

Neu beginnen: Klicken Sie auf Neue Sitzung und fragen Sie:

Which durian should I pick today?

🔍 Arbeit überprüfen lassen

  • Nachdem du deine Eindrücke geschildert hast, ruft der Koordinator sensory_sommelier_agent an und gibt ein Urteil ab: Die XO D24 ist reif (9 von 10), aber ihre starke Bitterkeit passt nicht zu deinem Gaumen. Frage stattdessen nach einer Red Prawn (D175) oder einer Black Thorn (D200).
  • Auf dem Tab Ereignisse sehen Sie, dass durian_advisor die einzelnen Spezialisten aufruft und sensory_sommelier_agent die Spezialisten evaluate_human_sensory_clues und get_cultivar_profile aufruft.
  • In der neuen Sitzung kennt der Agent bereits Ihren Geschmack und empfiehlt eine süße, nicht bittere Sorte, ohne noch einmal nachzufragen.

Drücken Sie im Terminal Ctrl + C, um den Playground zu beenden.

8. Mit Antigravity bereitstellen (optional)

Sie haben den KI-Agenten manuell erstellt und getestet. Jetzt lassen Sie die Antigravity CLI (agy), den KI-Programmier-Agenten von Google für das Terminal, die Bereitstellung übernehmen. Die Agents CLI-Skills bringen Antigravity bei, wie ein ADK-Agent korrekt bereitgestellt wird.

Bereitstellungs-APIs aktivieren

Aktivieren Sie die APIs für Cloud Run, Cloud Build und Artifact Registry, die von der Agents CLI zum Erstellen und Hosten Ihres Agenten verwendet werden:

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

Die Ausgabe sollte etwa so aussehen:

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

Agents CLI-Skills installieren

Installieren Sie die sieben Agents CLI-Skills in Ihrem Projektordner, wo sie von Antigravity automatisch erkannt werden:

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

🔍 Arbeit überprüfen lassen

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

Die Ausgabe sollte etwa so aussehen:

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 starten

Die Antigravity CLI ist in der Cloud Shell vorinstalliert. Starten Sie es aus Ihrem Projektordner:

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

Beim ersten Start werden Sie aufgefordert, sich mit Ihrem Google-Konto anzumelden, ein Farbschema auszuwählen, die Nutzungsbedingungen zu akzeptieren und dem aktuellen Ordner zu vertrauen.

Antigravity bitten, etwas bereitzustellen

Fügen Sie diesen Prompt in Antigravity ein:

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 liest den Skill und führt möglicherweise zuerst die Tests des Projekts aus. Anschließend wird agents-cli deploy ausgeführt, wodurch der Container mit Cloud Build erstellt und der Dienst durian-advisor bereitgestellt wird. Außerdem wird eine Testnachricht an den Live-Dienst gesendet. Die gesamte Ausführung dauert etwa fünf bis acht Minuten.

Wenn Antigravity beendet ist, beenden Sie es, indem Sie zweimal Ctrl + D drücken.

🔍 Arbeit überprüfen lassen

Senden Sie eine Nachricht an den bereitgestellten KI-Agenten. Verwenden Sie dazu die von Antigravity gespeicherte URL:

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

Die Ausgabe sollte etwa so aussehen:

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

Prüfen Sie jetzt, ob der Dienst Aufrufe ohne Token ablehnt:

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

Die Ausgabe sollte etwa so aussehen:

403

9. Web-Chatbot per Vibe Coding erstellen (optional)

Ihr KI-Agent ist live, aber privat. Jetzt setzen Sie die Antigravity-Unterhaltung fort, die Ihren Agenten, seine Zustandsschlüssel und seine URL bereits kennt, und bitten ihn, einen Web-Chatbot für Durian-Käufer zu erstellen und bereitzustellen.

Antigravity fortsetzen

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

Führen Sie in Antigravity den folgenden Slash-Befehl aus und wählen Sie Ihre Bereitstellungsunterhaltung aus der Liste aus:

/resume

Antigravity auffordern, den Chatbot zu erstellen

Fügen Sie diesen Prompt ein:

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 schreibt die Anwendung, erstellt das Dienstkonto, weist ihm die Rolle Cloud Run-Aufrufer für durian-advisor zu und stellt die Anwendung mit Cloud Build bereit. In der Regel wird der Chat-Endpunkt getestet, bevor der Vorgang abgeschlossen wird. Die gesamte Ausführung dauert etwa zehn Minuten. Wenn die URL ausgegeben wird, beenden Sie den Vorgang, indem Sie zweimal Ctrl + D drücken.

🔍 Arbeit überprüfen lassen

Öffnen Sie die von Antigravity ausgegebene https://durian-sommelier-web-....run.app-URL und führen Sie dann die folgenden Schritte aus:

  1. Tippe auf eine Geschmacksschaltfläche, z. B. „Süß und cremig“. Der KI-Agent bestätigt, dass er deine Vorlieben gespeichert hat.
  2. Laden Sie ein Foto einer Durian hoch oder geben Sie eine kurze Beschreibung der Schale ein. Der Agent identifiziert die Sorte und bittet Sie, die Pflanze mit Ihren Sinnen zu prüfen.
  3. Tippe auf die sensorischen Chips, die zu deiner Durian passen. Der KI-Agent antwortet mit einem Urteil, das sowohl die Reife als auch die Eignung für den Gaumen abdeckt.

10. Bereinigen

Löschen Sie die erstellten Ressourcen, damit keine Gebühren mehr anfallen.

Cloud Run-Dienste löschen

So löschen Sie den Web-Chatbot:

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

Löschen Sie den Agentendienst:

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

Dienstkonto löschen

Löschen Sie das Dienstkonto, unter dem der Web-Chatbot ausgeführt wurde:

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

Container-Images löschen

Bei Cloud Run-Quellbereitstellungen wird das Container-Image jedes Dienstes in ein Artifact Registry-Repository mit dem Namen cloud-run-source-deploy übertragen, das von anderen Bereitstellungen in Ihrem Projekt gemeinsam genutzt werden kann. Löschen Sie nur die beiden Images dieses Codelabs und behalten Sie das Repository.

Bild des KI-Agenten löschen:

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

Löschen Sie das Image des Web-Chatbots:

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

🔍 Arbeit überprüfen lassen

gcloud run services list --region us-central1

Die Ausgabe sollte etwa so aussehen:

Listed 0 items.

Lokale Dateien löschen

Entfernen Sie den Projektordner, einschließlich der Skills und der virtuellen Umgebung:

rm -rf ~/durian-advisor

Optional: Agents CLI deinstallieren:

uv tool uninstall google-agents-cli

Gesamtes Google Cloud-Projekt löschen (optional)

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

11. Glückwunsch

Glückwunsch! Sie haben ein multimodales Multi-Agenten-System Durian Sommelier mit dem ADK und der Agents CLI erstellt und getestet. Wenn Sie die optionalen Schritte ausgeführt haben, haben Sie die Anwendung auch mit der Antigravity CLI in Cloud Run bereitgestellt.

Was Sie erreicht haben

  • Ein ADK-Projekt mit agents-cli create erstellt und einen multimodalen Vision-Agenten mit einer einzigen MODEL-Einstellung erstellt
  • Human-in-the-Loop-Tools für Geruch, Ton und Berührung sowie ein Geschmacksspeicher, der im ADK-Zustand mit user:-Bereich gespeichert wird
  • Agenten in einen durian_advisor-Koordinator und zwei single_turn-Spezialisten aufteilen, die er wie Tools aufruft
  • (Optional) Antigravity CLI mit den Agents CLI-Skills verwendet, um den Agenten und einen Web-Chatbot in Cloud Run bereitzustellen

Nächste Schritte