SpyBara
Go Premium

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

9 added, 9 removed.

2026
Tue 4 01:59 Mon 3 20:02 Sun 2 19:00

Claude Code sur la Plateforme Agent de Google Cloud

Découvrez comment configurer Claude Code via la Plateforme Agent de Google Cloud, anciennement Vertex AI, y compris la configuration, la configuration IAM et la résolution des problèmes.

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

Conditions préalables

Avant de configurer Claude Code avec Google Cloud's Agent Platform, anciennement Vertex AI, assurez-vous que vous disposez de :

Pour vous connecter avec vos propres identifiants Google Cloud's Agent Platform, suivez Se connecter avec Google Cloud's Agent Platform ci-dessous. Pour déployer Claude Code dans une équipe, utilisez les étapes de configuration manuelle et épinglez vos versions de modèle avant le déploiement.

Se connecter avec Agent Platform

Si vous disposez d'identifiants Google Cloud et souhaitez commencer à utiliser Claude Code via Agent Platform de Google Cloud, l'assistant de connexion vous guide à travers le processus. Vous complétez les conditions préalables du côté GCP une fois par projet ; l'assistant gère le côté Claude Code.

1

Activer les modèles Claude dans votre projet GCP

Activez l'API Agent Platform de Google Cloud pour votre projet, puis demandez l'accès aux modèles Claude que vous souhaitez dans le Model Garden d'Agent Platform de Google Cloud. Consultez Configuration IAM pour les autorisations dont votre compte a besoin.

2

Démarrer Claude Code et choisir Agent Platform de Google Cloud

Exécutez claude. À l'invite de connexion, sélectionnez plateforme tierce, puis Google Vertex AI, l'étiquette que l'invite de connexion utilise toujours pour Agent Platform de Google Cloud.

3

Suivre les invites de l'assistant

Choisissez comment vous vous authentifiez auprès de Google Cloud : identifiants par défaut de l'application à partir de gcloud, fichier de clé de compte de service, ou identifiants déjà dans votre environnement. L'assistant détecte votre projet et votre région, vérifie quels modèles Claude votre projet peut invoquer, et vous permet de les épingler. Il enregistre le résultat dans le bloc env de votre fichier de paramètres utilisateur, vous n'avez donc pas besoin d'exporter les variables d'environnement vous-même.

Après vous être connecté, exécutez /setup-vertex à tout moment pour rouvrir l'assistant et modifier vos identifiants, votre projet, votre région ou vos épingles de modèle. L'étape d'épinglage du modèle commence à partir de vos modèles actuellement épinglés. L'assistant écrit dans ~/.claude/settings.json, ou dans $CLAUDE_CONFIG_DIR/settings.json lorsque CLAUDE_CONFIG_DIR est défini.

Configuration de la région

Claude Code prend en charge les points de terminaison Google Cloud's Agent Platform globaux, multi-régions et régionaux. Définissez CLOUD_ML_REGION sur global, un emplacement multi-région tel que eu ou us, ou une région spécifique telle que us-east5. Claude Code sélectionne le nom d'hôte Google Cloud's Agent Platform correct pour chaque formulaire, y compris les hôtes aiplatform.eu.rep.googleapis.com et aiplatform.us.rep.googleapis.com pour les emplacements multi-régions.

Configuration manuelle

Pour configurer Google Cloud's Agent Platform via des variables d'environnement au lieu de l'assistant, par exemple dans CI ou un déploiement d'entreprise scriptée, suivez les étapes ci-dessous.

1. Activer l'API Agent Platform

Activez l'API Agent Platform de Google Cloud dans votre projet GCP :

# Définissez votre ID de projet
gcloud config set project YOUR-PROJECT-ID

# Activez l'API Agent Platform
gcloud services enable aiplatform.googleapis.com

2. Demander l'accès au modèle

Demandez l'accès aux modèles Claude dans Google Cloud's Agent Platform :

  1. Accédez au Google Cloud's Agent Platform Model Garden
  2. Recherchez les modèles ' Claude '
  3. Demandez l'accès aux modèles Claude souhaités (par exemple, Claude Sonnet 4.6)
  4. Attendez l'approbation (peut prendre 24 à 48 heures)

