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 przedstawia sposób na zwiększenie możliwości paradygmatu tworzenia opartego na specyfikacji w Antigravity przez wprowadzenie nowego cyklu, który znacznie usprawnia dokumentację specyfikacji, w dużej mierze odwołując się do pakietu 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 Cloud SQL reservations.
• (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 z ćwiczeń 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 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 aktywnym 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, użyj banera u góry tego ćwiczenia, aby uzyskać próbne konto rozliczeniowe, którego możesz użyć w tym samouczku.

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

Instalowanie wstępnie wymaganych usług

Sprawdź, czy w systemie jest dostępny ten plik wykonywalny interfejsu wiersza poleceń:

• git
• gcloud
• uv
• npm

Instrukcje instalacji różnią się w zależności od systemu operacyjnego komputera.

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 laboratorium kodu 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>

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 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łaszania roszczeń dotyczących próbnego konta rozliczeniowego.

Ponieważ pracujesz lokalnie z Antigravity, uwierzytelnianie odbywa 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 łącznik 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.

WAŻNE! Poniższy krok pomoże Ci szybko skonfigurować projekt w chmurze Google Cloud połączony z wersją próbną konta rozliczeniowego (o ograniczonym dostępie). Jeśli wolisz użyć własnego poprzedniego projektu, możesz pominąć ten krok i wykonać ten krok:

Dodaj nazwę swojego projektu jako zmienną GOOGLE_CLOUD_PROJECT w pliku .env.

Aktywuj projekt w terminalu za pomocą polecenia gcloud config set project your-project-id.

Następnie możesz przejść bezpośrednio do sekcji Włączanie interfejsu API.

Jeśli nie masz pewności, przejdź do następnej sekcji

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łączam interfejs API

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.

Instalowanie zależności

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

Przygotowywanie infrastruktury bazy danych i danych

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.

Następnie uruchom scripts/setup_database.sh skrypt, aby przygotować całą potrzebną infrastrukturę. Wykonaj te czynności:

• Utwórz instancję Cloud SQL
• Sprawdź, czy instancja jest gotowa
• Przyznawanie uprawnień do Vertex AI
• Utwórz bazę danych
• Baza danych wyjściowych
• Uruchom usługę MCP Toolbox w tle

chmod +x scripts/setup_database.sh
./scripts/setup_database.sh > database_setup.log 2>&1 &

To polecenie uruchomi konfigurację w tle. Możesz okresowo sprawdzać dane wyjściowe w pliku database_setup.log.

Powinniśmy teraz mieć wszystkie wymagane repozytoria agentów ADK, z którymi możemy pracować. W następnej sekcji porozmawiamy o Antigravity i programowaniu opartym na specyfikacji.

3. Poznaj kod startowy i dowiedz się więcej o programowaniu opartym 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)
│   │   ├── mcp-toolbox-postgres/
│   │   │   └── SKILL.md     # MCP Toolbox config skill
│   │   └── repo-research/
│   │       └── SKILL.md     # Repo analysis skill
│   └── 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 – główny 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/mcp-toolbox-postgres/SKILL.md – umiejętność, która pomaga Antigravity w tworzeniu prawidłowej konfiguracji pliku tools.yaml dla zestawu narzędzi MCP. W tym module dowiesz się, jak skonfigurować sources, tools i embeddingModels, aby utworzyć prawidłowy potok RAG. Ta umiejętność nie zostanie aktywowana, dopóki nie dodasz odpowiedniego nagłówka YAML, który będzie rozpoznawany przez Antigravity.
• .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. Jest ona też 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 również możesz się nią posługiwać podczas sprawdzania jego wyników. 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ż działa zgodnie z zasadami 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 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, 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. 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 kontekstu 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 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.

Uwaga: projekt ma obecnie przepływy pracy (potok SDD) i 2 umiejętności (repo-research i mcp-toolbox-postgres), ale nie ma reguł. Później utworzymy project-context.mdregułę, która zapewni Antigravity stałą wiedzę o bazie kodu – jakie technologie są używane, jak są zorganizowane pliki i co zostało dotychczas 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 z zapytaniem, aby zdecydować, którą umiejętność wczytać w odpowiedzi na dane żądanie.

Otwórz plik .agents/skills/mcp-toolbox-postgres/SKILL.md w edytorze. Zastąp wiersze komentarza TODO(codelab) u góry tymi informacjami:

---
name: mcp-toolbox-postgres
description: Configure MCP Toolbox for PostgreSQL — sources, tools, and embedding models
---

Uwagi: umiejętność MCP Toolbox Postgres zawiera odpowiednią konfigurację dla sources, tools i embedding models.

