Tworzenie agentów ADK na podstawie specyfikacji za pomocą narzędzi Antigravity i Spec-kit

1. Wprowadzenie

Dodawanie funkcji do istniejącego agenta – nowej funkcji opartej na bazie danych – zwykle oznacza pisanie kodu standardowego, konfigurowanie integracji i zapewnianie spójności ze wzorcami już istniejącymi w bazie kodu. Antigravity przyspiesza każdy etap tego procesu: analizuje bazę kodu, aby uzyskać potrzebny kontekst, tworzy uporządkowane specyfikacje i plany wdrożenia do sprawdzenia, a także wprowadza zmiany w kodzie – wszystko to na podstawie wiedzy o domenie, którą pomaga Ci gromadzić w postaci umiejętności wielokrotnego użytku i konstytucji projektu, która egzekwuje zasady niepodlegające negocjacjom. To ćwiczenie w Codelabs przedstawia sposób na zwiększenie możliwości paradygmatu rozwoju opartego na specyfikacjach Antigravity poprzez wprowadzenie nowego cyklu, który znacznie usprawnia dokumentację specyfikacji, w dużej mierze odwołując się do spec-kit.

Co utworzysz

Lokalnie działająca aplikacja konsjerża restauracji z funkcją rezerwacji dodaną w ramach pełnego cyklu SDD:

• Rezerwacja – goście mogą rezerwować stoliki i sprawdzać rezerwacje dzięki nowym narzędziom bazy danych MCP Toolbox i tabeli reservations Cloud SQL.
• (Challenge) – opracuj własny interfejs agenta.
• (Challenge) – wdrażanie w Google Cloud za pomocą agenta Antigravity

Kod startowy zawiera działającego agenta ADK z wyszukiwaniem menu (słowa kluczowe + semantyka za pomocą zestawu narzędzi MCP) i śledzeniem preferencji żywieniowych (za pomocą ToolContext). Możesz go rozszerzyć bez ręcznego pisania kodu aplikacji – Antigravity zajmie się implementacją na podstawie Twoich specyfikacji.

Czego się nauczysz

• Jak zainicjować kontekst projektu, aby Antigravity zrozumiał istniejącą bazę kodu
• Jak tworzyć umiejętności Antigravity, które zawierają wiedzę merytoryczną (np. wzorce ćwiczeń ADK) do ponownego wykorzystania
• Jak określić strukturę projektu, na podstawie której przepływy pracy SDD będą weryfikować dane podczas planowania i analizy
• Jak korzystać z przepływów pracy opartych na specyfikacji (SDD) w Antigravity, aby systematycznie dodawać funkcje
• Jak rozszerzyć agenta ADK o nowe narzędzia oparte na bazie danych za pomocą zestawu narzędzi MCP

Wymagania wstępne

• Google Antigravity i git zainstalowane na komputerze lokalnym.
• konto Google Cloud z włączonym próbnym kontem rozliczeniowym,
• Aby zrozumieć kontekst przypadków użycia, warto wcześniej ukończyć 4 samouczki ADK (lub mieć równoważną wiedzę):
• Tworzenie agentów AI z użyciem ADK: podstawy
• Tworzenie agentów AI z użyciem pakietu ADK: wzbogacanie narzędziami
• Tworzenie trwałych agentów AI z użyciem pakietu ADK i CloudSQL
• Wdrażanie agenta ADK w Cloud Run, zarządzanie nim i jego obserwacja
• Baza danych jako narzędzie: agentowy RAG z ADK, MCP Toolbox i Cloud SQL

2. Konfigurowanie środowiska

WAŻNE UWAGI:

Aby wykonać zadania z tego samouczka, musisz mieć projekt Google Cloud z aktywnym kontem rozliczeniowym. Jeśli jeszcze go nie masz, wykonaj poniższe czynności, aby uzyskać próbne konto rozliczeniowe, którego możesz użyć w tym samouczku:

1. Otwórz okno incognito
2. Jeśli dołączasz do sesji warsztatowej, adres URL portalu do wykorzystania środków jest zwykle podawany podczas sesji. W przeciwnym razie możesz przejść do portalu do wykorzystania środków na koncie rozliczeniowym w okresie próbnym.
3. Zaloguj się przy użyciu osobistego konta Gmail ( Google Workspace / inne adresy e-mail nie będą działać! )
4. Postępuj zgodnie ze szczegółowymi instrukcjami dotyczącymi wykorzystania.

W tym kroku sklonujesz repozytorium początkowe, uwierzytelnisz się w Google Cloud, udostępnisz bazę danych Cloud SQL i przygotujesz lokalne środowisko Antigravity.

Uwagi: ten codelab jest w całości uruchamiany w Google Antigravity na Twoim komputerze lokalnym. Konfiguracja obejmuje ręczne uwierzytelnianie za pomocą polecenia interfejsu wiersza poleceń gcloud

Klonowanie repozytorium początkowego

Otwórz terminal w Antigravity (lub terminal systemowy). Sklonuj repozytorium towarzyszące i przejdź do katalogu:

git clone https://github.com/alphinside/sdd-adk-antigravity-starter.git sdd-adk-agents-agy
cd sdd-adk-agents-agy

Otwórz sklonowane repozytorium w Antigravity. Plik > Otwórz folder > wybierz sklonowany katalog sdd-adk-agents-agy.

Usuń zdalne repozytorium nadrzędne. Przepływy pracy SDD tworzą gałęzie Git dla specyfikacji funkcji. Usunięcie zdalnego repozytorium zapobiega przypadkowemu wypychaniu zmian do repozytorium początkowego:

git remote remove origin

Ważne: przepływy pracy SDD w tym ćwiczeniu korzystają z gałęzi git do organizowania specyfikacji funkcji. Usunięcie zdalnego repozytorium origin gwarantuje, że lokalne gałęzie i zatwierdzenia pozostaną lokalne. Jeśli chcesz utworzyć kopię zapasową swojej pracy, dodaj własne repozytorium zdalne: git remote add origin <your-repo-url>

