Desarrollo de agentes con ADK basados en especificaciones con Antigravity y Spec-kit

1. Introducción

Agregar funciones a un agente existente (una nueva capacidad respaldada por una base de datos) suele implicar escribir código repetitivo, conectar integraciones y mantener todo coherente con los patrones que ya se encuentran en la base de código. Antigravity acelera cada etapa de este proceso: analiza tu base de código para crear el contexto que necesita, produce especificaciones estructuradas y planes de implementación para tu revisión, y ejecuta los cambios de código, todo guiado por el conocimiento del dominio que te ayuda a capturar como habilidades reutilizables y una constitución del proyecto que aplica principios no negociables. En este codelab, se presenta una forma de potenciar el paradigma de desarrollo basado en especificaciones de Antigravity con la introducción de un nuevo ciclo para impulsar la documentación de especificaciones que hace referencia en gran medida a spec-kit.

Qué compilarás

Una aplicación de asistente de restaurante que se ejecuta de forma local con la reserva de restaurantes agregada a través de un ciclo de SDD completo:

• Reservas: Los invitados reservan mesas y verifican las reservas, con el respaldo de las nuevas herramientas de la base de datos de MCP Toolbox y una tabla reservations de Cloud SQL
• (Desafío): Desarrolla tu propia IU para el agente
• (Desafío): Realiza la implementación en Google Cloud con la ayuda del agente de Antigravity

El código de partida proporciona un agente de ADK funcional con búsqueda de menú (palabra clave + semántica a través de MCP Toolbox) y seguimiento de preferencias dietéticas (a través de ToolContext). Puedes extenderlo sin escribir código de aplicación de forma manual, ya que Antigravity controla la implementación según tus especificaciones.

Qué aprenderás

• Cómo inicializar el contexto del proyecto para que Antigravity comprenda una base de código existente
• Cómo crear habilidades de Antigravity que empaqueten conocimiento del dominio (p.ej., Patrones de codelab del ADK) para reutilizar
• Cómo establecer una constitución del proyecto con la que los flujos de trabajo del SDD realizan validaciones durante la planificación y el análisis
• Cómo usar los flujos de trabajo de desarrollo basado en especificaciones (SDD) en Antigravity para agregar funciones de forma sistemática
• Cómo extender un agente del ADK con nuevas herramientas respaldadas por bases de datos a través de MCP Toolbox

Requisitos previos

• Google Antigravity y git instalados en tu máquina local
• Una cuenta de Google Cloud con una cuenta de facturación de prueba habilitada
• Haber completado los cuatro codelabs de requisitos previos del ADK (o tener conocimientos equivalentes) será útil para comprender el contexto del caso de uso:
• Crea agentes de IA con el ADK: conceptos fundamentales
• Crea agentes de IA con el ADK: Poténcialos con herramientas
• Cómo crear agentes de IA persistentes con el ADK y Cloud SQL
• Implementa, administra y observa el agente del ADK en Cloud Run
• Base de datos como herramienta: RAG agente con ADK, MCP Toolbox y Cloud SQL

2. Configura tu entorno

NOTAS IMPORTANTES:

En este instructivo, se requiere un proyecto de Google Cloud con una cuenta de facturación activa. Si aún no tienes una, sigue los pasos que se indican a continuación para obtener una cuenta de facturación de prueba que se pueda usar en este instructivo:

1. Abrir ventana de incógnito
2. Si te unes a una sesión de taller, la URL del portal de canje suele proporcionarse en la sesión. De lo contrario, puedes navegar a este portal de canje de cuentas de facturación de prueba.
3. Accede con tu cuenta personal de Gmail ( no funcionarán las cuentas de Google Workspace ni otros correos electrónicos). ).
4. Sigue las instrucciones de canje paso a paso.

En este paso, se clona el repositorio de inicio, se realiza la autenticación con Google Cloud, se aprovisiona una base de datos de Cloud SQL y se prepara tu entorno local de Antigravity.

Notas: Este codelab se ejecuta por completo en Google Antigravity en tu máquina local. La configuración incluye la autenticación manual con el comando gcloud de la CLI

Clona el repositorio inicial

Abre una terminal en Antigravity (o en la terminal del sistema). Clona el repo complementario y accede al directorio:

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

Abre el repositorio clonado en Antigravity. File->Open Folder->selecciona el directorio clonado sdd-adk-agents-agy

Quita el control remoto upstream. Los flujos de trabajo de SDD crean ramas de Git para las especificaciones de funciones. Quitar el repositorio remoto evita que se envíe accidentalmente al repositorio de inicio:

git remote remove origin

Importante: Los flujos de trabajo de SDD en este codelab usan ramas git para organizar las especificaciones de funciones. Quitar el control remoto origin garantiza que tus ramas y confirmaciones locales sigan siendo locales. Si quieres crear una copia de seguridad de tu trabajo, agrega tu propio control remoto: git remote add origin <your-repo-url>

Requisitos previos a la instalación

Ejecuta la secuencia de comandos de requisitos previos. Verifica (y, si falta, instala) git, curl, gcloud, uv, Python 3.12 y MCP Toolbox:

bash scripts/setup_prerequisites.sh

Notas: La descarga de todos los requisitos previos tardará un tiempo. Abre una pestaña nueva para continuar con la siguiente sección mientras esperas a que finalice la descarga.

Autentica con Google Cloud

Ejecuta dos comandos de autenticación. Ambos abren un navegador para OAuth:

gcloud auth login
gcloud auth application-default login

Notas: En el segundo comando de OAuth, cuando se te solicite que selecciones el permiso. Revisa todas las opciones

Notas: Asegúrate de autenticarte con el correo electrónico que usas para reclamar la cuenta de facturación de prueba.

Como trabajas de forma local con Antigravity, te autenticas de forma manual. auth login autentica la CLI de gcloud. application-default login autentica los SDKs de Google Cloud que usa tu aplicación: las llamadas a Vertex AI del ADK y el conector de Cloud SQL para Python dependen de las credenciales predeterminadas de la aplicación.

Configura el proyecto de Google Cloud

Escribe las variables de ubicación en .env antes de ejecutar la secuencia de comandos de configuración del proyecto:

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

• GOOGLE_CLOUD_LOCATION=global se usa para las llamadas a la API de Vertex AI / Gemini.
• REGION=us-central1 se usa para Cloud SQL y otra infraestructura de GCP

Descarga y ejecuta la secuencia de comandos de configuración del proyecto. Crea o valida un proyecto de Google Cloud con facturación de prueba y guarda el ID del proyecto en .env. Luego, lo agrega como fuente:

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

Habilita las APIs necesarias:

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

Notas: Habilitar las APIs puede tardar un momento. Solo debes hacerlo una vez por proyecto.

Aprovisiona Cloud SQL

Establece la contraseña de la base de datos y agrégala a .env:

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

Importante: La contraseña codificada anterior solo se usa con fines de demostración. En un entorno de producción, almacena las credenciales de forma segura con un servicio como Secret Manager y haz referencia a ellas en el tiempo de ejecución. Nunca confirmes secretos de texto sin formato en el control de código fuente.

Crea la instancia de 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 &

El nivel db-custom-1-3840 es el mínimo requerido para la integración de AA de Vertex AI. La marca --enable-google-ml-integration permite que Cloud SQL llame a los modelos de incorporación de Gemini directamente desde SQL, lo que potencia la función de búsqueda semántica.

Notas: Este comando tarda aproximadamente 5 minutos y se ejecutará en segundo plano. Déjalo en ejecución en esta pestaña de la terminal y abre una pestaña de la terminal nueva para los próximos pasos.

Instala dependencias

Abre una nueva pestaña de la terminal. Asegúrate de que aún estés en el directorio del proyecto del repo clonado y vuelve a cargar las variables de entorno:

source .env

Usaremos uv como administrador de proyectos de Python. uv es un administrador de proyectos y paquetes de Python rápido escrito en Rust ( documentos ). En este codelab, se usa por su velocidad y simplicidad. Instala las dependencias de Python:

uv sync

Luego, actualiza el archivo .env del agente del ADK con la configuración de tu proyecto:

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

Ahora, deberíamos tener todos los repositorios de agentes de ADK iniciales necesarios para trabajar. Ahora hablemos más sobre Antigravity y el desarrollo basado en especificaciones en la siguiente sección mientras esperamos que todo esté listo.

3. Explora el código de partida y comprende el desarrollo basado en especificaciones

En este paso, se explica la estructura del código de partida, se presenta la metodología de desarrollo basado en especificaciones, se inicializa la base de datos y se verifica que el agente base funcione antes de comenzar a extenderlo.

Estructura del proyecto

Abre el proyecto del repo clonado en el editor de Antigravity y revisa el diseño del directorio:

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

Archivos de claves

Archivos de la aplicación del agente

