Spezifikationsgesteuerte ADK-Agentenentwicklung mit Antigravity und Spec-kit

1. Einführung

Wenn Sie einem vorhandenen Agenten Funktionen hinzufügen – in der Regel eine neue datenbankgestützte Funktion –, müssen Sie Boilerplate-Code schreiben, Integrationen einrichten und dafür sorgen, dass alles mit den Mustern im Code übereinstimmt. Antigravity beschleunigt jede Phase dieses Prozesses: Es analysiert Ihre Codebasis, um den erforderlichen Kontext zu erstellen, erstellt strukturierte Spezifikationen und Implementierungspläne zur Überprüfung und führt die Codeänderungen aus. Dabei wird es von Fachwissen geleitet, das Sie als wiederverwendbare Skills und eine Projektkonstitution erfassen können, die nicht verhandelbare Grundsätze durchsetzt. In diesem Codelab wird eine Möglichkeit vorgestellt, das Spec-driven Development-Paradigma von Antigravity zu optimieren, indem ein neuer Zyklus eingeführt wird, um die Spezifikationsdokumentation, die sich stark auf spec-kit bezieht, zu verbessern.

Aufgaben

Eine lokal ausgeführte Restaurant-Concierge-Anwendung mit Reservierungsbuchung, die über einen vollständigen SDD-Zyklus hinzugefügt wurde:

• Reservierungsbuchung: Gäste buchen Tische und prüfen Reservierungen. Dies wird durch neue MCP Toolbox-Datenbanktools und eine Cloud SQL-Tabelle reservations unterstützt.
• (Herausforderung): Entwickeln Sie eine eigene Benutzeroberfläche für den Agent.
• (Challenge): Mit dem Antigravity-Agent in Google Cloud bereitstellen

Der Startercode enthält einen funktionierenden ADK-Agenten mit Menüsuche (Stichwort + semantisch über MCP Toolbox) und Erfassung von Ernährungspräferenzen (über ToolContext). Sie können die Funktion erweitern, ohne Anwendungscode manuell zu schreiben. Antigravity übernimmt die Implementierung basierend auf Ihren Spezifikationen.

Lerninhalte

• Projektkontext so booten, dass Antigravity einen vorhandenen Codebase versteht
• So erstellen Sie Antigravity-Skills, die Domainwissen enthalten (z.B. ADK-Codelab-Muster) zur Wiederverwendung
• Festlegen einer Projektverfassung, anhand derer die SDD-Workflows während der Planung und Analyse validiert werden
• SDD-Workflows (Spec-Driven Development) in Antigravity verwenden, um systematisch Funktionen hinzuzufügen
• ADK-Agenten mit neuen datenbankgestützten Tools über die MCP Toolbox erweitern

Vorbereitung

• Google Antigravity und git auf Ihrem lokalen Computer installiert
• Ein Google Cloud-Konto mit aktiviertem Testabrechnungskonto
• Es ist hilfreich, wenn Sie die vier erforderlichen ADK-Codelabs bereits abgeschlossen haben oder über entsprechendes Wissen verfügen, um den Kontext des Anwendungsfalls zu verstehen:
• KI-Agents mit ADK erstellen: Grundlagen
• KI-Agents mit dem ADK erstellen: Tools einsetzen
• Persistente KI-Agents mit dem ADK und Cloud SQL erstellen
• ADK-KI-Agenten in Cloud Run bereitstellen, verwalten und beobachten
• Datenbank als Tool: Agentic RAG mit ADK, MCP Toolbox und Cloud SQL

2. Umgebung einrichten

WICHTIGE HINWEISE:

Für diese Anleitung ist ein Google Cloud-Projekt mit einem aktiven Rechnungskonto erforderlich. Wenn Sie noch keines haben, folgen Sie der Anleitung unten, um ein Testabrechnungskonto zu erstellen, das Sie für dieses Tutorial verwenden können:

1. Inkognitofenster öffnen
2. Wenn Sie an einer Workshopsitzung teilnehmen, wird die URL des Einlösungsportals in der Regel in der Sitzung angegeben. Andernfalls können Sie das Einlösungsportal für das Abrechnungskonto für Testversionen aufrufen.
3. Melden Sie sich mit Ihrem privaten Gmail-Konto an. Google Workspace- oder andere E‑Mail-Adressen funktionieren nicht. )
4. Folge der Schritt-für-Schritt-Anleitung zum Einlösen.

In diesem Schritt wird das Starter-Repository geklont, die Authentifizierung bei Google Cloud durchgeführt, eine Cloud SQL-Datenbank bereitgestellt und Ihre lokale Antigravity-Umgebung vorbereitet.

Hinweise:Dieses Codelab wird vollständig in Google Antigravity auf Ihrem lokalen Computer ausgeführt. Die Einrichtung umfasst die manuelle Authentifizierung mit dem gcloud-CLI-Befehl.

Starter-Repository klonen

Öffnen Sie ein Terminal in Antigravity (oder das Systemterminal). Klonen Sie das Begleit-Repository und wechseln Sie in das Verzeichnis:

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

Öffnen Sie das geklonte Repository in Antigravity. Datei -> Ordner öffnen -> wählen Sie das geklonte Verzeichnis sdd-adk-agents-agy aus.

Entfernen Sie die Upstream-Fernbedienung. In den SDD-Workflows werden Git-Branches für Funktionsspezifikationen erstellt. Durch das Entfernen des Remote-Repository wird verhindert, dass versehentlich in das Starter-Repository übertragen wird:

git remote remove origin

Wichtig:In den SDD-Workflows in diesem Codelab werden git-Branches verwendet, um Funktionsspezifikationen zu organisieren. Wenn Sie das Remote-Repository origin entfernen, bleiben Ihre lokalen Branches und Commits lokal. Wenn Sie Ihre Arbeit sichern möchten, fügen Sie Ihr eigenes Remote-Repository hinzu: git remote add origin <your-repo-url>

Erforderliche Komponenten installieren

Führen Sie das Skript für die Voraussetzungen aus. Es wird geprüft, ob git, curl, gcloud, uv, Python 3.12 und die MCP Toolbox installiert sind. Falls nicht, werden sie installiert:

bash scripts/setup_prerequisites.sh

Hinweise:Das Herunterladen aller Voraussetzungen dauert eine Weile. Öffnen Sie einen neuen Tab, um mit dem nächsten Abschnitt fortzufahren, während der Download abgeschlossen wird.

Mit Google Cloud authentifizieren

Führen Sie zwei Authentifizierungsbefehle aus. Beide öffnen einen Browser für OAuth:

gcloud auth login
gcloud auth application-default login

Hinweise:Beim zweiten OAuth-Befehl werden Sie aufgefordert, eine Berechtigung auszuwählen. Alle Optionen prüfen

Hinweise:Achten Sie darauf, dass Sie sich mit der E‑Mail-Adresse authentifizieren, mit der Sie das Abrechnungskonto für den Testzeitraum beanspruchen.

Da Sie lokal mit Antigravity arbeiten, authentifizieren Sie sich manuell. auth login authentifiziert die gcloud-Befehlszeile. application-default login authentifiziert Google Cloud SDKs, die von Ihrer Anwendung verwendet werden. Sowohl die Vertex AI-Aufrufe des ADK als auch der Cloud SQL-Python-Connector basieren auf Standardanmeldedaten für Anwendungen.

Google Cloud-Projekt einrichten

Schreiben Sie die Standortvariablen in .env, bevor Sie das Skript zur Projekteinrichtung ausführen:

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

• GOOGLE_CLOUD_LOCATION=global wird für Vertex AI-/Gemini API-Aufrufe verwendet.
• REGION=us-central1 wird für Cloud SQL und andere GCP-Infrastrukturen verwendet.

Laden Sie das Projekt-Setupskript herunter und führen Sie es aus. Damit wird ein Google Cloud-Projekt mit Testabrechnung erstellt oder validiert und die Projekt-ID in .env gespeichert. Anschließend wird die Quelle angegeben:

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

Aktivieren Sie die erforderlichen APIs:

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

Hinweise:Das Aktivieren von APIs kann einige Zeit dauern. Dies ist nur einmal pro Projekt erforderlich.

Cloud SQL bereitstellen

Legen Sie das Datenbankpasswort fest und fügen Sie es .env hinzu:

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

Wichtig:Das oben hartcodierte Passwort dient nur zu Schulungszwecken. In einer Produktionsumgebung sollten Sie Anmeldedaten sicher mit einem Dienst wie Secret Manager speichern und zur Laufzeit darauf verweisen. Übergeben Sie niemals Klartext-Secrets an die Quellcodeverwaltung.

Cloud SQL-Instanz erstellen:

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 &

Die db-custom-1-3840-Stufe ist die Mindestanforderung für die Vertex AI ML-Integration. Mit dem Flag --enable-google-ml-integration kann Cloud SQL Gemini-Embedding-Modelle direkt über SQL aufrufen. Dies ist die Grundlage für die semantische Suche.

Hinweise:Die Ausführung dieses Befehls dauert etwa 5 Minuten und erfolgt im Hintergrund. Lassen Sie es auf diesem Terminaltab laufen und öffnen Sie einen neuen Terminaltab für die nächsten Schritte.

Abhängigkeiten installieren

Öffnen Sie einen neuen Terminaltab. Achten Sie darauf, dass Sie sich weiterhin im Projektverzeichnis des geklonten Repositorys befinden, und laden Sie die Umgebungsvariablen neu:

source .env

Wir verwenden uv als Python-Projektmanager. uv ist ein schneller Python-Paket- und Projektmanager, der in Rust geschrieben wurde ( Dokumentation ). In diesem Codelab wird er aus Gründen der Geschwindigkeit und Einfachheit verwendet. Installieren Sie die Python-Abhängigkeiten:

uv sync

Aktualisieren Sie dann die Datei .env des ADK-Agents mit Ihrer Projektkonfiguration:

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

Jetzt sollten wir alle erforderlichen ADK-Agent-Starter-Repos haben, mit denen wir arbeiten können. Im nächsten Abschnitt geht es um Antigravity und die spezifikationsgetriebene Entwicklung.

3. Startercode ansehen und spezifikationsgetriebene Entwicklung verstehen

In diesem Schritt wird die Struktur des Startcodes erläutert, die Spec-Driven Development-Methodik vorgestellt, die Datenbank mit Daten gefüllt und geprüft, ob der Basis-Agent funktioniert, bevor Sie ihn erweitern.

Projektstruktur

Öffnen Sie das geklonte Repository-Projekt im Antigravity-Editor und sehen Sie sich das Verzeichnislayout an:

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

Schlüsseldateien

Dateien für die Agentenanwendung