Instalowanie wstępnie wymaganych usług

Uruchom skrypt wymagań wstępnych. Sprawdza, czy są zainstalowane te elementy (i w razie potrzeby je instaluje): git, curl, gcloud, uv, Python 3.12 i MCP Toolbox:

bash scripts/setup_prerequisites.sh

Uwagi: pobranie wszystkich wymagań wstępnych zajmie trochę czasu. Otwórz nową kartę, aby przejść do następnej sekcji, podczas gdy pobieranie będzie się kończyć.

Uwierzytelnianie w Google Cloud

Uruchom dwa polecenia uwierzytelniania. Obie metody otwierają przeglądarkę na potrzeby OAuth:

gcloud auth login
gcloud auth application-default login

Uwagi: w przypadku drugiego polecenia protokołu OAuth, gdy pojawi się prośba o wybranie uprawnień. Sprawdź wszystkie opcje

Uwagi: Uwierzytelnij się za pomocą adresu e-mail, którego używasz do zgłoszenia roszczenia dotyczącego próbnego konta rozliczeniowego.

Ponieważ pracujesz lokalnie z Antigravity, musisz uwierzytelnić się ręcznie. auth login uwierzytelnia interfejs wiersza poleceń gcloud. application-default login uwierzytelnia pakiety SDK Google Cloud, których używa Twoja aplikacja – wywołania Vertex AI w pakiecie ADK i oprogramowanie sprzęgające Cloud SQL Python korzystają z domyślnego uwierzytelniania aplikacji.

Konfigurowanie projektu Google Cloud

Zanim uruchomisz skrypt konfiguracji projektu, zapisz zmienne lokalizacji w .env:

echo "GOOGLE_CLOUD_LOCATION=global" > .env
echo "REGION=us-central1" >> .env

• GOOGLE_CLOUD_LOCATION=global jest używany w przypadku wywołań interfejsu Vertex AI API / Gemini API.
• REGION=us-central1 jest używany w Cloud SQL i innej infrastrukturze GCP.

Pobierz i uruchom skrypt konfiguracji projektu. Tworzy lub weryfikuje projekt w chmurze Google z rozliczeniami w okresie próbnym i zapisuje identyfikator projektu w .env, a następnie go pobiera:

curl -sL https://raw.githubusercontent.com/alphinside/cloud-trial-project-setup/main/setup_verify_trial_project.sh -o setup_verify_trial_project.sh

bash setup_verify_trial_project.sh && source .env

Włącz wymagane interfejsy API:

gcloud services enable \
  aiplatform.googleapis.com \
  sqladmin.googleapis.com \
  compute.googleapis.com \
  cloudresourcemanager.googleapis.com

Uwagi: włączenie interfejsów API może chwilę potrwać. Wystarczy to zrobić raz w przypadku każdego projektu.

Aprowizowanie Cloud SQL

Ustaw hasło do bazy danych i dodaj je do .env:

export DB_PASSWORD=codelabpassword
echo "DB_PASSWORD=${DB_PASSWORD}" >> .env

Ważne: powyższe hasło zostało zakodowane na stałe tylko na potrzeby tego samouczka. W środowisku produkcyjnym przechowuj dane logowania w bezpieczny sposób, korzystając z usługi takiej jak Secret Manager, i odwołuj się do nich w czasie działania programu. Nigdy nie przesyłaj do systemu kontroli wersji obiektów tajnych w postaci zwykłego tekstu.

Utwórz instancję Cloud SQL:

gcloud sql instances create restaurant-db \
  --database-version=POSTGRES_17 \
  --edition=ENTERPRISE \
  --region=${REGION} \
  --availability-type=ZONAL \
  --tier=db-custom-1-3840 \
  --root-password=${DB_PASSWORD} \
  --enable-google-ml-integration \
  --database-flags cloudsql.enable_google_ml_integration=on &

Poziom db-custom-1-3840 jest minimalnym wymaganiem w przypadku integracji ML z Vertex AI. Flaga --enable-google-ml-integration umożliwia Cloud SQL wywoływanie modeli osadzania Gemini bezpośrednio z SQL, co jest podstawą funkcji wyszukiwania semantycznego.

Uwagi: wykonanie tego polecenia zajmuje około 5 minut i odbywa się w tle. Pozostaw go uruchomionego na tej karcie terminala i otwórz nową kartę terminala, aby wykonać kolejne kroki.

Instalowanie zależności

Otwórz nową kartę terminala. Sprawdź, czy nadal znajdujesz się w katalogu projektu sklonowanego repozytorium, i ponownie wczytaj zmienne środowiskowe:

source .env

Jako menedżera projektu Pythona będziemy używać uv. uv to szybki menedżer pakietów i projektów w Pythonie napisany w języku Rust ( dokumentacja ). W tym ćwiczeniu używamy go ze względu na szybkość i prostotę. Zainstaluj zależności Pythona:

uv sync

Następnie zaktualizuj plik .env agenta ADK za pomocą konfiguracji projektu:

cat > restaurant_concierge/.env <<EOF
GOOGLE_CLOUD_PROJECT=${GOOGLE_CLOUD_PROJECT}
GOOGLE_CLOUD_LOCATION=global
GOOGLE_GENAI_USE_VERTEXAI=True
EOF

Powinniśmy teraz mieć wszystkie wymagane repozytoria agenta pakietu ADK do pracy. W następnej sekcji omówimy szczegółowo Antigravity i oparte na specyfikacji tworzenie, a w tym czasie wszystko będzie gotowe.

3. Poznaj kod startowy i programowanie oparte na specyfikacji

W tym kroku omówimy strukturę kodu startowego, przedstawimy metodologię rozwoju opartą na specyfikacji, zainicjujemy bazę danych i sprawdzimy, czy podstawowy agent działa, zanim zaczniesz go rozbudowywać.

Struktura projektu

Otwórz sklonowany projekt repozytorium w edytorze Antigravity i sprawdź układ katalogów:

sdd-adk-agents-agy/
├── .agents/
│   ├── workflows/                 # SDD slash commands (/speckit.*) – manual trigger
│   │   ├── speckit.specify.md
│   │   ├── speckit.clarify.md
│   │   ├── speckit.plan.md
│   │   ├── speckit.tasks.md
│   │   ├── speckit.analyze.md
│   │   ├── speckit.implement.md
│   │   ├── speckit.checklist.md
│   │   └── speckit.constitution.md
│   ├── skills/                   # Antigravity skills (loaded on demand, agent determined)
│   │   ├── adk-agent-development/
│   │   │   ├── SKILL.md     # ADK patterns
│   │   │   └── examples/
│   │   │       ├── basic_agent.py
│   │   │       ├── Dockerfile
│   │   │       ├── server.py
│   │   │       ├── stateful_agent.py
│   │   │       ├── toolbox_agent.py
│   │   │       ├── tools_agent.py
│   │   │       └── tools.yaml
│   │   └── repo-research/
│   │       └── SKILL.md     # Repo analysis 
│   └── rules/               # Always-active context
├── .specify/                # spec-kit SDD templates and memory
│   ├── memory/constitution.md
│   ├── templates/
│   └── scripts/
├── restaurant_concierge/    # ADK agent package
│   ├── __init__.py
│   ├── agent.py             # LlmAgent + ToolContext tools + Toolbox integration
│   └── .env                 # Vertex AI configuration
├── server.py                # FastAPI server wrapping the agent
├── tools.yaml               # MCP Toolbox tool definitions
├── scripts/                 # Setup scripts
└── pyproject.toml

Pliki kluczy

Pliki aplikacji agenta

• restaurant_concierge/agent.py – podstawowy agent. LlmAgent, która łączy narzędzia baz danych MCP Toolbox ze śledzeniem preferencji żywieniowych opartym na ToolContext. Agent wczytuje wszystkie narzędzia z serwera Toolbox i dodaje 2 funkcje Pythona (save_dietary_preference, get_dietary_preferences), które używają ToolContext do zarządzania stanem.
• tools.yaml – definicje narzędzi w Zestawie narzędzi MCP. Zdefiniowane są 3 narzędzia wyszukiwania w menu: wyszukiwanie słów kluczowych (search_menu), wyszukiwanie semantyczne za pomocą pgvector (semantic_search_menu) i filtr kategorii (get_menu_by_category). Nie ma jeszcze narzędzi do rezerwacji – dodasz je później.
• server.py – minimalny serwer FastAPI, który pokazuje, jak uzyskać dostęp do ADK jako obiektu FastAPI. get_fast_api_app() z ADK udostępnia wbudowane punkty końcowe, w tym /run_sse do przesyłania strumieniowego SSE i interfejsy API do zarządzania sesjami.

Antigravity Files

• .agents/skills/adk-agent-development/SKILL.md – wstępnie skonfigurowana umiejętność ( wygenerowana przez Antigravity) zawierająca skrócone wzorce referencyjne ze wszystkich 4 laboratoriów ADK. Jest obecnie nieaktywny (brak metadanych YAML) – musisz go później zaktualizować. Antigravity automatycznie wczytuje tę umiejętność, gdy wykryje pracę związaną z funkcjami agenta ADK i ich przykładami. To właśnie ta wiedza będzie później kierować Antigravity podczas planowania funkcji rezerwacji.
• .agents/skills/repo-research/SKILL.md – umiejętność, która uczy Antigravity, jak analizować repozytorium przyrostowo i tworzyć dokument z kontekstem projektu w formie strukturalnej. Wykorzystuje 4-etapowe podejście: skanowanie powierzchniowe (tylko drzewo katalogów), pliki konfiguracyjne i metadane, punkty wejścia i modele danych, a następnie ukierunkowane szczegółowe analizy. Każdy etap kończy się zapisaniem wyników przed przejściem do następnego. Podobnie jak w przypadku umiejętności ADK, jest ona nieaktywna, dopóki nie dodasz później wstępu w formacie YAML. Po aktywowaniu wywołaj go, aby wygenerować .agents/rules/project-context.md – kompleksowy dokument wprowadzający, który obejmuje architekturę, zależności środowiska wykonawczego, interfejs API i słowniczek domenowy.

Programowanie oparte na specyfikacji: od wbudowanego planowania w Antigravity po strukturalne SDD

Asystenci kodowania opartego na AI ułatwiają generowanie kodu na podstawie prompta. Ryzyko: opisujesz funkcję w jednym zdaniu, asystent pisze setki wierszy, a Ty akceptujesz je, bo wyglądają dobrze. Czasami nazywa się to „vibe coding” – kierujesz się intuicją, akceptując lub odrzucając wyniki na podstawie tego, czy wydają się odpowiednie. Jest szybki w przypadku prototypów i skryptów jednorazowych. Przestaje działać, gdy baza kodu się rozrasta, funkcje wchodzą ze sobą w interakcje lub gdy po kilku tygodniach wracasz do kodu i nie możesz sobie przypomnieć, dlaczego podjęto daną decyzję.

Spec-Driven Development (SDD) dodaje strukturę do tej pętli. Zanim wygenerujesz kod, musisz napisać specyfikację: co robi funkcja, komu służy i jakie są kryteria sukcesu. Asystent AI działa na podstawie tej specyfikacji, a Ty możesz ją sprawdzić, gdy będziesz przeglądać jego wyniki. Specyfikacja staje się jedynym źródłem wiarygodnych informacji o intencjach. Jeśli kod odbiega od specyfikacji, możesz to wykryć podczas sprawdzania. Jeśli wymagania się zmienią, najpierw zaktualizuj specyfikację, a potem wygeneruj ją ponownie. Decyzje są dokumentowane, a nie improwizowane.

Wymaga to kompromisu: SDD jest wolniejsze w przypadku poszczególnych funkcji niż vibe coding. Dokumenty piszesz przed napisaniem kodu. Ale korzyści się kumulują – każda przyszła zmiana w bazie kodu ma kontekst, każda implementacja wygenerowana przez AI ma umowę, którą można sprawdzić, a współpracowników (ludzi lub AI) możesz wprowadzić w temat, wskazując im specyfikacje, zamiast wyjaśniać decyzje z pamięci.

