Prasyarat

Sebelum mengonfigurasi Claude Code dengan Google Cloud's Agent Platform, yang sebelumnya dikenal sebagai Vertex AI, pastikan Anda memiliki:

• Akun Google Cloud Platform (GCP) dengan penagihan diaktifkan
• Proyek GCP dengan Google Cloud's Agent Platform API diaktifkan
• Akses ke model Claude yang diinginkan (misalnya, Claude Sonnet 4.6)
• Google Cloud SDK (gcloud) terinstal dan dikonfigurasi
• Kuota dialokasikan di wilayah GCP yang diinginkan

Untuk masuk dengan kredensial Google Cloud's Agent Platform Anda sendiri, ikuti Masuk dengan Google Cloud's Agent Platform di bawah. Untuk menerapkan Claude Code di seluruh tim, gunakan langkah pengaturan manual dan pin versi model Anda sebelum melakukan peluncuran.

Masuk dengan Agent Platform

Jika Anda memiliki kredensial Google Cloud dan ingin mulai menggunakan Claude Code melalui Agent Platform Google Cloud, wizard login akan memandu Anda. Anda menyelesaikan prasyarat sisi GCP sekali per proyek; wizard menangani sisi Claude Code.

Setelah Anda masuk, jalankan /setup-vertex kapan saja untuk membuka kembali wizard dan mengubah kredensial, proyek, wilayah, atau pin model Anda. Langkah pin model dimulai dari model yang saat ini Anda pin. Wizard menulis ke ~/.claude/settings.json, atau ke $CLAUDE_CONFIG_DIR/settings.json ketika CLAUDE_CONFIG_DIR diatur.

Konfigurasi wilayah

Claude Code mendukung Google Cloud's Agent Platform global, multi-region, dan titik akhir regional. Atur CLOUD_ML_REGION ke global, lokasi multi-region seperti eu atau us, atau wilayah spesifik seperti us-east5. Claude Code memilih nama host Google Cloud's Agent Platform yang benar untuk setiap bentuk, termasuk host aiplatform.eu.rep.googleapis.com dan aiplatform.us.rep.googleapis.com untuk lokasi multi-region.

Pengaturan manual

Untuk mengonfigurasi Google Cloud's Agent Platform melalui variabel lingkungan alih-alih wizard, misalnya di CI atau peluncuran perusahaan yang ditulis skrip, ikuti langkah-langkah di bawah.

1. Aktifkan Agent Platform API

Aktifkan Google Cloud's Agent Platform API di proyek GCP Anda. Ganti YOUR-PROJECT-ID dengan ID proyek GCP Anda di sini dan di langkah konfigurasi di bawah:

# Atur ID proyek Anda
gcloud config set project YOUR-PROJECT-ID

# Aktifkan Agent Platform API
gcloud services enable aiplatform.googleapis.com

2. Minta akses model

Minta akses ke model Claude di Google Cloud's Agent Platform:

1. Navigasikan ke Google Cloud's Agent Platform Model Garden
2. Cari model "Claude"
3. Minta akses ke model Claude yang diinginkan (misalnya, Claude Sonnet 4.6)
4. Tunggu persetujuan (mungkin memakan waktu 24-48 jam)

3) Konfigurasi kredensial GCP

Claude Code menggunakan autentikasi Google Cloud standar.

Untuk informasi lebih lanjut, lihat dokumentasi autentikasi Google Cloud.

Claude Code mendukung Workload Identity Federation berbasis sertifikat X.509 melalui rantai Application Default Credentials yang sama. Atur GOOGLE_APPLICATION_CREDENTIALS ke jalur file konfigurasi kredensial Anda.

Konfigurasi kredensial lanjutan

Claude Code mendukung penyegaran kredensial otomatis untuk GCP melalui pengaturan gcpAuthRefresh. Tambahkan ke file pengaturan Claude Code Anda, misalnya ~/.claude/settings.json. Ketika Claude Code mendeteksi bahwa kredensial GCP Anda telah kedaluwarsa atau tidak dapat dimuat, Claude Code menjalankan perintah yang dikonfigurasi untuk mendapatkan kredensial baru sebelum mencoba ulang permintaan.

