Tworzenie multimodalnego sommeliera durianów za pomocą pakietu ADK i Antigravity

1. Przegląd

Wybór dobrego duriana na przydrożnym straganie to zagadka sensoryczna. Kupujący muszą odróżnić prawdziwego Musang Kinga (D197) od podobnego owocu, ocenić, czy owoc spadł tego ranka czy kilka dni temu, i zgadnąć, czy w ogóle będzie im smakował.

W tym ćwiczeniu utworzysz i przetestujesz multimodalny system wieloagentowy Durian Sommelier za pomocą pakietu Agent Development Kit (ADK) i interfejsu wiersza poleceń agentów, a opcjonalnie wdrożysz go w Cloud Run za pomocą interfejsu wiersza poleceń Antigravity (podstawowe kroki zajmują około 45 minut, a 2 opcjonalne kroki Antigravity dodają około 20 minut). Wybór duriana pokazuje, gdzie kończy się percepcja AI, a gdzie zaczynają się ludzkie zmysły:

  • Co widzi AI: Gemini może przeanalizować zdjęcie skorupy i wykryć cechy odmiany, takie jak pięcioramienna gwiazda u podstawy Musang King, ciemny, zapadnięty czubek Black Thorn (D200), pierścień wielkości monety D24 lub sucha, pomarszczona łodyga.
  • Co może wyczuć tylko człowiek: model nie może powąchać szwu, aby wyczuć nutę alkoholu, postukać w łupinę, aby usłyszeć głuchy dźwięk, ani nacisnąć 2 kolców, aby sprawdzić, czy odskakują.
  • O czym musi pamiętać agent: 2 idealnie dojrzałe duriany nadal dzielą kupujących. Jedna osoba uwielbia gorzki, alkoholowy smak odmiany XO D24, a inna woli słodki, pozbawiony goryczy krem odmiany Red Prawn (D175).

Granica sensoryczna duriana: AI Vision a ludzkie zmysły

Co utworzysz

  • Etap 1 – agent z pojedynczym modelem wizyjnym: agent ADK utworzony za pomocą interfejsu wiersza poleceń agentów, który na podstawie zdjęcia identyfikuje odmianę i świeżość duriana.
  • Etap 2 – ludzkie zmysły i pamięć podniebienia: narzędzia, które oceniają to, co kupujący czuje, słyszy i odczuwa, oraz narzędzie, które zapisuje profil smakowy kupującego między sesjami.
  • Etap 3 – koordynator i specjaliści: koordynator durian_advisor, który wywołuje inspektora wizualnego i sommeliera sensorycznego, a następnie wydaje jeden jasny werdykt.
  • Etap 4 – usługa agenta Cloud Run: W opcjonalnym kroku Antigravity CLI wdraża agenta z umiejętnościami interfejsu wiersza poleceń agentów.
  • Etap 5 – czatbot internetowy Cloud Run: w kolejnym opcjonalnym kroku Antigravity CLI tworzy i wdraża aplikację do obsługi czatu dostosowaną do komórek, która komunikuje się z Twoim agentem.

Architektura

Architektura Durian Sommelier: chatbot internetowy Cloud Run wywołuje koordynatora durian_advisor w Cloud Run, który wywołuje specjalistów ds. wzroku i zmysłów oraz przechowuje informacje o preferencjach kupującego w stanie sesji ADK

Te 2 usługi Cloud Run pochodzą z opcjonalnych kroków Antigravity. Bez nich uruchamiasz tych samych agentów w środowisku testowym ADK w Cloud Shell.

Wymagania wstępne

  • podstawowa znajomość programowania w Pythonie,
  • Znajomość narzędzi wiersza poleceń i pojęć związanych z generatywną AI.
  • Nie jest wymagane wcześniejsze doświadczenie z pakietem ADK, interfejsem wiersza poleceń agentów ani Antigravity CLI.

