Configurar um gateway empresarial para o Google Antigravity

Neste documento, mostramos aos administradores e arquitetos de segurança como implantar e configurar um gateway empresarial para o Google Antigravity.

As organizações empresariais em setores regulamentados geralmente mantêm controles de rede rígidos que impedem que as estações de trabalho dos desenvolvedores façam conexões diretas de Internet com serviços externos ou concluam o login interativo do Google com base no navegador.

O Antigravity Enterprise Gateway permite rotear o tráfego do Antigravity por um gateway empresarial que sua organização opera antes de encaminhar solicitações de inferência ao Google. Essa arquitetura encaminha as solicitações de inferência de modelo pelo gateway e remove o login interativo, preservando a atribuição de faturamento do contrato do Gemini Enterprise.

Visão geral

Quando você configura o Antigravity Enterprise Gateway, as estações de trabalho do desenvolvedor se comunicam com o gateway empresarial em vez de se conectarem diretamente ao Google. Os desenvolvedores se autenticam no gateway com uma chave de API emitida pelo gateway, para que a Antigravity não solicite que eles façam login individualmente na Conta do Google. O gateway usa uma conta de serviço centralizada doGoogle Cloud para autenticar e encaminhar solicitações do Antigravity ao Google.

O Antigravity anexa automaticamente cabeçalhos de atribuição de cliente para identificar comandos de chat de desenvolvedores e Agentic Workflows. Para garantir que o uso desse modelo seja reconhecido e faturado de acordo com o contrato do Gemini Enterprise da sua organização, em vez de ser faturado como consumo de API bruta não comprometido, seu gateway precisa preservar e encaminhar estes cabeçalhos do Antigravity para o Google:

  • User-Agent: o Antigravity emite automaticamente um cabeçalho de identificação:

    User-Agent: antigravity/VERSION (aidev_client; auth_method=gateway)

  • X-Goog-Api-Client: identifica o ambiente de execução do cliente do Antigravity e a telemetria do SDK para que o Google credite a atividade à sua implantação empresarial licenciada.

Ferramentas e versões compatíveis

O Antigravity Enterprise Gateway é compatível com as seguintes ferramentas para desenvolvedores de IA:

Ferramenta Versão mínima Plataformas compatíveis
App Antigravity
  • 2.15.0 ou mais recente
 macOS, Windows e Linux
CLI do Antigravity (agy)
  • 1.2.15 ou mais recente
 macOS e Linux
Antigravity para IDEs
  • Visual Studio Code e Visual Studio: CLI do Antigravity 1.2.15 ou mais recente, que a extensão baixa e atualiza automaticamente.
  • Ambientes de desenvolvimento integrado do JetBrains e Zed (com servidor ACP): 1.3.0 ou mais recente
 Visual Studio Code, Visual Studio, ambientes de desenvolvimento integrado JetBrains e Zed. Para mais informações, consulte Extensões de IDE Antigravity.

Antes de começar

Antes de implantar o gateway, verifique se você tem:

  • Projeto do Google Cloud: um projeto do Google Cloud com acesso à Gemini Enterprise Agent Platform (antiga Vertex AI) e à API Gemini Enterprise Agent Platform (aiplatform.googleapis.com) ativada. A implantação do gateway empresarial não requer uma conta do Cloud Billing com fatura. Qualquer pessoa com acesso à Gemini Enterprise Agent Platform pode usar o gateway.
  • Conta de serviço: uma conta de serviço do Google Cloud no seu projeto que recebe o papel do IAM roles/aiplatform.user. O gateway usa essa conta de serviço para autenticar solicitações do Antigravity para o Google Cloud.
  • Registros de auditoria de acesso a dados: para verificar a atribuição de faturamento no Cloud Logging, ative os registros de auditoria de acesso a dados para a API Gemini Enterprise Agent Platform. Para mais informações, consulte Ativar registros de auditoria de acesso a dados.
  • Versões de cliente compatíveis: os desenvolvedores precisam usar uma versão compatível de cada ferramenta do Antigravity. Para mais informações, consulte Ferramentas compatíveis com o Antigravity.