{
  "gcpAuthRefresh": "gcloud auth application-default login",
  "env": {
    "ANTHROPIC_VERTEX_PROJECT_ID": "your-project-id"
  }
}

Sebelum menjalankan perintah, Claude Code meminta token akses dengan kredensial Anda saat ini untuk mengonfirmasi bahwa kredensial tersebut benar-benar kedaluwarsa, dan melewati perintah ketika kredensial masih berfungsi.

Jika pemeriksaan tidak selesai dalam lima detik, Claude Code juga melewati perintah dan menjalankannya hanya setelah permintaan gagal dengan kesalahan kredensial. Sebelum v2.1.261, pemeriksaan yang habis waktu dihitung sebagai kredensial yang kedaluwarsa, jadi perintah dapat membuka browser Anda saat startup meskipun kredensial Anda masih valid.

Claude Code menampilkan output perintah kepada Anda, tetapi tidak dapat mengirim input interaktif perintah. Ini berfungsi dengan baik untuk alur autentikasi berbasis browser di mana CLI menampilkan URL dan Anda menyelesaikan autentikasi di browser. Perintah penyegaran habis waktu setelah tiga menit jika autentikasi tidak selesai. Jika Anda mengatur gcpAuthRefresh dalam pengaturan proyek seperti .claude/settings.json, Claude Code menjalankannya di bawah aturan kepercayaan ruang kerja yang sama dengan hooks dalam file pengaturan, yang mencakup sesi -p di folder yang belum pernah Anda percayai.

4. Konfigurasi Claude Code

Atur variabel lingkungan berikut:

# Aktifkan integrasi Agent Platform
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

# Opsional: Timpa URL titik akhir Agent Platform untuk titik akhir kustom atau gateway
# export ANTHROPIC_VERTEX_BASE_URL=https://aiplatform.googleapis.com

# Ketika CLOUD_ML_REGION=global, timpa wilayah untuk model yang tidak mendukung titik akhir global
export VERTEX_REGION_CLAUDE_HAIKU_4_5=us-east5
export VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1

Sebagian besar versi model memiliki variabel VERTEX_REGION_CLAUDE_* yang sesuai. Lihat referensi variabel lingkungan untuk daftar lengkap. Periksa Google Cloud's Agent Platform Model Garden untuk menentukan model mana yang mendukung titik akhir global versus regional saja.

Jika nilai wilayah tidak berbentuk seperti nama wilayah atau lokasi, Claude Code memperlakukannya sebagai tidak diatur. Misalnya, Claude Code memperlakukan nilai yang berisi garis miring, titik, atau spasi sebagai tidak diatur. Claude Code kembali ke sumber yang berbeda untuk setiap variabel:

• VERTEX_REGION_CLAUDE_*: Claude Code kembali ke CLOUD_ML_REGION.
• CLOUD_ML_REGION: Claude Code kembali ke us-east5.

Prompt caching diaktifkan secara otomatis. Untuk menonaktifkannya, atur DISABLE_PROMPT_CACHING=1. Untuk meminta TTL cache 1 jam alih-alih default 5 menit, atur ENABLE_PROMPT_CACHING_1H=1; penulisan cache dengan TTL 1 jam ditagih dengan tarif yang lebih tinggi. Untuk menetapkan TTL yang berbeda untuk percakapan utama Anda dan untuk permintaan yang Claude Code buat di luar itu, pilih TTL sendiri.

Untuk menaikkan batas laju Anda, hubungi dukungan Google Cloud. Saat menggunakan Google Cloud's Agent Platform, perintah /logout tidak tersedia karena autentikasi ditangani melalui kredensial Google Cloud.

Claude Code memutuskan antara pencarian alat MCP dan pemuatan di muka berdasarkan generasi model:

• Claude Opus 4.5, Sonnet 4.5, Haiku 4.5, dan yang lebih baru: Claude Code mengaktifkan pencarian alat secara default.
• Model sebelumnya, termasuk semua model Claude 3.x: Claude Code memuat definisi alat MCP di muka, karena tumpukan penyajian Agent Platform mereka menolak header beta yang diperlukan. Mengatur ENABLE_TOOL_SEARCH=true tidak mengganti ini.

