Desenvolvimento de agentes do ADK orientado por especificações com Antigravity e Spec-kit

1. Introdução

Adicionar recursos a um agente atual (uma nova capacidade com suporte de banco de dados) geralmente significa escrever boilerplate, conectar integrações e manter tudo consistente com os padrões já presentes na base de código. O Antigravity acelera todas as etapas desse processo: ele analisa sua base de código para criar o contexto necessário, produz especificações estruturadas e planos de implementação para sua revisão e executa as mudanças de código. Tudo isso é orientado pelo conhecimento do domínio, que ajuda você a capturar como habilidades reutilizáveis e uma constituição de projeto que impõe princípios não negociáveis. Este codelab apresenta uma maneira de potencializar o paradigma de desenvolvimento orientado por especificações do Antigravity ao introduzir um novo ciclo para impulsionar a documentação de especificações, fazendo referência pesada ao spec-kit.

O que você vai criar

Um aplicativo de concierge de restaurante em execução local com reserva adicionada por um ciclo completo de SDD:

• Agendamento de reservas: os hóspedes reservam mesas e verificam reservas, com o apoio de novas ferramentas de banco de dados da caixa de ferramentas do MCP e uma tabela reservations do Cloud SQL.
• (Desafio): desenvolva sua própria interface para o agente
• (Desafio): implante no Google Cloud com a ajuda do agente Antigravity

O código inicial fornece um agente do ADK funcional com pesquisa de menu (palavra-chave + semântica via MCP Toolbox) e rastreamento de preferências alimentares (via ToolContext). Você o estende sem escrever código de aplicativo manualmente. O Antigravity processa a implementação com base nas suas especificações.

O que você vai aprender

• Como fazer o bootstrap do contexto do projeto para que o Antigravity entenda uma base de código existente
• Como criar habilidades de antigravidade que empacotam conhecimento de domínio (por exemplo, Padrões de codelab do ADK) para reutilização
• Como definir uma constituição de projeto que os fluxos de trabalho do SDD validam durante o planejamento e a análise
• Como usar fluxos de trabalho de desenvolvimento orientado por especificações (SDD, na sigla em inglês) no Antigravity para adicionar recursos de forma sistemática
• Como estender um agente do ADK com novas ferramentas baseadas em banco de dados usando a MCP Toolbox

Pré-requisitos

• Google Antigravity e git instalados na sua máquina local
• Uma conta do Google Cloud com uma conta de faturamento de teste ativada
• É útil ter concluído os quatro codelabs de pré-requisito do ADK (ou ter conhecimento equivalente) para entender o contexto do caso de uso:
• Como criar agentes de IA com o ADK: os fundamentos
• Como criar agentes de IA com o ADK: capacitação com ferramentas
• Como criar agentes de IA persistentes com o ADK e o Cloud SQL
• Implantar, gerenciar e observar o agente do ADK no Cloud Run
• Banco de dados como ferramenta: RAG agêntico com ADK, MCP Toolbox e Cloud SQL

2. Configuração de seu ambiente

OBSERVAÇÕES IMPORTANTES:

Este tutorial requer um projeto do Google Cloud com uma conta de faturamento ativa. Se você ainda não tiver uma, siga as etapas abaixo para criar uma conta de faturamento de teste que pode ser usada neste tutorial:

1. Abrir janela anônima
2. Se você estiver participando de uma sessão de workshop, o URL do portal de resgate geralmente será fornecido na sessão. Caso contrário, acesse este portal de resgate da conta de faturamento de teste.
3. Faça login usando sua conta pessoal do Gmail ( o Google Workspace e outros e-mails não funcionam).
4. Siga as instruções de resgate detalhadas.

Esta etapa clona o repositório inicial, faz a autenticação com o Google Cloud, provisiona um banco de dados do Cloud SQL e prepara seu ambiente local do Antigravity.

Observações:este codelab é executado totalmente no Google Antigravity na sua máquina local. A configuração inclui autenticação manual usando o comando da CLI gcloud

Clonar o repositório inicial

Abra um terminal no Antigravity (ou no terminal do sistema). Clone o repositório complementar e entre no diretório:

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

Abra o repositório clonado no Antigravity. Arquivo->Abrir pasta->selecione o diretório clonado sdd-adk-agents-agy

Remova o remoto upstream. Os fluxos de trabalho do SDD criam ramificações do Git para especificações de recursos. A remoção do repositório remoto evita o envio acidental para o repositório inicial:

git remote remove origin

Importante:os fluxos de trabalho de SDD neste codelab usam ramificações git para organizar as especificações de recursos. Remover o origin remoto garante que suas ramificações e commits locais permaneçam locais. Se quiser fazer backup do seu trabalho, adicione seu próprio remoto: git remote add origin <your-repo-url>

Pré-requisitos de instalação

Execute o script de pré-requisitos. Ele verifica (e instala, se estiver faltando) git, curl, gcloud, uv, Python 3.12 e a caixa de ferramentas do MCP:

bash scripts/setup_prerequisites.sh

Observações:o download de todos os pré-requisitos leva um tempo. Abra uma nova guia para continuar na próxima seção enquanto aguarda a conclusão do download.

Autenticar com o Google Cloud

Execute dois comandos de autenticação. Os dois abrem um navegador para OAuth:

gcloud auth login
gcloud auth application-default login

Observações:no segundo comando do OAuth, quando solicitado a selecionar a permissão. Ver todas as opções

Observações:faça a autenticação com o e-mail usado para reivindicar a conta de faturamento de teste.

Como você está trabalhando localmente com o Antigravity, faça a autenticação manual. O auth login autentica a CLI gcloud. O application-default login autentica os SDKs do Google Cloud usados pelo seu aplicativo. As chamadas da Vertex AI do ADK e o conector Python do Cloud SQL dependem do Application Default Credentials.

Configurar seu projeto do Google Cloud

Grave as variáveis de local em .env antes de executar o script de configuração do projeto:

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

• GOOGLE_CLOUD_LOCATION=global é usado para chamadas da API Gemini / Vertex AI.
• REGION=us-central1 é usado para o Cloud SQL e outras infraestruturas do GCP

Faça o download e execute o script de configuração do projeto. Ele cria ou valida um projeto do Google Cloud com faturamento de teste e salva o ID do projeto em .env. Em seguida, ele o origina:

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

Ative as APIs necessárias:

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

Observações:a ativação das APIs pode levar um tempo. Você só precisa fazer isso uma vez por projeto.

Provisionar o Cloud SQL

Defina a senha do banco de dados e adicione-a a .env:

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

Importante:a senha codificada acima é apenas para fins de tutorial. Em um ambiente de produção, armazene as credenciais com segurança usando um serviço como o Secret Manager e faça referência a elas no ambiente de execução. Nunca faça commit de secrets em texto simples no controle de origem.

Crie a instância do 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 &

O nível db-custom-1-3840 é o mínimo necessário para a integração de ML da Vertex AI. A flag --enable-google-ml-integration permite que o Cloud SQL chame modelos de incorporação do Gemini diretamente do SQL, o que alimenta o recurso de pesquisa semântica.

Observações:esse comando leva aproximadamente 5 minutos e é executado em segundo plano. Deixe-o em execução nessa guia do terminal e abra uma nova guia para as próximas etapas.

Instalar dependências

Abra uma nova guia do terminal. Verifique se você ainda está no diretório do projeto do repositório clonado e recarregue as variáveis de ambiente:

source .env

Vamos usar o uv como gerenciador de projetos Python. O uv é um gerenciador de projetos e pacotes Python rápido escrito em Rust ( documentos). Este codelab usa o uv para oferecer velocidade e simplicidade. Instale as dependências do Python:

uv sync

Em seguida, atualize o arquivo .env do agente do ADK com a configuração do projeto:

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

Agora, temos todo o repositório de agentes do ADK inicial necessário para trabalhar. Agora vamos falar mais sobre Antigravity e desenvolvimento orientado por especificações na próxima seção enquanto esperamos que tudo fique pronto.

3. Conhecer o código inicial e entender o desenvolvimento orientado por especificações

Esta etapa explica a estrutura do código inicial, apresenta a metodologia de desenvolvimento orientado por especificações, inicializa o banco de dados e verifica se o agente básico funciona antes de você começar a estendê-lo.

Estrutura do projeto

Abra o projeto do repositório clonado no editor do Antigravity e revise o layout do diretório:

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

Arquivos de chave

Arquivos de aplicativos do agente