Czego się nauczysz

  • Jak utworzyć projekt ADK za pomocą agents-cli create i zbudować agenta multimodalnego, który odczytuje zdjęcia.
  • gdzie kończy się percepcja AI (zapach, dźwięk, dotyk i osobiste preferencje) oraz jak projektować narzędzia z udziałem człowieka dla tych zmysłów;
  • Jak zapamiętywać preferencje każdego użytkownika w ramach różnych sesji za pomocą stanu ADK o zakresie user:
  • jak podzielić jednego agenta na koordynatora i wyspecjalizowanych agentów, którzy odpowiadają na pojedyncze pytania i są wywoływani przez koordynatora jak narzędzia;
  • opcjonalnie: jak przekazać Antigravity CLI umiejętności interfejsu wiersza poleceń agentów, aby umożliwić wdrożenie agenta i czatbota internetowego w Cloud Run.

Czego potrzebujesz

  • konto Google (jeśli chcesz otrzymać środki na warsztaty, użyj osobistego konta @gmail.com).
  • link do środków na warsztaty od instruktora (oraz aparat w telefonie do zeskanowania kodu QR) lub aktywne konto rozliczeniowe Cloud.
  • Google Chrome (zalecamy używanie okna incognito, aby uniknąć mieszania kont osobistych i służbowych).

2. Odbierz środki na Google Cloud (opcjonalnie)

Jeśli wykonujesz ten ćwiczenie we własnym zakresie i spełniasz wymagania, użyj banera środków w Google Developer Program na tej stronie, aby odebrać środki bez karty kredytowej. Jeśli uczestniczysz w warsztatach i masz link do środków na wydarzenie od instruktora, wykonaj czynności opisane w tej sekcji.

Odbierz środki na wydarzenie

Środki na warsztaty możesz odebrać w Google Builders Hub (w ramach programu Google Developer Program).

Aby odebrać środki na wydarzenie, wykonaj te czynności:

  1. Otwórz link do środków na warsztaty w oknie incognito i zaloguj się na swoje osobiste konto @gmail.com.
  2. Na karcie Odbierz korzyści kliknij Odbierz środki.

Karta „Odbierz korzyści” w Google Builders Hub z przyciskiem „Odbierz środki”.

  1. Opcjonalnie: jeśli zobaczysz prośbę o utworzenie profilu w programie Google Developer Program, wypełnij formularz.
  2. Gdy pojawi się okno Zeskanuj, aby potwierdzić, że jesteś człowiekiem, zeskanuj kod QR telefonem i dokończ weryfikację. Jeśli kod QR się nie pojawi, odśwież stronę i ponownie kliknij Odbierz środki.
  3. Sprawdź, czy pojawił się komunikat Successfully claimed your event credit! (Środki na wydarzenie zostały odebrane), a następnie kliknij Open Billing Account (Otwórz konto rozliczeniowe).

Karta potwierdzenia w Google Builders Hub z informacją o odebraniu środków na wydarzenie i przyciskiem Otwórz konto rozliczeniowe.

🔍 Sprawdź swoją pracę

Udostępnianie konta rozliczeniowego może potrwać do 5 minut. Aby sprawdzić, czy środki są aktywne, wykonaj te czynności:

  1. Jeśli strona Zarządzanie kontem rozliczeniowym nie jest jeszcze otwarta, otwórz Rozliczenia usługi Google Cloud (lub skopiuj adres URL do okna incognito):
https://console.cloud.google.com/billing
  1. Kliknij kartę Twoje konta rozliczeniowe i odświeżaj stronę, aż w kolumnie Stan przy koncie zawierającym środki GDP pojawi się wartość Aktywne.

Strona zarządzania kontem rozliczeniowym Google Cloud z aktywnym kontem rozliczeniowym środków GDP.

3. Tworzenie projektu Google Cloud (opcjonalnie)

Utwórz dedykowany projekt w chmurze Google, aby odizolować wszystkie zasoby z tego ćwiczenia i móc je łatwo usunąć po zakończeniu.

Aby utworzyć projekt Google Cloud, wykonaj te czynności:

  1. Otwórz Utwórz projekt (lub skopiuj adres URL do okna incognito):
