Google Antigravity CLI

Resumo

O Google Antigravity CLI é uma ferramenta de linha de comando distribuída como agy. A documentação oficial informa suporte nativo a Windows, macOS e Linux e descreve o diretório de instalação por usuário do Windows como %LOCALAPPDATA%\agy\bin.

Uso atual

Confirmado (evidência local, 2026-08-21): o instalador do Antigravity CLI foi executado na máquina Windows de Yan e informou que adicionou seu diretório de binários ao PATH do usuário. A sessão de terminal que executou o instalador ainda não herdava essa alteração; uma nova sessão é necessária para que a atualização de ambiente seja aplicada ao processo do terminal.

Confirmado (evidência local, 2026-08-23): o agy está na versão 1.1.19 e passou a ser usado por meio de um adaptador local OpenAI-compatível. O adaptador permite que o Hermes use a assinatura Google AI Pro como rota de fallback, sem expor credenciais no arquivo de configuração do Hermes ou nesta nota.

O adaptador oferece compatibilidade para conversas, listagem de modelos, consulta de quota e verificação de saúde; também registra telemetria local de uso. A autenticação continua sendo tratada pelo mecanismo de sessão da própria CLI, e não por uma chave da API Gemini comum.

Registro operacional (evidência local, 2026-08-23): uma resposta do Hermes foi atribuída ao modelo gemini-3.6-flash-tiered pela rota da assinatura AI Pro (ai-pro). Isso confirma o uso da rota para conversa naquele turno; não é garantia de disponibilidade contínua, que deve continuar sendo verificada por saúde e quota antes de tarefas longas.

Estado operacional registrado (2026-08-23)

Confirmado por evidência local registrada: foi criado um lançador na pasta de Inicialização do usuário do Windows para iniciar o ai-proxy sem janela no logon. O teste registrado parou o proxy, acionou esse lançador e confirmou que o serviço respondeu ao health check e a chamadas de conversa. Isso corrige o estado anterior de ausência de inicialização automática; a disponibilidade ainda deve ser verificada após reinicializações e antes de tarefas longas.

Confirmado por evidência local registrada: a rota aceita a solicitação amigável gemini-3.7-flash, mas o identificador retornado/usado pelo catálogo do adaptador é gemini-3.7-flash-tiered. O mapeamento local de aliases faz essa tradução. Um teste registrado de chat/completions foi concluído com sucesso pelo adaptador; isso comprova o funcionamento naquele momento, não disponibilidade futura nem acesso direto a uma API Gemini convencional.

Histórico operacional (relato de 2026-08-23; requer verificação no runtime): o endpoint local GET /v1/models foi ajustado para também anunciar os nomes amigáveis definidos no mapeamento de modelos, inclusive gemini-3.7-flash, além do ID de backend gemini-3.7-flash-tiered. A listagem é montada por ensure_models() no ai_proxy.py, que inclui as chaves de MODEL_MAP; assim, aliases amigáveis podem aparecer na seleção interativa do Hermes depois de reiniciar o ai-proxy ou renovar o catálogo com hermes model --refresh. A aceitação do alias em uma chamada não comprova, por si só, que ele já esteja visível na listagem: confirmar pelo refresh e pelo endpoint do adaptador.

Decisão técnica registrada: o adaptador passou a encaminhar as definições de ferramentas do Hermes e a converter chamadas de função e suas respostas entre os formatos do Hermes e do backend. Em chamadas com ferramentas, o backend exige que a assinatura de pensamento associada à chamada seja reenviada no turno de resposta da ferramenta; omiti-la causava falha de requisição. A correção é relevante porque respostas vazias podem ocorrer quando um modelo pretende usar uma ferramenta que o adaptador não encaminhou.

Quota por grupo no adaptador (2026-08-23)

Confirmado por evidência local registrada: a fonte de quota usada pela rota ai-pro retorna uma visão agregada por grupo de modelos e uma visão por modelo. O adaptador expõe a primeira em GET /v1/quota; a segunda ainda não é disponibilizada por uma rota própria do adaptador.