• restaurant_concierge/agent.py: o agente principal. Um LlmAgent que combina ferramentas de banco de dados da MCP Toolbox com o rastreamento de preferências alimentares com base em ToolContext. O agente carrega todas as ferramentas do servidor da caixa de ferramentas e adiciona duas funções Python (save_dietary_preference, get_dietary_preferences) que usam ToolContext para gerenciar o estado.
• tools.yaml: definições de ferramentas da caixa de ferramentas do MCP. Três ferramentas de pesquisa no menu são definidas: pesquisa de palavra-chave (search_menu), pesquisa semântica via pgvector (semantic_search_menu) e filtro de categoria (get_menu_by_category). Ainda não há ferramentas de reserva. Elas serão adicionadas mais tarde.
• server.py: um servidor FastAPI mínimo que mostra como acessar o ADK como um objeto FastAPI. O get_fast_api_app() do ADK fornece endpoints integrados, incluindo /run_sse para APIs de gerenciamento de sessão e streaming de SSE.

Arquivos do Antigravity

• .agents/skills/adk-agent-development/SKILL.md: uma habilidade pré-configurada ( gerada pelo Antigravity) que contém padrões de referência condensados de todos os quatro codelabs do ADK. No momento, ele está inativo (sem frontmatter YAML). Você precisará atualizar isso mais tarde. O Antigravity carrega essa habilidade automaticamente quando detecta trabalho relacionado a recursos do agente do ADK e exemplos. Esse é o conhecimento que orienta o Antigravity ao planejar o recurso de reserva mais tarde.
• .agents/skills/repo-research/SKILL.md: uma skill que ensina o Antigravity a analisar um repositório de forma incremental e produzir um documento de contexto de projeto estruturado. Ele usa uma abordagem de quatro fases: verificação da superfície (apenas árvore de diretórios), arquivos de configuração e metadados, pontos de entrada e modelos de dados e, em seguida, análises detalhadas direcionadas. Cada fase para e grava as descobertas antes de prosseguir para a próxima. Assim como a habilidade do ADK, ela fica inativa até que você adicione o frontmatter YAML mais tarde. Depois de ativado, invoque-o para gerar .agents/rules/project-context.md, um documento de integração abrangente que inclui arquitetura, dependências de tempo de execução, plataforma da API e glossário de domínio.

Desenvolvimento orientado por especificações: do planejamento integrado do Antigravity ao SDD estruturado

Com os assistentes de programação de IA, é fácil gerar código com base em um comando. O risco: você descreve um recurso em uma frase, o assistente escreve centenas de linhas, e você aceita porque parece certo. Isso às vezes é chamado de "programação de vibe": você direciona por feeling, aceitando ou rejeitando a saída com base em se ela parece funcionar. É rápido para protótipos e scripts descartáveis. Ele falha quando a base de código cresce, quando os recursos interagem ou quando você revisita o código semanas depois e não consegue reconstruir o motivo de uma decisão.

O desenvolvimento orientado por especificações (SDD, na sigla em inglês) adiciona estrutura a esse loop. Antes de gerar qualquer código, você escreve uma especificação: o que o recurso faz, para quem ele serve e quais são os critérios de sucesso. O assistente de IA trabalha com base nessa especificação, assim como você ao revisar a saída. A especificação se torna a única fonte de verdade para a intenção. Se o código divergir da especificação, você vai perceber isso na revisão. Se os requisitos mudarem, atualize a especificação primeiro e depois gere novamente. As decisões são documentadas, não improvisadas.

A troca é real: o SDD é mais lento por recurso do que a codificação de vibração. Você escreve documentos antes de escrever código. Mas o retorno é composto: toda mudança futura no código-fonte tem contexto, toda implementação gerada por IA tem um contrato revisável, e você pode integrar colaboradores (humanos ou de IA) mostrando as especificações em vez de explicar decisões de memória.

O Antigravity já segue os princípios de desenvolvimento orientado por especificações. Quando você define o agente como Modo de planejamento, ele produz dois artefatos antes de gravar qualquer código:

• Plano de implementação: uma visão geral da abordagem técnica proposta, das mudanças nos arquivos e das decisões de arquitetura
• Lista de tarefas: uma divisão estruturada de itens de trabalho

O Antigravity pede que você revise e aprove esses artefatos antes da execução. Esse loop de planejamento e implementação é o núcleo do desenvolvimento orientado por especificações: as especificações orientam o código, e não o contrário.