• restaurant_concierge/agent.py: Der Kern-Agent. Eine LlmAgent, die Datenbanktools der MCP Toolbox mit der ToolContext-basierten Erfassung von Ernährungspräferenzen kombiniert. Der Agent lädt alle Tools vom Toolbox-Server und fügt zwei Python-Funktionen (save_dietary_preference, get_dietary_preferences) hinzu, die ToolContext zum Verwalten des Status verwenden.
• tools.yaml – Definitionen von MCP-Toolbox-Tools. Es sind drei Menü-Suchtools definiert: die Stichwortsuche (search_menu), die semantische Suche über pgvector (semantic_search_menu) und der Kategoriefilter (get_menu_by_category). Es sind noch keine Reservierungstools vorhanden. Diese fügen Sie später hinzu.
• server.py: Ein minimaler FastAPI-Server, der zeigt, wie Sie als FastAPI-Objekt auf das ADK zugreifen können. get_fast_api_app() aus dem ADK bietet integrierte Endpunkte, darunter /run_sse für SSE-Streaming und APIs für die Sitzungsverwaltung.

Antigravity-Dateien

• .agents/skills/adk-agent-development/SKILL.md: Ein vorkonfigurierter Skill ( von Antigravity generiert), der komprimierte Referenzmuster aus allen vier ADK-Codelabs enthält. Sie ist derzeit inaktiv (YAML-Frontmatter fehlt). Sie müssen sie später aktualisieren. Antigravity lädt diesen Skill automatisch, wenn es Arbeit im Zusammenhang mit ADK-Agent-Funktionen und ihren Beispielen erkennt. Dieses Wissen leitet Antigravity bei der Planung der Reservierungsfunktion.
• .agents/skills/repo-research/SKILL.md: Eine Skill, mit der Antigravity lernt, ein Repository inkrementell zu analysieren und ein strukturiertes Projektkontextdokument zu erstellen. Dabei wird ein 4-Phasen-Ansatz verwendet: Oberflächenscan (nur Verzeichnisbaum), Konfigurations- und Metadatendateien, Einstiegspunkte und Datenmodelle sowie gezielte Analysen. In jeder Phase werden die Ergebnisse gespeichert, bevor mit der nächsten fortgefahren wird. Wie beim ADK-Skill ist er inaktiv, bis Sie später YAML-Frontmatter hinzufügen. Nach der Aktivierung können Sie das Tool aufrufen, um .agents/rules/project-context.md zu generieren – ein umfassendes Onboarding-Dokument, das Architektur, Laufzeitabhängigkeiten, API-Oberfläche und Domänen-Glossar abdeckt.

Spec-Driven Development: von der integrierten Planung von Antigravity bis hin zu strukturiertem SDD

KI-Code-Assistenten erleichtern das Generieren von Code aus einem Prompt. Das Risiko: Sie beschreiben eine Funktion in einem Satz, der Assistent schreibt Hunderte von Zeilen und Sie akzeptieren sie, weil sie richtig aussieht. Das wird auch als „Vibe Coding“ bezeichnet. Sie steuern die KI dabei intuitiv und akzeptieren oder lehnen die Ausgabe ab, je nachdem, ob sie zu funktionieren scheint. Es ist schnell für Prototypen und Einwegskripts. Das funktioniert nicht mehr, wenn die Codebasis wächst, wenn Funktionen interagieren oder wenn Sie Wochen später Code noch einmal aufrufen und nicht mehr nachvollziehen können, warum eine Entscheidung getroffen wurde.

Spec-Driven Development (SDD) gibt diesem Zyklus eine Struktur. Bevor Code generiert wird, schreiben Sie eine Spezifikation: Was macht das Feature, für wen ist es gedacht und was sind die Erfolgskriterien? Der KI-Assistent arbeitet auf Grundlage dieser Spezifikation – und Sie auch, wenn Sie die Ausgabe überprüfen. Die Spezifikation wird zur einzigen Quelle der Wahrheit für den Intent. Wenn der Code von der Spezifikation abweicht, wird dies bei der Überprüfung festgestellt. Wenn sich die Anforderungen ändern, aktualisieren Sie zuerst die Spezifikation und generieren Sie sie dann neu. Entscheidungen werden dokumentiert, nicht improvisiert.

Das ist ein echter Kompromiss: SDD ist pro Funktion langsamer als die Vibe-Codierung. Sie schreiben Dokumente, bevor Sie Code schreiben. Aber die Vorteile summieren sich: Jede zukünftige Änderung am Code hat Kontext, jede KI-generierte Implementierung hat einen überprüfbaren Vertrag und Sie können Mitarbeiter (menschlich oder KI) einarbeiten, indem Sie sie auf Spezifikationen verweisen, anstatt Entscheidungen aus dem Gedächtnis zu erklären.

Antigravity folgt bereits den Prinzipien der spezifikationsgesteuerten Entwicklung. Wenn Sie den Agent in den Planungsmodus versetzen, werden zwei Artefakte erstellt, bevor Code geschrieben wird:

• Implementierungsplan: Eine Übersicht über den vorgeschlagenen technischen Ansatz, Dateiänderungen und Architektur-Entscheidungen
• Aufgabenliste: eine strukturierte Aufschlüsselung von Arbeitselementen

Antigravity fordert Sie auf, diese Artefakte vor der Ausführung zu überprüfen und zu genehmigen. Dieser Planungs- und Implementierungszyklus ist das Herzstück der spezifikationsgesteuerten Entwicklung: Spezifikationen leiten den Code und nicht umgekehrt.