Limitação observada: na resposta por modelo, modelos pertencentes ao mesmo grupo podem apresentar a mesma fração restante. Assim, essa visão identifica os modelos do grupo, mas não demonstra uma franquia independente para cada modelo. No estado observado, Claude e GPT-OSS estavam em um grupo compartilhado, separado do grupo Gemini. Esse comportamento é um registro operacional da conta e do backend naquele momento, não uma garantia contratual; confirmar no runtime antes de planejar uso intensivo.

Paridade entre PC e VM (2026-08-23)

Confirmado por evidência local registrada: a VM foundry passou a executar sua própria instância local do ai-proxy, gerenciada pelo PM2 e persistida para reinicializações. Isso preserva o endereço de loopback usado pela configuração compartilhada do Hermes sem tentar alcançar o proxy do PC pela rede.

Confirmação operacional registrada: na VM, o health check e a listagem de modelos do adaptador responderam, e uma execução do Hermes usando o provider ai-pro e o modelo gemini-3.7-flash-tiered concluiu com resposta. O proxy foi adaptado para resolver de forma multiplataforma o caminho dos artefatos de autenticação da CLI; esta nota não registra nem deve registrar esses artefatos.

Cuidado: a evidência demonstra o estado naquele momento. Depois de manutenção, troca de máquina ou reinicialização, confirmar o processo do PM2, o health check e a quota local antes de depender da rota em uma tarefa longa.

Contexto e recuperação do serviço (2026-08-23)

Confirmado por evidência local registrada: o Hermes resolveu a janela de contexto de gemini-3.7-flash-tiered como 1.048.576 tokens nas duas instâncias. Portanto, o indicador de uso de contexto exibido pelo Hermes já estava correto; não foi necessário alterar o metadata de GET /v1/models do adaptador. Uma alteração experimental nesse endpoint foi revertida.

Incidente e correção registrados: após uma tentativa desnecessária de reinício, o lançador Windows anterior, baseado em cmd //c, não conseguiu reabrir o proxy no ambiente MSYS. Ele foi substituído por um wrapper que inicia o processo sem janela, aguarda o endpoint de saúde e falha explicitamente se o serviço não se recuperar. As operações start, stop, restart e status foram testadas no momento do registro. A VM recebeu a mesma versão do adaptador e seu processo PM2 foi reiniciado.

Validação pontual registrada: após a correção, o adaptador respondeu ao health check e uma chamada real ao modelo Gemini foi concluída tanto no Windows quanto na VM. Isso é evidência operacional daquele momento, não garantia de disponibilidade futura.

Risco de compatibilidade e de conta (2026-08-24)

Confirmado por evidência local registrada: o adaptador funciona com a sessão OAuth obtida pelo agy, consome a quota associada a essa rota e preserva respostas de limite como indisponibilidade de quota; ele não é uma API Gemini pública nem executa o binário agy a cada chamada. O adaptador reproduz chamadas ao backend usado pela CLI, incluindo endpoints internos; no cenário registrado, houve também uma rota alternativa de backend quando a rota principal devolveu limitação. Esses detalhes descrevem uma implementação local, não uma interface publicada ou estável.

Cuidado operacional: a documentação pública de Google AI Pro descreve benefícios e limites por produto, inclusive Antigravity, mas não documenta uma API OpenAI-compatível para reutilizar a sessão da CLI. Por isso, tratar essa rota como integração não oficial: alterações no backend, na CLI, na autenticação ou na política de uso podem interrompê-la ou levar a limitação da conta. Os Termos do Google também proíbem, entre outros comportamentos, engenharia reversa de serviços salvo quando permitida por lei e certos usos automatizados que violem instruções legíveis por máquina. Os antigos termos adicionais de IA generativa foram substituídos em 2024, salvo contratos específicos que ainda os referenciem. Esta nota não conclui que o adaptador viola os Termos; a conformidade depende da implementação, das instruções aplicáveis e da interpretação do Google.

Decisão prática: manter uso moderado, fallback independente e validação de saúde/quota antes de trabalhos longos. Para um caminho com suporte contratual e estabilidade de integração, preferir a API/documentação oficial aplicável ao produto desejado. Não registrar nem reutilizar fora do ambiente os artefatos de autenticação da CLI.

Execução sem console e resiliência do proxy Windows (2026-10-05)

Relato operacional — não verificado nesta curadoria: o lançador do ai-proxy no Windows foi alterado para usar pythonw.exe, evitando a criação de uma janela de console. O watchdog programado para o proxy também foi ajustado para iniciar reinícios com janela oculta. A alteração complementa o objetivo já registrado de manter o serviço em segundo plano.