• restaurant_concierge/agent.py: Es el agente principal. Un LlmAgent que combina las herramientas de base de datos de MCP Toolbox con el seguimiento de preferencias dietéticas basado en ToolContext. El agente carga todas las herramientas del servidor de Toolbox y agrega dos funciones de Python (save_dietary_preference, get_dietary_preferences) que usan ToolContext para administrar el estado.
• tools.yaml: Definiciones de herramientas de MCP Toolbox. Se definen tres herramientas de búsqueda en el menú: búsqueda por palabras clave (search_menu), búsqueda semántica a través de pgvector (semantic_search_menu) y filtro de categorías (get_menu_by_category). Aún no existen herramientas de reserva; las agregarás más adelante.
• server.py: Un servidor de FastAPI mínimo que muestra cómo puedes acceder al ADK como objeto de FastAPI. get_fast_api_app() del ADK proporciona extremos integrados, incluidos /run_sse para las APIs de administración de sesiones y transmisión de SSE.

Antigravity Files

• .agents/skills/adk-agent-development/SKILL.md: Es una habilidad preconfigurada ( generada por Antigravity) que contiene patrones de referencia condensados de los cuatro codelabs del ADK. Actualmente, está inactivo (falta el encabezado YAML), por lo que deberás actualizarlo más adelante. Antigravity carga esta habilidad automáticamente cuando detecta trabajo relacionado con las funciones del agente de ADK y sus ejemplos. Este es el conocimiento que guía a Antigravity cuando planifica la función de reserva más adelante.
• .agents/skills/repo-research/SKILL.md: Es una habilidad que le enseña a Antigravity a analizar un repositorio de forma incremental y a producir un documento de contexto del proyecto estructurado. Utiliza un enfoque de 4 fases: análisis superficial (solo el árbol de directorios), archivos de configuración y metadatos, puntos de entrada y modelos de datos, y, luego, análisis detallados específicos. Cada fase se detiene y escribe los hallazgos antes de pasar a la siguiente. Al igual que la habilidad del ADK, está inactiva hasta que agregues metadatos YAML más adelante. Una vez que se activa, invócala para generar .agents/rules/project-context.md, un documento de incorporación integral que abarca la arquitectura, las dependencias de tiempo de ejecución, la superficie de la API y el glosario de dominios.

Desarrollo basado en especificaciones: desde la planificación integrada de Antigravity hasta el SDD estructurado

Los asistentes de programación basados en IA facilitan la generación de código a partir de una instrucción. El riesgo es que describas una función en una oración, el asistente escriba cientos de líneas y la aceptes porque parece correcta. A veces, esto se denomina "programación de ambiente": diriges el proceso por intuición, aceptando o rechazando el resultado según si parece funcionar. Es rápido para prototipos y secuencias de comandos desechables. Se descompone cuando la base de código crece, cuando las funciones interactúan o cuando vuelves a revisar el código semanas después y no puedes reconstruir por qué se tomó una decisión.

El desarrollo basado en especificaciones (SDD) agrega estructura a este bucle. Antes de generar cualquier código, escribes una especificación: qué hace la función, a quién le sirve y cuáles son los criterios de éxito. El asistente de IA trabaja a partir de esas especificaciones, y tú también lo haces cuando revisas su resultado. La especificación se convierte en la única fuente de información sobre la intención. Si el código se desvía de las especificaciones, lo detectas en la revisión. Si cambian los requisitos, primero actualiza la especificación y, luego, vuelve a generar el código. Las decisiones se documentan, no se improvisan.

La compensación es real: la SDD es más lenta por función que la codificación de la vibra. Escribes documentos antes de escribir código. Pero los beneficios se acumulan: cada cambio futuro en el código base tiene contexto, cada implementación generada por IA tiene un contrato revisable y puedes incorporar colaboradores (humanos o de IA) mostrándoles especificaciones en lugar de explicar decisiones de memoria.

Antigravity ya sigue los principios de desarrollo basados en especificaciones. Cuando configuras el agente en el modo de planificación, produce dos artefactos antes de escribir cualquier código:

• Plan de implementación: Descripción general del enfoque técnico propuesto, los cambios en los archivos y las decisiones de arquitectura
• Lista de tareas: Un desglose estructurado de los elementos de trabajo

Antigravity te pide que revises y apruebes estos artefactos antes de la ejecución. Este bucle de planificación y, luego, implementación es el núcleo del desarrollo basado en especificaciones: las especificaciones guían el código, no al revés.