https://console.cloud.google.com/projectcreate
  1. Wpisz szczegóły projektu:
    • Nazwa projektu: wpisz opisową nazwę, np. google-cloud-workshop.
    • Konto rozliczeniowe (jeśli jest widoczne): wybierz konto GDP Credit (lub aktywne konto rozliczeniowe).
    • Zasób nadrzędny: pozostaw wybraną opcję Brak organizacji (lub wybierz organizację, jeśli jest to wymagane).
  2. Zapisz wygenerowany identyfikator projektu i kliknij Utwórz.

Formularz tworzenia projektu w chmurze Google z nazwą projektu, wygenerowanym identyfikatorem projektu, zasobem nadrzędnym i przyciskiem Utwórz.

🔍 Sprawdź swoją pracę

Po zakończeniu tworzenia projektu otwórz Powiadomienia na pasku narzędzi konsoli Google Cloud, a następnie kliknij Wybierz projekt.

Menu Powiadomienia w konsoli Google Cloud z opcją Utwórz projekt i linkiem Wybierz projekt.

4. Konfigurowanie środowiska

W tej sekcji skonfigurujesz Google Cloud Shell, włączysz interfejs Agent Platform API i zainstalujesz interfejs wiersza poleceń agentów za pomocą uv.

Konfigurowanie Cloud Shell

Uruchamianie Cloud Shell

Otwórz Google Cloud Shell z włączonym edytorem kodu i widokiem terminala (lub skopiuj adres URL do okna incognito) i kliknij Autoryzuj, jeśli pojawi się taka prośba:

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

Okno dialogowe autoryzacji Cloud Shell

Ustawianie identyfikatora projektu Google Cloud

Skopiuj i wklej ten fragment kodu w terminalu Cloud Shell. Wyświetli się ponumerowane menu dostępnych projektów w chmurze Google Cloud. Wpisz numer obok projektu (np. 1) i naciśnij Enter:

unset CLOUDSDK_CORE_PROJECT
PS3="Select your project (e.g. 1): "
select PROJECT_ID in $(gcloud projects list --format="value(projectId)"); do
  [ -n "$PROJECT_ID" ] && gcloud config set project "$PROJECT_ID" && break
done

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

Wybrany identyfikator projektu powinien być teraz podświetlony na żółto w terminalu Cloud Shell:

Terminal Cloud Shell z wybranym identyfikatorem projektu zaznaczonym na żółto

Włączanie interfejsu Agent Platform API

Włącz interfejs Agent Platform API, którego agenci używają do wywoływania Gemini:

gcloud services enable aiplatform.googleapis.com

🔍 Sprawdź swoją pracę

Dane wyjściowe powinny być podobne do tych:

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

Instalowanie interfejsu wiersza poleceń agentów

Sprawdź, czy narzędzie uv jest dostępne, a jego folder znajduje się w zmiennej PATH:

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

Zainstaluj interfejs wiersza poleceń agentów jako narzędzie uv:

uv tool install google-agents-cli==1.7.0

uv instaluje każde narzędzie we własnym odizolowanym środowisku i dodaje tylko polecenie agents-cli do PATH, dzięki czemu Python w systemie pozostaje nienaruszony. Nie musisz też samodzielnie instalować ADK. Każdy projekt utworzony przez interfejs wiersza poleceń agentów otrzymuje własne środowisko wirtualne z wersją ADK, z którą szablon został przetestowany.

🔍 Sprawdź swoją pracę

Sprawdź, czy interfejs wiersza poleceń agentów jest gotowy:

agents-cli --version

Dane wyjściowe powinny być podobne do tych:

agents-cli, version 1.7.0

5. Tworzenie szkieletu agenta multimodalnego rozpoznawania obrazów

Zacznij od małych kroków: użyj interfejsu wiersza poleceń agentów, aby wygenerować projekt ADK, a następnie przekształć przykładowego agenta w klasyfikator wizualny durianów.

Tworzenie szkieletu projektu

Wygeneruj projekt durian-advisor. --agent adk_python wybiera szablon ADK w Pythonie, --deployment-target cloud_run i --region us-central1 przygotowują go do Cloud Run, --prototype pomija konfigurację CI/CD, a --yes akceptuje wartości domyślne:

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