Implantar o gateway empresarial

É possível hospedar seu gateway empresarial usando qualquer plataforma conteinerizada ou gerenciada, como Cloud Run, Envoy, LiteLLM ou Apigee.

Seu gateway precisa atender a três requisitos de infraestrutura:

  1. Preservar cabeçalhos de atribuição do cliente: encaminhe os cabeçalhos de cliente recebidos sem alterações para o Google, incluindo User-Agent, X-Goog-Api-Client e todos os cabeçalhos personalizados configurados em gateway.customHeaders (como X-Cost-Center).

    Os clientes do Antigravity não enviam informações do projeto Google Cloud no modo de gateway. Se o gateway encaminhar solicitações para um projeto diferente daquele que contém a conta de serviço do gateway, configure o gateway para injetar o cabeçalho X-Goog-User-Project com o ID do projeto de destino para atribuição de faturamento e cota.

  2. Suporte a streaming sem buffer: limpe os blocos de eventos enviados pelo servidor (SSE) imediatamente ao processar solicitações de streaming (:streamGenerateContent?alt=sse). Não armazene blocos em buffer na camada do gateway.

  3. Confirmar endpoints de telemetria: responda com HTTP 200 OK ({}) a chamadas de métricas em segundo plano (POST /v1beta:*) ou encaminhe-as para seu sistema de gerenciamento de eventos e informações de segurança (SIEM).

Caminhos de solicitação obrigatórios

O gateway precisa rotear os seguintes caminhos de inferência. Os caminhos são relativos ao URL do gateway. Por exemplo, uma solicitação de streaming para https://gateway.cymbal.com usa https://gateway.cymbal.com/v1beta/models/MODEL_ID:streamGenerateContent?alt=sse.

  • Inferência de streaming: POST /v1beta/models/MODEL_ID:streamGenerateContent?alt=sse
  • Inferência unária: POST /v1beta/models/MODEL_ID:generateContent

O gateway também precisa aceitar os caminhos completos equivalentes da Gemini Enterprise Agent Platform:

  • Inferência de streaming: POST /v1beta1/projects/PROJECT_ID/locations/REGION/publishers/google/models/MODEL_ID:streamGenerateContent?alt=sse
  • Inferência unária: POST /v1beta1/projects/PROJECT_ID/locations/REGION/publishers/google/models/MODEL_ID:generateContent

Os corpos de solicitação usam o esquema JSON padrão generateContent (contents, generationConfig, safetySettings e systemInstruction).

Protocolos de transmissão compatíveis

O Antigravity Enterprise Gateway é compatível com dois protocolos de conexão para solicitações de inferência:

  • Protocolo Gemini (genai): o protocolo de transmissão padrão. A Antigravity envia solicitações de inferência formatadas no esquema generateContent do Google para os endpoints POST /v1beta/models/... descritos anteriormente.
  • Protocolo de transmissão da OpenAI (openai): quando você define gateway.wireProtocol como openai (ou define AGY_LLM_GATEWAY_WIRE_PROTOCOL=openai), o Antigravity formata as solicitações de inferência no protocolo de preenchimento de chat da OpenAI e as envia para POST /v1/chat/completions.

Autenticar solicitações para o gateway

A Antigravity se autentica no gateway com uma chave de API emitida pelo gateway. O Antigravity envia a chave de gateway.apiKey (ou a variável de ambiente AGY_LLM_GATEWAY_API_KEY) como um token do portador no cabeçalho Authorization:

Authorization: Bearer GATEWAY_API_KEY

O Antigravity não recebe credenciais do Google Cloud , tokens do OAuth ou certificados do cliente em nome dos desenvolvedores. O gateway precisa autenticar todas as solicitações e rejeitar aquelas que não apresentarem uma chave válida.