Atur ENABLE_TOOL_SEARCH=false untuk menonaktifkan pencarian alat pada setiap model. Sebelum v2.1.221, Claude Code menonaktifkan pencarian alat untuk semua model di Google Cloud's Agent Platform kecuali Anda mengatur ENABLE_TOOL_SEARCH=true.

5. Pin versi model

Atur variabel lingkungan ini ke ID model Google Cloud's Agent Platform spesifik.

Tanpa ANTHROPIC_DEFAULT_OPUS_MODEL, alias opus di Google Cloud's Agent Platform diselesaikan ke Opus 5.5, dan tanpa ANTHROPIC_DEFAULT_SONNET_MODEL, alias sonnet diselesaikan ke Sonnet 4.5. Contoh ini pin setiap alias ke versi spesifik:

export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-8'
export ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-5'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'

Untuk ID model saat ini dan warisan, lihat Ikhtisar Model. Lihat Konfigurasi Model untuk daftar lengkap variabel lingkungan.

Claude Code menggunakan model default ini ketika tidak ada variabel pinning yang diatur:

Tugas latar belakang seperti pembuatan judul sesi menggunakan model kecil/cepat, biasanya model kelas Haiku. Di Google Cloud's Agent Platform, Claude Code menggunakan model Sonnet default untuk tugas latar belakang karena Haiku mungkin tidak diaktifkan di setiap proyek atau wilayah. Dua pilihan mengubah model mana yang membawanya:

• Ketika Anda memilih model utama dengan --model, ANTHROPIC_MODEL, atau pengaturan model, tugas latar belakang menggunakan model tersebut. Ketika Claude Code memulai sesi pada model yang Anda atur dengan ANTHROPIC_DEFAULT_MODEL, tugas latar belakang menggunakan model tersebut juga. Mengatur ANTHROPIC_DEFAULT_OPUS_MODEL tanpa ANTHROPIC_DEFAULT_SONNET_MODEL juga dihitung sebagai pilihan, karena model Sonnet bawaan mungkin tidak diaktifkan dalam proyek yang mengarahkan Opus-nya sendiri.
• Untuk menggunakan Haiku untuk tugas latar belakang, atur ANTHROPIC_DEFAULT_HAIKU_MODEL ke ID model yang tersedia di proyek Anda.

Sebelum v2.1.280, model utama di Google Cloud's Agent Platform default ke Opus 5 dan alias opus diselesaikan ke Opus 5 dari v2.1.219. Pada v2.1.207 melalui v2.1.218, model utama di Google Cloud's Agent Platform default ke Opus 4.8 dan alias opus diselesaikan ke Opus 4.8. Sebelum v2.1.207, model utama default ke Sonnet 4.5, alias opus diselesaikan ke Opus 4.6, dan tugas latar belakang selalu menggunakan model utama.

Untuk menyesuaikan model lebih lanjut:

export ANTHROPIC_MODEL='claude-opus-4-8'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'

6. Verifikasi konfigurasi Anda

Mulai Claude Code dan jalankan /status untuk mengonfirmasi pengaturan. Baris API provider menampilkan Google Vertex AI, dan baris GCP project, Default region, dan Model menampilkan ID proyek, wilayah, dan model yang diselesaikan Anda. Jika baris penyedia hilang, variabel lingkungan tidak mencapai proses. Konfirmasi bahwa variabel tersebut diekspor di shell tempat Anda meluncurkan claude, atau atur di blok env dari file pengaturan Anda.

Pemeriksaan model startup

Ketika Claude Code dimulai dengan Google Cloud's Agent Platform dikonfigurasi, ia memverifikasi bahwa model yang dimaksudkan untuk digunakan dapat diakses di proyek Anda.

Jika Anda telah mempinkan versi model yang lebih lama dari default Claude Code saat ini, dan proyek Anda dapat memanggil versi yang lebih baru, Claude Code meminta Anda untuk memperbarui pin. Menerima menulis ID model baru ke file pengaturan pengguna Anda dan memulai ulang Claude Code. Menolak diingat sampai perubahan versi default berikutnya.