Antigravity już korzysta z zasad programowania opartego na specyfikacji. Gdy ustawisz agenta w trybie planowania, przed napisaniem kodu wygeneruje on 2 artefakty:

• Plan wdrożenia – omówienie proponowanego podejścia technicznego, zmian w plikach i decyzji dotyczących architektury.
• Lista zadań – uporządkowany podział elementów pracy.

Antigravity prosi o sprawdzenie i zatwierdzenie tych artefaktów przed wykonaniem. Ta pętla planowania i wdrażania jest podstawą tworzenia oprogramowania na podstawie specyfikacji: specyfikacje kierują kodem, a nie odwrotnie.

W tym ćwiczeniu rozwijamy tę podstawę, przedstawiając oparty na opiniach, kontrolowany wersjami przepływ pracy oparty na spec-kit – frameworku do tworzenia oprogramowania opartego na specyfikacjach od GitHuba. Każda funkcja przechodzi przez specjalny potok, w którym każdy artefakt jest samodzielnym dokumentem, który możesz sprawdzić, edytować i śledzić w git. Potok obejmuje 2 opcjonalne etapy kontroli jakości (wyjaśnianie i analizowanie), które pozwalają wykrywać problemy, zanim staną się problemami z wdrożeniem:

Faza	Artefakt	Purpose
/speckit.specify	spec.md	Określ, CO chcesz stworzyć (z perspektywy użytkownika, niezależnie od technologii).
/speckit.clarify (opcjonalnie)	Aktualizacja: spec.md	Wykrywanie niedostatecznie określonych obszarów, zadawanie ukierunkowanych pytań wyjaśniających i kodowanie odpowiedzi z powrotem w specyfikacji
/speckit.plan	plan.md, data-model.md, research.md	Zaprojektuj SPOSÓB jego utworzenia (podejście techniczne, modele danych, badania)
/speckit.tasks	tasks.md	Podziel plan na uporządkowane, praktyczne kroki.
/speckit.analyze (opcjonalnie)	Raport analizy	Przed wdrożeniem sprawdź zadania pod kątem ryzyka, luk i brakujących przypadków brzegowych.
/speckit.implement	Zmiany w kodzie	Wykonaj zadania, zaznaczając każde z nich.

Każdy artefakt jest zapisywany jako plik w specs/<feature-branch>/, wersjonowany w git i wielokrotnego użytku. Jeśli rozmowa zostanie przerwana lub chcesz wrócić do podjętych decyzji później, dokumenty specyfikacji są zawsze dostępne, a nie ukryte w historii czatu.

Uwagi: wbudowany artefakt Antigravity ma przewagę w interfejsie, który umożliwia użytkownikom komentowanie wygenerowanych artefaktów ( nawet obrazów!). ). Dlatego w tym samouczku zmodyfikujemy oryginalny prompt spec-kit, aby zintegrować go z wbudowanym artefaktem w fazach implement.

Repozytorium startowe zawiera te przepływy pracy SDD w .agents/workflows/ i szablony w .specify/templates/. Użyjesz ich później, aby dodać funkcje do agenta.

4. Dokończ konfigurację Cloud SQL i upewnij się, że agent podstawowy działa

Wróć na kartę terminala, na której działa polecenie tworzenia Cloud SQL. Po zakończeniu sprawdź, czy instancja jest gotowa:

gcloud sql instances describe restaurant-db --format="value(state)"

Jeśli w danych wyjściowych pojawi się RUNNABLE, przejdź dalej. Jeśli pojawi się PENDING_CREATE, odczekaj chwilę i ponownie uruchom polecenie.

Przyznaj kontu usługi Cloud SQL dostęp do Vertex AI (wymagany w przypadku funkcji osadzania w bazie danych):

SERVICE_ACCOUNT=$(gcloud sql instances describe restaurant-db --format="value(serviceAccountEmailAddress)")

gcloud projects add-iam-policy-binding $GOOGLE_CLOUD_PROJECT \
  --member="serviceAccount:$SERVICE_ACCOUNT" \
  --role="roles/aiplatform.user" \
  --quiet

Utwórz bazę danych:

gcloud sql databases create restaurant_db --instance=restaurant-db

Dane wyjściowe powinny wyglądać tak:

Creating Cloud SQL database...done.
Created database [restaurant_db].
instance: restaurant-db
name: restaurant_db
project: <your-project-id>

Punkt kontrolny: plik .env zawiera GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION, REGION i DB_PASSWORD. Instancja Cloud SQL restaurant-db działa. toolbox jest dostępny w PATH (zainstalowany przez setup_prerequisites.sh). Zależności Pythona są zainstalowane.

Wypełnianie bazy danych

Wczytaj zmienne środowiskowe i uruchom skrypt inicjujący bazę danych, aby utworzyć schemat i wstawić 16 pozycji menu:

source .env
uv run python scripts/seed_db.py

Oczekiwane dane wyjściowe:

Creating extensions...
Creating menu_items table...
Inserting 16 menu items...
Seeded 16 menu items.
Done.

Generowanie wektorów dystrybucyjnych na potrzeby wyszukiwania semantycznego:

uv run python scripts/generate_embeddings.py

Oczekiwane dane wyjściowe:

Generating embeddings for 16 menu items...
Generated embeddings for 16 menu items.

Wykorzystuje to wbudowaną funkcję embedding() Cloud SQL (za pomocą rozszerzenia google_ml_integration) do wywoływania gemini-embedding-001 bezpośrednio z SQL. Wektory 3072-wymiarowe są przechowywane w kolumnie embedding tabeli menu_items. Nie jest potrzebny żaden kod osadzania po stronie aplikacji.

Testowanie agenta podstawowego

Uruchom MCP Toolbox jako proces w tle:

set -a; source .env; set +a # Export env variables to child process
toolbox --tools-file tools.yaml --address 127.0.0.1 --port 5000 &