Dane wyjściowe powinny być podobne do tych:

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

✅ Success! Your agent project is ready.

Otwórz projekt w edytorze Cloud Shell. Spowoduje to ponowne załadowanie okna i uruchomienie terminala:

cloudshell workspace ~/durian-advisor

Zainstaluj zależności projektu w jego własnym folderze .venv:

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

Sprawdzanie pliku środowiska

Interfejs wiersza poleceń agentów zapisał też plik .env, który informuje pakiet ADK, aby wywoływał Gemini przez Twój projekt w chmurze Google Cloud:

grep GOOGLE_ ~/durian-advisor/.env

Dane wyjściowe powinny być podobne do tych:

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

Zachowaj GOOGLE_CLOUD_LOCATION=global. Gemini 3.8 Flash jest obsługiwany z punktu końcowego global, a nie z punktów końcowych regionu, takich jak us-central1, mimo że usługi Cloud Run działają w regionie us-central1.

Jeśli w polu GOOGLE_CLOUD_PROJECT wyświetla się your-gcp-project-id, interfejs wiersza poleceń agentów nie mógł wykryć Twojego projektu. Ustaw go za pomocą:

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

Tworzenie klasyfikatora wizyjnego

Każda odmiana ma znaczniki na skorupie, które Gemini może rozpoznać na zdjęciu:

Przewodnik wizualny po odmianach duriana pokazujący podstawę i kolce odmian Musang King, Black Thorn, Red Prawn i D24

Otwórz app/agent.py:

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

Zastąp jego zawartość tym kodem:

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

Ważne są tu pewne szczegóły:

  • Identyfikator modelu jest widoczny tylko w sekcji MODEL. Każdy agent, którego dodasz później, odziedziczy go, więc przełączanie modeli wymaga tylko jednej zmiany.
  • retry_options ponawia próby w przypadku błędów tymczasowych, takich jak ograniczanie liczby żądań, maksymalnie 3 razy.
  • app = App(...) opakowuje agenta zarówno w przypadku środowiska testowego, jak i serwera Cloud Run. Zachowaj nazwę aplikacji app i nazwę agenta durian_advisor, które pasują do wygenerowanego serwera i agents-cli-manifest.yaml.

Testowanie agenta w środowisku testowym

Uruchom środowisko testowe ADK:

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

Dane wyjściowe powinny być podobne do tych:

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

Na pasku narzędzi Cloud Shell kliknij Podgląd w przeglądarce i wybierz Podejrzyj na porcie 8080. Jeśli interfejs ADK Dev UI poprosi Cię o wybranie agenta, wybierz app. Następnie wyślij tego prompta lub załącz własne zdjęcie duriana za pomocą przycisku przesyłania:

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?

🔍 Sprawdź swoją pracę

Agent identyfikuje Musang King (D197) i przyznaje wysoką ocenę świeżości ze względu na wilgotną zieloną łodygę. Następnie przyznaje, czego nie może stwierdzić na podstawie zdjęcia: zapachu, dźwięku pukania, sprężystości kolców i tego, czy smak będzie Ci odpowiadał.

Zanim przejdziesz dalej, naciśnij Ctrl + C w terminalu, aby zatrzymać Playground.

6. Dodaj ludzkie zmysły i pamięć smaku

Kamera nie ma węchu, słuchu ani dotyku, więc musisz stworzyć narzędzia, które poproszą kupującego o wykorzystanie tych zmysłów. Zapewnisz też agentowi długoterminową pamięć o preferencjach każdego kupującego. W tym kroku napiszesz narzędzia, a w następnym połączysz je z agentami.

Dodawanie katalogu odmian

Utwórz app/durian_data.py:

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

Wklej ten katalog referencyjny. Przechowywanie danych we własnym module pozwala zachować krótki kod agenta:

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

Dodawanie narzędzi sensorycznych

Utwórz app/sensory_tools.py:

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

Wklej ten kod:

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