In diesem Codelab wird diese Grundlage mit einem meinungsbasierten, versionskontrollierten Workflow auf Basis von spec-kit – einem spezifikationsbasierten Entwicklungs-Framework von GitHub – weiter ausgebaut. Jedes Feature durchläuft eine Pipeline, in der jedes Artefakt ein eigenständiges Dokument ist, das Sie in git überprüfen, bearbeiten und nachverfolgen können. Die Pipeline umfasst zwei optionale Quality-Gate-Phasen („Klären“ und „Analysieren“), in denen Probleme erkannt werden, bevor sie zu Implementierungsproblemen werden:

Phase	Artefakt	Purpose
/speckit.specify	spec.md	Definieren Sie, WAS entwickelt werden soll (nutzerorientiert, technologieunabhängig).
/speckit.clarify (optional)	Aktualisiert: spec.md	Unterbestimmte Bereiche identifizieren, gezielte Fragen zur Klärung stellen, Antworten wieder in die Spezifikation aufnehmen
/speckit.plan	plan.md, data-model.md, research.md	Entwerfen, WIE es erstellt werden soll (technischer Ansatz, Datenmodelle, Recherche)
/speckit.tasks	tasks.md	Plan in geordnete, umsetzbare Schritte unterteilen
/speckit.analyze (optional)	Analysebericht	Aufgaben vor der Implementierung auf Risiken, Lücken oder fehlende Grenzfälle prüfen
/speckit.implement	Codeänderungen	Führen Sie die Aufgaben aus und haken Sie jede ab.

Jedes Artefakt wird als Datei in specs/<feature-branch>/ gespeichert, in Git versioniert und kann wiederverwendet werden. Wenn eine Unterhaltung unterbrochen wird oder Sie später noch einmal auf Entscheidungen zurückgreifen möchten, sind die Spezifikationsdokumente immer verfügbar und nicht in einem Chatverlauf verborgen.

Hinweise:Das integrierte Antigravity-Artefakt hat eine übergeordnete Rolle in der Benutzeroberfläche, sodass Nutzer das generierte Artefakt kommentieren können ( sogar Bilder!). ). Daher ändern wir in dieser Anleitung den ursprünglichen spec-kit-Prompt, um ihn in die integrierten Artefakte in den implement-Phasen zu integrieren.

Das Starter-Repository enthält diese SDD-Workflows in .agents/workflows/ und Vorlagen in .specify/templates/. Sie werden später verwendet, um dem Agent Funktionen hinzuzufügen.

4. Cloud SQL-Einrichtung abschließen und dafür sorgen, dass der Base Agent funktioniert

Wechseln Sie zurück zum Terminaltab, auf dem der Befehl zum Erstellen der Cloud SQL-Instanz ausgeführt wird. Prüfen Sie nach Abschluss, ob die Instanz bereit ist:

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

Wenn in der Ausgabe RUNNABLE angezeigt wird, fahren Sie fort. Wenn PENDING_CREATE angezeigt wird, warten Sie einen Moment und führen Sie den Befehl noch einmal aus.

Gewähren Sie dem Cloud SQL-Dienstkonto Zugriff auf Vertex AI (erforderlich für die In-Database-Embedding-Funktion):

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

Erstellen Sie die Datenbank:

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

Die Ausgabe sollte so aussehen:

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

Checkpoint:Ihre .env-Datei enthält GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION, REGION und DB_PASSWORD. Die Cloud SQL-Instanz restaurant-db wird ausgeführt. toolbox ist in Ihrem PATH verfügbar (durch setup_prerequisites.sh installiert). Python-Abhängigkeiten sind installiert.

Daten in die Datenbank einlesen

Laden Sie Ihre Umgebungsvariablen und führen Sie das Datenbank-Seed-Skript aus, um das Schema zu erstellen und 16 Menüelemente einzufügen:

source .env
uv run python scripts/seed_db.py

Erwartete Ausgabe:

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

Vektoreinbettungen für die semantische Suche generieren:

uv run python scripts/generate_embeddings.py

Erwartete Ausgabe:

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

Dazu wird die integrierte embedding()-Funktion von Cloud SQL (über die google_ml_integration-Erweiterung) verwendet, um gemini-embedding-001 direkt über SQL aufzurufen. Die 3.072-dimensionalen Vektoren werden in der Spalte embedding von menu_items gespeichert. Es ist kein anwendungsseitiger Einbettungscode erforderlich.

Basis-Agent testen

Starten Sie die MCP Toolbox als Hintergrundprozess:

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

Die Toolbox stellt Datenbanktools über HTTP bereit. Der Agent stellt über http://127.0.0.1:5000 eine Verbindung her.

Starten Sie die ADK-Entwicklungsoberfläche:

uv run adk web .

Öffnen Sie die Entwickler-UI in Ihrem Browser. Testen Sie den Agent dann mit diesen Prompts:

What appetizers do you have?

Prüfen:Der Agent fragt die Datenbank ab und gibt Menüpunkte zurück.

I'm vegetarian

Überprüfen:Der Agent speichert die Ernährungspräferenz im Agent-Status.

Can I make a reservation for tomorrow?

Prüfen:Der Agent kann dies nicht verarbeiten (es sind noch keine Reservierungstools vorhanden).

Beenden Sie die ADK-Entwicklungsoberfläche zweimal mit Ctrl+C. Lassen Sie die Toolbox im Hintergrund laufen. Sie benötigen sie später noch einmal.