3) Configurer les identifiants GCP

Claude Code utilise l'authentification Google Cloud standard.

Pour plus d'informations, consultez la documentation d'authentification Google Cloud.

Claude Code v2.1.121 ou version ultérieure prend en charge la Fédération d'identité de charge de travail basée sur certificat X.509 via la même chaîne Application Default Credentials. Définissez GOOGLE_APPLICATION_CREDENTIALS sur le chemin de votre fichier de configuration des identifiants.

Configuration avancée des identifiants

Claude Code prend en charge l'actualisation automatique des identifiants GCP via le paramètre gcpAuthRefresh. Lorsque Claude Code détecte que vos identifiants GCP ont expiré ou ne peuvent pas être chargés, il exécute la commande configurée pour obtenir de nouveaux identifiants avant de réessayer la demande.

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

La sortie de la commande s'affiche à l'utilisateur, mais l'entrée interactive n'est pas prise en charge. Cela fonctionne bien pour les flux d'authentification basés sur navigateur où l'interface de ligne de commande affiche une URL et vous complétez l'authentification dans le navigateur. La commande d'actualisation expire après trois minutes si l'authentification ne se termine pas. Si vous définissez gcpAuthRefresh dans les paramètres du projet tels que .claude/settings.json, la commande s'exécute uniquement après que vous ayez accepté l'invite de confiance de l'espace de travail.

4. Configurer Claude Code

Définissez les variables d'environnement suivantes :

# Activez l'intégration Agent Platform
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

# Optionnel : Remplacez l'URL du point de terminaison Agent Platform pour les points de terminaison personnalisés ou les passerelles
# export ANTHROPIC_VERTEX_BASE_URL=https://aiplatform.googleapis.com

# Optionnel : Désactivez la mise en cache des invites si nécessaire
export DISABLE_PROMPT_CACHING=1

# Optionnel : Demandez une TTL de cache d'invites d'1 heure au lieu de la valeur par défaut de 5 minutes
export ENABLE_PROMPT_CACHING_1H=1

# Quand CLOUD_ML_REGION=global, remplacez la région pour les modèles qui ne prennent pas en charge les points de terminaison globaux
export VERTEX_REGION_CLAUDE_HAIKU_4_5=us-east5
export VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1

La plupart des versions de modèle ont une variable VERTEX_REGION_CLAUDE_* correspondante. Consultez la référence des variables d'environnement pour la liste complète. Vérifiez Google Cloud's Agent Platform Model Garden pour déterminer quels modèles prennent en charge les points de terminaison globaux par rapport aux points de terminaison régionaux uniquement.

La mise en cache des invites est activée automatiquement. Pour la désactiver, définissez DISABLE_PROMPT_CACHING=1. Pour demander une TTL de cache d'1 heure au lieu de la valeur par défaut de 5 minutes, définissez ENABLE_PROMPT_CACHING_1H=1 ; les écritures de cache avec une TTL d'1 heure sont facturées à un taux plus élevé. Pour des limites de débit accrues, contactez le support Google Cloud. Lors de l'utilisation de Google Cloud's Agent Platform, la commande /logout est indisponible car l'authentification est gérée via les identifiants Google Cloud.

Claude Code désactive la recherche d'outils MCP par défaut sur Google Cloud's Agent Platform, de sorte que les définitions d'outils MCP se chargent à l'avance. Google Cloud's Agent Platform prend en charge la recherche d'outils pour Claude Sonnet 4.5 et versions ultérieures et Claude Opus 4.5 et versions ultérieures. Définissez ENABLE_TOOL_SEARCH=true pour l'activer sur ces modèles. Les modèles antérieurs sur Google Cloud's Agent Platform n'acceptent pas l'en-tête bêta requis, et les demandes échouent si vous activez la recherche d'outils avec eux.

5. Épingler les versions de modèle

Définissez ces variables d'environnement sur des ID de modèle Google Cloud's Agent Platform spécifiques.