Otwórz plik .agents/skills/repo-research/SKILL.md w edytorze. Zastąp wiersze komentarza TODO(codelab) u góry tymi informacjami:

---
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. Pamiętaj, ż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łowy nagłówek:

head -4 .agents/skills/mcp-toolbox-postgres/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.

Instalowanie umiejętności dostępnych publicznie

Umiejętności w ściągawce ADK

Wcześniej sprawdziliśmy umiejętności, które sami utworzyliśmy ( umiejętności repo-research i mcp-toolbox-postgres). Istnieje jednak wiele innych umiejętności, które są przydatne w procesie tworzenia oprogramowania i można je łatwo zainstalować w agencie kodowania. Na przykład w tym samouczku musimy korzystać z ADK, dlatego potrzebujemy odpowiedniej wiedzy o tym, jak z niego korzystać. Zainstalujmy umiejętność dokumentacji ADK za pomocą tego polecenia:

npx skills add google/adk-docs

Następnie pojawi się prośba o potwierdzenie instalacji, jak pokazano poniżej.

Naciśnij y, aby przejść do następnego promptu i wybrać umiejętności do zainstalowania, jak pokazano poniżej. Na razie wybierzmy tylko adk-cheatsheet (naciśnij spację, aby wybrać, a potem Enter, aby potwierdzić).

Następnie kliknij Enter (Enter) przy innej opcji, aby włączyć instalację domyślną i zainstalować umiejętność w bieżącym projekcie.

Nowa umiejętność ADK zostanie dodana do katalogu .agents/skills, czyli adk-cheatsheet.

Caveman Skills

Jedną z przydatnych umiejętności, która pozwala zmniejszyć zużycie tokenów, jest umiejętność jaskiniowca . Ta umiejętność może skrócić token wyjściowy agenta, co jest dobrym rozwiązaniem, gdy korzystasz z pełnego rozwoju opartego na specyfikacji, jak w tym samouczku.

npx skills add JuliusBrussee/caveman

Podobnie jak wcześniej wybierzmy na razie umiejętność caveman.

Następnie kliknij Enter (Enter) przy innej opcji, aby włączyć instalację domyślną i zainstalować umiejętność w bieżącym projekcie.

Powinniśmy mieć już skonfigurowane 4 umiejętności i być gotowi do rozpoczęcia procesu SDD.

.agents/skills/
├── adk-cheatsheet
├── caveman
├── mcp-toolbox-postgres
└── repo-research

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, and communicate efficiently

Antigravity dopasowuje Twoje żądanie do umiejętności repo-research i caveman ( polecenie umożliwiające efektywną komunikację) 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ć umiejętność, 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).

5. SDD Cycle — Add Reservation Feature

Ten krok obejmuje pełny cykl SDD, który umożliwia dodanie rezerwacji do agenta obsługi klienta restauracji. Przechodzisz przez wszystkie etapy Antigravity – określanie, wyjaśnianie, planowanie, zadania, analiza, wdrażanie – i obserwujesz, jak każdy artefakt jest budowany na podstawie poprzedniego. 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ęść procesu programowania wspomaganego przez AI. Proces SDD zapewnia, że przed przekształceniem 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 przekazać 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 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.

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 Update the restaurant concierge agent to multi agent architecture which separate responsibilities for handling menu and reservations. Use your ADK and MCP toolbox skill to implement it properly

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

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.

6. 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 bazy danych początkowych. 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. Przeprowadzimy migrację bazy danych, aby uwzględnić nową tabelę, i ponownie uruchomimy przybornik, aby pobrać nowe definicje narzędzi w tools.yaml. Zatrzymaj wszystkie trwające procesy Toolbox, a potem uruchom nowy:

lsof -ti:5000 | xargs kill -9 2>/dev/null; echo "Done"
./scripts/setup_database.sh > database_setup.log 2>&1 &

W database_setup.log możesz sprawdzić dziennik wyjściowy, aby dowiedzieć się, czy Antigravity generuje prawidłowy kod i konfigurację. Jeśli pojawi się błąd, spróbuj rozwiązać go, wchodząc w interakcję z agentem.

Jeśli wszystko pójdzie dobrze, możemy uruchomić 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. Ukończono 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>/.

7. 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 sugeruje React lub podobne rozwiązanie, nakieruj go na prostotę (zasada „zachowaj prostotę” 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ń.

8. 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, który pełni funkcję konsjerża w restauracji i umożliwia wyszukiwanie menu, wyszukiwanie semantyczne, śledzenie preferencji dietetycznych i rezerwowanie 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 z przepływem 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, 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

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