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 zbudować 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. Ten przewodnik wprowadza sposób na zwiększenie możliwości paradygmatu rozwoju opartego na specyfikacjach Antigravity przez 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 rezerwacją 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 Cloud SQL reservations.
(Wyzwanie) – opracuj własny interfejs agenta.
(Challenge) – wdrożenie w Google Cloud z pomocą agenta Antigravity

Kod początkowy zawiera działającego agenta ADK z wyszukiwaniem w menu (słowa kluczowe + semantyka za pomocą MCP Toolbox) 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 rozumiał istniejącą bazę kodu
Jak tworzyć umiejętności Antigravity, które zawierają wiedzę merytoryczną (np. wzorców ćwiczeń w Codelabs dotyczących ADK do ponownego wykorzystania.
Jak ustawić konstytucję 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 specyfikacjach (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 szkolenia ADK (lub mieć równoważną wiedzę):
Tworzenie agentów AI za pomocą ADK: podstawy
Tworzenie agentów AI za pomocą ADK: zwiększanie możliwości dzięki narzędziom
Tworzenie trwałych agentów AI za pomocą ADK i CloudSQL
Wdrażanie agenta ADK w Cloud Run, zarządzanie nim i obserwowanie go
Baza danych jako narzędzie: RAG z elementami agenta z ADK, MCP Toolbox i Cloud SQL

2. Konfigurowanie środowiska

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

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

Instalowanie wstępnie wymaganych usług

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

bash scripts/setup_prerequisites.sh

Uwierzytelnianie w Google Cloud

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

gcloud auth login
gcloud auth application-default login

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 ADK Vertex AI i łącznik Cloud SQL Python korzystają z domyślnych danych logowania 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 / 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 Google Cloud 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

Aprowizowanie Cloud SQL

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

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

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.

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 projektów w Pythonie 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 laboratorium 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 agentów ADK, nad którymi możemy pracować. W następnej sekcji omówimy dokładniej Antigravity i rozwój oparty na specyfikacjach.

3. Poznaj kod startowy i dowiedz się więcej o programowaniu opartym na specyfikacji

W tym kroku omówimy strukturę kodu początkowego, 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 bazy danych MCP Toolbox ze śledzeniem preferencji żywieniowych na podstawie ToolContext. Agent wczytuje wszystkie narzędzia z serwera Zestawu narzędzi 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 samouczkó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 przyrostowo analizować repozytorium 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.

Spec-Driven Development: od wbudowanego planowania w Antigravity do strukturalnego SDD

Asystenci kodowania 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 – i Ty też, gdy sprawdzasz 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ż kodowanie wibracyjne. 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 wprowadzać w temat, wskazując im specyfikacje, zamiast wyjaśniać decyzje z pamięci.

Antigravity już teraz jest rozwijany zgodnie z zasadami rozwoju opartego na specyfikacjach. 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 ich wykonaniem. Ta pętla planowania i wdrażania jest podstawą tworzenia oprogramowania opartego na specyfikacjach: specyfikacje kierują kodem, a nie odwrotnie.

To ćwiczenie rozszerza te podstawy o 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 osobnym dokumentem, który możesz sprawdzić, edytować i śledzić w git. Potok obejmuje 2 opcjonalne fazy 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, braków lub pominiętych 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.

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 wyświetli się PENDING_CREATE, poczekaj 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>

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 narzędzia MCP 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 &

Zestaw narzędzi 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 deweloperski w przeglądarce. Następnie przetestuj agenta za pomocą tych promptów:

What appetizers do you have?

I'm vegetarian

Can I make a reservation for tomorrow?

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

5. Wczytywanie kontekstu projektu za pomocą Antigravity

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

Repozytorium nie jest dobrze zarządzane
README obsolete
Dokumentacja nie jest często aktualizowana

W takiej sytuacji zwykle zaczynamy od utworzenia mapy lub kontekstu projektu, nad którym ma pracować Antigravity. Ten krok pokazuje jeden z przykładów 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żda osoba w tym obszarze roboczym widzi te reguły ( jeśli zostały aktywowane). Używaj reguł, aby przekazywać informacje dotyczące całego projektu, np. decyzje dotyczące architektury, 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.

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 frontmatter 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ą funkcję załadować w odpowiedzi na dane żądanie.

Otwarte

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

w edytorze. Zastąp dwa wiersze komentarza TODO(codelab) u góry tymi informacjami wstępnymi:

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

Otwarte

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

w edytorze. Zastąp dwa wiersze komentarza TODO(codelab) u góry tymi informacjami wstępnymi:

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

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 umiejętności 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.

Ustalanie 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 czego weryfikować – 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.

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 elementy bazują na poprzednich. To podstawowe doświadczenie edukacyjne w tym laboratorium.

Określ funkcję

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

/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 funkcji powyżej.

Specyfikacja skupia 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 niedokładnie 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ę przed rozpoczęciem planowania.

Planowanie wdrożenia

Uruchom przepływ pracy planowania:

/speckit.plan

Antigravity generuje plan techniczny w 2 fazach:

Faza badań – rozwiązuje niewiadome dotyczące istniejącej bazy kodu, generuje research.md
Faza projektowania – tworzy data-model.md (definicję encji 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 są zgodne z formatem 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 → Historie użytkowników → 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.

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

Antigravity wykonuje zadania i zaznacza je jako ukończone. 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,
...

Zmiany powinny dotyczyć skryptu bazy danych początkowych. 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).

Jeśli wszystko przebiegnie prawidłowo, 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 nowe:

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

Do I have any upcoming reservations?

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

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 frontendowej. 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 ADK udostępnia /run_sse na potrzeby przesyłania strumieniowego i /apps/{app_name}/users/{user_id}/sessions na potrzeby 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 z programowania pokazano już, jak wdrożyć i utrwalić agenta ADK. Odwołaj się do tych ćwiczeń w Antigravity.

9. Gratulacje!

Rozszerzasz 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 obsługujący restauracje 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 pokazujący przepływ pracy: określ → wyjaśnij → zaplanuj → zadania → przeanalizuj → wdróż.

Czego się dowiedziałeś

Jak używać przepływów pracy opartych na specyfikacjach w Antigravity, aby systematycznie dodawać funkcje do istniejącej bazy kodu
Jak tworzyć umiejętności Antigravity, które zawierają wiedzę z danej dziedziny, aby można było jej używać 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