Sviluppo di agenti ADK basato sulle specifiche con Antigravity e Spec-kit

1. Introduzione

L'aggiunta di funzionalità a un agente esistente, una nuova funzionalità basata su database, in genere comporta la scrittura di boilerplate, la configurazione delle integrazioni e il mantenimento della coerenza con i pattern già presenti nel codebase. Antigravity accelera ogni fase di questo processo: analizza la tua base di codice per creare il contesto necessario, produce specifiche strutturate e piani di implementazione da esaminare ed esegue le modifiche al codice. Tutto ciò è guidato dalla conoscenza del dominio, che ti aiuta ad acquisire competenze riutilizzabili e una costituzione del progetto che impone principi non negoziabili. Questo codelab introduce un modo per potenziare il paradigma di sviluppo basato sulle specifiche di Antigravity introducendo un nuovo ciclo per migliorare la documentazione delle specifiche che fa riferimento in modo massiccio a spec-kit.

Cosa creerai

Un'applicazione di concierge per ristoranti in esecuzione locale con prenotazione aggiunta tramite un ciclo SDD completo:

• Prenotazione: gli ospiti prenotano tavoli e controllano le prenotazioni, supportati da nuovi strumenti di database MCP Toolbox e da una tabella Cloud SQL reservations
• (Sfida) – sviluppa la tua UI per l'agente
• (Sfida) – esegui il deployment su Google Cloud con l'aiuto dell'agente Antigravity

Il codice iniziale fornisce un agente ADK funzionante con ricerca di menu (parole chiave + semantica tramite MCP Toolbox) e monitoraggio delle preferenze alimentari (tramite ToolContext). Puoi estenderlo senza scrivere codice dell'applicazione a mano. Antigravity gestisce l'implementazione in base alle tue specifiche.

Obiettivi didattici

• Come eseguire il bootstrap del contesto del progetto in modo che Antigravity comprenda una codebase esistente
• Come creare competenze Antigravity che includono conoscenze del dominio (ad es. ADK codelab patterns) for reuse
• Come impostare una costituzione del progetto rispetto alla quale i flussi di lavoro SDD vengono convalidati durante la pianificazione e l'analisi
• Come utilizzare i flussi di lavoro di sviluppo basato sulle specifiche (SDD) in Antigravity per aggiungere sistematicamente funzionalità
• Come estendere un agente ADK con nuovi strumenti basati su database tramite MCP Toolbox

Prerequisiti

• Google Antigravity e git installati sulla tua macchina locale
• Un account Google Cloud con un account di fatturazione di prova abilitato
• Il completamento precedente dei quattro codelab ADK propedeutici (o conoscenze equivalenti) sarà utile per comprendere il contesto dello scenario d'uso:
• Building AI Agents with ADK: The Foundation
• Creazione di agenti AI con ADK: strumenti per potenziare le funzionalità
• Creazione di agenti AI persistenti con ADK e Cloud SQL
• Esegui il deployment, gestisci e osserva l'agente ADK su Cloud Run
• Database come strumento: RAG agentica con ADK, MCP Toolbox e Cloud SQL

2. Configura l'ambiente

NOTE IMPORTANTI:

Questo tutorial richiede un progetto Google Cloud con un account di fatturazione attivo. Se non ne hai ancora uno, segui i passaggi riportati di seguito per ottenere un account di fatturazione di prova che può essere utilizzato per questo tutorial:

1. Apri finestra di navigazione in incognito
2. Se partecipi a una sessione di workshop, l'URL del portale di utilizzo viene in genere fornito nella sessione. In alternativa, puoi accedere a questo portale di utilizzo dell'account di fatturazione di prova.
3. Accedi utilizzando il tuo account Gmail personale ( altri indirizzi email o Google Workspace non funzionano). )
4. Segui le istruzioni per il riscatto passo passo.

Questo passaggio clona il repository iniziale, esegue l'autenticazione con Google Cloud, esegue il provisioning di un database Cloud SQL e prepara l'ambiente locale Antigravity.

Note: questo codelab viene eseguito interamente in Google Antigravity sul tuo computer locale. La configurazione include l'autenticazione manuale utilizzando il comando CLI gcloud

Clona il repository iniziale

Apri un terminale in Antigravity (o nel terminale di sistema). Clona il repository complementare e accedi alla directory:

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

Apri il repository clonato in Antigravity. File->Apri cartella->seleziona la directory clonata sdd-adk-agents-agy

Rimuovi il telecomando upstream. I flussi di lavoro SDD creano rami Git per le specifiche delle funzionalità. La rimozione del repository remoto impedisce il push accidentale nel repository iniziale:

git remote remove origin

Importante:i flussi di lavoro SDD in questo codelab utilizzano i rami git per organizzare le specifiche delle funzionalità. La rimozione del repository remoto origin garantisce che i rami e i commit locali rimangano locali. Se vuoi eseguire il backup del tuo lavoro, aggiungi il tuo telecomando: git remote add origin <your-repo-url>

Installa i prerequisiti

Esegui lo script dei prerequisiti. Verifica la presenza di (e installa se mancanti) git, curl, gcloud, uv, Python 3.12 e MCP Toolbox:

bash scripts/setup_prerequisites.sh

Note:il download di tutti i prerequisiti richiederà un po' di tempo. Apri una nuova scheda per continuare con la sezione successiva mentre aspetti che il download venga completato.

Autenticazione con Google Cloud

Esegui due comandi di autenticazione. Entrambi aprono un browser per OAuth:

gcloud auth login
gcloud auth application-default login

Note:nel secondo comando OAuth, quando ti viene chiesto di selezionare l'autorizzazione. Controlla tutte le opzioni

Note: assicurati di eseguire l'autenticazione con l'email che utilizzi per richiedere l'account di fatturazione di prova

Poiché lavori localmente con Antigravity, l'autenticazione viene eseguita manualmente. auth login autentica la CLI gcloud. application-default login autentica gli SDK Google Cloud utilizzati dall'applicazione. Le chiamate ADK a Vertex AI e il connettore Python Cloud SQL si basano entrambi sulle credenziali predefinite dell'applicazione.

Configurare il progetto Google Cloud.

Scrivi le variabili di posizione in .env prima di eseguire lo script di configurazione del progetto:

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

• GOOGLE_CLOUD_LOCATION=global viene utilizzato per le chiamate API Vertex AI / Gemini.
• REGION=us-central1 viene utilizzato per Cloud SQL e altre infrastrutture Google Cloud

Scarica ed esegui lo script di configurazione del progetto. Crea o convalida un progetto Google Cloud con la fatturazione di prova e salva l'ID progetto in .env, quindi lo recupera:

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

Abilita le API richieste:

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

Note: l'abilitazione delle API potrebbe richiedere qualche istante. Devi farlo solo una volta per progetto.

Provisioning di Cloud SQL

Imposta la password del database e aggiungila a .env:

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

Importante:la password hardcoded riportata sopra è solo a scopo didattico. In un ambiente di produzione, archivia le credenziali in modo sicuro utilizzando un servizio come Secret Manager e fai riferimento a queste credenziali in fase di runtime. Non eseguire mai il commit dei secret in formato di testo normale nel controllo del codice sorgente.

Crea l'istanza Cloud SQL:

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

Il livello db-custom-1-3840 è il minimo richiesto per l'integrazione di Vertex AI ML. Il flag --enable-google-ml-integration consente a Cloud SQL di chiamare i modelli di incorporamento Gemini direttamente da SQL, il che supporta la funzionalità di ricerca semantica.

Note:l'esecuzione di questo comando richiede circa 5 minuti e verrà eseguito in background. Lascia l'esecuzione in questa scheda del terminale e apri una nuova scheda del terminale per i passaggi successivi.

Installa le dipendenze

Apri una nuova scheda del terminale. Assicurati di trovarti ancora nella directory del progetto del repository clonato e ricarica le variabili di ambiente:

source .env

Utilizzeremo uv come gestore di progetti Python. uv è un gestore di progetti e pacchetti Python veloce scritto in Rust ( documenti). Questo codelab lo utilizza per la velocità e la semplicità. Installa le dipendenze Python:

uv sync

Quindi aggiorna il file .env dell'agente ADK con la configurazione del progetto:

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

Ora dovremmo avere tutti i repository dell'agente ADK iniziali richiesti su cui lavorare. Ora parliamo di Antigravity e dello sviluppo basato sulle specifiche nella sezione successiva, mentre aspettiamo che tutto sia pronto.

3. Esplorare il codice iniziale e comprendere lo sviluppo basato sulle specifiche

Questo passaggio illustra la struttura del codice iniziale, introduce la metodologia di sviluppo basata sulle specifiche, inizializza il database e verifica che l'agente di base funzioni prima di iniziare a estenderlo.

Struttura del progetto

Apri il progetto del repository clonato nell'editor Antigravity e rivedi il layout della directory:

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

File di chiavi

File dell'applicazione agente

