SpyBara
Go Premium

google-vertex-ai.md 2026-07-09 23:58 UTC to 2026-07-10 17:00 UTC

38 added, 38 removed.

2026
Fri 31 22:02 Wed 29 19:02 Tue 28 23:57 Mon 27 21:02 Sun 26 19:02 Sat 25 21:59 Fri 24 23:01 Thu 23 23:57 Wed 22 23:59 Tue 21 23:00 Mon 20 23:01 Sat 18 16:02 Fri 17 22:57 Thu 16 22:59 Wed 15 22:00 Tue 14 23:01 Mon 13 23:57 Sat 11 19:03 Fri 10 17:00 Thu 9 23:58 Wed 8 16:02 Tue 7 16:02 Mon 6 23:57 Sat 4 03:01 Fri 3 23:00 Thu 2 23:59 Wed 1 21:01

Claude Code su Google Cloud's Agent Platform

Scopri come configurare Claude Code tramite Google Cloud's Agent Platform, precedentemente Vertex AI, inclusa la configurazione, la configurazione IAM e la risoluzione dei problemi.

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()}
; };

Prerequisiti

Prima di configurare Claude Code con Google Cloud's Agent Platform di Google Cloud, precedentemente noto come Vertex AI, assicurati di avere:

Per accedere con le tue credenziali Google Cloud's Agent Platform, segui Accedi con Google Cloud's Agent Platform di seguito. Per distribuire Claude Code in un team, utilizza i passaggi di configurazione manuale e fissa le versioni del tuo modello prima del rollout.

Accedi con Agent Platform

Se hai credenziali Google Cloud e desideri iniziare a utilizzare Claude Code tramite Google Cloud's Agent Platform, la procedura guidata di accesso ti guida attraverso i passaggi. Completi i prerequisiti lato GCP una volta per progetto; la procedura guidata gestisce il lato Claude Code.

1

Abilita i modelli Claude nel tuo progetto GCP

Abilita Google Cloud's Agent Platform API per il tuo progetto, quindi richiedi accesso ai modelli Claude che desideri in Google Cloud's Agent Platform Model Garden. Consulta Configurazione IAM per le autorizzazioni di cui il tuo account ha bisogno.

2

Avvia Claude Code e scegli Google Cloud's Agent Platform

Esegui claude. Al prompt di accesso, seleziona 3rd-party platform, quindi Google Vertex AI, l'etichetta che il prompt di accesso utilizza ancora per Google Cloud's Agent Platform.

3

Segui i prompt della procedura guidata

Scegli come autenticarti a Google Cloud: Application Default Credentials da gcloud, un file di chiave dell'account di servizio, o credenziali già presenti nel tuo ambiente. La procedura guidata rileva il tuo progetto e la tua regione, verifica quali modelli Claude il tuo progetto può invocare, e ti consente di fissarli. Salva il risultato nel blocco env del tuo file di impostazioni utente, quindi non è necessario esportare variabili di ambiente da solo.

Dopo aver effettuato l'accesso, esegui /setup-vertex in qualsiasi momento per riaprire la procedura guidata e modificare le tue credenziali, progetto, regione o fissaggi di modello.

Configurazione della regione

Claude Code supporta endpoint di Google Cloud's Agent Platform globali, multi-regione e regionali. Imposta CLOUD_ML_REGION su global, una posizione multi-regione come eu o us, o una regione specifica come us-east5. Claude Code seleziona il nome host corretto di Google Cloud's Agent Platform per ogni modulo, inclusi gli host aiplatform.eu.rep.googleapis.com e aiplatform.us.rep.googleapis.com per le posizioni multi-regione.

Configurazione manuale

Per configurare Google Cloud's Agent Platform tramite variabili di ambiente invece della procedura guidata, ad esempio in CI o in un rollout aziendale con script, segui i passaggi di seguito.

1. Abilita Agent Platform API

Abilita Google Cloud's Agent Platform API nel tuo progetto GCP:

# Imposta il tuo ID progetto
gcloud config set project YOUR-PROJECT-ID

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

2. Richiedi accesso al modello

Richiedi accesso ai modelli Claude in Google Cloud's Agent Platform:

  1. Accedi a Google Cloud's Agent Platform Model Garden
  2. Cerca i modelli "Claude"
  3. Richiedi accesso ai modelli Claude desiderati (ad esempio, Claude Sonnet 4.6)
  4. Attendi l'approvazione (potrebbe richiedere 24-48 ore)

3) Configura le credenziali GCP

Claude Code utilizza l'autenticazione standard di Google Cloud.

Per ulteriori informazioni, consulta la documentazione di autenticazione di Google Cloud.

Claude Code v2.1.121 o versioni successive supporta X.509 certificate-based Workload Identity Federation attraverso la stessa catena Application Default Credentials. Imposta GOOGLE_APPLICATION_CREDENTIALS al percorso del tuo file di configurazione delle credenziali.

Configurazione avanzata delle credenziali

Claude Code supporta l'aggiornamento automatico delle credenziali GCP tramite l'impostazione gcpAuthRefresh. Quando Claude Code rileva che le tue credenziali GCP sono scadute o non possono essere caricate, esegue il comando configurato per ottenere nuove credenziali prima di riprovare la richiesta.

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

L'output del comando viene visualizzato all'utente, ma l'input interattivo non è supportato. Questo funziona bene per i flussi di autenticazione basati su browser in cui la CLI mostra un URL e completi l'autenticazione nel browser. Il comando di aggiornamento scade dopo tre minuti se l'autenticazione non viene completata. Se imposti gcpAuthRefresh nelle impostazioni del progetto come .claude/settings.json, il comando viene eseguito solo dopo che accetti il prompt di fiducia dell'area di lavoro.

4. Configura Claude Code

