SDK do Antigravity: o que é, instalação e seu primeiro agente

O que é o SDK do Antigravity?

Um SDK permite que a aplicação chame um recurso de produto de forma mantida. O SDK do Antigravity permite definir um agente, conectar ferramentas aprovadas e consumir o resultado em Python. Serve para assistentes internos, testes e fluxos repetíveis.

A diferença principal é quem controla o fluxo: o IDE serve para trabalho interativo, a CLI para comandos e o SDK para a aplicação orquestrar o processo. Eles se complementam, mas não compartilham uma versão ou configuração universal.

Como instalar o SDK do Antigravity para Python

Comece pela página oficial de início do SDK e pelos metadados atuais no PyPI. Confira Python, extras, autenticação e imports em vez de copiar um exemplo antigo. Use ambiente e projeto descartáveis, mantenha segredos fora do Git e comece com uma solicitação reversível.

python -m venv .venv
.venv\Scripts\activate  # Windows
source .venv/bin/activate   # macOS or Linux
python -m pip install --upgrade pip
python -m pip install google-antigravity

1. Crie um ambiente isoladoUse um ambiente virtual local para manter resolução e rollback previsíveis.
2. Instale da fonte mantidaSiga as instruções oficiais, incluindo extras e autenticação atuais.
3. Fixe depois de testarExecute o exemplo mínimo e registre a versão e o runtime aprovados.
4. Não faça commit da configuraçãoUse variáveis de ambiente ou um gerenciador de segredos.
5. Leia as notas antes de atualizarA API do SDK pode mudar independentemente do desktop, CLI ou IDE.

Confirme os requisitos do Python e as instruções atuais antes da produção.

Crie um primeiro agente pequeno

Um bom primeiro agente tem uma tarefa, uma instrução e um resultado revisável. Resuma uma nota curta ou classifique um fixture local. Não reúna navegador, shell, banco e escrita no início: será mais difícil isolar falhas.

Classes e propriedades dependem da versão atual do SDK. O exemplo mostra o fluxo básico: configurar, solicitar, inspecionar e seguir o ciclo documentado. Use-o como estrutura, não como garantia permanente da API.

from google.antigravity import Agent, AgentConfig

config = AgentConfig(
    instructions="Summarize the supplied release note in three bullets."
)
agent = Agent(config=config)
result = agent.run("Release note: the test suite now reports flaky browser checks.")
print(result)

• Entrada — Use um fixture curto com uma resposta esperada.
• Resultado — Inspecione o resultado antes de adicionar automação.
• Ciclo de vida — Siga o ciclo de vida e as tentativas documentados.
• Repetibilidade — Guarde prompt, versão, configurações e resultado observado.

Adicione ferramentas uma por vez

As ferramentas ligam o raciocínio do agente a uma ação externa. Escolha a menor ação útil, defina um contrato de entrada estreito, valide argumentos e devolva um resultado limitado. Registre identificadores seguros; não exponha a pasta pessoal nem dê escrita quando leitura bastar.

Use subagentes para tarefas separadas

Um subagente ajuda quando uma tarefa tem um papel realmente separado, como planejamento, busca, validação ou formatação. Defina limites claros de entrada e saída para cada papel; o planejador não deve herdar as credenciais do validador.

Comece em sequência para inspecionar cada passagem. Adicione paralelismo, timeouts e tentativas quando os limites estiverem estáveis, mantendo falhas parciais visíveis.

Retorne uma saída estruturada verificável

Texto livre é conveniente para uma pessoa, mas frágil para a lógica. Quando o resultado alimenta banco, interface, teste ou agente, use a saída estruturada atual do SDK com um schema pequeno e valide-o localmente.

Um schema não torna a resposta verdadeira: verifique tipos, valores permitidos e campos obrigatórios. Separe diagnósticos da saída do usuário.

result = agent.run("Classify the fixture.")
validated = {
    "label": result.label,
    "confidence": float(result.confidence),
    "needs_review": bool(result.needs_review),
}
assert validated["label"] in {"pass", "review", "fail"}

• Valide o objeto retornado na aplicação.
• Use enums e strings limitadas para escolhas finitas.
• Trate campos ausentes ou inválidos como falha visível.
• Separe diagnóstico da saída para o usuário.

SDK, IDE ou CLI: escolha a superfície certa

O SDK incorpora um fluxo de agente no código, o IDE serve para projetos interativos e a CLI para comandos e scripts. Escolha a superfície dona da tarefa, não três botões para o mesmo fluxo.

As versões podem avançar em datas diferentes. Registre a fonte e a data do componente usado.

Verificações de segurança e confiabilidade

Um SDK pode tornar um agente parte de uma aplicação real. Revise origem do pacote, credenciais, destinos de rede, caminhos, argumentos e logs. Comece com projeto descartável e conta de teste ao acessar dados externos.

Mantenha aprovação para alterar arquivos, enviar mensagens, gastar dinheiro, mudar contas ou publicar. Use timeouts e tentativas limitadas e diferencie entrada inválida, serviço indisponível, permissão negada e revisão humana.

• Credenciais — Use um gerenciador de segredos; nunca grave tokens no Git ou em prompts.
• Caminhos — Permita somente diretórios do projeto, nunca a raiz do disco.
• Ações — Separe leitura de escrita, shell, navegador e rede.
• Observabilidade — Registre IDs, duração, resultado e categorias seguras de erro.
• Recuperação — Documente desativação, revogação, repetição e rollback.

Problemas comuns no SDK do Antigravity

Quando a primeira execução falhar, reduza o sistema a uma variável por vez.

O pacote instala, mas o import falha

Confirme ambiente e interpretador e compare o import com o quickstart atual. Verifique os metadados antes de mudar o código.

O agente retorna erro de autorização

Compare credencial, escopo e permissões com a documentação atual. Remova segredos dos logs e repita a solicitação mínima.

Uma ferramenta trava ou se repete

Adicione timeout, registre o limite e teste com entrada fixa. Não repita automaticamente uma escrita desconhecida.

A saída estruturada está incompleta

Reduza o schema e valide localmente os campos obrigatórios. Trate recusa, truncamento e dados inválidos como revisão.

Referência de versão e fonte de verdade

Em 12 de setembro de 2026, o PyPI mostrava google-antigravity v0.1.16. Listagens oficiais mostravam desktop v2.13.0, CLI v1.2.0 e IDE v2.5.5; evoluem separadamente.

Use páginas oficiais atuais e registre a versão instalada. A página de download é o fallback para desktop e CLI.