Mengonfigurasi gateway perusahaan untuk Google Antigravity

Dokumen ini menunjukkan kepada administrator dan arsitek keamanan cara men-deploy dan mengonfigurasi gateway perusahaan untuk Google Antigravity.

Organisasi perusahaan di industri yang diatur sering kali mempertahankan kontrol jaringan yang ketat yang mencegah workstation developer membuat koneksi internet langsung ke layanan eksternal atau menyelesaikan login Google interaktif berbasis browser.

Antigravity Enterprise Gateway memungkinkan Anda merutekan traffic Antigravity melalui gateway perusahaan yang dioperasikan organisasi Anda sebelum meneruskan permintaan inferensi ke Google. Arsitektur ini merutekan permintaan inferensi model melalui gateway Anda dan menghapus login interaktif sekaligus mempertahankan atribusi penagihan kontrak Gemini Enterprise Anda.

Ringkasan

Saat Anda mengonfigurasi Antigravity Enterprise Gateway, workstation developer akan berkomunikasi dengan gateway perusahaan, bukan terhubung langsung ke Google. Developer melakukan autentikasi ke gateway dengan kunci API yang dikeluarkan oleh gateway Anda, sehingga Antigravity tidak meminta mereka untuk login ke Akun Google individual. Gateway Anda kemudian menggunakan akun layananGoogle Cloud terpusat untuk mengautentikasi dan meneruskan permintaan Antigravity ke Google.

Antigravity otomatis melampirkan header atribusi klien untuk mengidentifikasi perintah chat developer dan alur kerja agen. Untuk memastikan penggunaan model ini dikenali dan ditagih berdasarkan perjanjian Gemini Enterprise yang ada di organisasi Anda, bukan ditagih sebagai konsumsi API mentah yang tidak berkomitmen, gateway Anda harus mempertahankan dan meneruskan header Antigravity ini ke Google:

  • User-Agent: Antigravity otomatis memunculkan header identifikasi:

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

  • X-Goog-Api-Client: Mengidentifikasi runtime klien Antigravity dan telemetri SDK sehingga Google mengatribusikan aktivitas tersebut ke deployment perusahaan berlisensi Anda.

Alat dan versi yang didukung

Antigravity Enterprise Gateway mendukung alat developer AI berikut:

Alat Versi minimum Platform yang didukung
Aplikasi Antigravity
  • 2.15.0 atau yang lebih baru
 macOS, Windows, dan Linux
Antigravity CLI (agy)
  • 1.2.15 atau yang lebih baru
 macOS dan Linux
Antigravity untuk IDE
  • Visual Studio Code dan Visual Studio: Antigravity CLI 1.2.15 atau yang lebih baru, yang didownload dan diupdate secara otomatis oleh ekstensi.
  • JetBrains IDE dan Zed (dengan server ACP): 1.3.0 atau yang lebih baru
 Visual Studio Code, Visual Studio, JetBrains IDE, dan Zed. Untuk mengetahui informasi selengkapnya, lihat Ekstensi Antigravity IDE.

Sebelum memulai

Sebelum men-deploy gateway, pastikan Anda memiliki hal berikut:

  • Project Google Cloud: Project Google Cloud dengan akses ke Gemini Enterprise Agent Platform (sebelumnya Vertex AI) dan Gemini Enterprise Agent Platform API (aiplatform.googleapis.com) diaktifkan. Men-deploy gateway perusahaan tidak memerlukan akun Penagihan Cloud dengan invoice. Siapa pun yang memiliki akses ke Gemini Enterprise Agent Platform dapat menggunakan gateway.
  • Akun layanan: Akun layanan Google Cloud di project Anda yang diberi peran IAM roles/aiplatform.user. Gateway Anda menggunakan akun layanan ini untuk mengautentikasi permintaan Antigravity ke Google Cloud.
  • Log audit Akses Data: Untuk memverifikasi atribusi penagihan di Cloud Logging, aktifkan log audit Akses Data untuk Gemini Enterprise Agent Platform API. Untuk mengetahui informasi selengkapnya, lihat Mengaktifkan log audit Akses Data.
  • Versi klien yang didukung: Developer harus menggunakan versi yang didukung dari setiap alat Antigravity. Untuk mengetahui informasi selengkapnya, lihat Alat Antigravity yang didukung.

Men-deploy gateway perusahaan

Anda dapat menghosting gateway perusahaan menggunakan platform dalam container atau terkelola, seperti Cloud Run, Envoy, LiteLLM, atau Apigee.