Este codelab vai além dessa base com um fluxo de trabalho opinativo e controlado por versão baseado no spec-kit, um framework de desenvolvimento orientado por especificações do GitHub. Cada recurso passa por um pipeline deliberado em que cada artefato é um documento independente que pode ser revisado, editado e rastreado no git. O pipeline inclui duas fases opcionais de controle de qualidade (esclarecer e analisar) que detectam problemas antes que eles se tornem problemas de implementação:

Fase	Artefato	Purpose
/speckit.specify	spec.md	Definir O QUE construir (voltado para o usuário, independente de tecnologia)
/speckit.clarify (opcional)	Atualização: spec.md	Identificar áreas não especificadas, fazer perguntas de esclarecimento direcionadas e codificar respostas de volta à especificação
/speckit.plan	plan.md, data-model.md, research.md	Projetar COMO construir (abordagem técnica, modelos de dados, pesquisa)
/speckit.tasks	tasks.md	Divida o plano em etapas ordenadas e práticas
/speckit.analyze (opcional)	Relatório de análise	Analise as tarefas para identificar riscos, lacunas ou casos extremos ausentes antes da implementação.
/speckit.implement	Mudanças no código	Execute as tarefas, marcando cada uma delas

Cada artefato é mantido como um arquivo em specs/<feature-branch>/, controlado por versão no git e reutilizável. Se uma conversa for interrompida ou se você quiser revisar as decisões mais tarde, os documentos de especificação estarão sempre disponíveis, não em um histórico de chat.

Observações:o artefato integrado antigravidade tem superioridade na interface, o que permite que o usuário comente sobre o artefato gerado, até mesmo uma imagem. ). Portanto, neste tutorial, modificamos o comando spec-kit original para integrar com o artefato integrado nas fases implement.

O repositório inicial inclui esses fluxos de trabalho do SDD em .agents/workflows/ e modelos em .specify/templates/. Você vai usá-los mais tarde para adicionar recursos ao agente.

4. Concluir a configuração do Cloud SQL e garantir que o agente de base esteja funcionando

Volte para a guia do terminal em que o comando de criação do Cloud SQL está sendo executado. Quando ele for concluído, verifique se a instância está pronta:

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

Se a saída mostrar RUNNABLE, continue. Se ele mostrar PENDING_CREATE, aguarde um momento e execute o comando novamente.

Conceda à conta de serviço do Cloud SQL acesso à Vertex AI (necessário para a função de incorporação no banco de dados):

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

Crie o banco de dados:

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

A saída será semelhante a esta:

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

Ponto de controle:seu arquivo .env contém GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION, REGION e DB_PASSWORD. A instância restaurant-db do Cloud SQL está em execução. O toolbox está disponível no seu PATH (instalado pelo setup_prerequisites.sh). As dependências do Python estão instaladas.

Propagar o banco de dados

Carregue as variáveis de ambiente e execute o script de seed do banco de dados para criar o esquema e inserir 16 itens de menu:

source .env
uv run python scripts/seed_db.py

Saída esperada:

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

Gerar embeddings de vetor para pesquisa semântica:

uv run python scripts/generate_embeddings.py

Saída esperada:

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

Isso usa a função embedding() integrada do Cloud SQL (pela extensão google_ml_integration) para chamar gemini-embedding-001 diretamente do SQL. Os vetores de 3.072 dimensões são armazenados na coluna embedding de menu_items. Não é necessário código de incorporação do lado do aplicativo.

Testar o agente de base

Inicie a MCP Toolbox como um processo em 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 &

A caixa de ferramentas veicula ferramentas de banco de dados por HTTP. O agente se conecta a ele em http://127.0.0.1:5000.

Inicie a interface de desenvolvimento do ADK:

uv run adk web .

Abra a interface de desenvolvimento no navegador. Em seguida, teste o agente com estes comandos:

What appetizers do you have?

Inspecionar:o agente consulta o banco de dados e retorna itens de menu.

I'm vegetarian

Inspecionar:o agente salva a preferência alimentar no estado do agente.

Can I make a reservation for tomorrow?

Inspecionar:o agente não consegue lidar com isso (ainda não existem ferramentas de reserva)

Interrompa a interface do desenvolvedor do ADK com Ctrl+C duas vezes. Deixe a caixa de ferramentas em execução em segundo plano. Você vai usá-la novamente mais tarde.