Imposta le seguenti variabili di ambiente:

# Abilita integrazione Agent Platform
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

# Facoltativo: Esegui l'override dell'URL dell'endpoint Agent Platform per endpoint personalizzati o gateway
# export ANTHROPIC_VERTEX_BASE_URL=https://aiplatform.googleapis.com

# Facoltativo: Disabilita prompt caching se necessario
export DISABLE_PROMPT_CACHING=1

# Facoltativo: Richiedi TTL cache prompt di 1 ora invece del valore predefinito di 5 minuti
export ENABLE_PROMPT_CACHING_1H=1

# Quando CLOUD_ML_REGION=global, esegui l'override della regione per i modelli che non supportano endpoint globali
export VERTEX_REGION_CLAUDE_HAIKU_4_5=us-east5
export VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1

La maggior parte delle versioni del modello ha una variabile VERTEX_REGION_CLAUDE_* corrispondente. Consulta il riferimento delle variabili di ambiente per l'elenco completo. Controlla Google Cloud's Agent Platform Model Garden per determinare quali modelli supportano endpoint globali rispetto a quelli solo regionali.

Prompt caching è abilitato automaticamente. Per disabilitarlo, imposta DISABLE_PROMPT_CACHING=1. Per richiedere un TTL cache di 1 ora invece del valore predefinito di 5 minuti, imposta ENABLE_PROMPT_CACHING_1H=1; le scritture della cache con TTL di 1 ora vengono fatturate a una tariffa più elevata. Per limiti di velocità aumentati, contatta il supporto di Google Cloud. Quando utilizzi Google Cloud's Agent Platform, il comando /logout non è disponibile poiché l'autenticazione è gestita tramite le credenziali di Google Cloud.

Claude Code disabilita MCP tool search per impostazione predefinita su Google Cloud's Agent Platform, quindi le definizioni degli strumenti MCP vengono caricate in anticipo. Google Cloud's Agent Platform supporta la ricerca degli strumenti per Claude Sonnet 4.5 e versioni successive e Claude Opus 4.5 e versioni successive. Imposta ENABLE_TOOL_SEARCH=true per abilitarla su questi modelli. I modelli precedenti su Google Cloud's Agent Platform non accettano l'intestazione beta richiesta e le richieste non riescono se abiliti la ricerca degli strumenti con essi.

5. Fissa le versioni del modello

Imposta queste variabili di ambiente su ID modello Google Cloud's Agent Platform specifici.

Senza ANTHROPIC_DEFAULT_OPUS_MODEL, l'alias opus su Google Cloud's Agent Platform si risolve in Opus 4.6. Impostalo sull'ID di Opus 4.8 per utilizzare il modello più recente:

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'

Per gli ID modello attuali e legacy, consulta Panoramica dei modelli. Consulta Configurazione del modello per l'elenco completo delle variabili di ambiente.

Claude Code utilizza questi modelli predefiniti quando nessuna variabile di fissaggio è impostata:

Tipo di modello Valore predefinito
Modello primario claude-sonnet-4-5@20250929
Modello piccolo/veloce Uguale al modello primario

Le attività in background come la generazione del titolo della sessione utilizzano il modello piccolo/veloce, normalmente un modello della classe Haiku. Su Google Cloud's Agent Platform, Claude Code imposta per impostazione predefinita questo al modello primario perché Haiku potrebbe non essere abilitato in ogni progetto o regione. Per utilizzare Haiku per le attività in background, imposta ANTHROPIC_DEFAULT_HAIKU_MODEL su un ID modello disponibile nel tuo progetto.

Per personalizzare ulteriormente i modelli:

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

Controlli del modello all'avvio

Quando Claude Code si avvia con Google Cloud's Agent Platform configurato, verifica che i modelli che intende utilizzare siano accessibili nel tuo progetto. Questo controllo richiede Claude Code v2.1.98 o versione successiva.

Se hai fissato una versione del modello più vecchia del valore predefinito corrente di Claude Code, e il tuo progetto può invocare la versione più recente, Claude Code ti chiede di aggiornare il fissaggio. Accettare scrive il nuovo ID modello nel tuo file di impostazioni utente e riavvia Claude Code. Rifiutare viene ricordato fino al prossimo cambio di versione predefinita.

Se non hai fissato un modello e il valore predefinito corrente non è disponibile nel tuo progetto, Claude Code ritorna alla versione precedente per la sessione corrente e mostra un avviso. Il ritorno non è persistente. Abilita il modello più recente in Model Garden o fissa una versione per rendere la scelta permanente.

Configurazione IAM

Assegna le autorizzazioni IAM richieste:

Il ruolo roles/aiplatform.user include le autorizzazioni richieste:

Per autorizzazioni più restrittive, crea un ruolo personalizzato con solo le autorizzazioni di cui sopra.

Per i dettagli, consulta la documentazione IAM di Google Cloud Vertex AI.

Finestra di contesto da 1M token

Claude Sonnet 5, Opus 4.6 e versioni successive, e Sonnet 4.6 supportano la finestra di contesto da 1M token su Google Cloud's Agent Platform. Sonnet 5 funziona sempre con la finestra da 1M, senza alcuna variante [1m] da selezionare. Per gli altri modelli, Claude Code abilita automaticamente la finestra di contesto estesa quando selezioni una variante di modello 1M.

La procedura guidata di configurazione offre un'opzione di contesto 1M quando fissa i modelli. Per abilitarla per un modello fissato manualmente, aggiungi [1m] all'ID del modello. Consulta Fissa i modelli per le distribuzioni di terze parti per i dettagli.

Risoluzione dei problemi

Se riscontri errori "Could not load the default credentials":

Se riscontri problemi di quota:

Se riscontri errori "model not found" 404:

Se riscontri errori 429:

Risorse aggiuntive