Gateway Anda harus memenuhi tiga persyaratan infrastruktur:

  1. Mempertahankan header atribusi klien: Teruskan header klien yang masuk tanpa perubahan ke Google, termasuk User-Agent, X-Goog-Api-Client, dan header kustom apa pun yang dikonfigurasi di gateway.customHeaders (seperti X-Cost-Center).

    Klien antigravitasi tidak mengirimkan informasi project Google Cloud dalam mode gateway. Jika gateway Anda meneruskan permintaan ke project selain project yang berisi akun layanan gateway, konfigurasikan gateway Anda untuk memasukkan header X-Goog-User-Project dengan project ID target untuk atribusi penagihan dan kuota.

  2. Mendukung streaming tanpa buffering: Segera kosongkan potongan Server-Sent Events (SSE) saat memproses permintaan streaming (:streamGenerateContent?alt=sse). Jangan melakukan buffering potongan di lapisan gateway.

  3. Mengonfirmasi endpoint telemetri: Berikan respons dengan HTTP 200 OK ({}) ke panggilan metrik latar belakang (POST /v1beta:*), atau teruskan ke sistem informasi keamanan dan manajemen peristiwa (SIEM) Anda.

Jalur permintaan wajib

Gateway Anda harus merutekan jalur inferensi berikut. Jalur bersifat relatif terhadap URL gateway Anda. Misalnya, permintaan streaming ke https://gateway.cymbal.com menggunakan https://gateway.cymbal.com/v1beta/models/MODEL_ID:streamGenerateContent?alt=sse.

  • Inferensi streaming: POST /v1beta/models/MODEL_ID:streamGenerateContent?alt=sse
  • Inferensi unary: POST /v1beta/models/MODEL_ID:generateContent

Gateway Anda juga harus menerima jalur Gemini Enterprise Agent Platform lengkap yang setara:

  • Inferensi streaming: POST /v1beta1/projects/PROJECT_ID/locations/REGION/publishers/google/models/MODEL_ID:streamGenerateContent?alt=sse
  • Inferensi unary: POST /v1beta1/projects/PROJECT_ID/locations/REGION/publishers/google/models/MODEL_ID:generateContent

Isi permintaan menggunakan skema JSON generateContent standar (contents, generationConfig, safetySettings, dan systemInstruction).

Protokol kabel yang didukung

Antigravity Enterprise Gateway mendukung dua protokol kabel untuk permintaan inferensi:

  • Protokol Gemini (genai): Protokol kabel default. Antigravity mengirimkan permintaan inferensi yang diformat dalam skema generateContent Google ke endpoint POST /v1beta/models/... yang dijelaskan sebelumnya.
  • Protokol wire OpenAI (openai): Saat Anda menetapkan gateway.wireProtocol ke openai (atau menetapkan AGY_LLM_GATEWAY_WIRE_PROTOCOL=openai), Antigravity memformat permintaan inferensi dalam protokol Chat Completions OpenAI dan mengirimkannya ke POST /v1/chat/completions.

Mengautentikasi permintaan ke gateway Anda

Antigravity melakukan autentikasi ke gateway Anda dengan kunci API yang dikeluarkan oleh gateway Anda. Antigravity mengirimkan kunci dari gateway.apiKey (atau variabel lingkungan AGY_LLM_GATEWAY_API_KEY) sebagai token pemilik di header Authorization:

Authorization: Bearer GATEWAY_API_KEY

Antigravity tidak mendapatkan kredensial Google Cloud , token OAuth, atau sertifikat klien atas nama developer. Gateway Anda harus mengautentikasi setiap permintaan dan menolak permintaan yang tidak menyertakan kunci yang valid.

Karena kunci API disimpan di workstation developer, gabungkan dengan kontrol tingkat jaringan:

  • Menjaga gateway tetap pribadi: Ekspos gateway hanya di jaringan perusahaan Anda, misalnya melalui Load Balancer Aplikasi internal yang dijangkau workstation melalui Cloud VPN atau Cloud Interconnect. Jangan berikan endpoint publik ke gateway.
  • Batasi perangkat yang dapat terhubung: Izinkan koneksi hanya dari workstation terkelola, misalnya dengan menggunakan aturan firewall, proxy akses jaringan zero-trust, atau pemeriksaan postur perangkat.
  • Melindungi dan merotasi kunci: Simpan kunci di Secret Manager, validasi kunci pada setiap permintaan, dan rotasi kunci secara rutin. Untuk mengatribusikan penggunaan ke setiap developer, berikan kunci terpisah kepada setiap developer.