Este codelab lleva esa base más allá con un flujo de trabajo opinativo y con control de versiones basado en spec-kit, un framework de desarrollo basado en especificaciones de GitHub. Cada función pasa por una canalización deliberada en la que cada artefacto es un documento independiente que puedes revisar, editar y hacer un seguimiento en git. La canalización incluye dos fases opcionales de puerta de calidad (aclarar y analizar) que detectan problemas antes de que se conviertan en problemas de implementación:

Fase	Artefacto	Purpose
/speckit.specify	spec.md	Define QUÉ se debe compilar (orientado al usuario, independiente de la tecnología)
/speckit.clarify (opcional)	Última actualización: spec.md	Identificar áreas no especificadas, hacer preguntas de aclaración específicas y codificar las respuestas en la especificación
/speckit.plan	plan.md, data-model.md, research.md	Diseñar CÓMO construirlo (enfoque técnico, modelos de datos, investigación)
/speckit.tasks	tasks.md	Divide el plan en pasos ordenados y prácticos.
/speckit.analyze (opcional)	Informe de análisis	Revisar las tareas para detectar riesgos, brechas o casos extremos faltantes antes de la implementación
/speckit.implement	Cambios en el código	Ejecuta las tareas y marca cada una de ellas.

Cada artefacto se conserva como un archivo en specs/<feature-branch>/, se controla la versión en Git y se puede reutilizar. Si se interrumpe una conversación o quieres volver a revisar las decisiones más adelante, los documentos de especificaciones siempre estarán disponibles, no ocultos en un historial de chat.

Notas: El artefacto integrado antigravedad tiene superioridad en la IU, lo que permite que el usuario comente sobre el artefacto generado (¡incluso la imagen!). ). Por lo tanto, en este instructivo, modificaremos la instrucción spec-kit original para integrarla con el artefacto integrado en las fases de implement.

El repo de inicio incluye estos flujos de trabajo de SDD en .agents/workflows/ y plantillas en .specify/templates/. Los usarás más adelante para agregar funciones al agente.

4. Completa la configuración de Cloud SQL y asegúrate de que el agente básico funcione

Vuelve a la pestaña de la terminal en la que se ejecuta el comando de creación de Cloud SQL. Una vez que se complete, verifica que la instancia esté lista:

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

Si el resultado muestra RUNNABLE, continúa. Si muestra PENDING_CREATE, espera un momento y vuelve a ejecutar el comando.

Otorga a la cuenta de servicio de Cloud SQL acceso a Vertex AI (obligatorio para la función de incorporación en la base de datos):

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 la base de datos:

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

Deberías ver un resultado como este:

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

Punto de control: Tu archivo .env contiene GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION, REGION y DB_PASSWORD. La instancia restaurant-db de Cloud SQL está en ejecución. toolbox está disponible en tu PATH (instalado por setup_prerequisites.sh). Las dependencias de Python están instaladas.

Propaga la base de datos

Carga tus variables de entorno y ejecuta la secuencia de comandos de inicialización de la base de datos para crear el esquema y, luego, insertar 16 elementos de menú:

source .env
uv run python scripts/seed_db.py

Resultado esperado:

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

Genera embeddings de vectores para la búsqueda semántica:

uv run python scripts/generate_embeddings.py

Resultado esperado:

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

Esto usa la función embedding() integrada de Cloud SQL (a través de la extensión google_ml_integration) para llamar a gemini-embedding-001 directamente desde SQL. Los vectores de 3,072 dimensiones se almacenan en la columna embedding de menu_items, por lo que no se necesita código de incorporación del lado de la aplicación.

Prueba el agente base

Inicia MCP Toolbox como un proceso en segundo plano:

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 entrega herramientas de base de datos a través de HTTP. El agente se conecta a él en http://127.0.0.1:5000.

Inicia la IU de desarrollo del ADK:

uv run adk web .

Abre la IU para desarrolladores en tu navegador. Luego, prueba el agente con estas instrucciones:

What appetizers do you have?

Inspeccionar: El agente consulta la base de datos y devuelve elementos del menú.

I'm vegetarian

Inspeccionar: El agente guarda la preferencia dietética en su estado.

Can I make a reservation for tomorrow?

Inspeccionar: El agente no puede controlar esto (aún no existen herramientas de reserva).

Detén la IU de desarrollo del ADK con Ctrl+C dos veces. Deja Toolbox ejecutándose en segundo plano, ya que lo volverás a usar más adelante.