Checkpoint:Der Basis-Agent funktioniert – die Menüsuche (Keyword + semantisch) und die Ernährungspräferenzen funktionieren richtig. Reservierungsanfragen schlagen fehl, weil keine Reservierungstools vorhanden sind. Sie kennen die Projektstruktur und wissen, welche Lücke Sie schließen werden.

5. Projektkontext mit Antigravity bootstrappen

Nun simulieren wir die Situation mit einer Bedingung, die unserem Arbeitsalltag „etwas näher“ kommt:

• Schlecht verwaltetes Repository
• README veraltet
• Dokumentationen werden nicht häufig aktualisiert

Hinweis:Wenn dies nicht auf Sie zutrifft, können Sie sich glücklich schätzen.

Als Erstes erstellen wir in solchen Fällen in der Regel eine Karte oder einen Kontext für das Projekt, an dem Antigravity arbeiten soll. In diesem Schritt wird ein Beispiel für einen Ansatz gezeigt, mit dem Antigravity ein umfassendes Verständnis einer vorhandenen Codebasis vermittelt werden kann. Dazu wird ein Skill erstellt, der das Repository analysiert und ein Projektkontextdokument generiert.

Außerdem wird die Projektverfassung eingerichtet – die nicht verhandelbaren Grundsätze, anhand derer die SDD-Workflows validiert werden. Zusammen liefern sie Antigravity den Kontext und die Einschränkungen, die für die SDD-Zyklen später erforderlich sind.

Die Antigravity-Kontexthierarchie

Antigravity verwendet drei Kontextebenen mit jeweils unterschiedlichem Umfang:

• Regeln (.agents/rules/): Immer aktive Anweisungen. In jeder Unterhaltung in diesem Arbeitsbereich sind sie zu sehen ( sofern Sie sie aktiviert haben). Verwenden Sie Regeln für projektweiten Kontext wie Architektur-Entscheidungen, Codierungsstandards oder Informationen zum Technologiestack.
• Kompetenzen (.agents/skills/): On-Demand-Wissen. Antigravity lädt einen Skill nur, wenn die aktuelle Aufgabe mit dem Feld description des Skills übereinstimmt. Skills für fachbereichsspezifisches Referenzmaterial verwenden
• Workflows (.agents/workflows/): Gespeicherte Prompts, die mit /-Befehlen ausgelöst werden. Verwenden Sie Workflows für wiederholbare mehrstufige Prozesse wie die SDD-Pipeline.

Hinweis:Das Projekt enthält derzeit Workflows (SDD-Pipeline) und einen Skill (ADK-Agent-Entwicklung), aber keine Regeln. Eine project-context.md-Regel ermöglicht Antigravity ein dauerhaftes Verständnis der Codebasis – welche Technologien verwendet werden, wie Dateien organisiert sind und was bisher entwickelt wurde.

Fähigkeiten aktivieren

Das Starter-Repository enthält zwei vorgefertigte Skills in .agents/skills/. Sie enthalten detaillierte Anleitungen, beginnen aber mit TODO(codelab)-Kommentaren anstelle des erforderlichen YAML-Frontmatter. Ohne Frontmatter kann Antigravity sie nicht erkennen.

Für Antigravity-Skills ist oben in der Datei ein YAML-Frontmatter-Block mit zwei Feldern erforderlich:

• name: Eine eindeutige Kennung für den Skill.
• description: Eine Zusammenfassung in natürlicher Sprache, die Antigravity abgleicht, um zu entscheiden, welcher Skill für eine bestimmte Anfrage geladen werden soll.

Öffnen

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

im Editor. Ersetzen Sie die beiden TODO(codelab)-Kommentarzeilen oben durch dieses Frontmatter:

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

Hinweise: Der ADK-Agenten-Entwicklungsskill enthält komprimierte Muster und Beispiele aus fünf ADK-Codelabs: Agentenstruktur, Tool-Typen, Statusverwaltung, Bereitstellung.

Öffnen

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

im Editor. Ersetzen Sie die beiden TODO(codelab)-Kommentarzeilen oben durch dieses Frontmatter:

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

Hinweise:Lesen Sie die Datei repo-research SKILL.md sorgfältig durch. Dies ist ein Beispiel für einen Prompt, mit dem Sie Ihr Repository analysieren können. Die Regeln für inkrementelle Updates sind bewusst konservativ gehalten. Wenn der Kontext von Antigravity während der Recherche erschöpft ist oder die Unterhaltung unterbrochen wird, wird alles, was bisher ermittelt wurde, bereits in der Datei gespeichert. Wenn Sie den Skill noch einmal aufrufen, wird er an der Stelle fortgesetzt, an der er beendet wurde.

Achtung! Wenn Sie ein großes Repository analysieren, kann Ihr Kontingent schnell aufgebraucht sein.

Prüfen Sie, ob beide Skills gültige Frontmatter haben:

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

Jedes sollte ----Trennzeichen enthalten, die die Felder name: und description: umschließen. Wenn die Trennzeichen oder Felder fehlen, erkennt Antigravity den Skill nicht.

Beide Skills werden bei Bedarf geladen. Antigravity gleicht Ihre Anfrage mit dem Feld description ab und ruft die vollständigen Anweisungen nur bei Bedarf ab.

Projektkontext generieren

Prüfen Sie, ob das Verzeichnis „rules“ vorhanden ist:

mkdir -p .agents/rules

Starten Sie im Agent Manager/Chat-Feld von Antigravity (im Editormodus drücken Sie ctrl + L) eine neue Unterhaltung. Typ:

Research this repository and create a project context document

Antigravity ordnet Ihre Anfrage dem Skill repo-research zu und beginnt mit der systematischen Analyse der Codebasis. Es liest Konfigurationsdateien, Quellcode und Dokumentation und füllt dann die Vorlage für den Projektkontext mit den Ergebnissen.

Öffnen Sie nach Abschluss des Vorgangs .agents/rules/project-context.md im Editor. Es enthält konkrete Informationen zum Projekt: Technologiestack (Python 3.12, ADK, MCP Toolbox, Cloud SQL), Projektstruktur, Datenmodell (Tabelle „menu_items“ mit pgvector) und externe Integrationen.

Tipp:Das Projektkontextdokument wächst mit dem Fortschritt des Projekts. Sie können den Skill noch einmal ausführen, um den Kontext mit den neuen Ergänzungen zu aktualisieren. Die Regeln für inkrementelle Updates sorgen dafür, dass vorhandene Inhalte beibehalten werden. Neue Technologien, Einheiten und Integrationen werden angehängt und nicht überschrieben.

Verwenden Sie für gezielte Aktualisierungen spezifische Prompts: „Recherchiere das Datenbankschema und aktualisiere den Projektkontext“ oder „Aktualisiere den Projektkontext mit den neuen Tool-Definitionen“. Jeder Aufruf wird dem vorhandenen Dokument hinzugefügt.

Projektkonstitution festlegen

In den SDD-Workflows wird während der Planung und Analyse auf eine Projektverfassung unter .specify/memory/constitution.md verwiesen. Im /speckit.plan-Workflow wird eine „Constitution Check“-Prüfung durchgeführt und /speckit.analyze kennzeichnet Verstöße als CRITICAL. Wenn die Verfassung als leere Vorlage mit Platzhalter-Tokens belassen wird, gibt es nichts, woran die Prüfungen vorgenommen werden können. Pläne und Analysen werden ohne Schutzmaßnahmen ausgeführt.

In der Verfassung werden nicht verhandelbare Projektgrundsätze definiert. Dies ist ein kleines Repository, das von einem einzelnen Entwickler verwaltet wird. Die Verfassung sollte diesen Umfang widerspiegeln. Halten Sie die Dinge einfach und einheitlich und vermeiden Sie eine Überentwicklung.

Starten Sie im Agent Manager von Antigravity eine neue Unterhaltung. Führen Sie den Workflow für die Verfassung aus:

/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 füllt die Verfassungsvorlage mit konkreten Grundsätzen, weist eine Version (1.0.0) zu und führt eine Konsistenzprüfung für die SDD-Vorlagen durch.

Sehen Sie sich die generierte Verfassung unter .specify/memory/constitution.md an. Prüfen Sie, ob die drei Grundsätze vorhanden und klar formuliert sind.

Hinweis:Die Verfassung ist bewusst auf drei Grundsätze beschränkt, die für einen einzelnen Entwickler gelten. Der /speckit.constitution-Workflow unterstützt inkrementelle Änderungen. Führen Sie ihn mit zusätzlichen Grundsätzen noch einmal aus. Die Versionsverwaltung wird automatisch übernommen. Bei einem Teamprojekt würden Sie Prinzipien für die Codeprüfung, Testdisziplin, Observability und API-Versionsverwaltung hinzufügen.

Checkpoint : .agents/rules/project-context.md ist mit konkreten Informationen zum Repository vorhanden. .agents/skills/repo-research/SKILL.md zeigt die Erstellung von Skills mit YAML-Frontmatter, Anweisungen und Konfliktlösung. .specify/memory/constitution.md enthält drei Projektgrundsätze, anhand derer die Planungs- und Analyse-Workflows validiert werden. Sie kennen die dreistufige Kontexthierarchie: Regeln (immer aktiv), Skills (auf Abruf) und Workflows (Slash-Befehle).

6. SDD Cycle – Funktion „Reservierung hinzufügen“

In diesem Schritt wird ein vollständiger SDD-Zyklus durchlaufen, um dem Restaurant-Concierge-Agenten die Reservierungsbuchung hinzuzufügen. Sie führen Antigravity durch die einzelnen Phasen – Spezifizieren, Klären, Planen, Aufgaben, Analysieren, Implementieren – und beobachten, wie jedes Artefakt auf dem vorherigen aufbaut. Das ist der Kern des Codelabs.

Wichtig! Antigravity ist ein KI‑Assistent. Die generierten Artefakte (Spezifikationen, Pläne, Aufgaben, Code) können sich von den in dieser Anleitung beschriebenen unterscheiden. Die Dateinamen, genauen SQL-Schemas und die Codestruktur können variieren. Das ist normal und gehört zur Arbeit mit KI-Unterstützung. Im SDD-Workflow prüfen Sie jedes Artefakt, bevor es zu Code wird. Treffen Sie also eine fundierte Entscheidung, um Ausgaben, die nicht Ihren Erwartungen entsprechen, zu akzeptieren, zu ändern oder neu zu generieren.

Funktion angeben

Starten Sie im Agent Manager von Antigravity eine neue Unterhaltung. Geben Sie den Workflow-Befehl /speckit.specify mit einer Funktionsbeschreibung ein:

/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 erstellt einen Feature-Branch, generiert ein Spezifikationsdokument und führt eine Qualitätsvalidierung durch. Wenn Antigravity Fragen zur Klärung stellt, beantworten Sie diese anhand der obigen Funktionsbeschreibung.