Jak działają te narzędzia:

  • ADK przekształca każdą funkcję w narzędzie, które model może wywołać. Docstring staje się opisem narzędzia, a sekcja Args wyjaśnia każdy parametr.
  • Wskazówki dotyczące typu Literal[...] stają się stałymi opcjami w schemacie narzędzia, więc Gemini musi zmapować „pachnie trochę alkoholem” na dokładnie 1 dozwoloną wartość, np. boozy_fermented.
  • get_cultivar_profile zwraca wyraźny stan NOT_FOUND z obsługiwanymi kluczami zamiast wymyślać odmianę.

Dodaj narzędzie do zapamiętywania smaków

Utwórz app/memory_tools.py:

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

Wklej ten kod:

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

Jak działa pamięć podniebienia:

  • ADK automatycznie przekazuje parametr tool_context i ukrywa go przed modelem, więc Gemini widzi tylko 2 parametry dotyczące smaku.
  • Prefiks user: ogranicza zakres klucza stanu do użytkownika, a nie bieżącej sesji, dzięki czemu profil podąża za kupującym do każdej nowej rozmowy.
  • Nie potrzebujesz osobnego narzędzia do pobierania. Agenci odczytują profil bezpośrednio w instrukcjach za pomocą obiektu zastępczego {user:palate_profile?}. Jeśli profil jeszcze nie istnieje, ? powoduje, że obiekt zastępczy jest pusty, zamiast zgłaszać błąd.

🔍 Sprawdź swoją pracę

Wybierz duriana, który pachnie alkoholem, wydaje głuchy dźwięk i ma sprężyste kolce:

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

Dane wyjściowe powinny być podobne do tych:

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

7. Koordynowanie agentów specjalistycznych

Pojedynczy agent, który w jednym prompcie musi połączyć reguły dotyczące wyglądu, ocenę sensoryczną i dopasowanie do podniebienia, często się gubi. Zamiast tego przydzielisz każde zadanie wyspecjalizowanemu agentowi, a koordynator połączy ich odpowiedzi:

  • vision_inspector_agent odczytuje ze zdjęcia odmianę i świeżość, a następnie zwraca ustrukturyzowany raport.
  • sensory_sommelier_agent ocenia zapach, dźwięk i odczucia kupującego, a także sprawdza, czy odmiana odpowiada jego podniebieniu.
  • durian_advisor rozmawia z kupującym, zapisuje jego preferencje, dzwoni do każdego specjalisty i pisze ostateczną opinię.

Tworzenie inspektora wizyjnego

Utwórz app/vision_agent.py:

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

Wklej ten kod:

"""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 sprawia, że specjalista zwraca uporządkowane dane, na których koordynator może polegać.
  • include_contents="default" umożliwia temu specjaliście wyświetlanie rozmowy, w tym przesłanego zdjęcia. Bez niego specjalista od pojedynczych odpowiedzi widzi tylko prośbę przekazaną przez koordynatora.
  • disallow_transfer_to_parent i disallow_transfer_to_peers usuwają narzędzie transfer_to_agent, które ADK przyznałby temu subagentowi. Specjalista, który widzi całą rozmowę, może ulec pokusie przekazania czatu z powrotem koordynatorowi zamiast przesłania raportu.

Tworzenie sommeliera sensorycznego

Utwórz app/sensory_agent.py:

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

Wklej ten kod:

"""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 określa, co koordynator musi przekazać: odmianę i 3 raporty sensoryczne kupującego, opisane własnymi słowami. Specjalista mapuje te słowa na dozwolone wartości narzędzia.
  • {user:palate_profile?} umieszcza zapisane preferencje kupującego w instrukcji, dzięki czemu specjalista może ocenić dopasowanie bez konieczności sprawdzania pamięci.
  • Żaden specjalista nie ustawia model. Oba dziedziczą MODEL koordynatora.
  • Obaj specjaliści używają tych samych 2 flag przeniesienia, więc każdy z nich zawsze przekazuje informacje koordynatorowi.

Połączenie koordynatora

Otwórz app/agent.py:

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

Zastąp jego zawartość koordynatorem:

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

