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 z 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 implementacji do sprawdzenia oraz wprowadza zmiany w kodzie – wszystko to na podstawie wiedzy o domenie, którą pomaga Ci rejestrować jako umiejętności wielokrotnego użytku, oraz konstytucji projektu, która egzekwuje zasady niepodlegające negocjacjom. To ćwiczenie przedstawia sposób na ulepszenie paradygmatu rozwoju opartego na specyfikacjach Antigravity przez wprowadzenie nowego cyklu, który znacznie zwiększa dokumentację specyfikacji, często odwołując się do spec-kit.

Co utworzysz

Lokalnie działająca aplikacja konsjerża restauracji z rezerwacją miejsc 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 użytkownika dla agenta.
• (Challenge) – wdrażanie w Google Cloud za pomocą agenta Antigravity

Kod startowy zawiera działającego agenta pakietu ADK z wyszukiwaniem w 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 mógł zrozumieć istniejącą bazę kodu
• Jak tworzyć umiejętności Antigravity i konfigurować MCP, które zawierają wiedzę o domenie (np. dokumenty ADK, umiejętności innych firm) 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 samouczka, 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: te warsztaty programistyczne są w całości przeprowadzane w Google Antigravity na 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 używają 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 urządzenie 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 roszczenia sobie prawa do 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 ADK i łącznik Pythona Cloud SQL 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.

WAŻNE! Poniższy krok pomoże Ci szybko skonfigurować projekt Google Cloud połączony z wersją próbną konta rozliczeniowego (strict). Jeśli wolisz użyć własnego 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 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łą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 w Pythonie użyjemy 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

Przygotowywanie infrastruktury bazy danych i danych

Ustaw hasło do bazy danych i dodaj je do tematu .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 o nasionach
• Uruchamianie usługi 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 – podstawowy agent. LlmAgent, która łączy narzędzia bazodanowe 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 MCP Toolbox. Zdefiniowano 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.

Pliki Antigravity

• .agents/skills/mcp-toolbox-postgres/SKILL.md – umiejętność, która pomaga Antigravity w tworzeniu prawidłowej konfiguracji tools.yaml dla zestawu narzędzi MCP. W ramach tego szkolenia 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 uporządkowanej. 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 on też nieaktywny, dopóki nie dodasz później metadanych YAML. Po aktywowaniu wywołaj go, aby wygenerować .agents/rules/project-context.md – kompleksowy dokument wprowadzający obejmujący 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 tych specyfikacji, a Ty możesz je sprawdzić, aby ocenić jego wyniki. Specyfikacja staje się jedynym źródłem wiarygodnych informacji o intencjach. Jeśli kod odbiega od specyfikacji, wykryjesz to 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 przez wersje przepływ pracy oparty na spec-kit, czyli frameworku do tworzenia oprogramowania opartego na specyfikacjach od GitHuba. Każda funkcja przechodzi przez specjalny proces, 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	Identyfikowanie 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 lub 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 użytkownika, 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 uważać 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 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 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 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 sekcji z metadanymi Antigravity nie może ich wykryć.

Umiejętności Antigravity wymagają bloku sekcji z metadanymi 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.

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: dokładnie przeczytaj plik 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łowe informacje wstępne:

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.

Konfigurowanie MCP w dokumentacji ADK

Aby nasz agent ds. kodowania miał odpowiednią wiedzę na temat tworzenia agenta ADK, musi mieć dostęp do dokumentacji ADK. Możemy to włączyć, konfigurując serwer MCP w dokumentacji ADK .

Najpierw w edytorze Antigravity znajdź ikonę „wielokropka” w prawym górnym rogu okna agenta i kliknij ją. Zobaczysz opcje konfiguracji MCP i dostosowywania, takie jak te. Kliknij MCP.

Następnie kliknij przycisk Manage MCP servers.

Otworzy się karta konfiguracji serwerów MCP. Następnie kliknij przycisk View Raw Config.

Spowoduje to otwarcie pliku mcp_config.json. Teraz skopiuj i wklej tę konfigurację do pliku.