Hinweis:Nach Abschluss der Spezifikation kann Antigravity Übergaben wie Build Technical Plan (Technischen Plan erstellen) oder Clarify Spec Requirements (Spezifikationsanforderungen klären) präsentieren. Diese sind ein Hinweis auf die nächste Workflowphase (/speckit.plan oder /speckit.clarify).

Die Spezifikation konzentriert sich auf WAS und WARUM, nicht auf WIE. Es wird die Nutzerfreundlichkeit beschrieben („Gäste können eine Reservierung vornehmen, indem sie ihren Namen, die Anzahl der Personen, das Datum und die Uhrzeit angeben“), ohne SQL-Tabellen, tools.yaml oder ADK-APIs zu erwähnen. Details zur Implementierung folgen in der Planungsphase.

Sehen Sie sich die generierte Spezifikation unter specs/<branch-name>/spec.md an. Prüfen Sie, ob die funktionalen Anforderungen und Erfolgskriterien berücksichtigt werden.

Spezifikation erläutern (optional)

Führen Sie den Workflow „Clarify“ aus, um unterbestimmte Bereiche in der Spezifikation zu identifizieren und zu beheben:

/speckit.clarify

Antigravity scannt die Spezifikation nach Unklarheiten, fehlenden Akzeptanzkriterien und unzureichend spezifizierten Anforderungen. Es werden gezielte Fragen zur Klärung gestellt, die jeweils mit einer kurzen Auswahl oder Formulierung beantwortet werden können. Ihre Antworten werden direkt in die Spezifikation codiert, sodass sie präziser ist, bevor die Planung beginnt.

Tipp:Der Schritt „Klären“ ist optional, wird aber für komplexe Funktionen empfohlen. Bei einfachen Spezifikationen können Sie direkt mit der Planung beginnen.

Implementierung planen

Planungsworkflow ausführen:

/speckit.plan

Antigravity generiert einen technischen Plan in zwei Phasen:

1. Recherchevorgang: Unbekannte Aspekte der vorhandenen Codebasis werden geklärt und research.md wird generiert.
2. Entwurfsphase: Erstellt data-model.md (Definition der Reservierungseinheit) und aktualisiert project-context.md.

Antigravity sollte bei der Planung die adk-agent-development-Fähigkeit nutzen. Prüfen Sie die wichtigsten Artefakte:

• specs/<branch-name>/plan.md – der technische Ansatz: welche Dateien geändert werden müssen, welche Muster zu befolgen sind
• specs/<branch-name>/data-model.md: die Definition der Reservierungsentität (Spalten, Typen, Beziehungen)
• specs/<branch-name>/research.md – getroffene Entscheidungen und Begründung

Aufgaben generieren

Workflow „Aufgaben“ ausführen

/speckit.tasks

Antigravity unterteilt den Plan in eine geordnete Aufgabenliste in specs/<branch-name>/tasks.md. Aufgaben folgen einem strengen Checklistenformat mit IDs, Prioritätsmarkierungen und Dateipfaden, z. B.:

- [ ] [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

Aufgaben sind in Phasen unterteilt: Einrichtung → Grundlagen → User-Storys → Optimierung. Sehen Sie sich die Aufgabenliste an, um zu verstehen, was erstellt und geändert wird.

Aufgaben analysieren (optional)

Führen Sie den Analyse-Workflow aus, um die Aufgaben auf Risiken und Lücken zu prüfen:

/speckit.analyze

Antigravity vergleicht die Aufgabenliste mit der Spezifikation und dem Plan und sucht nach fehlenden Grenzfalltests, Aufgaben, die in Konflikt stehen könnten, oder Lücken zwischen den Anforderungen der Spezifikation und der geplanten Arbeit. Beheben Sie kritische Probleme, bevor Sie die Implementierung vornehmen.

Tipp:Der Analyseschritt ist am nützlichsten, wenn die Aufgabenliste lang ist oder die Funktion mehrere Subsysteme betrifft. Bei einer fokussierten Funktion wie der Reservierungsbuchung reicht ein kurzer Scan aus.

7. Implementieren

Führen Sie den Implementierungsworkflow aus:

/speckit.implement

Antigravity präsentiert einen endgültigen Implementierungsplan und ein Aufgabenartefakt. Prüfen und genehmigen Sie sie, um fortzufahren.

Tipp:Sie können direkt einen Kommentar dazu abgeben. Dies ist nur mit dem integrierten Antigravity-Artefakt möglich.

Antigravity führt die Aufgaben aus und hakt jede ab, sobald sie erledigt ist. Wenn der Vorgang abgeschlossen ist, wird der vollständige Walkthrough angezeigt.

Codeänderungen testen

Prüfen Sie nach Abschluss der Implementierung, ob die wichtigsten Änderungen vorgenommen wurden. Die genauen Dateinamen und Inhalte können variieren, aber diese Muster sollten wie in tools.yaml und agent.py vorhanden sein:

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

Die Ausgabe sieht ungefähr so aus:

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

Und für agent.py

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

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

Vielleicht finden Sie Änderungen wie diese:

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

Hinweis:Wenn grep für keine der beiden Dateien Übereinstimmungen zurückgibt, wurde bei der Implementierung möglicherweise eine andere Namensgebung verwendet. Prüfen Sie in git diff, ob alle Änderungen vorgenommen wurden und ob die reservierungsbezogene Logik hinzugefügt wurde.

Die Änderungen sollten sich auf das Seed-Datenbankskript auswirken. Versuchen wir, es auszuführen.

source .env
uv run python scripts/seed_db.py

Das aktualisierte Skript sollte die Tabelle reservations erstellen, falls sie noch nicht vorhanden ist. Sie sollten eine Ausgabe sehen, die bestätigt, dass die neue Tabelle erstellt wurde (die vorhandenen menu_items-Daten bleiben erhalten).

Hinweis:Antigravity hat möglicherweise ein separates Migrationsskript erstellt (z.B. scripts/create_reservations.py) anstatt seed_db.py zu aktualisieren. Suchen Sie in git diff --name-only nach neuen Skripts in scripts/ und führen Sie diese stattdessen aus.

Wenn bis zu diesem Punkt alles gut läuft, können wir die Funktion in der Entwickler-UI des ADK-Agents testen. Starten Sie die Toolbox neu, um die neuen Tooldefinitionen in tools.yaml zu übernehmen. Beenden Sie alle vorhandenen Toolbox-Prozesse und starten Sie einen neuen:

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

Starten Sie die ADK-Entwicklungsoberfläche:

uv run adk web .

Öffnen Sie http://localhost:8000 in Ihrem Browser und testen Sie mit diesen Prompts:

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

Prüfen:Der Kundenservicemitarbeiter sollte die Reservierungsdetails bestätigen und die Reservierung erstellen.

Do I have any upcoming reservations?

Überprüfen:Der Agent sollte die gerade vorgenommene Reservierung auflisten.

Beenden Sie nun die ADK-Entwicklungsoberfläche mit Ctrl+C (zweimal).

Checkpoint:Der Agent übernimmt die Reservierungsbuchung und ‑suche. Sie haben einen vollständigen SDD-Zyklus durchlaufen: festlegen → klären → planen → Aufgaben → analysieren → implementieren → testen. In jeder Phase wurde ein versioniertes Artefakt in specs/<branch-name>/ erstellt.

8. Herausforderungen (optional)

Sie kennen jetzt den gesamten SDD-Workflow. So testen Sie es:

• Führen Sie einen zweiten SDD-Zyklus aus, um eine Webchat-Oberfläche für den Restaurant-Concierge zu erstellen – diesmal ohne Schritt-für-Schritt-Anleitung.
• Agent für das Produktionsszenario in Cloud Run bereitstellen

Hinweise

• Das Projekt hat kein Frontend-Framework. Antigravity sollte reines HTML/CSS/JS vorschlagen. Wenn React oder Ähnliches vorgeschlagen wird, sollte es auf Einfachheit ausgerichtet werden (das Prinzip „Keep it simple“ Ihrer Verfassung sollte dies auffangen).
• Der ADK-Server stellt /run_sse für das Streaming und /apps/{app_name}/users/{user_id}/sessions für die Sitzungsverwaltung bereit. Antigravity ermittelt diese aus dem Projektkontext.
• Starten Sie den Server nach der Implementierung mit uv run uvicorn server:app --host 0.0.0.0 --port 8080 (nicht adk web), damit die Bereitstellung statischer Dateien funktioniert.
• Testen Sie unter http://localhost:8080/static/index.html.
• In den Referenz-Codelabs wird bereits gezeigt, wie ADK-Agenten bereitgestellt und beibehalten werden. Gib Antigravity Referenzen dazu!

9. Glückwunsch!

Sie haben einen ADK-Agenten für Restaurant-Concierge-Dienste mit der Reservierungsbuchung erweitert – vollständig über die SDD-Workflows von Antigravity, ohne Anwendungscode manuell zu schreiben.

Was Sie erstellt haben

• Ein ADK-Agent für Restaurant-Concierge mit Menüsuche, semantischer Suche, Erfassung von Ernährungspräferenzen und Reservierungsbuchung
• Eine Antigravity-Skill für die Repository-Recherche, die ein Projektkontextdokument generiert und verwaltet
• Eine Projektverfassung, die nicht verhandelbare Grundsätze während der Planung und Analyse durchsetzt
• Ein vollständiger SDD-Zyklus, der den Workflow „Spezifizieren → Klären → Planen → Aufgaben → Analysieren → Implementieren“ veranschaulicht

Das haben Sie gelernt

• Spezifikationsgesteuerte Entwicklungsworkflows in Antigravity verwenden, um einer vorhandenen Codebasis systematisch Funktionen hinzuzufügen
• Antigravity-Skills erstellen, die Domainwissen für die Wiederverwendung in Unterhaltungen bündeln
• So wird der Projektkontext so eingerichtet, dass Antigravity fundierte Entscheidungen zu Architektur, Mustern und Technologie treffen kann
• Festlegen einer Projektverfassung, anhand derer die SDD-Workflows validiert werden
• ADK-Agenten mit neuen datenbankgestützten Tools über die MCP Toolbox erweitern

Bereinigen

Beenden Sie alle laufenden lokalen Prozesse (Toolbox):

pkill -f toolbox 2>/dev/null

Löschen Sie die Cloud SQL-Instanz, um laufende Gebühren zu vermeiden:

gcloud sql instances delete restaurant-db --quiet

Optional: Gesamtes Projekt löschen:

gcloud projects delete $GOOGLE_CLOUD_PROJECT

Wichtig:Sie können diesen Löschvorgang für einen begrenzten Zeitraum mit dem Befehl gcloud projects undelete ${GOOGLE_CLOUD_PROJECT} rückgängig machen.