Punto de control: El agente base funciona correctamente: la búsqueda en el menú (semántica y por palabras clave) y las preferencias dietéticas funcionan correctamente. Las solicitudes de reserva fallan porque no existen herramientas de reserva. Comprendes la estructura del proyecto y la brecha que estás a punto de cubrir.

5. Cómo iniciar el contexto del proyecto con Antigravity

Ahora, simulemos las cosas con una condición que se acerque más a nuestro trabajo diario:

• Repositorio mal administrado
• README obsoleto
• Las documentaciones no se actualizan con frecuencia

Nota: Considera que tienes mucha suerte si esto no refleja tu condición.

Lo primero que queremos hacer en este tipo de situaciones es crear un mapa o contexto sobre el proyecto en el que queremos que trabaje Antigravity. En este paso, se muestra un ejemplo de un enfoque para que Antigravity comprenda en profundidad una base de código existente. Para ello, se crea una habilidad que analiza el repositorio y genera un documento de contexto del proyecto.

También establece la constitución del proyecto, es decir, los principios no negociables con los que se validan los flujos de trabajo del SDD. En conjunto, estos elementos le brindan a Antigravity el contexto y las restricciones que necesita para los ciclos de SDD más adelante.

La jerarquía de contexto de Antigravity

Antigravity usa tres niveles de contexto, cada uno con un alcance diferente:

• Reglas (.agents/rules/): Son instrucciones siempre activas. Todos los participantes de este espacio de trabajo las ven ( si las activaste). Usa reglas para el contexto de todo el proyecto, como decisiones de arquitectura, estándares de codificación o información de la pila de tecnología.
• Habilidades (.agents/skills/): Conocimiento a pedido. Antigravity carga una habilidad solo cuando la tarea actual coincide con el campo description de la habilidad. Usar habilidades para material de referencia específico del dominio
• Flujos de trabajo (.agents/workflows/): Son instrucciones guardadas que se activan con comandos de /. Usa flujos de trabajo para procesos repetibles de varios pasos, como la canalización de SDD.

Nota: Actualmente, el proyecto tiene flujos de trabajo (canalización de SDD) y una habilidad (desarrollo de agentes de ADK), pero no tiene reglas. Una regla de project-context.md le brinda a Antigravity una comprensión persistente de la base de código: qué tecnologías se usan, cómo se organizan los archivos y qué se compiló hasta el momento.

Activa las habilidades

El repo de inicio incluye dos habilidades escritas previamente en .agents/skills/. Contienen instrucciones detalladas, pero comienzan con comentarios TODO(codelab) en lugar del encabezado YAML requerido. Sin frontmatter, Antigravity no puede descubrirlos.

Las habilidades de antigravedad requieren un bloque de frontmatter YAML en la parte superior del archivo con dos campos:

• name: Es un identificador único de la skill.
• description: Es un resumen en lenguaje natural con el que Antigravity compara la solicitud para decidir qué habilidad cargar.

Abrir

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

en el editor Reemplaza las dos líneas de comentarios TODO(codelab) en la parte superior con este 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.
---

Notas: La habilidad de desarrollo de agentes del ADK contiene patrones condensados y ejemplos de cinco codelabs del ADK: estructura del agente, tipos de herramientas, administración de estados y

Abrir

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

en el editor Reemplaza las dos líneas de comentarios TODO(codelab) en la parte superior con este 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.
---

Notas: Lee el archivo SKILL.md de repo-research en detalle. Este es un ejemplo de instrucción para analizar tu repositorio. Ten en cuenta que las reglas de actualización incremental son intencionalmente conservadoras. Si el contexto de Antigravity se agota a mitad de la investigación o se interrumpe la conversación, todo lo que se descubrió hasta el momento ya se guardó en el archivo. Si vuelves a invocar la skill, se reanudará desde donde la dejaste sin perder el progreso.

Advertencia Analizar un repositorio grande puede agotar tu cuota rápidamente.

Verifica que ambas habilidades tengan un frontmatter válido:

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

Cada uno debe mostrar delimitadores --- que envuelvan los campos name: y description:. Si faltan los delimitadores o los campos, Antigravity no reconocerá la habilidad.

Ambas habilidades se cargan a pedido: Antigravity compara tu solicitud con el campo description y extrae las instrucciones completas solo cuando son pertinentes.

Genera el contexto del proyecto

Asegúrate de que exista el directorio de reglas:

mkdir -p .agents/rules

En el cuadro de chat o de Agent Manager de Antigravity (en el modo de edición, presiona ctrl + L), inicia una conversación nueva. Tipo:

Research this repository and create a project context document

Antigravity asocia tu solicitud con la habilidad repo-research y comienza a analizar la base de código de forma sistemática. Lee archivos de configuración, código fuente y documentación, y, luego, completa la plantilla de contexto del proyecto con sus hallazgos.

Cuando termines, abre .agents/rules/project-context.md en el editor. Contiene información concreta sobre el proyecto: pila de tecnología (Python 3.12, ADK, MCP Toolbox, Cloud SQL), estructura del proyecto, modelo de datos (tabla menu_items con pgvector) e integraciones externas.

Nota: El documento de contexto del proyecto crece a medida que el proyecto evoluciona. Puedes volver a ejecutar la skill para actualizar el contexto con las nuevas incorporaciones. Las reglas de actualización incremental garantizan que se conserve el contenido existente: se agregan nuevas tecnologías, entidades e integraciones, no se reemplazan.

Para las actualizaciones segmentadas, usa instrucciones específicas: "Investiga el esquema de la base de datos y actualiza el contexto del proyecto" o "Actualiza el contexto del proyecto con las nuevas definiciones de herramientas". Cada invocación se agrega al documento existente.

Establece la constitución del proyecto

Los flujos de trabajo de SDD hacen referencia a la constitución del proyecto en .specify/memory/constitution.md durante la planificación y el análisis. El flujo de trabajo /speckit.plan ejecuta una "verificación de la Constitución" en su contra, y /speckit.analyze marca los incumplimientos como CRÍTICOS. Si la constitución se deja como una plantilla en blanco con tokens de marcador de posición, estas verificaciones no tendrán nada con qué validar, y los planes y análisis se ejecutarán sin medidas de protección.

La constitución define los principios no negociables del proyecto. Este es un repositorio pequeño que mantiene un solo desarrollador, por lo que la constitución debe reflejar ese alcance: mantén las cosas simples y coherentes, y evita el exceso de ingeniería.

En el Administrador de agentes de Antigravity, inicia una nueva conversación. Ejecuta el flujo de trabajo de la constitución:

/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 completa la plantilla de constitución con principios concretos, asigna una versión (1.0.0) y ejecuta una verificación de coherencia en las plantillas del SDD.

Revisa la constitución generada en .specify/memory/constitution.md. Verifica que los tres principios estén presentes y se indiquen con claridad.

Nota: La constitución se mantiene deliberadamente en 3 principios enfocados en un desarrollador individual. El flujo de trabajo de /speckit.constitution admite modificaciones incrementales: vuelve a ejecutarlo con principios adicionales y se encargará del control de versiones automáticamente. En el caso de un proyecto de equipo, agregarías principios para la revisión de código, la disciplina de pruebas, la observabilidad y el control de versiones de la API.

Punto de control: .agents/rules/project-context.md existe con información concreta sobre el repositorio. .agents/skills/repo-research/SKILL.md muestra la creación de habilidades con encabezado YAML, instrucciones y resolución de conflictos. .specify/memory/constitution.md contiene tres principios del proyecto con los que se validan los flujos de trabajo de planificación y análisis. Comprendes la jerarquía de contexto de tres niveles: reglas (siempre activas), habilidades (a pedido) y flujos de trabajo (comandos con barra).

6. Ciclo de SDD: Función de agregar reserva

En este paso, se explica un ciclo completo de SDD para agregar la reserva de mesa al agente de asistente de restaurante. Conduces Antigravity a través de cada fase (especificar, aclarar, planificar, tareas, analizar, implementar) y observas cómo cada artefacto se basa en el anterior. Esta es la experiencia de aprendizaje principal del codelab.

Importante: Antigravity es un asistente de IA, por lo que los artefactos que genera (especificaciones, planes, tareas, código) pueden diferir de lo que se describe en este instructivo. Los nombres de los archivos, los esquemas SQL exactos y la estructura del código pueden variar. Esto es normal y forma parte del trabajo con el desarrollo asistido por IA. El flujo de trabajo de SDD garantiza que revises cada artefacto antes de que se convierta en código, por lo que debes usar tu criterio para aceptar, modificar o regenerar cualquier resultado que no coincida con tus expectativas.

Especifica el atributo

En el Administrador de agentes de Antigravity, inicia una nueva conversación. Escribe el comando de flujo de trabajo /speckit.specify con una descripción de la función:

/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 una rama de función, genera un documento de especificaciones y ejecuta la validación de calidad. Si Antigravity presenta preguntas aclaratorias, respóndelas según la descripción de la función anterior.