Ponto de verificação:o agente de base funciona. A pesquisa de menu (palavra-chave + semântica) e a função de preferências alimentares estão corretas. As solicitações de reserva falham porque não há ferramentas de reserva. Você entende a estrutura do projeto e a lacuna que vai preencher.

5. Inicializar o contexto do projeto com o Antigravity

Agora, vamos simular as coisas com uma condição "um pouco mais próxima" do nosso trabalho diário:

• Repositório mal gerenciado
• README obsoleta
• Documentações não atualizadas com frequência

Observação:considere-se muito sortudo se isso não refletir sua condição.

A primeira coisa que queremos fazer nesse tipo de situação é criar um mapa ou contexto sobre o projeto em que queremos que o Antigravity trabalhe. Esta etapa mostra um exemplo de abordagem para dar ao Antigravity um entendimento profundo de uma base de código existente. Para isso, crie uma habilidade que analise o repositório e gere um documento de contexto do projeto.

Ele também configura a constituição do projeto, ou seja, os princípios não negociáveis que os fluxos de trabalho do SDD validam. Juntos, eles fornecem ao Antigravity o contexto e as restrições necessárias para os ciclos de SDD mais tarde.

A hierarquia de contexto do Antigravity

O Antigravity usa três níveis de contexto, cada um com um escopo diferente:

• Regras (.agents/rules/): instruções sempre ativas. Todas as conversas nesse espaço de trabalho mostram o contexto ( se você o ativou). Use regras para contexto em todo o projeto, como decisões de arquitetura, padrões de programação ou informações sobre o pacote de tecnologia.
• Habilidades (.agents/skills/): conhecimento sob demanda. O Antigravity carrega uma habilidade somente quando a tarefa atual corresponde ao campo description da habilidade. Use habilidades para material de referência específico do domínio.
• Fluxos de trabalho (.agents/workflows/): comandos salvos acionados com comandos /. Use fluxos de trabalho para processos repetíveis de várias etapas, como o pipeline SDD.

Observação:o projeto tem fluxos de trabalho (pipeline SDD) e uma habilidade (desenvolvimento de agente do ADK), mas não tem regras. Uma regra project-context.md oferece ao Antigravity um entendimento persistente da base de código: quais tecnologias estão em uso, como os arquivos são organizados e o que foi criado até agora.

Ativar as habilidades

O repositório inicial inclui duas habilidades pré-gravadas em .agents/skills/. Eles contêm instruções detalhadas, mas começam com comentários TODO(codelab) em vez do frontmatter YAML obrigatório. Sem frontmatter, o Antigravity não consegue descobrir esses arquivos.

As habilidades de antigravidade exigem um bloco de frontmatter YAML na parte de cima do arquivo com dois campos:

• name: um identificador exclusivo da skill.
• description: um resumo em linguagem natural que o Antigravity usa para decidir qual habilidade carregar para uma determinada solicitação.

Abrir

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

no editor. Substitua as duas linhas de comentário TODO(codelab) na parte de cima por 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.
---

Observações: a habilidade de desenvolvimento de agentes do ADK contém padrões condensados e exemplos de cinco codelabs do ADK: estrutura do agente, tipos de ferramentas, gerenciamento de estado e implantação.

Abrir

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

no editor. Substitua as duas linhas de comentário TODO(codelab) na parte de cima por 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.
---

Observações:leia o arquivo repo-research SKILL.md em detalhes. Este é um exemplo de comando para analisar seu repositório. Observe que as regras de atualização incremental são intencionalmente conservadoras. Se o contexto do Antigravity acabar no meio da pesquisa ou se a conversa for interrompida, tudo o que foi descoberto até o momento já estará salvo no arquivo. Ao invocar novamente a skill, ela retoma de onde parou sem perder o progresso.

Atenção! Analisar um repositório grande pode esgotar sua cota rapidamente.

Verifique se as duas habilidades têm frontmatter válido:

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

Cada um deles precisa mostrar delimitadores --- envolvendo os campos name: e description:. Se os delimitadores ou campos estiverem faltando, o Antigravity não vai reconhecer a habilidade.

As duas habilidades são carregadas sob demanda. O Antigravity compara sua solicitação com o campo description e extrai as instruções completas apenas quando relevante.

Gerar o contexto do projeto

Verifique se o diretório de regras existe:

mkdir -p .agents/rules

Na caixa de chat/gerenciador de agentes do Antigravity (no modo de edição, pressione ctrl + L), inicie uma nova conversa. Tipo:

Research this repository and create a project context document

O Antigravity corresponde sua solicitação à habilidade repo-research e começa a analisar sistematicamente a base de código. Ele lê arquivos de configuração, código-fonte e documentação e preenche o modelo de contexto do projeto com as descobertas.

Depois de concluir, abra .agents/rules/project-context.md no editor. Ele contém informações concretas sobre o projeto: stack de tecnologia (Python 3.12, ADK, caixa de ferramentas do MCP, Cloud SQL), estrutura do projeto, modelo de dados (tabela menu_items com pgvector) e integrações externas.

Dica:o documento de contexto do projeto cresce à medida que o projeto evolui. Você pode executar a skill novamente para atualizar o contexto com as novas adições. As regras de atualização incremental garantem que o conteúdo atual seja preservado. Novas tecnologias, entidades e integrações são anexadas, não substituídas.

Para atualizações direcionadas, use comandos específicos: "Pesquise o esquema do banco de dados e atualize o contexto do projeto" ou "Atualize o contexto do projeto com as novas definições de ferramentas". Cada invocação é adicionada ao documento atual.

Definir a constituição do projeto

Os fluxos de trabalho do SDD fazem referência a uma constituição de projeto em .specify/memory/constitution.md durante o planejamento e a análise. O fluxo de trabalho /speckit.plan executa uma "verificação de constituição" e /speckit.analyze sinaliza violações como CRÍTICAS. Se a constituição for deixada como um modelo em branco com tokens de marcador de posição, essas verificações não terão nada para validar. Os planos e as análises serão executados sem restrições.

A constituição define princípios não negociáveis do projeto. Este é um pequeno repositório mantido por um único desenvolvedor. Portanto, a constituição precisa refletir esse escopo. Mantenha as coisas simples e consistentes e evite o excesso de engenharia.

No Gerenciador de agentes do Antigravity, inicie uma conversa. Execute o fluxo de trabalho de constituição:

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

O Antigravity preenche o modelo de constituição com princípios concretos, atribui uma versão (1.0.0) e executa uma verificação de consistência nos modelos de SDD.

Revise a constituição gerada em .specify/memory/constitution.md. Verifique se os três princípios estão presentes e claramente declarados.

Observação:a constituição é mantida propositalmente em três princípios para um desenvolvedor independente. O fluxo de trabalho /speckit.constitution aceita alterações incrementais. Execute-o novamente com mais princípios, e ele vai processar o controle de versões automaticamente. Em um projeto em equipe, você adicionaria princípios para revisão de código, disciplina de teste, capacidade de observação e controle de versões da API.

Ponto de verificação : .agents/rules/project-context.md existe com informações concretas sobre o repositório. .agents/skills/repo-research/SKILL.md demonstra a criação de habilidades com frontmatter YAML, instruções e resolução de conflitos. .specify/memory/constitution.md contém três princípios de projeto que os fluxos de trabalho de planejamento e análise validam. Você entende a hierarquia de contexto de três níveis: regras (sempre ativas), habilidades (sob demanda) e fluxos de trabalho (comandos de barra).

6. Ciclo de SDD: recurso "Adicionar reserva"

Esta etapa mostra um ciclo completo de SDD para adicionar a reserva de mesa ao agente concierge do restaurante. Você conduz o Antigravity por cada fase (especificar, esclarecer, planejar, tarefas, analisar, implementar), observando como cada artefato se baseia no anterior. Essa é a principal experiência de aprendizado do codelab.

Importante: O Antigravity é um assistente de IA. Os artefatos gerados (especificações, planos, tarefas, código) podem ser diferentes do que este tutorial descreve. Os nomes dos arquivos, os esquemas SQL exatos e a estrutura do código podem variar. Isso é esperado e faz parte do trabalho com desenvolvimento assistido por IA. O fluxo de trabalho do SDD garante que você revise todos os artefatos antes que eles se tornem código. Portanto, use seu julgamento para aceitar, modificar ou regenerar qualquer saída que não corresponda às suas expectativas.

Especificar o recurso

No Gerenciador de agentes do Antigravity, inicie uma conversa. Digite o comando de fluxo de trabalho /speckit.specify com uma descrição do recurso:

/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").

O Antigravity cria uma ramificação de recurso, gera um documento de especificação e executa a validação de qualidade. Se o Antigravity fizer perguntas de esclarecimento, responda com base na descrição do recurso acima.

