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 mesa agregada a través de un ciclo completo de SDD:

• Reservas: Los huéspedes reservan mesas y verifican las reservas con 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 del ADK que funciona con la búsqueda de menús (semántica y por palabras clave a través de MCP Toolbox) y el seguimiento de preferencias dietéticas (a través de ToolContext). Puedes extenderlo sin escribir código de la 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 su reutilización
• Cómo establecer una constitución del proyecto con la que los flujos de trabajo de SDD realizan validaciones durante la planificación y el análisis
• Cómo usar 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 activa 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:
• Cómo crear agentes de IA con el ADK: conceptos básicos
• Cómo crear agentes de IA con el ADK: poténcialos con herramientas
• Cómo compilar agentes de IA persistentes con ADK y Cloud SQL
• Cómo implementar, administrar y observar el agente de 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, usa el banner que se encuentra en la parte superior de este codelab para obtener una cuenta de facturación de prueba que se pueda usar para este instructivo.

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

Requisitos previos a la instalación

Asegúrate de que tu sistema tenga el siguiente ejecutable de la CLI:

• git
• gcloud
• uv
• npm

Las instrucciones de instalación varían según el sistema operativo de tu computadora.

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

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

IMPORTANTE: El siguiente paso se proporciona para ayudarte a configurar rápidamente el proyecto de Google Cloud vinculado a una cuenta de facturación de prueba (estricta). Si prefieres usar tu proyecto anterior, puedes omitir el siguiente paso y, en su lugar, realizar el siguiente:

Agrega tu propio nombre de proyecto como la variable GOOGLE_CLOUD_PROJECT en el archivo .env.

Activa tu proyecto en la terminal con gcloud config set project your-project-id.

Luego, puedes ir directamente a la sección Habilitación de la API.

Si no tienes certeza al respecto, continúa con la siguiente sección

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 y, luego, lo establece 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

Habilitando API

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.

Instala dependencias

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

Prepara la infraestructura y los datos de la base de datos

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.

Luego, ejecuta la secuencia de comandos scripts/setup_database.sh para preparar toda la infraestructura necesaria. Realizará las siguientes acciones:

• Crear una instancia de Cloud SQL
• Cómo verificar si la instancia está lista
• Otorga permisos de Vertex AI
• Crear base de datos
• Base de datos de origen
• Ejecuta el servicio de MCP Toolbox en segundo plano

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

Este comando ejecutará la configuración en segundo plano. Puedes verificar el resultado periódicamente en el archivo database_setup.log.

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 a 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)
│   │   ├── mcp-toolbox-postgres/
│   │   │   └── SKILL.md     # MCP Toolbox config skill
│   │   └── repo-research/
│   │       └── SKILL.md     # Repo analysis skill
│   └── rules/               # Always-active context
├── .specify/                # spec-kit SDD templates and memory
│   ├── memory/constitution.md
│   ├── templates/
│   └── scripts/
├── restaurant_concierge/    # ADK agent package
│   ├── __init__.py
│   ├── agent.py             # LlmAgent + ToolContext tools + Toolbox integration
│   └── .env                 # Vertex AI configuration
├── server.py                # FastAPI server wrapping the agent
├── tools.yaml               # MCP Toolbox tool definitions
├── scripts/                 # Setup scripts
└── pyproject.toml

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 transmisión de SSE y administración de sesiones.

Antigravity Files

• .agents/skills/mcp-toolbox-postgres/SKILL.md: Es una habilidad que guía a Antigravity sobre cómo crear una configuración adecuada de tools.yaml para MCP Toolbox. Esta habilidad enseñará la configuración relacionada con sources, tools y embeddingModels que se requiere para compilar una canalización de RAG adecuada. Esta habilidad no se activará hasta que agregues el frontmatter de YAML adecuado para que Antigravity lo reconozca.
• .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. También está inactivo hasta que agregues el front matter de YAML más adelante. Una vez activado, invócalo 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 con 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 "codificación de ambiente": diriges el proceso según tu intuición, y aceptas o rechazas el resultado en función de 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: el SDD es más lento por función que la codificación vibe. Escribes documentos antes de escribir código. Sin embargo, los beneficios se acumulan: cada cambio futuro en la base de código 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 del desarrollo basado 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 basado en opiniones 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 control 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 están disponibles, no enterrados 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 original de spec-kit 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. 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 la conversación en 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 tecnológica.
• 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 2 habilidades (repo-research y mcp-toolbox-postgres), pero no tiene reglas. Más adelante, crearemos una regla project-context.md que le dará 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 ha compilado 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.