Toolbox udostępnia narzędzia do baz danych przez HTTP. Pracownik obsługi klienta połączy się z Tobą o godzinie http://127.0.0.1:5000.

Uruchom interfejs programisty ADK:

uv run adk web .

Otwórz interfejs programisty w przeglądarce. Następnie przetestuj agenta za pomocą tych promptów:

What appetizers do you have?

Sprawdź: agent wysyła zapytanie do bazy danych i zwraca pozycje menu.

I'm vegetarian

Sprawdź: agent zapisuje preferencje żywieniowe w stanie agenta.

Can I make a reservation for tomorrow?

Sprawdzanie: agent nie może tego zrobić (nie ma jeszcze narzędzi do rezerwacji).

Zatrzymaj interfejs programisty ADK, dwukrotnie klikając Ctrl+C. Pozostaw Toolbox działający w tle – użyjesz go ponownie później.

Punkt kontrolny: agent podstawowy działa – wyszukiwanie w menu (słowo kluczowe + semantyka) i preferencje żywieniowe działają prawidłowo. Prośby o rezerwację nie są realizowane, ponieważ nie ma narzędzi do rezerwacji. Znasz strukturę projektu i wiesz, jaką lukę chcesz wypełnić.

5. Wczytywanie kontekstu projektu za pomocą Antigravity

Teraz zasymulujmy sytuację, która jest „trochę bliższa” naszej codziennej pracy:

• Źle zarządzane repozytorium
• README obsolete
• Dokumentacja nie jest często aktualizowana

Uwaga: jeśli nie odzwierciedla to Twojej sytuacji, możesz uznać się za szczęściarza.

W takiej sytuacji zwykle zaczynamy od utworzenia mapy lub kontekstu projektu, nad którym ma pracować Antigravity. Ten krok pokazuje przykład podejścia do zapewnienia Antigravity dogłębnego zrozumienia istniejącej bazy kodu przez utworzenie umiejętności, która analizuje repozytorium i generuje dokument kontekstu projektu.

Konfiguruje też konstytucję projektu, czyli zasady, które nie podlegają negocjacjom i w odniesieniu do których weryfikowane są przepływy pracy SDD. Razem zapewniają one Antigravity kontekst i ograniczenia potrzebne w późniejszych cyklach SDD.

Hierarchia kontekstowa Antigravity

Antigravity używa 3 poziomów kontekstu, z których każdy ma inny zakres:

• Reguły (.agents/rules/): zawsze aktywne instrukcje. Każdy uczestnik rozmowy w tym obszarze roboczym widzi te informacje ( jeśli zostały włączone). Używaj reguł, aby przekazywać kontekst dotyczący całego projektu, np. decyzje architektoniczne, standardy kodowania lub informacje o stosie technologicznym.
• Umiejętności (.agents/skills/): wiedza na żądanie. Antigravity wczytuje umiejętność tylko wtedy, gdy bieżące zadanie pasuje do pola description umiejętności. Używaj umiejętności w przypadku materiałów referencyjnych dotyczących konkretnej dziedziny.
• Przepływy pracy (.agents/workflows/): zapisane prompty wywoływane za pomocą poleceń /. Używaj przepływów pracy w przypadku powtarzalnych procesów wieloetapowych, takich jak potok SDD.

Uwaga: projekt ma obecnie przepływy pracy (potok SDD) i umiejętność (tworzenie agenta ADK), ale nie ma reguł. project-context.md Reguła zapewnia Antigravity trwałe zrozumienie bazy kodu – jakie technologie są używane, jak są zorganizowane pliki i co zostało do tej pory zbudowane.

Aktywowanie umiejętności

Repozytorium startowe zawiera 2 gotowe umiejętności w .agents/skills/. Zawierają szczegółowe instrukcje, ale zaczynają się od TODO(codelab) komentarzy zamiast wymaganego nagłówka YAML. Bez wstępu Antigravity nie może ich wykryć.

Umiejętności antygrawitacyjne wymagają bloku metadanych YAML u góry pliku z 2 polami:

• name – unikalny identyfikator umiejętności.
• description – podsumowanie w języku naturalnym, które Antigravity porównuje, aby zdecydować, którą umiejętność wczytać w odpowiedzi na dane żądanie.

Otwarte

.agents/skills/adk-agent-development/SKILL.md

w edytorze. Zastąp 2 wiersze komentarza TODO(codelab) u góry tymi metadanymi:

---
name: adk-agent-development
description: Comprehensive guide for building, developing, and deploying AI agents using Google's Agent Development Kit (ADK) with Gemini models, covering agent creation, tools, state management, persistence, deployment, and database integration via MCP Toolbox.
---

Uwagi: umiejętność tworzenia agenta ADK zawiera skrócone wzorce i przykłady z 5 ćwiczeń w Codelabs ADK: struktura agenta, typy narzędzi, zarządzanie stanem, wdrażanie.

Otwarte

.agents/skills/repo-research/SKILL.md

w edytorze. Zastąp 2 wiersze komentarza TODO(codelab) u góry tymi metadanymi:

---
name: repo-research
description: Analyze a repository's structure, technologies, and patterns to create or update a project context document. Use when asked to research, analyze, or understand a codebase.
---

Uwagi: zapoznaj się ze szczegółami w pliku repo-research SKILL.md. To jest przykładowy prompt do analizy repozytorium. Zwróć uwagę, że reguły aktualizacji przyrostowych są celowo konserwatywne. Jeśli kontekst Antigravity wyczerpie się w trakcie wyszukiwania lub rozmowa zostanie przerwana, wszystko, co zostało do tej pory odkryte, zostanie zapisane w pliku. Ponowne wywołanie umiejętności spowoduje wznowienie od miejsca, w którym została przerwana, bez utraty postępów.

Ostrzeżenie! Analiza dużego repozytorium może szybko wyczerpać limit.

Sprawdź, czy obie umiejętności mają prawidłowe informacje wstępne:

head -4 .agents/skills/adk-agent-development/SKILL.md
head -4 .agents/skills/repo-research/SKILL.md