Observação:depois de concluir a especificação, a Antigravity pode apresentar transferências de controle, como "Criar plano técnico" ou "Esclarecer requisitos de especificação". Esses são indicadores da próxima fase do fluxo de trabalho (/speckit.plan ou /speckit.clarify).

A especificação se concentra no O QUÊ e no POR QUÊ, não no COMO. Ele descreve a experiência do usuário ("Os convidados podem fazer uma reserva informando nome, número de pessoas, data e horário") sem mencionar tabelas SQL, tools.yaml ou APIs ADK. Os detalhes da implementação vêm na fase de planejamento.

Revise a especificação gerada em specs/<branch-name>/spec.md. Verifique se ele captura os requisitos funcionais e os critérios de sucesso.

Esclareça a especificação (opcional)

Execute o fluxo de trabalho de esclarecimento para identificar e resolver áreas pouco especificadas na especificação:

/speckit.clarify

O Antigravity verifica a especificação em busca de ambiguidades, critérios de aceitação ausentes e requisitos subespecificados. Ele faz perguntas de esclarecimento direcionadas, cada uma respondida com uma pequena seleção ou frase. Suas respostas são codificadas diretamente na especificação, tornando-a mais precisa antes do início do planejamento.

Dica:a etapa de esclarecimento é opcional, mas recomendada para recursos complexos. Para especificações simples, pule direto para o planejamento.

Planejar a implementação

Execute o fluxo de trabalho de planejamento:

/speckit.plan

O Antigravity gera um plano técnico em duas fases:

1. Fase de pesquisa: resolve dúvidas sobre a base de código atual e gera research.md
2. Fase de projeto: cria data-model.md (definição da entidade de reservas) e atualiza project-context.md

O Antigravity precisa usar a habilidade adk-agent-development durante o planejamento. Revise os principais artefatos:

• specs/<branch-name>/plan.md: a abordagem técnica (quais arquivos modificar, quais padrões seguir)
• specs/<branch-name>/data-model.md: a definição da entidade de reservas (colunas, tipos, relações)
• specs/<branch-name>/research.md: decisões tomadas e justificativa

Gerar tarefas

Executar o fluxo de trabalho de tarefas

/speckit.tasks

O Antigravity divide o plano em uma lista de tarefas ordenada no specs/<branch-name>/tasks.md. As tarefas seguem um formato de lista de verificação estrito com IDs, marcadores de prioridade e caminhos de arquivo. Por exemplo:

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

As tarefas são organizadas em fases: Configuração → Fundamentos → Histórias do usuário → Refinamento. Leia a lista de tarefas para entender o que será criado e modificado.

Analisar tarefas (opcional)

Execute o fluxo de trabalho de análise para revisar as tarefas em busca de riscos e lacunas:

/speckit.analyze

O Antigravity verifica a lista de tarefas em relação à especificação e ao plano, procurando casos extremos ausentes, tarefas que podem entrar em conflito ou lacunas entre os requisitos da especificação e o trabalho planejado. Resolva problemas críticos antes da implementação.

Dica:a etapa de análise é mais útil quando a lista de tarefas é longa ou o recurso afeta vários subsistemas. Para um recurso específico, como reserva de agendamento, uma verificação rápida é suficiente.

7. Implementação

Execute o fluxo de trabalho de implementação:

/speckit.implement

A Antigravity apresenta um plano de implementação final e um artefato de tarefa. Revise e aprove para continuar

Dica:você pode comentar diretamente! Isso só pode ser feito com o artefato integrado do Antigravity.

O Antigravity executa as tarefas, marcando cada uma delas como concluída. Quando terminar, ele vai apresentar o tutorial completo.

Testar as mudanças de código

Depois que a implementação for concluída, verifique se as principais mudanças foram feitas. Os nomes e o conteúdo exatos dos arquivos podem variar, mas esses padrões devem estar presentes, como em tools.yaml e agent.py:

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

Você vai observar este tipo de saída:

...
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 para agent.py

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

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

Talvez você encontre mudanças como esta

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

Observação:se grep não retornar correspondências para nenhum dos arquivos, a implementação pode ter usado nomes diferentes. Confira git diff para ver o conjunto completo de mudanças e verificar se a lógica relacionada à reserva foi adicionada.

As mudanças devem afetar o script do banco de dados de inicialização. Vamos tentar executá-lo.

