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

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

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 createi 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:
- Otwórz link do środków na warsztaty w oknie incognito i zaloguj się na swoje osobiste konto
@gmail.com. - Na karcie Odbierz korzyści kliknij Odbierz środki.

- Opcjonalnie: jeśli zobaczysz prośbę o utworzenie profilu w programie Google Developer Program, wypełnij formularz.
- 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.
- 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).

🔍 Sprawdź swoją pracę
Udostępnianie konta rozliczeniowego może potrwać do 5 minut. Aby sprawdzić, czy środki są aktywne, wykonaj te czynności:
- 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
- Kliknij kartę Twoje konta rozliczeniowe i odświeżaj stronę, aż w kolumnie Stan przy koncie zawierającym środki GDP pojawi się wartość Aktywne.

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:
- Otwórz Utwórz projekt (lub skopiuj adres URL do okna incognito):
https://console.cloud.google.com/projectcreate
- 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).
- Nazwa projektu: wpisz opisową nazwę, np.
- Zapisz wygenerowany identyfikator projektu i kliknij 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.

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

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:

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:

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_optionsponawia 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ę aplikacjiappi nazwę agentadurian_advisor, które pasują do wygenerowanego serwera iagents-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
Argswyjaś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_profilezwraca wyraźny stanNOT_FOUNDz 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_contexti 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_agentodczytuje ze zdjęcia odmianę i świeżość, a następnie zwraca ustrukturyzowany raport.sensory_sommelier_agentocenia zapach, dźwięk i odczucia kupującego, a także sprawdza, czy odmiana odpowiada jego podniebieniu.durian_advisorrozmawia 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=VisionReportsprawia, ż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_parentidisallow_transfer_to_peersusuwają narzędzietransfer_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=SensoryCluesokreś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ąMODELkoordynatora. - 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_agenti 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_advisordzwoni do każdego specjalisty, asensory_sommelier_agentdzwoni doevaluate_human_sensory_cluesiget_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:
- Kliknij przycisk smaku, np. słodki i kremowy. Agent potwierdza, że zapisał Twoje podniebienie.
- Prześlij zdjęcie duriana lub wpisz krótki opis jego skorupy. Agent identyfikuje odmianę i prosi o przeprowadzenie kontroli sensorycznej.
- 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 createi zbudowaliśmy multimodalnego agenta wizyjnego z jednym ustawieniemMODEL; - 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_advisori 2 specjalistówsingle_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
- Jeśli je pominiesz, wróć do opcjonalnych kroków Antigravity, aby wdrożyć agenta i czatbota internetowego w Cloud Run.
- Utrwalanie pamięci podniebienia dzięki usłudze sesji opartej na bazie danych
- Mierzenie jakości odpowiedzi za pomocą
agents-cli eval - Zapoznaj się z dokumentacją pakietu Agent Development Kit (ADK).
- Dowiedz się więcej o interfejsie wiersza poleceń agentów.
- Zapoznaj się z dokumentacją Cloud Run.
- Dołącz do programu GEAR (Gemini Enterprise Agent Ready), aby wziąć udział w warsztatach i ścieżkach szkoleniowych.