Sans ANTHROPIC_DEFAULT_OPUS_MODEL, l'alias opus sur Google Cloud's Agent Platform se résout à Opus 4.8, et sans ANTHROPIC_DEFAULT_SONNET_MODEL, l'alias sonnet se résout à Sonnet 4.5. Cet exemple épingle chaque alias à une version spécifique :

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'

Pour les ID de modèle actuels et hérités, consultez Aperçu des modèles. Consultez Configuration du modèle pour la liste complète des variables d'environnement.

Claude Code utilise ces modèles par défaut lorsqu'aucune variable d'épinglage n'est définie :

Type de modèle Valeur par défaut
Modèle principal claude-opus-4-8
Modèle petit/rapide claude-sonnet-4-5@20250929

Les tâches en arrière-plan telles que la génération de titre de session utilisent le modèle petit/rapide, normalement un modèle de classe Haiku. Sur Google Cloud's Agent Platform, Claude Code utilise le modèle Sonnet par défaut pour les tâches en arrière-plan car Haiku peut ne pas être activé dans tous les projets ou régions. Deux sélections changent le modèle qui les exécute :

Avant v2.1.207, le modèle principal sur Google Cloud's Agent Platform était par défaut Sonnet 4.5, l'alias opus se résolvait à Opus 4.6, et les tâches en arrière-plan utilisaient toujours le modèle principal.

Pour personnaliser davantage les modèles :

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

Vérifications du modèle au démarrage

Lorsque Claude Code démarre avec Google Cloud's Agent Platform configuré, il vérifie que les modèles qu'il a l'intention d'utiliser sont accessibles dans votre projet.

Si vous avez épinglé une version de modèle plus ancienne que la valeur par défaut actuelle de Claude Code, et que votre projet peut invoquer la version plus récente, Claude Code vous invite à mettre à jour l'épingle. L'acceptation écrit le nouvel ID de modèle dans votre fichier de paramètres utilisateur et redémarre Claude Code. Le refus est mémorisé jusqu'au prochain changement de version par défaut.

Si vous n'avez pas épinglé un modèle et que la valeur par défaut actuelle n'est pas disponible dans votre projet, Claude Code revient à la version précédente pour la session actuelle et affiche un avis. Il essaie d'abord les versions antérieures du modèle par défaut et, lorsque la valeur par défaut est un modèle Opus et qu'aucune version Opus n'est disponible, revient au modèle Sonnet par défaut. Le retour n'est pas persistant. Activez le modèle plus récent dans Model Garden ou épinglez une version pour rendre le choix permanent.

Configuration IAM

Attribuez les autorisations IAM requises :

Le rôle roles/aiplatform.user inclut les autorisations requises :

Pour des autorisations plus restrictives, créez un rôle personnalisé avec uniquement les autorisations ci-dessus.

Pour plus de détails, consultez la documentation IAM de Google Cloud Vertex AI.

Fenêtre de contexte de 1M de jetons

Claude Sonnet 5, Opus 4.6 et versions ultérieures, ainsi que Sonnet 4.6, prennent en charge la fenêtre de contexte de 1M de jetons sur la plateforme Agent de Google Cloud. Sonnet 5 s'exécute toujours avec la fenêtre 1M, sans variante [1m] à sélectionner. Pour les autres modèles, Claude Code active automatiquement la fenêtre de contexte étendue lorsque vous sélectionnez une variante de modèle 1M.

L'assistant de configuration offre une option de contexte 1M lorsqu'il épingle les modèles. Pour l'activer pour un modèle épinglé manuellement à la place, ajoutez [1m] à l'ID du modèle. Consultez Épingler les modèles pour les déploiements tiers pour plus de détails.

Résolution des problèmes

Si vous rencontrez des erreurs « Impossible de charger les identifiants par défaut » :

Si vous rencontrez des problèmes de quota :

Si vous rencontrez des erreurs « modèle non trouvé » 404 :

Si vous rencontrez des erreurs 429 :

Ressources supplémentaires