source .env
uv run python scripts/seed_db.py

O script atualizado vai criar a tabela reservations se ela ainda não existir. Você vai ver uma saída confirmando que a nova tabela foi criada. Os dados menu_items atuais são preservados.

Observação:a Antigravity pode ter criado um script de migração separado (por exemplo, scripts/create_reservations.py) em vez de atualizar seed_db.py. Verifique git diff --name-only para encontrar novos scripts em scripts/ e execute-os.

Se tudo correr bem até aqui, podemos testar o recurso na interface de desenvolvimento do agente do ADK. Reinicie a caixa de ferramentas para selecionar as novas definições de ferramentas em tools.yaml. Interrompa qualquer processo da caixa de ferramentas e inicie um novo:

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

Inicie a interface de desenvolvimento do ADK:

uv run adk web .

Abra http://localhost:8000 no navegador e teste com estes comandos:

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

Inspecionar:o agente precisa confirmar os detalhes da reserva e criá-la.

Do I have any upcoming reservations?

Inspecionar:o agente precisa listar a reserva que você acabou de fazer.

Agora, pare a interface do desenvolvedor do ADK com Ctrl+C duas vezes.

Ponto de verificação:o agente lida com a reserva e a pesquisa de reservas. Você concluiu um ciclo completo de SDD: especificar → esclarecer → planejar → tarefas → analisar → implementar → testar. Cada fase produziu um artefato com versão em specs/<branch-name>/.

8. Desafios (opcional)

Agora você conhece todo o fluxo de trabalho de SDD. Teste:

• Execute um segundo ciclo de SDD para criar uma interface de chat na Web para o concierge do restaurante. Desta vez, sem orientação detalhada.
• Implantar o agente no Cloud Run para um cenário de produção

Dicas

• O projeto não tem um framework de front-end. O Antigravity precisa sugerir HTML/CSS/JS simples. Se ele sugerir React ou algo parecido, peça para simplificar. O princípio "mantenha a simplicidade" da sua constituição deve resolver isso.
• O servidor ADK expõe /run_sse para streaming e /apps/{app_name}/users/{user_id}/sessions para gerenciamento de sessões. O Antigravity descobre essas informações no contexto do projeto.
• Após a implementação, inicie o servidor com uv run uvicorn server:app --host 0.0.0.0 --port 8080 (não adk web) para que a montagem de arquivos estáticos funcione.
• Teste em http://localhost:8080/static/index.html.
• Os codelabs de referência já mostram como implantar e manter o agente do ADK. Dê referências de Antigravity a isso.

9. Parabéns!

Você estendeu um agente ADK de concierge de restaurante com reserva de reservas, tudo isso usando os fluxos de trabalho SDD da Antigravity, sem escrever código de aplicativo manualmente.

O que você criou

• Um agente do ADK de concierge de restaurante com pesquisa de cardápio, pesquisa semântica, rastreamento de preferências alimentares e reserva
• Uma habilidade da Antigravity para pesquisa de repositório que gera e mantém um documento de contexto do projeto.
• Uma constituição de projeto que impõe princípios não negociáveis durante o planejamento e a análise
• Um ciclo completo de SDD demonstrando o fluxo de trabalho especificar → esclarecer → planejar → tarefas → analisar → implementar

O que você aprendeu

• Como usar fluxos de trabalho de desenvolvimento orientado por especificações no Antigravity para adicionar recursos de maneira sistemática a uma base de código atual
• Como criar habilidades do Antigravity que empacotam o conhecimento do domínio para reutilização em conversas
• Como inicializar o contexto do projeto para que o Antigravity tome decisões informadas sobre arquitetura, padrões e escolhas de tecnologia
• Como definir uma constituição de projeto que os fluxos de trabalho do SDD validam
• Como estender um agente do ADK com novas ferramentas baseadas em banco de dados usando a MCP Toolbox

Limpar

Interrompa todos os processos locais em execução (Toolbox):

pkill -f toolbox 2>/dev/null

Exclua a instância do Cloud SQL para evitar cobranças contínuas:

gcloud sql instances delete restaurant-db --quiet

Se quiser, exclua todo o projeto:

gcloud projects delete $GOOGLE_CLOUD_PROJECT

Importante:é possível desfazer essa operação de exclusão por um período limitado usando este comando gcloud projects undelete ${GOOGLE_CLOUD_PROJECT}