Abre .agents/skills/mcp-toolbox-postgres/SKILL.md en el editor. Reemplaza las líneas de comentarios TODO(codelab) en la parte superior con este frontmatter:

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

Notas: La habilidad de Postgres de la caja de herramientas de MCP contiene la configuración adecuada para sources, tools y embedding models.

Abre .agents/skills/repo-research/SKILL.md en el editor. Reemplaza las 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 front matter válido:

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

Instala habilidades disponibles públicamente

Hoja de referencia de ADK Skills

Anteriormente, inspeccionamos las habilidades que creamos por nuestra cuenta ( las habilidades repo-research y mcp-toolbox-postgres). Sin embargo, hay muchas otras habilidades que son útiles para respaldar nuestro desarrollo de software y que se pueden instalar fácilmente en nuestro agente de programación. Por ejemplo, en este instructivo, necesitamos interactuar con el ADK, por lo que necesitaremos conocimientos adecuados sobre cómo compilar con el ADK. Instalemos la habilidad de documentación del ADK con el siguiente comando:

npx skills add google/adk-docs

Luego, se te pedirá que confirmes la instalación, como se muestra a continuación.

Presiona y para continuar con el siguiente mensaje y seleccionar las habilidades que deseas instalar, como se muestra a continuación. Por ahora, solo usaremos adk-cheatsheet (presiona la barra espaciadora para seleccionar y, luego, Intro para confirmar).

Luego, haz clic en Intro para habilitar la instalación predeterminada y la instalación de la skill en tu proyecto actual.

Verás que se agregó una nueva habilidad del ADK al directorio .agents/skills, que es adk-cheatsheet.

Habilidades de cavernícola

Una de las habilidades útiles para reducir el uso de tokens es esta habilidad de cavernícola . Esta habilidad puede reducir el token de salida del agente,lo que lo convierte en una buena combinación cuando utilizas un desarrollo completo basado en especificaciones como este instructivo.

npx skills add JuliusBrussee/caveman

Al igual que antes, seleccionemos la habilidad caveman por ahora.

Luego, haz clic en Intro para habilitar la instalación predeterminada y la instalación de la skill en tu proyecto actual.

Ahora, ya deberíamos tener 4 habilidades configuradas y listas para comenzar nuestro recorrido por el SDD.

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

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

Antigravity relaciona tu solicitud con la habilidad de repo-research y caveman ( comando para comunicarse de manera eficiente) y comienza a analizar sistemáticamente la base de código. 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 tecnológica (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 habilidad 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 específicas, 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 de un 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 que se ajustan a un desarrollador independiente. El flujo de trabajo de /speckit.constitution admite modificaciones incrementales: ejecútalo de nuevo 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).

5. 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 las características:

/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 funciones, 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 las características 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 las tablas de SQL, tools.yaml ni las 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 de aclaración específicas, cada una de las cuales se puede responder con una selección o frase breve. Tus respuestas se codifican directamente en las especificaciones, lo que las hace más precisas 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 Update the restaurant concierge agent to multi agent architecture which separate responsibilities for handling menu and reservations. Use your ADK and MCP toolbox skill to implement it properly

Antigravity 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 debe 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, relaciones).
• specs/<branch-name>/research.md: Decisiones tomadas y fundamentos

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 usuarios → 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 compara la lista de tareas 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.

6. 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. Revisa y aprueba el cambio 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á el tutorial completo.

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 como este:

...
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 el script de la base de datos de inicialización. 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. Realicemos la migración de la base de datos para incorporar la tabla nueva y reiniciar 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:

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

Puedes verificar el registro de salida en database_setup.log para saber si Antigravity genera el código y la configuración correctos. Si encuentras un error, intenta interactuar con el agente para corregirlo.

Si todo sale bien, podemos iniciar 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>/.

7. Desafíos (opcional)

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

• Ejecuta un segundo ciclo de SDD para compilar 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 situaciones 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 lo simplifique (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 los 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. ¡Dale referencias de Antigravity a esto!

8. ¡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 la 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 de SDD completo que demuestra el flujo de trabajo de especificar → aclarar → planificar → tareas → analizar → implementar

Qué aprendiste

• Cómo usar flujos de trabajo de desarrollo basado 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}