• restaurant_concierge/agent.py: l'agente principale. Un LlmAgent che combina gli strumenti di database MCP Toolbox con il monitoraggio delle preferenze alimentari basato su ToolContext. L'agente carica tutti gli strumenti dal server di Strumenti e aggiunge due funzioni Python (save_dietary_preference, get_dietary_preferences) che utilizzano ToolContext per gestire lo stato.
• tools.yaml: definizioni degli strumenti della cassetta degli attrezzi MCP. Sono definiti tre strumenti di ricerca nel menu: ricerca per parola chiave (search_menu), ricerca semantica tramite pgvector (semantic_search_menu) e filtro per categoria (get_menu_by_category). Non esistono ancora strumenti di prenotazione, che aggiungerai in un secondo momento
• server.py: un server FastAPI minimale che mostra come accedere all'ADK come oggetto FastAPI. get_fast_api_app() di ADK fornisce endpoint integrati, tra cui /run_sse per le API di gestione delle sessioni e dello streaming SSE.

Antigravity Files

• .agents/skills/adk-agent-development/SKILL.md: un'abilità preconfigurata ( generata da Antigravity) contenente pattern di riferimento condensati di tutti e quattro i codelab ADK. Al momento è inattiva (manca il frontmatter YAML). Dovrai aggiornarla in un secondo momento. Antigravity carica automaticamente questa competenza quando rileva un lavoro correlato alle funzionalità dell'agente ADK e ai relativi esempi. Queste informazioni guidano Antigravity quando pianifica la funzionalità di prenotazione in un secondo momento.
• .agents/skills/repo-research/SKILL.md: una competenza che insegna ad Antigravity come analizzare un repository in modo incrementale e produrre un documento di contesto del progetto strutturato. Utilizza un approccio in quattro fasi: scansione superficiale (solo struttura ad albero delle directory), file di configurazione e metadati, punti di ingresso e modelli di dati, quindi analisi approfondite mirate. Ogni fase si interrompe e scrive i risultati prima di procedere alla successiva. Come la skill ADK, è inattiva finché non aggiungi il frontmatter YAML in un secondo momento. Una volta attivato, richiamalo per generare .agents/rules/project-context.md, un documento di onboarding completo che copre architettura, dipendenze di runtime, superficie API e glossario del dominio.

Sviluppo basato sulle specifiche: dalla pianificazione integrata di Antigravity allo sviluppo basato sulle specifiche strutturato

Gli assistenti di programmazione AI semplificano la generazione di codice da un prompt. Il rischio: descrivi una funzionalità in una frase, l'assistente scrive centinaia di righe e tu le accetti perché sembrano corrette. A volte questa operazione viene chiamata "vibe coding": ti orienti in base alle sensazioni, accettando o rifiutando l'output in base a se ti sembra funzionare. È veloce per i prototipi e gli script temporanei. Si interrompe quando la base di codice cresce, quando le funzionalità interagiscono o quando rivisiti il codice settimane dopo e non riesci a ricostruire il motivo per cui è stata presa una decisione.

Lo sviluppo basato sulle specifiche (SDD) aggiunge struttura a questo ciclo. Prima di generare qualsiasi codice, scrivi una specifica: cosa fa la funzionalità, a chi è rivolta e quali sono i criteri di successo. L'assistente AI funziona in base a queste specifiche, così come tu quando esamini il suo output. La specifica diventa l'unica fonte attendibile per l'intent. Se il codice si discosta dalle specifiche, lo rilevi durante la revisione. Se i requisiti cambiano, aggiorna prima la specifica, poi rigenerala. Le decisioni sono documentate, non improvvisate.

Il compromesso è reale: l'SDD è più lento per funzionalità rispetto alla codifica delle vibrazioni. Scrivi i documenti prima di scrivere il codice. Ma il vantaggio è composto: ogni modifica futura al codice sorgente ha un contesto, ogni implementazione generata dall'AI ha un contratto esaminabile e puoi integrare collaboratori (umani o AI) indirizzandoli alle specifiche anziché spiegare le decisioni a memoria.

Antigravity segue già i principi di sviluppo basati sulle specifiche. Quando imposti l'agente sulla modalità di pianificazione, vengono prodotti due artefatti prima di scrivere qualsiasi codice:

• Piano di implementazione: una panoramica dell'approccio tecnico proposto, delle modifiche ai file e delle decisioni sull'architettura
• Elenco di attività: una suddivisione strutturata degli elementi di lavoro

Antigravity ti chiede di esaminare e approvare questi artefatti prima dell'esecuzione. Questo ciclo di pianificazione e implementazione è il fulcro dello sviluppo basato sulle specifiche: le specifiche guidano il codice, non il contrario.