Untuk mengetahui informasi selengkapnya, lihat Pertimbangan keamanan.

Menghubungkan gateway Anda ke Gemini Enterprise Agent Platform

Gateway Anda memanggil Gemini Enterprise Agent Platform API menggunakan akun layanan Google Cloud . Anda dapat membangun gateway di gateway API terkelola seperti Apigee, atau men-deploy gateway seperti Envoy atau LiteLLM di infrastruktur Anda sendiri.

  1. Aktifkan API yang diperlukan:

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

    Ganti PROJECT_ID dengan project ID Google Cloud Anda.

  2. Buat akun layanan untuk gateway dan berikan peran 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"

    Ganti SERVICE_ACCOUNT_NAME dengan nama untuk akun layanan, seperti agy-gateway-sa.

  3. Buat kunci API gateway, simpan di Secret Manager, dan izinkan akun layanan membacanya:

    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"

    Ganti SECRET_NAME dengan nama untuk secret, seperti agy-gateway-api-key. Anda mendistribusikan kunci ini ke workstation sebagai gateway.apiKey di admin_settings.json.

  4. Konfigurasikan gateway Anda untuk melakukan hal berikut:

    • Lakukan autentikasi ke Gemini Enterprise Agent Platform sebagai akun layanan.
    • Membaca kunci API dari Secret Manager dan menolak permintaan yang tidak menyediakannya.
    • Izinkan permintaan berjalan setidaknya selama 60 menit agar respons streaming yang panjang tidak terputus.

Untuk mengonfirmasi bahwa gateway berfungsi sebelum Anda mengonfigurasi workstation, lihat Menguji gateway secara langsung.

Men-deploy setelan menggunakan MDM

Untuk mengonfigurasi workstation developer secara terpusat, deploy file konfigurasi admin_settings.json menggunakan sistem pengelolaan perangkat seluler (MDM) Anda, seperti Jamf, Microsoft Intune, Ansible, atau MDM Google Workspace.

Antigravity membaca admin_settings.json dari jalur sistem operasi berikut:

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

Untuk men-deploy file setelan, lakukan hal berikut:

  1. Buat file admin_settings.json dengan URL gateway, kunci API, dan model yang disetujui. Untuk contoh, lihat Contoh konfigurasi.

  2. Di sistem MDM, buat paket, kebijakan, atau skrip yang menyalin file ke jalur untuk setiap sistem operasi target. Jalankan dengan hak istimewa administrator sehingga file dimiliki oleh akun administrator, dan developer dapat membaca, tetapi tidak dapat mengubahnya. Misalnya, skrip MDM Anda dapat menjalankan perintah berikut:

    macOS

    Di shell, jalankan perintah berikut sebagai administrator:

    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

    Di shell, jalankan perintah berikut sebagai administrator:

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

    Windows

    Di PowerShell, jalankan perintah berikut sebagai administrator:

    $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")

    Perintah ini membuat folder dan file dapat dibaca oleh semua pengguna dan hanya dapat ditulis oleh administrator.

  3. Tetapkan paket atau kebijakan ke perangkat atau grup perangkat yang menggunakan Antigravity.

  4. Mulai ulang Antigravity di workstation agar memuat setelan baru.

  5. Untuk mengonfirmasi bahwa workstation terhubung ke gateway, lihat Memverifikasi koneksi klien.

Prioritas setelan

Antigravity membaca setelan gateway dari tiga sumber. Jika setelan yang sama ditentukan di lebih dari satu sumber, sumber dengan prioritas lebih tinggi akan menang:

  1. File setelan administrator (tertinggi): admin_settings.json di-deploy oleh sistem MDM Anda.
  2. Variabel lingkungan: AGY_LLM_GATEWAY_* variabel yang ditetapkan di workstation. Untuk mengetahui informasi selengkapnya, lihat Menghubungkan Antigravity ke Gateway Enterprise.
  3. File setelan pengguna (terendah): ~/.antigravity/settings.json di folder beranda developer.

Setelan digabungkan kolom demi kolom. Misalnya, jika admin_settings.json menetapkan URL gateway, tetapi bukan kunci API, Antigravity akan menggunakan kunci API dari variabel lingkungan. Karena file setelan administrator memiliki prioritas tertinggi, developer tidak dapat mengganti nilai yang Anda tetapkan di dalamnya.