Como a chave de API é armazenada nas estações de trabalho do desenvolvedor, combine-a com controles no nível da rede:

  • Manter o gateway particular: exponha o gateway apenas na rede corporativa, por exemplo, por meio de um balanceador de carga de aplicativo interno que as estações de trabalho acessam pelo Cloud VPN ou pelo Cloud Interconnect. Não forneça um endpoint público ao gateway.
  • Restringir quais dispositivos podem se conectar: permita conexões apenas de estações de trabalho gerenciadas, por exemplo, usando regras de firewall, um proxy de acesso à rede de confiança zero ou verificações de postura do dispositivo.
  • Proteger e alternar chaves: armazene chaves no Secret Manager, valide-as em cada solicitação e alterne-as regularmente. Para atribuir o uso a desenvolvedores individuais, emita uma chave separada para cada desenvolvedor.

Para mais informações, consulte Considerações de segurança.

Conectar o gateway à Gemini Enterprise Agent Platform

Seu gateway chama a API Gemini Enterprise Agent Platform usando uma conta de serviço do Google Cloud . É possível criar o gateway em um gateway de API gerenciado, como a Apigee, ou implantar um gateway como o Envoy ou o LiteLLM na sua própria infraestrutura.

  1. Ative as APIs necessárias:

    gcloud services enable \
  aiplatform.googleapis.com \
  secretmanager.googleapis.com \
  --project=PROJECT_ID

    Substitua PROJECT_ID pelo Google Cloud ID do projeto.

  2. Crie uma conta de serviço para o gateway e conceda a ela o papel roles/aiplatform.user:

    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
  --project=PROJECT_ID \
  --display-name="Antigravity Enterprise Gateway"

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"

    Substitua SERVICE_ACCOUNT_NAME por um nome para a conta de serviço, como agy-gateway-sa.

  3. Gere uma chave de API de gateway, armazene-a no Secret Manager e permita que a conta de serviço a leia:

    openssl rand -base64 32 | tr -d '\n' | gcloud secrets create SECRET_NAME \
  --project=PROJECT_ID \
  --data-file=-

gcloud secrets add-iam-policy-binding SECRET_NAME \
  --project=PROJECT_ID \
  --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/secretmanager.secretAccessor"

    Substitua SECRET_NAME por um nome para o secret, como agy-gateway-api-key. Distribua essa chave para as estações de trabalho como gateway.apiKey em admin_settings.json.

  4. Configure o gateway para fazer o seguinte:

    • Autentique-se na Gemini Enterprise Agent Platform como a conta de serviço.
    • Ler a chave de API do Secret Manager e rejeitar solicitações que não a apresentem.
    • Permita que as solicitações sejam executadas por pelo menos 60 minutos para que as respostas de streaming longas não sejam interrompidas.

Para confirmar se o gateway funciona antes de configurar as estações de trabalho, consulte Testar o gateway diretamente.

Implantar configurações usando o MDM

Para configurar as estações de trabalho de desenvolvedor de forma centralizada, implante o arquivo de configuração admin_settings.json usando seu sistema de gerenciamento de dispositivos móveis (MDM), como Jamf, Microsoft Intune, Ansible ou MDM do Google Workspace.

O Antigravity lê admin_settings.json nos seguintes caminhos do sistema operacional:

  • macOS: /Library/Application Support/Antigravity/admin_settings.json
  • Linux: /etc/antigravity/admin_settings.json
  • Windows: %ProgramData%\Antigravity\admin_settings.json

Para implantar o arquivo de configurações, faça o seguinte:

  1. Crie um arquivo admin_settings.json com o URL do gateway, a chave de API e os modelos aprovados. Para ver um exemplo, consulte Exemplo de configuração.

  2. No sistema de MDM, crie um pacote, uma política ou um script que copie o arquivo para o caminho de cada sistema operacional de destino. Execute-o com privilégios de administrador para que o arquivo seja de propriedade de uma conta de administrador e os desenvolvedores possam ler, mas não modificar. Por exemplo, o script de MDM pode executar os seguintes comandos:

    macOS

    Em um shell, execute os seguintes comandos como administrador:

    sudo mkdir -p "/Library/Application Support/Antigravity"