Relato operacional — não verificado nesta curadoria: o servidor HTTP local passou a tratar ConnectionResetError, ConnectionAbortedError e BrokenPipeError sem despejar traceback no console quando clientes locais encerram uma conexão abruptamente. Erros não enquadrados nessa classe continuam destinados ao log local, segundo o relato.

Validação pontual relatada: após reiniciar o serviço, foi informado que o processo sem janela escutava a porta local configurada e que GET /healthz respondeu com sucesso. Isso confirma apenas o estado observado naquele momento; conferir o processo, o endpoint de saúde e a quota antes de tarefas longas ou após reinicialização.

Limitações e cuidados

• O PATH gravado no registro do usuário não atualiza processos de terminal que já estavam em execução.
• Não registrar no vault credenciais de OAuth, tokens, arquivos de sessão ou dados de conta.
• O adaptador é local e destinado ao Hermes; endpoints, modelos disponíveis e limites da assinatura podem mudar sem aviso. Confirmar o estado pelo endpoint de saúde e pela quota antes de operações longas.
• Recursos, versões e opções da CLI devem ser confirmados na documentação oficial antes de serem adotados em automações.

Relações no vault

• Dev - Computação
• Hermes Agent

Fontes

• Installation & Auth — Google Antigravity Docs, documentação oficial, consultada em 2026-08-21.
• Getting Started with Antigravity CLI — Google Antigravity Docs, documentação oficial, consultada em 2026-08-21.
• Use Google AI Pro benefits — Google One Help, documentação oficial, consultada em 2026-08-24 (benefícios por produto, limites de uso e referência a Antigravity).
• Google Terms of Service, termos oficiais, consultados em 2026-08-24 (restrições sobre engenharia reversa e determinados acessos automatizados).
• Generative AI Additional Terms of Service, fonte histórica: a página informa que esses termos deixaram de se aplicar em 2024, salvo contratos específicos; verificado em 2026-10-05.
• Evidência local: lote de captura batch-4944b9b453e545bf8a5593f87a7948ee, consultado em 2026-08-21.
• Evidência local: lote de captura batch-f751d59556a44b1a80016b98c31620c5, consultado em 2026-08-23.
• Evidência local: lote de captura batch-0ae1bf9dec344965a556cc5c432cebe2, consultado em 2026-08-23.
• Evidência local: lote de captura batch-dc5788ba73f0490c81a1810df580bbd5, consultado em 2026-08-23.
• Evidência local: lote de captura batch-16b96f6d703549e99682b12ba9a58a3a, consultado em 2026-08-23.
• Evidência local: lote de captura batch-c78086c3fca242908b3a47fe977da8eb, consultado em 2026-08-23 (ajuste relatado para a listagem de aliases; marcado como pendente de verificação no runtime).
• Evidência local: lote de captura batch-b21127c838514acba20cc47ebeda9346, consultado em 2026-08-23 (detalhe de implementação de ensure_models() e MODEL_MAP; marcado como pendente de verificação no runtime).
• Evidência local: lote de captura batch-156c30635a2d429db5dbd3ea3218fef1, consultado em 2026-08-23 (observação de quota por grupo e por modelo; comportamento marcado como operacional e sujeito a mudança).
• Evidência local: lote de captura batch-6f2392177b75478a8d70a62e077e9333, consultado em 2026-08-23 (paridade operacional do ai-proxy entre PC e VM; sem credenciais registradas).
• Evidência local: lote de captura batch-18e761b4f4094f3297dc376c9fac7c02, consultado em 2026-08-24 (janela de contexto reconhecida pelo Hermes e recuperação do lançador Windows; sem credenciais registradas).
• Evidência local: lote de captura batch-3e0cb184b0d14deb9f0cb660abace931, consultado em 2026-08-24 (avaliação de risco de compatibilidade/conta da rota local; sem credenciais, percentuais de quota ou identificadores de conta).
• Evidência local: lote de captura batch-81ac0f11023e4d42851ffb02e388743f, consultado em 2026-10-05 (execução sem console, tratamento de desconexões locais e health check relatados; sem credenciais, identificadores de processo ou caminhos locais).