Nota: Después de completar la especificación, es posible que Antigravity presente transferencias como "Crear plan técnico" o "Aclarar requisitos de especificación". Son indicadores de la siguiente fase del flujo de trabajo (/speckit.plan o /speckit.clarify).

La especificación se centra en el QUÉ y el POR QUÉ, no en el CÓMO. Describe la experiencia del usuario ("Los invitados pueden reservar proporcionando su nombre, la cantidad de personas, la fecha y la hora") sin mencionar tablas de SQL, tools.yaml ni APIs del ADK. Los detalles de implementación se definen en la fase de planificación.

Revisa la especificación generada en specs/<branch-name>/spec.md. Verifica que capture los requisitos funcionales y los criterios de éxito.

Aclarar la especificación (opcional)

Ejecuta el flujo de trabajo de aclaración para identificar y resolver las áreas poco especificadas en las especificaciones:

/speckit.clarify

Antigravity analiza las especificaciones en busca de ambigüedades, criterios de aceptación faltantes y requisitos no especificados. Te hace preguntas específicas para aclarar dudas, y cada respuesta se puede dar con una selección o frase breve. Tus respuestas se codifican directamente en la especificación, lo que la hace más precisa antes de que comience la planificación.

Nota: El paso de aclaración es opcional, pero se recomienda para las funciones complejas. En el caso de las especificaciones sencillas, ve directamente a la planificación.

Planifica la implementación

Ejecuta el flujo de trabajo de planificación:

/speckit.plan

Antigravity genera un plan técnico en dos fases:

1. Fase de investigación: Resuelve las incógnitas sobre la base de código existente y genera research.md
2. Fase de diseño: Crea data-model.md (definición de la entidad de reservas) y actualiza project-context.md.

Antigravity debería usar la habilidad adk-agent-development durante la planificación. Revisa los artefactos clave:

• specs/<branch-name>/plan.md: El enfoque técnico: qué archivos modificar y qué patrones seguir
• specs/<branch-name>/data-model.md: Es la definición de la entidad de reservas (columnas, tipos y relaciones).
• specs/<branch-name>/research.md: Decisiones tomadas y justificación

Genera tareas

Ejecuta el flujo de trabajo de tareas

/speckit.tasks

Antigravity divide el plan en una lista de tareas ordenada en specs/<branch-name>/tasks.md. Las tareas siguen un formato de lista de verificación estricto con IDs, marcadores de prioridad y rutas de acceso a archivos, por ejemplo:

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

Las tareas se organizan en fases: Configuración → Fundamentos → Historias de usuario → Pulido. Revisa la lista de tareas para comprender qué se creará y modificará.

Analiza las tareas (opcional)

Ejecuta el flujo de trabajo de análisis para revisar las tareas en busca de riesgos y brechas:

/speckit.analyze

Antigravity verifica la lista de tareas en comparación con las especificaciones y el plan, y busca casos extremos faltantes, tareas que puedan entrar en conflicto o brechas entre los requisitos de las especificaciones y el trabajo planificado. Aborda los problemas críticos antes de la implementación.

Nota: El paso de análisis es más útil cuando la lista de tareas es larga o la función afecta a varios subsistemas. Para una función enfocada, como la reserva de un lugar, un análisis rápido es suficiente.

7. Implementación

Ejecuta el flujo de trabajo de implementación:

/speckit.implement

Antigravity presenta un plan de implementación final y un artefacto de tareas. Revísala y aprueba para continuar

Nota: Puedes comentar directamente. Esto solo se puede hacer con el artefacto integrado Antigravity.

Antigravity ejecuta las tareas y marca cada una a medida que las completa. Cuando termine, se mostrará la guía completa.

Prueba los cambios en el código

Una vez que se complete la implementación, verifica que se hayan realizado los cambios clave. Es posible que los nombres y el contenido exactos de los archivos varíen, pero estos patrones deberían estar presentes como en tools.yaml y agent.py:

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

Verás un resultado similar al siguiente:

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

Y para agent.py

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

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

Tal vez encuentres cambios como este

...
- **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: Si grep no devuelve coincidencias para ninguno de los archivos, es posible que la implementación haya usado nombres diferentes. Consulta git diff para ver el conjunto completo de cambios y verificar que se haya agregado la lógica relacionada con las reservas.

Los cambios deberían afectar la secuencia de comandos de la base de datos inicial. Intentemos ejecutarla.

source .env
uv run python scripts/seed_db.py

