Claude Code su Google Cloud's Agent Platform

​

Prerequisiti

• Un account Google Cloud Platform (GCP) con fatturazione abilitata
• Un progetto GCP con Google Cloud’s Agent Platform API abilitata
• Accesso ai modelli Claude desiderati (ad esempio, Claude Sonnet 4.6)
• Google Cloud SDK (gcloud) installato e configurato
• Quota allocata nella regione GCP desiderata

​

Accedi con Agent Platform

​

Configurazione della regione

​

Configurazione manuale

​

1. Abilita Agent Platform API

# 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

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

​

Configurazione avanzata delle credenziali

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

​

4. Configura Claude Code

# 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

# 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

• VERTEX_REGION_CLAUDE_*: Claude Code ritorna a CLOUD_ML_REGION.
• CLOUD_ML_REGION: Claude Code ritorna a us-east5.

• Claude Opus 4.5, Sonnet 4.5, Haiku 4.5 e versioni successive: Claude Code abilita la ricerca degli strumenti per impostazione predefinita.
• Modelli precedenti, inclusi tutti i modelli Claude 3.x: Claude Code carica le definizioni degli strumenti MCP in anticipo, perché i loro stack di servizio Agent Platform rifiutano l’intestazione beta richiesta. L’impostazione di ENABLE_TOOL_SEARCH=true non esegue l’override di questo.

​

5. Fissa le versioni del modello

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'

• Quando selezioni un modello primario con --model, ANTHROPIC_MODEL, o l’impostazione model, le attività in background utilizzano quel modello. Quando Claude Code avvia la sessione sul modello che hai impostato con ANTHROPIC_DEFAULT_MODEL, le attività in background utilizzano quel modello anche. L’impostazione di ANTHROPIC_DEFAULT_OPUS_MODEL senza ANTHROPIC_DEFAULT_SONNET_MODEL conta anche come una selezione, perché il modello Sonnet integrato potrebbe non essere abilitato in un progetto che indirizza il suo Opus.
• Per utilizzare Haiku per le attività in background, imposta ANTHROPIC_DEFAULT_HAIKU_MODEL su un ID modello disponibile nel tuo progetto.

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

​

6. Verifica la tua configurazione

​

Controlli del modello all’avvio

​

Configurazione IAM

• aiplatform.endpoints.predict - Richiesto per l’invocazione del modello e il conteggio dei token

​

Finestra di contesto da 1M token

​

Risoluzione dei problemi

• Esegui gcloud auth application-default login per configurare le credenziali predefinite dell’applicazione
• Imposta GOOGLE_APPLICATION_CREDENTIALS su un percorso di file della chiave dell’account di servizio
• Vedi Configure GCP credentials per tutte le opzioni

• Controlla le quote attuali o richiedi un aumento della quota tramite Cloud Console

• Conferma che il modello è abilitato in Model Garden
• Verifica che il modello sia disponibile nella posizione che hai specificato. Alcuni modelli sono offerti solo su posizioni global o multi-regione come eu e us, non in regioni specifiche
• Se utilizzi CLOUD_ML_REGION=global, controlla che i tuoi modelli supportino endpoint globali in Model Garden in “Supported features”. Per i modelli che non supportano endpoint globali, puoi:
  • Specificare un modello supportato tramite ANTHROPIC_MODEL o ANTHROPIC_DEFAULT_HAIKU_MODEL, oppure
  • Impostare una regione o una posizione multi-regione utilizzando le variabili di ambiente VERTEX_REGION_<MODEL_NAME>

• Per gli endpoint regionali, assicurati che il modello primario e il modello piccolo/veloce siano supportati nella tua regione selezionata
• Considera di passare a CLOUD_ML_REGION=global per una migliore disponibilità

​

Risorse aggiuntive

• Documentazione di Google Cloud’s Agent Platform
• Prezzi di Google Cloud’s Agent Platform
• Quote e limiti di Google Cloud’s Agent Platform