sudo install -m 644 -o root -g wheel admin_settings.json \
"/Library/Application Support/Antigravity/admin_settings.json"

    Linux

    Em um shell, execute os seguintes comandos como administrador:

    sudo install -D -m 644 -o root -g root admin_settings.json \
/etc/antigravity/admin_settings.json

    Windows

    No PowerShell, execute os comandos a seguir como administrador:

    $dir = Join-Path $env:ProgramData "Antigravity"
# Remove any folder that a non-admin created first, so they can't keep ownership.
if (Test-Path $dir) { Remove-Item -Recurse -Force $dir }
New-Item -ItemType Directory -Path $dir | Out-Null
# Administrators own the folder; only admins and SYSTEM can write; users can read.
icacls $dir /setowner "*S-1-5-32-544"
icacls $dir /inheritance:r /grant:r "*S-1-5-32-544:(OI)(CI)F" "*S-1-5-18:(OI)(CI)F" "*S-1-5-32-545:(OI)(CI)RX"
Copy-Item admin_settings.json (Join-Path $dir "admin_settings.json")

    Esses comandos tornam a pasta e o arquivo legíveis para todos os usuários e graváveis apenas para administradores.

  3. Atribua o pacote ou a política aos dispositivos ou grupos de dispositivos que usam o Antigravity.

  4. Reinicie o Antigravity nas estações de trabalho para que ele carregue as novas configurações.

  5. Para confirmar se as estações de trabalho se conectam ao gateway, consulte Verificar conexões do cliente.

Precedência de configurações

O Antigravity lê as configurações de gateway de três fontes. Quando a mesma configuração é definida em mais de uma origem, a origem com maior precedência vence:

  1. Arquivo de configurações do administrador (mais alto): admin_settings.json implantado pelo sistema de MDM.
  2. Variáveis de ambiente: variáveis AGY_LLM_GATEWAY_* definidas na estação de trabalho. Para mais informações, consulte Conectar o Antigravity a um gateway corporativo.
  3. Arquivo de configurações do usuário (mais baixo): ~/.antigravity/settings.json na pasta inicial do desenvolvedor.

As configurações são mescladas campo por campo. Por exemplo, se admin_settings.json definir o URL do gateway, mas não a chave de API, o Antigravity vai usar a chave de API de uma variável de ambiente. Como o arquivo de configurações do administrador tem a maior precedência, os desenvolvedores não podem substituir os valores definidos nele.

Exemplo de configuração

O exemplo de arquivo admin_settings.json a seguir configura o Antigravity para rotear o tráfego de IA por um gateway empresarial em https://gateway.cymbal.com, anexa cabeçalhos de centro de custo corporativo e restringe a seleção de modelos aos aprovados:

{
  "gateway": {
    "enabled": true,
    "url": "https://gateway.cymbal.com",
    "apiKey": "GATEWAY_API_KEY",
    "wireProtocol": "genai",
    "customHeaders": {
      "X-Cost-Center": "Platform-Engineering",
      "X-Corporate-BU": "DevTools"
    }
  },
  "caCertPath": "/etc/ssl/certs/cymbal-root-ca.pem",
  "models": {
    "defaultModelId": "gemini-3.8-flash",
    "list": [
      { "modelId": "gemini-3.8-flash" },
      { "modelId": "gemini-3.7-flash" },
      { "modelId": "gemini-3.1-pro-preview" }
    ]
  }
}