{
    "mcpServers": {
        "adk-docs-mcp": {
            "command": "uvx",
            "args": [
                "--from",
                "mcpdoc",
                "mcpdoc",
                "--urls",
                "AgentDevelopmentKit:https://adk.dev/llms.txt",
                "--transport",
                "stdio"
            ]
        }
    }
}

Uwaga: nie zapomnij zapisać zmian.

Ta konfiguracja umożliwi agentowi do kodowania wyszukiwanie i odczytywanie dokumentacji pakietu ADK za pomocą serwera MCP.

Instalowanie umiejętności dostępnych publicznie

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.

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 już mieć skonfigurowane 4 umiejętności i być gotowi do rozpoczęcia procesu SDD.

.agents/skills/
├── 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 skuteczną 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 przyrostowej 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 „kontrolę 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ą uruchamiane 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 wszystkie 3 zasady są obecne i jasno sformułowane.

Uwaga: konstytucja jest celowo ograniczona do 3 zasad przeznaczonych dla niezależnego dewelopera. Przepływ pracy /speckit.constitution obsługuje przyrostowe zmiany – uruchom go ponownie z dodatkowymi zasadami, a automatycznie zajmie się wersjonowaniem. W przypadku projektu zespołowego dodasz zasady dotyczące sprawdzania kodu, dyscypliny testowania, możliwości obserwacji i wersjonowania 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ą sekcji z metadanymi YAML, instrukcji i rozwiązywania konfliktów. .specify/memory/constitution.md zawiera 3 zasady projektu, które są weryfikowane w przepływach pracy związanych z planowaniem i analizowaniem. Znasz 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. Przeprowadź Antigravity przez każdy etap: określ, wyjaśnij, zaplanuj, wykonaj zadania, przeanalizuj i wdroż. Zobacz, jak każdy artefakt jest tworzony 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ęść 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 ukończeniu specyfikacji Antigravity może wyświetlić prośby o przekazanie informacji, np. „Opracuj plan techniczny” lub „Wyjaśnij wymagania specyfikacji”. Są to sygnały do przejścia do następnego etapu przepływu pracy (/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 uwzględnia wymagania funkcjonalne i kryteria sukcesu.

Wyjaśnij specyfikację (opcjonalnie)

Uruchom proces 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ń. Zadaje ukierunkowane pytania wyjaśniające, na które można odpowiedzieć krótkim wyborem lub frazą. 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 Update the restaurant concierge agent to multi agent architecture which separate responsibilities for handling menu and reservations. Utilize your access to ADK Docs tools 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 Antigravity powinna korzystać z narzędzi MCP w dokumentacji ADK i umiejętności związanych z dokumentacją zestawu narzędzi MCP. 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 zagrożeń 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ąż 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 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
...

Oraz 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 grep nie zwróci żadnych wyników dla żadnego z plików, wdrożenie mogło 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: Antigravity mogło utworzyć osobny skrypt migracji (np. scripts/create_reservations.py) zamiast aktualizować seed_db.py. Sprawdź, czy w scripts/ nie ma nowych skryptów w git diff --name-only, i uruchom je zamiast poprzednich.

Jeśli wszystko przebiegnie pomyślnie, możemy przetestować 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 nowe:

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 go za pomocą tych promptów:

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ą 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 wygenerował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 frontendowej. Antigravity powinien proponować czysty HTML/CSS/JS. Jeśli sugeruje React lub podobne rozwiązanie, nakieruj go na prostotę (zasada „nie komplikuj” z Twojej konstytucji powinna to wychwycić).
• Serwer pakietu 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 w kontekście 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.
• Test na stronie http://localhost:8080/static/index.html.
• W ćwiczeniach referencyjnych pokazujemy, jak wdrożyć i utrwalić agenta ADK. Podaj odniesienia do Antigravity.

8. Gratulacje!

Rozszerzasz agenta ADK 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 wyszukiwania informacji o repozytorium, 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ś(-aś)

• Jak korzystać z przepływów pracy opartych na specyfikacji w Antigravity, aby systematycznie dodawać funkcje do istniejącej bazy kodu
• Tworzenie umiejętności Antigravity i konfigurowanie MCP, które zawierają wiedzę o domenie 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ą weryfikować dane
• 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):

lsof -ti:5000 | xargs kill -9 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}