Ponieważ obaj specjaliści korzystają z mode="single_turn", ADK udostępnia koordynatorowi 2 dodatkowe narzędzia o nazwach vision_inspector_agent i sensory_sommelier_agent. Instrukcja odnosi się do nich pod tymi nazwami.

Testowanie koordynatora w środowisku testowym

Ponownie uruchom środowisko testowe:

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

Otwórz Podgląd w przeglądarce na porcie 8080 i przeprowadź krótką rozmowę z agentem.

Naucz Gemini swoich preferencji:

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

Otwórz kartę Stan. Powinien pojawić się zapisany profil, podobny do tego:

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

Pokaż mu duriana (opisz go lub załącz zdjęcie):

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?

Koordynator wywołuje vision_inspector_agent, który identyfikuje XO D24. Następnie prosi o powąchanie szwu, postukanie w łupinę i ściśnięcie 2 kolców.

Zgłaszanie tego, co widzisz:

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

Zacznij od nowa: kliknij Nowa sesja i zapytaj:

Which durian should I pick today?

🔍 Sprawdź swoją pracę

  • Po przekazaniu informacji o swoich wrażeniach koordynator dzwoni do sensory_sommelier_agent i wydaje jeden werdykt: XO D24 jest dojrzały (9 na 10), ale jego wysoka gorycz nie pasuje do Twojego podniebienia, więc poproś o Red Prawn (D175) lub Black Thorn (D200).
  • Na karcie Zdarzenia możesz zobaczyć, że durian_advisor dzwoni do każdego specjalisty, a sensory_sommelier_agent dzwoni do evaluate_human_sensory_clues i get_cultivar_profile.
  • W nowej sesji agent zna już Twoje preferencje i poleca słodką odmianę bez goryczy, nie pytając o to ponownie.

Aby zatrzymać Playground, naciśnij Ctrl + C w terminalu.

8. Wdrażanie za pomocą Antigravity (opcjonalnie)

Agent został utworzony i przetestowany ręcznie. Teraz wdrożysz ją za pomocą Antigravity CLI (agy), agenta AI od Google do kodowania w terminalu. Umiejętności interfejsu wiersza poleceń agentów uczą Antigravity, jak prawidłowo wdrażać agenta ADK.

Włączanie interfejsów API wdrażania

Włącz interfejsy Cloud Run API, Cloud Build API i Artifact Registry API, których interfejs wiersza poleceń agentów używa do tworzenia i hostowania agenta:

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

Dane wyjściowe powinny być podobne do tych:

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

Instalowanie umiejętności interfejsu wiersza poleceń agentów

Zainstaluj 7 umiejętności interfejsu wiersza poleceń agentów w folderze projektu, gdzie Antigravity wykryje je automatycznie:

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

🔍 Sprawdź swoją pracę

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

Dane wyjściowe powinny być podobne do tych:

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

Uruchamianie Antigravity CLI

Interfejs Antigravity CLI jest wstępnie zainstalowany w Cloud Shell. Uruchom go z folderu projektu:

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

Przy pierwszym uruchomieniu Antigravity poprosi Cię o zalogowanie się na konto Google, wybranie motywu kolorystycznego, zaakceptowanie warunków korzystania z usługi i zaufanie bieżącemu folderowi.

Poproś Antigravity o wdrożenie

Wklej tego prompta w 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 odczytuje umiejętność i może najpierw uruchomić testy projektu. Następnie uruchamia agents-cli deploy, który tworzy kontener za pomocą Cloud Build i wdraża usługę durian-advisor, a także wysyła wiadomość testową do działającej usługi. Cały proces trwa około 5–8 minut.

Po zakończeniu działania Antigravity wyjdź z niego, naciskając dwukrotnie Ctrl + D.

🔍 Sprawdź swoją pracę

Wyślij wiadomość do wdrożonego agenta, używając adresu URL zapisanego przez Antigravity:

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

Dane wyjściowe powinny być podobne do tych:

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

Teraz sprawdź, czy usługa odrzuca wywołania bez tokena:

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