Questo codelab si basa su queste fondamenta e propone un flusso di lavoro basato su opinioni e controllato dalla versione basato su spec-kit, un framework di sviluppo basato sulle specifiche di GitHub. Ogni funzionalità viene sottoposta a una pipeline deliberata in cui ogni artefatto è un documento autonomo che puoi esaminare, modificare e monitorare in git. La pipeline include due fasi facoltative di controllo qualità (chiarimento e analisi) che rilevano i problemi prima che diventino problemi di implementazione:

Fase	Artefatto	Purpose
/speckit.specify	spec.md	Definisci COSA creare (rivolto agli utenti, indipendente dalla tecnologia)
/speckit.clarify (facoltativo)	Aggiornamento: spec.md	Identificare le aree non specificate, porre domande di chiarimento mirate, codificare le risposte nella specifica
/speckit.plan	plan.md, data-model.md, research.md	Progetta COME realizzarlo (approccio tecnico, modelli di dati, ricerca)
/speckit.tasks	tasks.md	Suddividi il piano in passaggi ordinati e attuabili
/speckit.analyze (facoltativo)	Report di analisi	Esamina le attività per individuare rischi, lacune o casi limite mancanti prima dell'implementazione
/speckit.implement	Modifiche al codice	Esegui le attività, spuntandole una per una

Ogni artefatto viene salvato come file in specs/<feature-branch>/, controllato dalla versione in Git e riutilizzabile. Se una conversazione viene interrotta o vuoi rivedere le decisioni in un secondo momento, i documenti delle specifiche sono sempre disponibili e non vengono persi nella cronologia chat.

Note:l'artefatto integrato Antigravity ha la priorità nell'interfaccia utente, il che consente agli utenti di commentare l'artefatto generato ( anche l'immagine). ). Pertanto, in questo tutorial modifichiamo il prompt spec-kit originale per integrarlo con l'artefatto integrato nelle fasi implement.

Il repository iniziale include questi flussi di lavoro SDD in .agents/workflows/ e i modelli in .specify/templates/. Li utilizzerai in un secondo momento per aggiungere funzionalità all'agente.

4. Completa la configurazione di Cloud SQL e assicurati che l'agente di base funzioni

Torna alla scheda del terminale in cui è in esecuzione il comando di creazione di Cloud SQL. Al termine, verifica che l'istanza sia pronta:

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

Se l'output mostra RUNNABLE, procedi. Se viene visualizzato PENDING_CREATE, attendi un momento ed esegui di nuovo il comando.

Concedi al service account Cloud SQL l'accesso a Vertex AI (obbligatorio per la funzione di incorporamento nel database):

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

Crea il database:

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

Dovresti vedere un output simile al seguente:

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

Checkpoint: il file .env contiene GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION, REGION e DB_PASSWORD. L'istanza Cloud SQL restaurant-db è in esecuzione. toolbox è disponibile nel tuo PATH (installato da setup_prerequisites.sh). Le dipendenze Python sono installate.

Inserire dati nel database

Carica le variabili di ambiente ed esegui lo script di inizializzazione del database per creare lo schema e inserire 16 voci di menu:

source .env
uv run python scripts/seed_db.py

Output previsto:

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

Genera vector embedding per la ricerca semantica:

uv run python scripts/generate_embeddings.py

Output previsto:

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

