SpyBara
Go Premium

google-vertex-ai.md 2026-08-03 20:02 UTC to 2026-08-04 22:59 UTC

9 added, 9 removed.

2026
Wed 5 19:57 Tue 4 22:59 Mon 3 20:02 Sun 2 19:00

Claude Code di Platform Agen Google Cloud

Pelajari tentang mengonfigurasi Claude Code melalui Platform Agen Google Cloud, yang sebelumnya bernama Vertex AI, termasuk pengaturan, konfigurasi IAM, dan pemecahan masalah.

export const ContactSalesCard = ({surface}) => { const utm = content => utm_source=claude_code&utm_medium=docs&utm_content=${surface}_${content}; const iconArrowRight = (size = 13) => <svg width={size} height={size} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true"> ; const STYLES = .cc-cs { --cs-slate: #141413; --cs-clay: #d97757; --cs-clay-deep: #c6613f; --cs-gray-000: #ffffff; --cs-gray-700: #3d3d3a; --cs-border-default: rgba(31, 30, 29, 0.15); font-family: inherit; } .dark .cc-cs { --cs-slate: #f0eee6; --cs-gray-000: #262624; --cs-gray-700: #bfbdb4; --cs-border-default: rgba(240, 238, 230, 0.14); } .cc-cs-card { display: flex; align-items: center; justify-content: space-between; gap: 16px; padding: 14px 16px; margin: 0; background: var(--cs-gray-000); border: 0.5px solid var(--cs-border-default); border-radius: 8px; flex-wrap: wrap; } .cc-cs-text { font-size: 13px; color: var(--cs-gray-700); line-height: 1.5; flex: 1; min-width: 240px; } .cc-cs-text strong { font-weight: 550; color: var(--cs-slate); } .cc-cs-actions { display: flex; align-items: center; gap: 8px; flex-shrink: 0; } .cc-cs-btn-clay { display: inline-flex; align-items: center; gap: 8px; background: var(--cs-clay-deep); color: #fff; border: none; border-radius: 8px; padding: 8px 14px; font-size: 13px; font-weight: 500; transition: background-color 0.15s; white-space: nowrap; } .cc-cs-btn-clay:hover { background: var(--cs-clay); } .cc-cs-btn-ghost { display: inline-flex; align-items: center; gap: 8px; background: transparent; color: var(--cs-gray-700); border: 0.5px solid var(--cs-border-default); border-radius: 8px; padding: 8px 14px; font-size: 13px; font-weight: 500; } .cc-cs-btn-ghost:hover { background: rgba(0, 0, 0, 0.04); } .dark .cc-cs-btn-ghost:hover { background: rgba(255, 255, 255, 0.04); } @media (max-width: 720px) { .cc-cs-actions { width: 100%; } }; return <div className="cc-cs not-prose"> <div className="cc-cs-card"> <div className="cc-cs-text"> Deploying Claude Code across your organization? Talk to sales about enterprise plans, SSO, and centralized billing.

<div className="cc-cs-actions"> <a href={https://claude.com/pricing?${utm('view_plans')}#plans-business} className="cc-cs-btn-ghost"> View plans <a href={https://claude.com/contact-sales?${utm('contact_sales')}} className="cc-cs-btn-clay"> Contact sales {iconArrowRight()}
; };

Prasyarat

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

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.

1

Aktifkan model Claude di proyek GCP Anda

Aktifkan API Agent Platform Google Cloud untuk proyek Anda, kemudian minta akses ke model Claude yang Anda inginkan di Model Garden Agent Platform Google Cloud. Lihat konfigurasi IAM untuk izin yang akun Anda butuhkan.

2

Mulai Claude Code dan pilih Agent Platform Google Cloud

Jalankan claude. Pada prompt login, pilih 3rd-party platform, kemudian Google Vertex AI, label yang masih digunakan prompt login untuk Agent Platform Google Cloud.

3

Ikuti prompt wizard

Pilih cara Anda melakukan autentikasi ke Google Cloud: Application Default Credentials dari gcloud, file kunci akun layanan, atau kredensial yang sudah ada di lingkungan Anda. Wizard mendeteksi proyek dan wilayah Anda, memverifikasi model Claude mana yang dapat dijalankan proyek Anda, dan memungkinkan Anda untuk mempinnya. Ini menyimpan hasilnya ke blok env dari file pengaturan pengguna Anda, jadi Anda tidak perlu mengekspor variabel lingkungan sendiri.

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:

# 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 v2.1.121 atau lebih baru 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. 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"
  }
}

Output perintah ditampilkan kepada pengguna, tetapi input interaktif tidak didukung. 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, perintah hanya berjalan setelah Anda menerima prompt kepercayaan ruang kerja.

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

# Opsional: Nonaktifkan prompt caching jika diperlukan
export DISABLE_PROMPT_CACHING=1

# Opsional: Minta TTL cache prompt 1 jam alih-alih default 5 menit
export ENABLE_PROMPT_CACHING_1H=1

# 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.

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 batas laju yang lebih tinggi, hubungi dukungan Google Cloud. Saat menggunakan Google Cloud's Agent Platform, perintah /logout tidak tersedia karena autentikasi ditangani melalui kredensial Google Cloud.

Claude Code menonaktifkan pencarian alat MCP secara default di Google Cloud's Agent Platform, sehingga definisi alat MCP dimuat di muka. Google Cloud's Agent Platform mendukung pencarian alat untuk Claude Sonnet 4.5 dan lebih baru serta Claude Opus 4.5 dan lebih baru. Atur ENABLE_TOOL_SEARCH=true untuk mengaktifkannya pada model tersebut. Model sebelumnya di Google Cloud's Agent Platform tidak menerima header beta yang diperlukan, dan permintaan gagal jika Anda mengaktifkan pencarian alat dengan model tersebut.

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 4.8, 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:

Jenis model Nilai default
Model utama claude-opus-4-8
Model kecil/cepat claude-sonnet-4-5@20250929

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:

Sebelum v2.1.207, model utama di Google Cloud's Agent Platform 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'

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.

Konfigurasi IAM

Tetapkan izin IAM yang diperlukan:

Peran roles/aiplatform.user mencakup izin yang diperlukan:

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

Untuk detail, lihat dokumentasi IAM Platform Agent 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":

Jika Anda mengalami masalah kuota:

Jika Anda mengalami kesalahan "model not found" 404:

Jika Anda mengalami kesalahan 429:

Sumber daya tambahan