Dane wyjściowe powinny być podobne do tych:

403

9. Zastosuj vibe coding i stwórz czatbota internetowego (opcjonalnie)

Twój agent jest aktywny, ale prywatny. Teraz wznowisz rozmowę z Antigravity, która zna już Twojego agenta, jego klucze stanu i adres URL, i poprosisz o utworzenie i wdrożenie chatbota internetowego dla kupujących duriany.

Wznów Antigravity

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

W Antigravity uruchom to polecenie po ukośniku i wybierz z listy rozmowę dotyczącą wdrożenia:

/resume

Poproś Antigravity o utworzenie czatbota

Wklej tego prompta:

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 pisze aplikację, tworzy konto usługi, przypisuje mu rolę wywołującego Cloud Run w usłudze durian-advisor i wdraża aplikację za pomocą Cloud Build. Zwykle przed zakończeniem testuje punkt końcowy czatu. Cały proces trwa około 10 minut. Gdy pojawi się adres URL, wyjdź, naciskając dwukrotnie Ctrl + D.

🔍 Sprawdź swoją pracę

Otwórz adres URL https://durian-sommelier-web-....run.app wyświetlony przez Antigravity, a następnie:

  1. Kliknij przycisk smaku, np. słodki i kremowy. Agent potwierdza, że zapisał Twoje podniebienie.
  2. Prześlij zdjęcie duriana lub wpisz krótki opis jego skorupy. Agent identyfikuje odmianę i prosi o przeprowadzenie kontroli sensorycznej.
  3. Kliknij elementy sensoryczne, które pasują do Twojego duriana. Agent odpowiada, podając jedną ocenę, która obejmuje dojrzałość i dopasowanie do podniebienia.

10. Czyszczenie danych

Usuń utworzone zasoby, aby nie były już naliczane opłaty.

Usuwanie usług Cloud Run

Usuń czatbota internetowego:

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

Usuń usługę agenta:

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

Usuwanie konta usługi

Usuń konto usługi, którego używał internetowy chatbot:

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

Usuwanie obrazów kontenerów

Wdrożenia źródłowe Cloud Run przesyłają obraz kontenera każdej usługi do repozytorium Artifact Registry o nazwie cloud-run-source-deploy, które może być udostępniane innym wdrożeniom w Twoim projekcie. Usuń tylko 2 obrazy z tego ćwiczenia i zachowaj repozytorium.

Usuń obraz agenta:

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

Usuń obraz czatbota internetowego:

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

🔍 Sprawdź swoją pracę

gcloud run services list --region us-central1

Dane wyjściowe powinny być podobne do tych:

Listed 0 items.

Usuwanie plików lokalnych

Usuń folder projektu wraz z umiejętnościami i środowiskiem wirtualnym:

rm -rf ~/durian-advisor

Opcjonalnie odinstaluj interfejs wiersza poleceń agentów:

uv tool uninstall google-agents-cli

Usuwanie całego projektu w chmurze Google (opcjonalnie)

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

11. Gratulacje

Gratulacje! Udało Ci się utworzyć i przetestować multimodalny system wieloagentowy Durian Sommelier za pomocą ADK i interfejsu wiersza poleceń agentów. Jeśli wykonano opcjonalne kroki, aplikacja została też wdrożona w Cloud Run za pomocą Antigravity CLI.

osiągnięcia,

  • utworzyliśmy projekt ADK za pomocą polecenia agents-cli create i zbudowaliśmy multimodalnego agenta wizyjnego z jednym ustawieniem MODEL;
  • Narzędzia do rozpoznawania zapachu, dźwięku i dotyku z udziałem człowieka oraz pamięć podniebienia przechowywana w stanie ADK o zakresie user:
  • Podziel agenta na koordynatora durian_advisor i 2 specjalistów single_turn, których wywołuje on jak narzędzia.
  • (Opcjonalnie) Użycie interfejsu wiersza poleceń Antigravity CLI z umiejętnościami interfejsu wiersza poleceń agentów do wdrożenia agenta i czatbota internetowego w Cloud Run.

Dalsze kroki