Każdy z nich powinien zawierać ograniczniki --- otaczające pola name: i description:. Jeśli brakuje ograniczników lub pól, Antigravity nie rozpozna umiejętności.

Obie funkcje są wczytywane na żądanie – Antigravity dopasowuje Twoje żądanie do pola description i pobiera pełne instrukcje tylko wtedy, gdy są one istotne.

Generowanie kontekstu projektu

Sprawdź, czy istnieje katalog reguł:

mkdir -p .agents/rules

W oknie Menedżer agentów/czat Antigravity (w trybie edytora naciśnij ctrl + L) rozpocznij nową rozmowę. Typ:

Research this repository and create a project context document

Antigravity dopasowuje Twoje żądanie do repo-research i rozpoczyna systematyczną analizę bazy kodu. Odczytuje pliki konfiguracyjne, kod źródłowy i dokumentację, a następnie wypełnia szablon kontekstu projektu swoimi ustaleniami.

Po zakończeniu otwórz .agents/rules/project-context.md w edytorze. Zawiera konkretne informacje o projekcie: stos technologiczny (Python 3.12, ADK, MCP Toolbox, Cloud SQL), strukturę projektu, model danych (tabela menu_items z pgvector) i integracje zewnętrzne.

Wskazówka: dokument kontekstu projektu rozwija się wraz z projektem. Możesz ponownie uruchomić funkcję, aby zaktualizować kontekst o nowe dodatki. Reguły aktualizacji przyrostowych zapewniają zachowanie dotychczasowych treści – nowe technologie, podmioty i integracje są dodawane, a nie zastępowane.

W przypadku aktualizacji ukierunkowanych używaj konkretnych promptów: „Zbadaj schemat bazy danych i zaktualizuj kontekst projektu” lub „Zaktualizuj kontekst projektu o definicje nowych narzędzi”. Każde wywołanie dodaje informacje do istniejącego dokumentu.

Ustalenie konstytucji projektu

Podczas planowania i analizy przepływy pracy SDD odwołują się do konstytucji projektu w .specify/memory/constitution.md. Przepływ pracy /speckit.plan przeprowadza „sprawdzanie zgodności z konstytucją”, a /speckit.analyze oznacza naruszenia jako KRYTYCZNE. Jeśli konstytucja pozostanie pustym szablonem z tokenami zastępczymi, te kontrole nie będą miały punktu odniesienia do weryfikacji – plany i analizy będą przeprowadzane bez zabezpieczeń.

Konstytucja określa zasady projektu, które nie podlegają negocjacjom. Jest to małe repozytorium utrzymywane przez jednego programistę, więc konstytucja powinna odzwierciedlać ten zakres – zachowaj prostotę i spójność oraz unikaj nadmiernego skomplikowania.

W Menedżerze agentów Antigravity rozpocznij nową rozmowę. Uruchom przepływ pracy dotyczący konstytucji:

/speckit.constitution This is a small restaurant concierge ADK agent maintained by one developer. Set 3 principles: (1) All database operations go through MCP Toolbox tool definitions in tools.yaml — no raw SQL in Python code, no ORM. (2) Session state uses ADK ToolContext — no custom state management, no external state stores. (3) Keep it simple — follow existing file and naming conventions exactly.

Antigravity wypełnia szablon konstytucji konkretnymi zasadami, przypisuje wersję (1.0.0) i przeprowadza kontrolę spójności w szablonach SDD.

Sprawdź wygenerowaną konstytucję na stronie .specify/memory/constitution.md. Sprawdź, czy te 3 zasady są obecne i jasno sformułowane.

Uwaga: konstytucja jest celowo ograniczona do 3 zasad, które są dostosowane do potrzeb niezależnego dewelopera. Przepływ pracy /speckit.constitution obsługuje przyrostowe zmiany – stosuj go ponownie z dodatkowymi zasadami, a automatycznie zajmie się obsługą wersji. W przypadku projektu zespołowego dodaj zasady dotyczące inspekcji kodu, dyscypliny testowania, dostrzegalności i obsługi wersji interfejsu API.

Punkt kontrolny: .agents/rules/project-context.md istnieje z konkretnymi informacjami o repozytorium. .agents/skills/repo-research/SKILL.md pokazuje tworzenie umiejętności za pomocą wstępu w formacie YAML, instrukcji i rozwiązywania konfliktów. .specify/memory/constitution.md zawiera 3 zasady projektu, na podstawie których weryfikowane są przepływy pracy związane z planowaniem i analizowaniem. Poznaj 3-poziomową hierarchię kontekstu: reguły (zawsze aktywne), umiejętności (na żądanie) i przepływy pracy (polecenia z ukośnikiem).

6. SDD Cycle — Add Reservation Feature

Ten krok obejmuje pełny cykl SDD, który umożliwia dodanie rezerwacji do agenta obsługi klienta restauracji. W każdej fazie (określanie, wyjaśnianie, planowanie, zadania, analiza, wdrażanie) korzystasz z Antigravity, obserwując, jak poszczególne artefakty są budowane na podstawie poprzednich. To podstawowe ćwiczenie w tym laboratorium.

Ważne: Antigravity to asystent AI – wygenerowane przez niego artefakty (specyfikacje, plany, zadania, kod) mogą się różnić od tych opisanych w tym samouczku. Nazwy plików, dokładne schematy SQL i struktura kodu mogą się różnić. Jest to oczekiwane i stanowi część pracy z programowaniem wspomaganym przez AI. Proces SDD zapewnia, że przed przekształceniem każdego artefaktu w kod sprawdzisz go. Dlatego, jeśli wynik nie spełnia Twoich oczekiwań, możesz go zaakceptować, zmodyfikować lub wygenerować ponownie.

Określ funkcję

W Menedżerze agentów Antigravity rozpocznij nową rozmowę. Wpisz /speckit.specify polecenie przepływu pracy z opisem cech:

/speckit.specify Add reservation booking capability to the restaurant concierge agent. Guests should be able to make a table reservation by providing their name, party size, date, and time. They should also be able to check existing reservations. The agent should confirm reservation details before booking and handle special requests (e.g., "window seat", "birthday celebration").