Contoh konfigurasi

Contoh file admin_settings.json berikut mengonfigurasi Antigravity untuk merutekan traffic AI melalui gateway perusahaan di https://gateway.cymbal.com, melampirkan header pusat biaya perusahaan, dan membatasi pemilihan model ke model yang disetujui:

{
  "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" }
    ]
  }
}

Contoh konfigurasi ini menentukan setelan berikut:

  • gateway.enabled: Mengaktifkan mode pemilihan rute gateway. Jika disetel ke true, Antigravity akan mengirimkan semua permintaan inferensi ke gateway Anda, bukan mengirimkannya langsung ke Google, dan tidak akan meminta developer untuk login dengan Akun Google.
  • gateway.url: Endpoint HTTPS gateway perusahaan Anda (https://gateway.cymbal.com).
  • gateway.apiKey: Kunci API (GATEWAY_API_KEY) yang diperlukan gateway Anda untuk mengizinkan permintaan. Gateway Anda yang menerbitkan kunci ini, bukan Google. Antigravity mengirimkannya sebagai token pemilik di header Authorization.

  • gateway.wireProtocol: Protokol kabel API. Nilai yang didukung adalah:

    • genai (default): Menggunakan protokol Gemini API (POST /v1beta/models/...).
    • openai: Menggunakan protokol jaringan OpenAI Chat Completions (POST /v1/chat/completions).

  • gateway.customHeaders: Header HTTP kustom (X-Cost-Center dan X-Corporate-BU) yang ditambahkan Antigravity ke setiap permintaan. Gunakan header ini untuk mengatribusikan penggunaan ke tim atau pusat biaya di log gateway atau SIEM Anda.

  • caCertPath: Jalur absolut ke paket root certificate authority (CA) perusahaan Anda. Setelan ini memastikan workstation memercayai sertifikat TLS internal gateway Anda.

  • models.defaultModelId: Model yang dipilih Antigravity secara default (seperti gemini-3.8-flash).

  • models.list: Model yang disetujui yang dapat dipilih developer di Antigravity. Setiap entri memerlukan modelId yang cocok dengan model yang disajikan oleh gateway Anda. Untuk mengetahui daftar model Google yang didukung, lihat Model yang didukung.

Pertimbangan keamanan

Saat Anda merencanakan autentikasi dan atribusi gateway, pertimbangkan hal berikut:

  • Header yang disediakan klien tidak tepercaya: Developer mengontrol workstation mereka sendiri, sehingga mereka dapat mengubah header yang ditetapkan oleh variabel lingkungan (AGY_LLM_GATEWAY_HEADERS) atau dalam file setelan pengguna. Jangan mengandalkan header ini untuk logging audit yang penting bagi keamanan atau atribusi penagihan.
  • Sematkan header menggunakan MDM: Untuk mencegah developer mengganti header atribusi atau kebijakan, tentukan header tersebut di gateway.customHeaders di admin_settings.json. Nilai di admin_settings.json lebih diutamakan daripada variabel lingkungan dan setelan pengguna.
  • Melakukan autentikasi di lapisan jaringan atau lapisan transpor: Untuk memverifikasi identitas developer atau menerapkan atribusi pusat biaya yang ketat, autentikasi traffic di lapisan jaringan atau lapisan transpor, seperti dengan mutual TLS (mTLS), single sign-on (SSO) tingkat proxy, atau mikrosegmentasi jaringan. Jangan hanya mengandalkan kunci API atau header HTTP.

Memverifikasi deployment

Sebelum men-deploy file konfigurasi ke workstation developer, pastikan gateway perusahaan Anda merutekan traffic dengan benar dan informasi atribusi sampai ke Cloud Logging.

Menguji gateway secara langsung

Uji endpoint gateway perusahaan Anda secara langsung menggunakan curl sebelum menguji di workstation developer. Menguji gateway secara langsung akan mengonfirmasi bahwa perutean jaringan, validasi sertifikat TLS, autentikasi, dan streaming Server-Sent Events (SSE) tanpa buffering berfungsi secara independen dari Antigravity.

Contoh perintah curl berikut mengirimkan permintaan streaming langsung ke endpoint gateway Anda:

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"}]}]}'

Dalam perintah ini:

  • -N: Menonaktifkan buffering respons di curl sehingga Peristiwa yang Dikirim Server (SSE) langsung di-streaming.
  • MODEL_ID: Model yang disetujui dari models.list Anda (seperti gemini-3.8-flash atau gemini-3.7-flash). Sebaiknya lakukan pengujian dengan model Flash untuk verifikasi awal. Untuk mengetahui daftar model yang tersedia, lihat Model yang didukung.
  • Authorization: Mengirim kunci API gateway (GATEWAY_API_KEY) untuk mengautentikasi permintaan dengan gateway.
  • User-Agent: Mengirim string atribusi klien yang digunakan Google untuk mengatribusikan penggunaan ke perjanjian Gemini Enterprise Anda.
  • streamGenerateContent?alt=sse: Memanggil endpoint API streaming untuk model yang ditentukan.

Pastikan gateway langsung menstreaming potongan respons. Jika Anda mengalami error koneksi, peringatan sertifikat, atau penundaan buffering respons, lihat Pemecahan masalah.

Memverifikasi koneksi klien

Periksa status klien di workstation yang dikonfigurasi:

  • Aplikasi Antigravity: Di status bar bawah, pastikan indikator menampilkan Connected: Enterprise Gateway. Di Account Settings, pastikan Enterprise Gateway Mode Active ditampilkan.

  • Antigravity CLI: Jalankan perintah pengujian:

    agy -p "Explain binary search in Go"

    Perintah ini mengirimkan perintah pengujian ke gateway. Pastikan respons di-streaming di terminal Anda tanpa menampilkan dialog login Google interaktif. Jika klien gagal terhubung atau meminta autentikasi Google, lihat Pemecahan masalah.

Memverifikasi atribusi di Cloud Logging

Di konsol Google Cloud , pastikan header atribusi diterima:

  1. Di konsol Google Cloud , buka halaman Logs Explorer:

    Buka Logs Explorer

  2. Jalankan kueri berikut:

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

  3. Periksa metadata entri log. Pastikan protoPayload.requestMetadata.callerSuppliedUserAgent berisi antigravity/VERSION (aidev_client; auth_method=gateway).

Jika tidak ada entri log yang muncul, pastikan log audit Akses Data diaktifkan untuk Gemini Enterprise Agent Platform API.

Orientasi developer

Setelah memverifikasi gateway, siapkan developer Anda untuk menggunakan Antigravity:

  • Workstation terkelola: Jika Anda men-deploy admin_settings.json menggunakan sistem MDM, developer tidak perlu melakukan konfigurasi apa pun. Antigravity terhubung ke gateway secara otomatis saat dimulai.
  • Sandbox dan pipeline CI/CD: Untuk developer yang bekerja di runner dalam container, host SSH jarak jauh, atau lingkungan pengembangan yang tidak dikelola, berikan URL gateway, kunci API, dan jalur root CA Anda. Arahkan developer ke Menghubungkan Antigravity ke Gateway Enterprise.

Pemecahan masalah

Tabel berikut mencantumkan masalah deployment umum dan cara mengatasinya:

Gejala Penyebab Resolusi
x509: certificate signed by unknown authority Workstation tidak memercayai sertifikat TLS gateway. Tentukan jalur ke paket root CA perusahaan Anda menggunakan caCertPath di admin_settings.json.
401 Unauthorized atau 403 Forbidden Kunci API tidak valid atau akun layanan gateway tidak memiliki akses. Verifikasi nilai gateway.apiKey, dan pastikan akun layanan gateway memiliki peran IAM roles/aiplatform.user di project target.
404 Not Found Model yang diminta tidak tersedia di gateway perusahaan, atau ID model salah ketik. Pastikan setiap ID model yang dikonfigurasi di models.list di admin_settings.json cocok dengan nama model yang disajikan oleh gateway perusahaan Anda.
gateway.wireProtocol 'openai' is not supported by the ACP server admin_settings.json atau variabel lingkungan menentukan protokol kabel openai, yang tidak didukung oleh server ACP. Tetapkan wireProtocol ke genai (atau hapus untuk menggunakan default) untuk workstation JetBrains IDE dan Zed.
Waktu tunggu respons streaming habis Gateway melakukan buffering pada respons HTTP. Konfigurasi gateway untuk menonaktifkan buffering respons untuk Server-Sent Events (text/event-stream).
Perintah Antigravity untuk login dengan Google Mode gateway tidak diaktifkan, atau Antigravity tidak dapat menemukan file setelan. Pastikan admin_settings.json di-deploy ke jalur sistem operasi yang benar dan berisi "enabled": true serta url di bagian gateway.

Langkah berikutnya