Este exemplo de configuração define as seguintes configurações:

  • gateway.enabled: ativa o modo de roteamento do gateway. Quando definido como true, o Antigravity envia todas as solicitações de inferência para o gateway, em vez de enviá-las diretamente ao Google, e não solicita que os desenvolvedores façam login com uma Conta do Google.
  • gateway.url: o endpoint HTTPS do gateway empresarial (https://gateway.cymbal.com).
  • gateway.apiKey: a chave de API (GATEWAY_API_KEY) que o gateway exige para autorizar solicitações. Seu gateway emite essa chave, não o Google. O Antigravity o envia como um token do portador no cabeçalho Authorization.

  • gateway.wireProtocol: o protocolo de transmissão da API. Os valores aceitos são:

    • genai (padrão): usa o protocolo da API Gemini (POST /v1beta/models/...).
    • openai: usa o protocolo de conexão de preenchimento de chat da OpenAI (POST /v1/chat/completions).

  • gateway.customHeaders: cabeçalhos HTTP personalizados (X-Cost-Center e X-Corporate-BU) que o Antigravity adiciona a cada solicitação. Use esses cabeçalhos para atribuir o uso a equipes ou centros de custo nos registros do gateway ou no SIEM.

  • caCertPath: o caminho absoluto para o pacote de autoridade certificadora (CA) raiz corporativa. Essa configuração garante que as estações de trabalho confiem no certificado TLS interno do gateway.

  • models.defaultModelId: o modelo que o Antigravity seleciona por padrão (como gemini-3.8-flash).

  • models.list: os modelos aprovados que os desenvolvedores podem selecionar no Antigravity. Cada entrada requer um modelId correspondente a um modelo disponibilizado pelo gateway. Para uma lista de modelos do Google compatíveis, consulte Modelos compatíveis.

Considerações sobre segurança

Ao planejar a autenticação e a atribuição do gateway, considere o seguinte:

  • Os cabeçalhos fornecidos pelo cliente não são confiáveis: os desenvolvedores controlam as próprias estações de trabalho, então podem mudar os cabeçalhos definidos por variáveis de ambiente (AGY_LLM_GATEWAY_HEADERS) ou no arquivo de configurações do usuário. Não confie nesses cabeçalhos para geração de registros de auditoria ou atribuição de faturamento essenciais para a segurança.
  • Fixar cabeçalhos usando o MDM: para impedir que os desenvolvedores substituam cabeçalhos de atribuição ou de política, defina-os em gateway.customHeaders em admin_settings.json. Os valores em admin_settings.json têm precedência sobre as variáveis de ambiente e as configurações do usuário.
  • Autenticar na camada de rede ou de transporte: para verificar a identidade do desenvolvedor ou aplicar uma atribuição rigorosa de centro de custo, autentique o tráfego na camada de rede ou de transporte, como com o TLS mútuo (mTLS), o Logon único (SSO) no nível do proxy ou a microssegmentação de rede. Não dependa apenas da chave de API ou dos cabeçalhos HTTP.

Verificar a implantação

Antes de implantar arquivos de configuração nas estações de trabalho do desenvolvedor, verifique se o gateway corporativo encaminha o tráfego corretamente e se as informações de atribuição chegam ao Cloud Logging.

Testar o gateway diretamente

Teste o endpoint do gateway empresarial diretamente usando curl antes de testar em estações de trabalho para desenvolvedores. Testar o gateway diretamente confirma que o roteamento de rede, a validação de certificado TLS, a autenticação e o streaming de eventos enviados pelo servidor (SSE, na sigla em inglês) sem buffer funcionam de maneira independente do Antigravity.

O exemplo de comando curl a seguir envia uma solicitação de streaming diretamente para o endpoint do gateway:

curl -N -X POST "https://gateway.cymbal.com/v1beta/models/MODEL_ID:streamGenerateContent?alt=sse" \
  -H "Authorization: Bearer GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "User-Agent: antigravity/1.2.15 (aidev_client; auth_method=gateway)" \
  -d '{"contents": [{"role": "user", "parts": [{"text": "Reply with PONG"}]}]}'

Nesse comando:

  • -N: desativa o armazenamento em buffer de respostas em curl para que os eventos enviados pelo servidor (SSE) sejam transmitidos imediatamente.
  • MODEL_ID: um modelo aprovado do seu models.list (como gemini-3.8-flash ou gemini-3.7-flash). Recomendamos testar com um modelo Flash para a verificação inicial. Para uma lista de modelos disponíveis, consulte Modelos compatíveis.
  • Authorization: envia a chave de API do gateway (GATEWAY_API_KEY) para autenticar a solicitação com o gateway.
  • User-Agent: envia a string de atribuição do cliente que o Google usa para atribuir o uso ao seu contrato do Gemini Enterprise.
  • streamGenerateContent?alt=sse: chama o endpoint de API de streaming para o modelo especificado.

Verifique se o gateway transmite os blocos de resposta imediatamente. Se você encontrar erros de conexão, avisos de certificado ou atrasos no armazenamento em buffer de resposta, consulte Solução de problemas.

Verificar conexões de cliente

Verifique o status do cliente em uma estação de trabalho configurada:

  • App Antigravity: na barra de status na parte de baixo, verifique se o indicador mostra Connected: Enterprise Gateway. Em Configurações da conta, verifique se a opção Modo de gateway empresarial ativo está aparecendo.

  • CLI do Antigravity: execute um comando de teste:

    agy -p "Explain binary search in Go"

    Esse comando envia um comando de teste para o gateway. Verifique se a resposta é transmitida no terminal sem exibir uma solicitação interativa de login do Google. Se o cliente não se conectar ou solicitar a autenticação do Google, consulte Solução de problemas.

Verificar a atribuição no Cloud Logging

No console do Google Cloud , verifique se os cabeçalhos de atribuição foram recebidos:

  1. No console do Google Cloud , acesse a página Análise de registros:

    Acessar a Análise de registros

  2. Execute a seguinte consulta:

    resource.type="aiplatform.googleapis.com/Endpoint" OR
protoPayload.serviceName="aiplatform.googleapis.com"

  3. Inspecione os metadados da entrada de registro. Verifique se protoPayload.requestMetadata.callerSuppliedUserAgent contém antigravity/VERSION (aidev_client; auth_method=gateway).

Se nenhuma entrada de registro aparecer, verifique se os registros de auditoria de acesso a dados estão ativados para a API Gemini Enterprise Agent Platform.

Integrar desenvolvedores

Depois de verificar o gateway, prepare os desenvolvedores para usar o Antigravity:

  • Estações de trabalho gerenciadas: se você implantar o admin_settings.json usando seu sistema de MDM, os desenvolvedores não precisarão realizar nenhuma configuração. O Antigravity se conecta ao gateway automaticamente quando é iniciado.
  • Sandboxes e pipelines de CI/CD: para desenvolvedores que trabalham em executores conteinerizados, hosts SSH remotos ou ambientes de desenvolvimento não gerenciados, forneça o URL do gateway, a chave de API e o caminho da CA raiz. Oriente os desenvolvedores a conectar o Antigravity a um gateway empresarial.

Solução de problemas

A tabela a seguir lista problemas comuns de implantação e como resolvê-los:

Sintoma Causa Resolução
x509: certificate signed by unknown authority A estação de trabalho não confia no certificado TLS do gateway. Especifique o caminho para o pacote de CA raiz corporativo usando caCertPath em admin_settings.json.
401 Unauthorized ou 403 Forbidden A chave de API é inválida ou a conta de serviço do gateway não tem acesso. Verifique o valor de gateway.apiKey e se a conta de serviço do gateway tem o papel do IAM roles/aiplatform.user no projeto de destino.
404 Not Found O modelo solicitado não está disponível no gateway corporativo ou o ID do modelo foi digitado incorretamente. Verifique se cada ID de modelo configurado em models.list em admin_settings.json corresponde a um nome de modelo que seu gateway corporativo disponibiliza.
gateway.wireProtocol 'openai' is not supported by the ACP server admin_settings.json ou uma variável de ambiente especifica o protocolo de transmissão openai, que não é compatível com o servidor ACP. Defina wireProtocol como genai (ou omita para usar o padrão) para as estações de trabalho do ambiente de desenvolvimento integrado do JetBrains e do Zed.
Tempo limite das respostas de streaming O gateway está armazenando em buffer as respostas HTTP. Configure o gateway para desativar o armazenamento em buffer de respostas para eventos enviados pelo servidor (text/event-stream).
O Antigravity solicita o login do Google O modo de gateway não está ativado ou o Antigravity não consegue encontrar o arquivo de configurações. Verifique se admin_settings.json está implantado no caminho correto do sistema operacional e contém "enabled": true e um url na seção gateway.

A seguir