Antigravity tworzy gałąź funkcji, generuje dokument specyfikacji i przeprowadza weryfikację jakości. Jeśli Antigravity zada pytania wyjaśniające, odpowiedz na nie na podstawie opisu cech powyżej.

Uwaga: po zakończeniu specyfikacji Antigravity może przedstawić Ci informacje, np. „Utwórz plan techniczny” lub „Wyjaśnij wymagania specyfikacji”. Są to wskazówki dotyczące następnego etapu procesu (/speckit.plan lub /speckit.clarify).

Specyfikacja koncentruje się na tym, CO i DLACZEGO, a nie na tym, JAK. Opisuje on wrażenia użytkownika („Goście mogą dokonać rezerwacji, podając swoje imię i nazwisko, liczbę osób, datę i godzinę”) bez wspominania o tabelach SQL, tools.yaml ani interfejsach API ADK. Szczegóły implementacji pojawiają się na etapie planowania.

Sprawdź wygenerowaną specyfikację na stronie specs/<branch-name>/spec.md. Sprawdź, czy obejmuje wymagania funkcjonalne i kryteria sukcesu.

Wyjaśnij specyfikację (opcjonalnie)

Uruchom przepływ pracy wyjaśniania, aby zidentyfikować i rozwiązać problemy z niedokładnie określonymi obszarami w specyfikacji:

/speckit.clarify

Antigravity skanuje specyfikację pod kątem niejasności, brakujących kryteriów akceptacji i niedostatecznie określonych wymagań. Zawiera ukierunkowane pytania wyjaśniające, na które można odpowiedzieć krótkim fragmentem lub zwrotem. Twoje odpowiedzi są bezpośrednio kodowane z powrotem w specyfikacji, co zwiększa jej precyzję jeszcze przed rozpoczęciem planowania.

Wskazówka: krok wyjaśnienia jest opcjonalny, ale zalecany w przypadku złożonych funkcji. W przypadku prostych specyfikacji przejdź od razu do planowania.

Planowanie wdrożenia

Uruchom przepływ pracy planowania:

/speckit.plan

Antigravity generuje plan techniczny w 2 fazach:

1. Faza badań – rozwiązuje niewiadome dotyczące istniejącej bazy kodu, generuje research.md
2. Faza projektowania – tworzy data-model.md (definicję jednostki rezerwacji) i aktualizuje project-context.md.

Podczas planowania Antygrawitacja powinna używać umiejętności adk-agent-development. Sprawdź kluczowe artefakty:

• specs/<branch-name>/plan.md – podejście techniczne: które pliki zmodyfikować i jakie wzorce zastosować;
• specs/<branch-name>/data-model.md – definicja elementu rezerwacji (kolumny, typy, relacje);
• specs/<branch-name>/research.md – podjęte decyzje i ich uzasadnienie;

Generowanie zadań

Uruchamianie przepływu pracy dotyczącego zadań

/speckit.tasks

Antigravity dzieli plan na uporządkowaną listę zadań w specs/<branch-name>/tasks.md. Zadania mają format listy kontrolnej z identyfikatorami, znacznikami priorytetu i ścieżkami do plików, np.:

- [ ] [T001] [P] Create reservations table schema in scripts/seed_db.py
- [ ] [T002] [P] Add create_reservation tool to tools.yaml
- [ ] [T003] [P] Add list_reservations tool to tools.yaml
- [ ] [T004] [P] Update agent instruction in restaurant_concierge/agent.py

Zadania są podzielone na etapy: Konfiguracja → Podstawy → Historyjki użytkownika → Dopracowanie. Przejrzyj listę zadań, aby dowiedzieć się, co zostanie utworzone i zmodyfikowane.

Analizowanie zadań (opcjonalnie)

Uruchom przepływ pracy analizy, aby sprawdzić zadania pod kątem ryzyka i luk:

/speckit.analyze

Antigravity sprawdza listę zadań pod kątem specyfikacji i planu, szukając brakujących przypadków brzegowych, zadań, które mogą ze sobą kolidować, lub luk między wymaganiami specyfikacji a planowaną pracą. Przed wdrożeniem rozwiązania rozwiąż problemy krytyczne.

Wskazówka: etap analizy jest najbardziej przydatny, gdy lista zadań jest długa lub funkcja obejmuje wiele podsystemów. W przypadku funkcji o wąskim zakresie, np. rezerwacji, wystarczy szybkie skanowanie.

7. Wdrożenie

Uruchom przepływ pracy związany z wdrożeniem:

/speckit.implement

Antigravity przedstawia ostateczny plan wdrożenia i artefakt zadania. Sprawdź i zatwierdź go, aby kontynuować.

Wskazówka: możesz skomentować go bezpośrednio. Można to zrobić tylko za pomocą wbudowanego artefaktu Antigravity.

Antigravity wykonuje zadania, zaznaczając każde z nich po ukończeniu. Po zakończeniu wyświetli się pełny przewodnik.

Testowanie zmian w kodzie

Po zakończeniu wdrażania sprawdź, czy kluczowe zmiany zostały wprowadzone. Dokładne nazwy plików i ich zawartość mogą się różnić, ale powinny zawierać te wzorce, jak w przypadku tools.yaml i agent.py:

# Verify reservation tools were added to tools.yaml
grep -i "reservation" tools.yaml

Zobaczysz dane wyjściowe podobne do tych:

...
get_reservations_by_name:
      Retrieve all reservations for a guest by their name. Uses case-insensitive
      SELECT id, guest_name, party_size, reservation_datetime, special_requests, created_at
      FROM reservations
      ORDER BY reservation_datetime DESC
...

A w przypadku agent.py

# Verify agent instruction was updated
grep -i "reservation" restaurant_concierge/agent.py

# Check what files changed
git diff --name-only

Możesz zauważyć takie zmiany:

...
- **Table Reservations**: Help guests book a table or check their existing reservations.
## Reservation Booking Rules
When a guest wants to make a reservation, collect ALL of the following before confirming:
**IMPORTANT**: Before calling `book_reservation`, you MUST:
- Only call `book_reservation` after the guest says "yes" or "confirm"
## Checking Reservations
When a guest asks to check their reservations:
- Use `get_reservations_by_name` to find their bookings
        book_reservation,
...

Uwaga: jeśli polecenie grep nie zwróci żadnych wyników dla żadnego z plików, może to oznaczać, że implementacja używa innej nazwy. Sprawdź git diff, aby zobaczyć pełny zestaw zmian i upewnić się, że dodano logikę związaną z rezerwacjami.

Zmiany powinny dotyczyć skryptu początkowej bazy danych. Spróbujmy go wykonać.

source .env
uv run python scripts/seed_db.py

Zaktualizowany skrypt powinien utworzyć tabelę reservations, jeśli jeszcze nie istnieje. Powinny się wyświetlić dane wyjściowe potwierdzające utworzenie nowej tabeli (dotychczasowe dane menu_items zostaną zachowane).

Uwaga: firma Antigravity mogła utworzyć osobny skrypt migracji (np. scripts/create_reservations.py) zamiast aktualizować skrypt seed_db.py. Sprawdź, czy w scripts/ nie ma nowych skryptów w git diff --name-only, i uruchom je.

Jeśli wszystko przebiegnie pomyślnie, możemy przetestować tę funkcję w interfejsie programisty agenta ADK. Uruchom ponownie Toolbox, aby pobrać nowe definicje narzędzi w tools.yaml. Zatrzymaj wszystkie trwające procesy Toolbox, a potem uruchom nowy:

pkill -f toolbox 2>/dev/null
toolbox --tools-file tools.yaml --address 127.0.0.1 --port 5000 &

Uruchom interfejs programisty ADK:

uv run adk web .

Otwórz http://localhost:8000 w przeglądarce i przetestuj te prompty:

I'd like to book a table for 4 people on Friday at 7pm under the name Timmy

Sprawdź: agent powinien potwierdzić szczegóły rezerwacji i ją utworzyć.

Do I have any upcoming reservations?

Sprawdź: agent powinien wyświetlić utworzoną przez Ciebie rezerwację.

Teraz zatrzymaj interfejs programisty ADK, naciskając dwukrotnie Ctrl+C.

Punkt kontrolny: agent obsługuje rezerwacje i wyszukiwanie rezerwacji. Masz za sobą pełny cykl SDD: określanie → wyjaśnianie → planowanie → zadania → analiza → wdrażanie → testowanie. Każda faza generowała artefakt z określoną wersją w specs/<branch-name>/.

8. Wyzwania (opcjonalnie)

Znasz już cały przepływ pracy SDD. Sprawdź to:

• Przeprowadź drugi cykl SDD, aby utworzyć interfejs czatu w internecie dla konsjerża restauracji – tym razem bez szczegółowych instrukcji.
• Wdrażanie agenta w Cloud Run w scenariuszu produkcyjnym

Wskazówki

• Projekt nie ma platformy front-end. Antigravity powinien proponować czysty HTML/CSS/JS – jeśli zasugeruje React lub podobne rozwiązanie, nakieruj go na prostotę (zasada „keep it simple” z Twojej konstytucji powinna to wychwycić).
• Serwer pakietu ADK udostępnia /run_sse do przesyłania strumieniowego i /apps/{app_name}/users/{user_id}/sessions do zarządzania sesjami. Antigravity wykrywa je na podstawie kontekstu projektu.
• Po wdrożeniu uruchom serwer za pomocą polecenia uv run uvicorn server:app --host 0.0.0.0 --port 8080 (nie adk web), aby działało montowanie plików statycznych.
• Testuj na stronie http://localhost:8080/static/index.html.
• W ćwiczeniach referencyjnych pokazujemy, jak wdrożyć i utrwalić agenta ADK. Podaj w Antigravity odniesienia do tych ćwiczeń.

9. Gratulacje!

Rozszerzono agenta ADK konsjerża restauracji o możliwość rezerwacji – w całości za pomocą przepływów pracy SDD Antigravity, bez ręcznego pisania kodu aplikacji.

Co utworzysz

• Agent ADK konsjerża restauracji z wyszukiwaniem menu, wyszukiwaniem semantycznym, śledzeniem preferencji dietetycznych i rezerwacją stolików
• Umiejętność Antigravity do badania repozytoriów, która generuje i aktualizuje dokument kontekstu projektu
• konstytucję projektu, która podczas planowania i analizy wymusza przestrzeganie zasad niepodlegających negocjacjom;
• Pełny cykl SDD obejmujący przepływ pracy określ → wyjaśnij → zaplanuj → zadania → przeanalizuj → wdróż

Czego się dowiedziałeś

• Jak korzystać z przepływów pracy opartych na specyfikacji w Antigravity, aby systematycznie dodawać funkcje do istniejącej bazy kodu
• Jak tworzyć umiejętności Antigravity, które zawierają wiedzę z danej dziedziny do ponownego wykorzystania w różnych rozmowach
• Jak zainicjować kontekst projektu, aby Antigravity podejmował świadome decyzje dotyczące architektury, wzorców i wyboru technologii
• Jak ustawić konstytucję projektu, na podstawie której przepływy pracy SDD będą przeprowadzać weryfikację
• Jak rozszerzyć agenta ADK o nowe narzędzia oparte na bazie danych za pomocą zestawu narzędzi MCP

Czyszczenie danych

Zatrzymaj wszystkie uruchomione procesy lokalne (Toolbox):

pkill -f toolbox 2>/dev/null

Aby uniknąć dalszych opłat, usuń instancję Cloud SQL:

gcloud sql instances delete restaurant-db --quiet

Opcjonalnie możesz usunąć cały projekt:

gcloud projects delete $GOOGLE_CLOUD_PROJECT

Ważne: możesz cofnąć tę operację usuwania przez ograniczony czas, używając tego polecenia: gcloud projects undelete ${GOOGLE_CLOUD_PROJECT}