Jika Anda belum mempinkan model dan default saat ini tidak tersedia di proyek Anda, Claude Code kembali untuk sesi saat ini dan menampilkan pemberitahuan. Ia mencoba versi sebelumnya dari model default terlebih dahulu dan, ketika default adalah model Opus dan tidak ada versi Opus yang tersedia, kembali ke model Sonnet default. Fallback tidak disimpan. Aktifkan model yang lebih baru di Model Garden atau pin versi untuk membuat pilihan permanen.

Ketika Anda memulai sesi pada versi Sonnet atau Opus tertentu, misalnya dengan --model, ANTHROPIC_MODEL, atau pengaturan model, versi tersebut bertindak sebagai default yang dipinkan untuk sesi yang cocok dengan alias sonnet atau opus. Claude Code melewati pemeriksaan ketersediaan untuk default bawaan yang diganti model Anda dan dimulai pada model yang Anda konfigurasi, tanpa pemberitahuan fallback.

Alias model seperti opus tidak bertindak sebagai pin, begitu juga dengan ID model yang tidak dikenali Claude Code.

Konfigurasi IAM

Tetapkan peran roles/aiplatform.user, yang mencakup izin yang diperlukan:

• aiplatform.endpoints.predict - Diperlukan untuk invokasi model dan penghitungan token

Untuk izin yang lebih ketat, buat peran kustom dengan hanya izin di atas.

Untuk detail, lihat dokumentasi IAM Agent Platform Google Cloud.

Jendela konteks token 1M

Claude Sonnet 5, Opus 4.6 dan yang lebih baru, serta Sonnet 4.6 mendukung jendela konteks token 1M di Platform Agent Google Cloud. Sonnet 5 selalu berjalan dengan jendela 1M, tanpa varian [1m] untuk dipilih. Untuk model lainnya, Claude Code secara otomatis mengaktifkan jendela konteks yang diperluas ketika Anda memilih varian model 1M.

Wizard pengaturan menawarkan opsi konteks 1M ketika mempinkan model. Untuk mengaktifkannya untuk model yang dipinkan secara manual, tambahkan [1m] ke ID model. Lihat Pin models for third-party deployments untuk detail.

Pemecahan masalah

Jika Anda mengalami kesalahan "Could not load the default credentials":

• Jalankan gcloud auth application-default login untuk menyiapkan Application Default Credentials
• Atur GOOGLE_APPLICATION_CREDENTIALS ke jalur file kunci akun layanan
• Lihat Configure GCP credentials untuk semua opsi

Jika Anda mengalami masalah kuota:

• Periksa kuota saat ini atau minta peningkatan kuota melalui Cloud Console

Jika Anda mengalami kesalahan "model not found" 404:

• Konfirmasi model diaktifkan di Model Garden
• Verifikasi model tersedia di lokasi yang Anda tentukan. Beberapa model hanya ditawarkan di lokasi global atau multi-region seperti eu dan us, bukan di wilayah spesifik
• Jika menggunakan CLOUD_ML_REGION=global, periksa bahwa model Anda mendukung titik akhir global di Model Garden di bawah "Supported features". Untuk model yang tidak mendukung titik akhir global, baik:
  • Tentukan model yang didukung melalui ANTHROPIC_MODEL atau ANTHROPIC_DEFAULT_HAIKU_MODEL, atau
  • Atur wilayah atau lokasi multi-region menggunakan variabel lingkungan VERTEX_REGION_<MODEL_NAME>

Jika Anda mengalami kesalahan 429:

• Untuk titik akhir regional, pastikan model utama dan model kecil/cepat didukung di wilayah yang Anda pilih
• Pertimbangkan untuk beralih ke CLOUD_ML_REGION=global untuk ketersediaan yang lebih baik

Sumber daya tambahan

• Dokumentasi Google Cloud's Agent Platform
• Harga Google Cloud's Agent Platform
• Kuota dan batas Google Cloud's Agent Platform