Utilizza la funzione embedding() integrata di Cloud SQL (tramite l'estensione google_ml_integration) per chiamare gemini-embedding-001 direttamente da SQL. I vettori a 3072 dimensioni vengono memorizzati nella colonna embedding di menu_items, senza bisogno di codice di incorporamento lato applicazione.

Testa l'agente di base

Avvia la casella degli strumenti MCP come processo in background:

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

Toolbox gestisce gli strumenti del database tramite HTTP. L'agente si connette alle ore http://127.0.0.1:5000.

Avvia l'interfaccia utente di sviluppo dell'ADK:

uv run adk web .

Apri l'interfaccia utente di sviluppo nel browser. Poi, prova l'agente con questi prompt:

What appetizers do you have?

Ispeziona:l'agente esegue query sul database e restituisce le voci di menu

I'm vegetarian

Ispezione:l'agente salva la preferenza alimentare nello stato dell'agente

Can I make a reservation for tomorrow?

Ispezione:l'agente non può gestire questa richiesta (non esistono ancora strumenti di prenotazione)

Interrompi l'interfaccia utente di sviluppo dell'ADK con Ctrl+C due volte. Lascia in esecuzione Toolbox in background. Lo utilizzerai di nuovo in un secondo momento.

Checkpoint: l'agente di base funziona: la ricerca nel menu (parole chiave + semantica) e le preferenze alimentari funzionano correttamente. Le richieste di prenotazione non vanno a buon fine perché non esistono strumenti di prenotazione. Comprendi la struttura del progetto e la lacuna che stai per colmare.

5. Bootstrap del contesto del progetto con Antigravity

Ora simuliamo le cose con una condizione "un po' più vicina" al nostro lavoro quotidiano:

• Repository non ben gestito
• README obsoleto
• Documentazioni non aggiornate di frequente

Nota:se questa situazione non ti riguarda, considerati molto fortunato.

La prima cosa che vogliamo fare in questo tipo di situazione è di solito creare una mappa o un contesto sul progetto su cui vogliamo che Antigravity lavori. Questo passaggio mostra un esempio di approccio su come fornire ad Antigravity una comprensione approfondita di un codebase esistente creando una skill che analizzi il repository e generi un documento di contesto del progetto.

Inoltre, configura la costituzione del progetto, ovvero i principi non negoziabili che i flussi di lavoro SDD convalidano. Insieme, forniscono ad Antigravity il contesto e i vincoli necessari per i cicli SDD successivi.

Gerarchia del contesto di Antigravity

Antigravity utilizza tre livelli di contesto, ognuno con un ambito diverso:

• Regole (.agents/rules/): istruzioni sempre attive. Ogni conversazione in questo spazio di lavoro li vede ( se li hai attivati). Utilizza le regole per il contesto a livello di progetto, ad esempio decisioni sull'architettura, standard di codifica o informazioni sullo stack tecnologico.
• Competenze (.agents/skills/): conoscenze on demand. Antigravity carica un'abilità solo quando l'attività corrente corrisponde al campo description dell'abilità. Utilizza le competenze per materiale di riferimento specifico del dominio.
• Flussi di lavoro (.agents/workflows/): prompt salvati attivati con i comandi /. Utilizza i workflow per processi ripetibili in più passaggi come la pipeline SDD.

Nota:il progetto attualmente ha flussi di lavoro (pipeline SDD) e una skill (sviluppo di agenti ADK), ma nessuna regola. Una regola project-context.md consente ad Antigravity di comprendere in modo persistente il codebase: quali tecnologie sono in uso, come sono organizzati i file, cosa è stato creato finora.

Attivare le competenze

Il repository iniziale include due skill precompilate in .agents/skills/. Contengono istruzioni dettagliate, ma iniziano con commenti TODO(codelab) anziché con il frontmatter YAML richiesto. Senza frontespizio, Antigravity non può rilevarli.

Le competenze antigravitazionali richiedono un blocco frontmatter YAML nella parte superiore del file con due campi:

• name: un identificatore univoco per la skill
• description: un riepilogo in linguaggio naturale che Antigravity confronta per decidere quale skill caricare per una determinata richiesta

Apri

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

nell'editor. Sostituisci le due righe di commento TODO(codelab) nella parte superiore con questo frontespizio:

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

Note: la skill di sviluppo dell'agente ADK contiene pattern ed esempi condensati di cinque codelab ADK: struttura dell'agente, tipi di strumenti, gestione dello stato, deployment

Apri

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

nell'editor. Sostituisci le due righe di commento TODO(codelab) nella parte superiore con questo frontespizio:

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

Note: leggi in dettaglio il file SKILL.md repo-research. Questo è un esempio di prompt per analizzare il repository. Tieni presente che le regole di aggiornamento incrementale sono intenzionalmente conservative. Se il contesto di Antigravity termina durante la ricerca o la conversazione viene interrotta, tutto ciò che è stato scoperto finora viene salvato nel file. Se richiami la skill, questa riprende da dove era stata interrotta senza perdere i progressi.

Attenzione! L'analisi di un repository di grandi dimensioni può esaurire rapidamente la quota.

Verifica che entrambe le skill abbiano un frontespizio valido:

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

Ognuno deve mostrare i delimitatori --- che racchiudono i campi name: e description:. Se i delimitatori o i campi non sono presenti, Antigravity non riconoscerà la skill.

Entrambe le competenze vengono caricate on demand: Antigravity confronta la tua richiesta con il campo description e recupera le istruzioni complete solo quando sono pertinenti.

Genera il contesto del progetto

Assicurati che esista la directory delle regole:

mkdir -p .agents/rules

Nella casella Agent Manager/Chat di Antigravity (in modalità editor premi ctrl + L), avvia una nuova conversazione. Tipo:

Research this repository and create a project context document

Antigravity abbina la tua richiesta alla competenza repo-research e inizia ad analizzare sistematicamente il codebase. Legge i file di configurazione, il codice sorgente e la documentazione, quindi compila il modello di contesto del progetto con i risultati.

Una volta completata, apri .agents/rules/project-context.md nell'editor. Contiene informazioni concrete sul progetto: stack tecnologico (Python 3.12, ADK, MCP Toolbox, Cloud SQL), struttura del progetto, modello di dati (tabella menu_items con pgvector) e integrazioni esterne.

Suggerimento:il documento di contesto del progetto cresce man mano che il progetto si evolve. Puoi eseguire di nuovo la skill per aggiornare il contesto con le nuove aggiunte. Le regole di aggiornamento incrementale garantiscono la conservazione dei contenuti esistenti: le nuove tecnologie, entità e integrazioni vengono aggiunte, non sovrascritte.

Per aggiornamenti mirati, utilizza prompt specifici: "Analizza lo schema del database e aggiorna il contesto del progetto" o "Aggiorna il contesto del progetto con le nuove definizioni degli strumenti". Ogni chiamata viene aggiunta al documento esistente.

Imposta la costituzione del progetto

I workflow SDD fanno riferimento a una costituzione del progetto all'indirizzo .specify/memory/constitution.md durante la pianificazione e l'analisi. Il flusso di lavoro /speckit.plan esegue un "controllo della costituzione" e /speckit.analyze segnala le violazioni come CRITICHE. Se la costituzione viene lasciata come modello vuoto con token segnaposto, questi controlli non hanno nulla da convalidare: i piani e le analisi vengono eseguiti senza protezioni.

La costituzione definisce i principi non negoziabili del progetto. Si tratta di un piccolo repository gestito da un singolo sviluppatore, quindi la costituzione deve riflettere questo ambito: mantieni le cose semplici, coerenti ed evita di esagerare con la progettazione.

In Agent Manager di Antigravity, avvia una nuova conversazione. Esegui il workflow della costituzione:

/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 compila il modello di costituzione con principi concreti, assegna una versione (1.0.0) ed esegue un controllo di coerenza nei modelli SDD.

Esamina lo statuto generato all'indirizzo .specify/memory/constitution.md. Verifica che i tre principi siano presenti e chiaramente indicati.

Nota:la costituzione è volutamente limitata a tre principi pensati per un singolo sviluppatore. Il flusso di lavoro /speckit.constitution supporta le modifiche incrementali: eseguilo di nuovo con principi aggiuntivi e gestisce automaticamente il controllo delle versioni. Per un progetto di gruppo, aggiungeresti principi per la revisione del codice, la disciplina dei test, l'osservabilità e il controllo delle versioni delle API.

Checkpoint: .agents/rules/project-context.md esiste con informazioni concrete sul repository. .agents/skills/repo-research/SKILL.md mostra la creazione di skill con frontmatter YAML, istruzioni e risoluzione dei conflitti. .specify/memory/constitution.md contiene tre principi del progetto rispetto ai quali vengono convalidati i flussi di lavoro di pianificazione e analisi. Comprendi la gerarchia del contesto a tre livelli: regole (sempre attive), competenze (on demand), flussi di lavoro (comandi slash).

6. Ciclo SDD - Funzionalità Aggiungi prenotazione

Questo passaggio illustra un ciclo SDD completo per aggiungere la prenotazione al concierge del ristorante. Guiderai Antigravity in ogni fase: specifica, chiarisci, pianifica, attività, analizza, implementa, osservando come ogni artefatto si basa su quello precedente. Questa è l'esperienza di apprendimento principale del codelab.

Importante: Antigravity è un assistente AI. Gli artefatti generati (specifiche, piani, attività, codice) potrebbero differire da quelli descritti in questo tutorial. I nomi dei file, gli schemi SQL esatti e la struttura del codice possono variare. Questo è previsto e fa parte dello sviluppo basato sull'AI. Il flusso di lavoro SDD ti consente di esaminare ogni artefatto prima che diventi codice, quindi usa il tuo giudizio per accettare, modificare o rigenerare qualsiasi output che non corrisponde alle tue aspettative.

Specifica la funzionalità

In Agent Manager di Antigravity, avvia una nuova conversazione. Digita il comando del flusso di lavoro /speckit.specify con una descrizione della funzionalità:

/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 crea un ramo della funzionalità, genera un documento di specifiche ed esegue la convalida della qualità. Se Antigravity presenta domande di chiarimento, rispondi in base alla descrizione della funzionalità riportata sopra.

Nota:dopo aver completato la specifica, Antigravity potrebbe presentare trasferimenti come "Crea piano tecnico" o "Chiarisci requisiti specifiche". Questi sono gli indizi per la fase successiva del flusso di lavoro (/speckit.plan o /speckit.clarify)

La specifica si concentra sul COSA e sul PERCHÉ, non sul COME. Descrive l'esperienza utente ("Gli ospiti possono prenotare una prenotazione fornendo nome, numero di persone, data e ora") senza menzionare tabelle SQL, tools.yaml o API ADK. I dettagli dell'implementazione vengono forniti nella fase di pianificazione.

Esamina la specifica generata all'indirizzo specs/<branch-name>/spec.md. Verifica che acquisisca i requisiti funzionali e i criteri di successo.

(Facoltativo) Chiarisci la specifica

Esegui il workflow di chiarimento per identificare e risolvere le aree non specificate nelle specifiche:

/speckit.clarify

Antigravity analizza le specifiche per rilevare ambiguità, criteri di accettazione mancanti e requisiti non specificati. Pone domande di chiarimento mirate, a cui è possibile rispondere con una breve selezione o frase. Le risposte vengono codificate direttamente nella specifica, rendendola più precisa prima dell'inizio della pianificazione.

Suggerimento:il passaggio di chiarimento è facoltativo, ma consigliato per le funzionalità complesse. Per specifiche semplici, vai direttamente alla pianificazione.

Pianificare l'implementazione

Esegui il workflow di pianificazione:

/speckit.plan

Antigravity genera un piano tecnico in due fasi:

1. Fase di ricerca: risolve gli aspetti sconosciuti del codebase esistente e genera research.md
2. Fase di progettazione: crea data-model.md (definizione dell'entità prenotazioni) e aggiorna project-context.md

Antigravity deve utilizzare l'abilità adk-agent-development durante la pianificazione. Esamina gli artefatti chiave:

• specs/<branch-name>/plan.md: l'approccio tecnico: quali file modificare, quali pattern seguire
• specs/<branch-name>/data-model.md: la definizione dell'entità prenotazioni (colonne, tipi, relazioni)
• specs/<branch-name>/research.md: decisioni prese e motivazioni

Generare attività

Esegui il workflow delle attività

/speckit.tasks

Antigravity suddivide il piano in un elenco di attività ordinate in specs/<branch-name>/tasks.md. Le attività seguono un formato di elenco di controllo rigoroso con ID, indicatori di priorità e percorsi dei file, ad esempio:

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

Le attività sono organizzate in fasi: Configurazione → Di base → User story → Rifinitura. Scansiona l'elenco attività per capire cosa verrà creato e modificato.

(Facoltativo) Analizzare le attività

Esegui il flusso di lavoro di analisi per esaminare le attività relative a rischi e lacune:

/speckit.analyze

Antigravity confronta l'elenco delle attività con le specifiche e il piano, cercando casi limite mancanti, attività che potrebbero entrare in conflitto o lacune tra i requisiti delle specifiche e il lavoro pianificato. Risolvi i problemi critici prima dell'implementazione.

Suggerimento:il passaggio di analisi è più utile quando l'elenco delle attività è lungo o la funzionalità tocca più sottosistemi. Per una funzionalità mirata come la prenotazione, è sufficiente una scansione rapida.

7. Implementare

Esegui il workflow di implementazione:

/speckit.implement

Antigravity presenta un piano di implementazione finale e un artefatto dell'attività. Esaminalo e approvalo per procedere.

Suggerimento:puoi commentarlo direttamente. Questa operazione può essere eseguita solo con l'artefatto integrato Antigravity

Antigravity esegue le attività, spuntandole man mano che le completa. Al termine, verrà visualizzata la procedura dettagliata completa.

Testare le modifiche al codice

Al termine dell'implementazione, verifica che siano state apportate le modifiche chiave. I nomi e i contenuti esatti dei file possono variare, ma questi pattern devono essere presenti come in tools.yaml e agent.py:

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

L'output dovrebbe essere simile al seguente:

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

E per agent.py

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

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

Forse troverai modifiche come questa

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

Nota:se grep non restituisce corrispondenze per nessuno dei due file, l'implementazione potrebbe aver utilizzato una denominazione diversa. Controlla git diff per visualizzare l'insieme completo delle modifiche e verificare che sia stata aggiunta la logica relativa alla prenotazione.

Le modifiche dovrebbero interessare lo script del database seed, proviamo a eseguirlo

source .env
uv run python scripts/seed_db.py

Lo script aggiornato deve creare la tabella reservations se non esiste già. Dovresti visualizzare un output che conferma la creazione della nuova tabella (i dati menu_items esistenti vengono conservati).

Nota:Antigravity potrebbe aver creato uno script di migrazione separato (ad es. scripts/create_reservations.py) anziché aggiornare seed_db.py. Controlla git diff --name-only per eventuali nuovi script in scripts/ ed esegui questi ultimi.

Se tutto va bene fino a questo punto, possiamo testare la funzionalità nell'interfaccia utente di sviluppo dell'agente ADK. Riavvia la casella degli strumenti per acquisire le nuove definizioni degli strumenti in tools.yaml. Interrompi qualsiasi processo Toolbox esistente, quindi avviane uno nuovo:

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

Avvia l'interfaccia utente di sviluppo dell'ADK:

uv run adk web .

Apri http://localhost:8000 nel browser e prova con questi prompt:

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

Ispeziona:l'agente deve confermare i dettagli della prenotazione e crearla

Do I have any upcoming reservations?

Ispeziona:l'agente deve elencare la prenotazione che hai appena effettuato

Ora, arresta la UI di sviluppo dell'ADK con Ctrl+C due volte.

Checkpoint: l'agente gestisce la prenotazione e la ricerca delle prenotazioni. Hai completato un ciclo SDD completo: specifica → chiarisci → pianifica → attività → analizza → implementa → testa. Ogni fase ha prodotto un artefatto con controllo delle versioni in specs/<branch-name>/.

8. Sfide (facoltative)

Ora conosci l'intero flusso di lavoro SDD. Mettilo alla prova:

• Esegui un secondo ciclo SDD per creare un'interfaccia di chat web per il concierge del ristorante, questa volta senza indicazioni passo passo.
• Esegui il deployment dell'agente in Cloud Run per lo scenario di produzione

Suggerimenti

• Il progetto non ha un framework frontend. Antigravity dovrebbe proporre HTML/CSS/JS di base. Se suggerisce React o simili, invitalo a semplificare (il principio "semplifica" della tua costituzione dovrebbe risolvere il problema).
• Il server ADK espone /run_sse per lo streaming e /apps/{app_name}/users/{user_id}/sessions per la gestione delle sessioni. Antigravity li rileva dal contesto del progetto.
• Dopo l'implementazione, avvia il server con uv run uvicorn server:app --host 0.0.0.0 --port 8080 (non adk web) in modo che il montaggio del file statico funzioni.
• Test presso http://localhost:8080/static/index.html.
• I codelab di riferimento mostrano già come eseguire il deployment e rendere persistente l'agente ADK. Fai riferimento a questi codelab in Antigravity.

9. Complimenti!

Hai esteso un agente ADK di concierge del ristorante con la prenotazione, il tutto tramite i flussi di lavoro SDD di Antigravity, senza scrivere codice dell'applicazione a mano.

Cosa hai creato

• Un agente ADK concierge di un ristorante con ricerca di menu, ricerca semantica, monitoraggio delle preferenze alimentari e prenotazione
• Un'abilità Antigravity per la ricerca di repository che genera e gestisce un documento di contesto del progetto
• Una costituzione del progetto che impone principi non negoziabili durante la pianificazione e l'analisi
• Un ciclo SDD completo che dimostri il flusso di lavoro specifica → chiarisci → pianifica → attività → analizza → implementa

Che cosa hai imparato

• Come utilizzare i flussi di lavoro di sviluppo basati sulle specifiche in Antigravity per aggiungere sistematicamente funzionalità a un codebase esistente
• Come creare competenze Antigravity che raggruppano le conoscenze del dominio per il riutilizzo nelle conversazioni
• Come eseguire il bootstrap del contesto del progetto in modo che Antigravity prenda decisioni informate su architettura, pattern e scelte tecnologiche
• Come impostare una costituzione del progetto rispetto alla quale vengono convalidati i flussi di lavoro SDD
• Come estendere un agente ADK con nuovi strumenti basati su database tramite MCP Toolbox

Esegui la pulizia

Interrompi eventuali processi locali in esecuzione (Toolbox):

pkill -f toolbox 2>/dev/null

Elimina l'istanza Cloud SQL per evitare addebiti continui:

gcloud sql instances delete restaurant-db --quiet

(Facoltativo) Elimina l'intero progetto:

gcloud projects delete $GOOGLE_CLOUD_PROJECT

Importante:puoi annullare questa operazione di eliminazione per un periodo di tempo limitato utilizzando questo comando gcloud projects undelete ${GOOGLE_CLOUD_PROJECT}