La secuencia de comandos actualizada debe crear la tabla reservations si aún no existe. Deberías ver un resultado que confirme que se creó la tabla nueva (se conservan los datos existentes de menu_items).

Nota: Es posible que Antigravity haya creado una secuencia de comandos de migración independiente (p.ej., scripts/create_reservations.py) en lugar de actualizar seed_db.py. Verifica si hay secuencias de comandos nuevas en git diff --name-only para scripts/ y ejecuta esas en su lugar.

Si todo sale bien hasta este punto, podemos probar la función en la IU para desarrolladores del agente del ADK. Reinicia la Caja de herramientas para recoger las nuevas definiciones de herramientas en tools.yaml. Detén cualquier proceso de Toolbox existente y, luego, inicia uno nuevo:

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

Inicia la IU de desarrollo del ADK:

uv run adk web .

Abre http://localhost:8000 en tu navegador y prueba con estas instrucciones:

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

Inspeccionar: El agente debe confirmar los detalles de la reserva y crearla.

Do I have any upcoming reservations?

Inspeccionar: El agente debe enumerar la reserva que acabas de hacer.

Ahora, detén la IU de desarrollo del ADK con Ctrl+C dos veces.

Punto de control: El agente controla la reserva y la búsqueda de reservas. Completaste un ciclo completo de SDD: especificar → aclarar → planificar → tareas → analizar → implementar → probar. Cada fase produjo un artefacto versionado en specs/<branch-name>/.

8. Desafíos (opcional)

Ahora conoces el flujo de trabajo completo del SDD. Ponlo a prueba:

• Ejecuta un segundo ciclo de SDD para crear una interfaz de chat web para el asistente del restaurante, esta vez sin orientación paso a paso.
• Implementa tu agente en Cloud Run para la situación de producción

Sugerencias

• El proyecto no tiene un framework de frontend. Antigravity debería proponer HTML/CSS/JS sin formato. Si sugiere React o algo similar, indícale que sea más simple (el principio de "mantener la simplicidad" de tu constitución debería detectar esto).
• El servidor del ADK expone /run_sse para la transmisión y /apps/{app_name}/users/{user_id}/sessions para la administración de sesiones. Antigravity las descubre a partir del contexto del proyecto.
• Después de la implementación, inicia el servidor con uv run uvicorn server:app --host 0.0.0.0 --port 8080 (no con adk web) para que funcione la activación del archivo estático.
• Prueba en http://localhost:8080/static/index.html.
• Los codelabs de referencia ya muestran cómo implementar y conservar el agente de ADK. ¡Haz referencia a Antigravity!

9. ¡Felicitaciones!

Extendiste un agente del ADK de asistente de restaurante con reserva de mesa, todo a través de los flujos de trabajo de SDD de Antigravity, sin escribir código de aplicación de forma manual.

Qué compilaste

• Un agente de ADK de conserje de restaurantes con búsqueda de menús, búsqueda semántica, seguimiento de preferencias dietéticas y reserva de mesas
• Una habilidad de Antigravity para la investigación de repositorios que genera y mantiene un documento de contexto del proyecto
• Una constitución del proyecto que aplica principios no negociables durante la planificación y el análisis
• Un ciclo completo de SDD que demuestra el flujo de trabajo de especificar → aclarar → planificar → tareas → analizar → implementar

Qué aprendiste

• Cómo usar flujos de trabajo de desarrollo basados en especificaciones en Antigravity para agregar funciones de forma sistemática a una base de código existente
• Cómo crear habilidades de Antigravity que empaqueten el conocimiento del dominio para reutilizarlo en las conversaciones
• Cómo iniciar el contexto del proyecto para que Antigravity tome decisiones fundamentadas sobre la arquitectura, los patrones y las opciones tecnológicas
• Cómo establecer una constitución del proyecto con la que se validan los flujos de trabajo del SDD
• Cómo extender un agente del ADK con nuevas herramientas respaldadas por bases de datos a través de MCP Toolbox

Limpia

Detén los procesos locales en ejecución (Toolbox):

pkill -f toolbox 2>/dev/null

Borra la instancia de Cloud SQL para evitar cargos continuos:

gcloud sql instances delete restaurant-db --quiet

De manera opcional, borra todo el proyecto:

gcloud projects delete $GOOGLE_CLOUD_PROJECT

Importante: Puedes deshacer esta operación de eliminación durante un período limitado con este comando gcloud projects undelete ${GOOGLE_CLOUD_PROJECT}