Claude Agent SDK en Europe : Bedrock et Vertex AI

TL;DR

Le Claude Agent SDK intègre la boucle d’agent de Claude Code dans votre propre service Python ou TypeScript. Pour héberger les données dans l’UE, évitez l’API Anthropic directe : activez CLAUDE_CODE_USE_BEDROCK=1 avec un profil d’inférence eu. depuis Francfort, ou CLAUDE_CODE_USE_VERTEX=1 avec CLOUD_ML_REGION=eu. Épinglez le modèle, isolez le conteneur, budgétez les tokens.

Qu’est-ce que le Claude Agent SDK, et pourquoi le fournisseur compte-t-il ?

Le Claude Agent SDK est une bibliothèque qui intègre les outils, la boucle d’agent, les permissions, les sessions et les hooks de Claude Code dans une application que vous exploitez vous-même. Le fournisseur du modèle est un choix distinct. Par défaut, le SDK appelle api.anthropic.com. Deux variables d’environnement le redirigent vers Amazon Bedrock ou Google Cloud, où vous choisissez un routage européen.

La présentation de l’Agent SDK le décrit comme “Claude Code as a library”. Il existe en Python (claude-agent-sdk) et en TypeScript (@anthropic-ai/claude-agent-sdk). Il faut Python 3.10 ou plus récent, ou Node.js 18 ou plus récent. Les deux paquets embarquent un binaire Claude Code natif : la version de la CLI suit donc celle du SDK. À la date de rédaction, le changelog Python affiche la version 0.2.163 avec la CLI 2.1.286, le changelog TypeScript la version 0.3.287, alignée sur Claude Code v2.1.287.

L’architecture conditionne tout le reste. Chaque appel à query() lance un sous-processus claude qui dialogue avec votre code via stdio et possède un shell, un répertoire de travail et des transcriptions JSONL sur le disque local. Ce n’est pas un simple wrapper d’API sans état, mais un processus durable avec des fichiers.

Trois points avant de choisir un fournisseur :

• Pas de connexion par abonnement. Sauf accord préalable, Anthropic n’autorise pas les produits tiers bâtis sur le SDK à proposer la connexion claude.ai ni les limites de débit des abonnements. Les agents en production s’authentifient par clé API ou par identifiants cloud.
• Managed Agents n’existe pas sur les clouds. L’alternative hébergée d’Anthropic, Claude Managed Agents, est indiquée comme non prise en charge sur Bedrock et sur Google Cloud. Si votre stratégie d’hébergement des données passe par Bedrock ou Vertex, vous hébergez le SDK vous-même.
• Même agent, autre point de terminaison. La documentation du SDK indique que le trafic HTTPS sortant va vers api.anthropic.com ou vers le point de terminaison régional du fournisseur sur Bedrock ou Google Cloud.

Nous recommandons Bedrock ou Vertex plutôt que l’API directe dès qu’un agent traite des données personnelles ou du code source inscrit au registre des traitements. Le contrat, le contrôle de la région et la facturation se trouvent alors dans un compte cloud que vous gouvernez déjà. Pour la comparaison générale des fournisseurs, consultez notre guide Claude sur AWS Bedrock en Europe.

Comment brancher l’Agent SDK sur Bedrock dans l’UE ?

Définissez CLAUDE_CODE_USE_BEDROCK=1, fournissez des identifiants AWS au processus et fixez AWS_REGION sur une région européenne comme eu-central-1 (Francfort) ou eu-west-3 (Paris). Claude Code associe toute région eu-* au préfixe eu. des profils d’inférence interrégionaux. Épinglez ensuite le modèle, car la valeur par défaut évolue avec les versions du SDK et pointe aujourd’hui vers Opus 5.5.

Le guide Bedrock décrit l’ordre de résolution de la région : AWS_REGION, puis AWS_DEFAULT_REGION, puis le profil AWS actif, et enfin un repli sur us-east-1. Cette dernière étape est le piège. Un conteneur sans variable de région ni fichier de configuration AWS finit aux États-Unis. Les identifiants proviennent de la chaîne standard du SDK AWS : rôle d’instance ou de tâche, profil SSO, clés d’accès, ou clé API Bedrock dans AWS_BEARER_TOKEN_BEDROCK.

Les identifiants de profils UE à épingler aujourd’hui :

Modèle	Profil UE Bedrock	Ce qu’en dit AWS	Option mono-région
Claude Sonnet 5	eu.anthropic.claude-sonnet-5	Conserve les données dans les régions de l’UE	bedrock-mantle en eu-north-1 ou eu-west-1
Claude Opus 5.5	eu.anthropic.claude-opus-5-5	Conserve les données dans les régions de l’UE	Aucune région UE sur bedrock-mantle
Les deux, préfixe global.	global.anthropic.claude-...	Routage mondial, sans contrainte de résidence	Sans objet

La fiche modèle d’Opus 5.5 indique une date de lancement au 22 septembre 2026, une fenêtre de contexte de 1 million de tokens et 128 000 tokens en sortie. Pour les deux modèles, Francfort et Paris figurent parmi les régions sources du profil géographique UE. AWS précise aussi que les profils interrégionaux peuvent router vers des régions opt-in que vous n’avez pas activées, où les prompts peuvent être stockés pour la détection des abus. Avec le profil UE, cela reste dans l’UE. Votre registre des traitements doit pourtant mentionner “régions de l’UE”, pas “Francfort”.

Un agent Python minimal sur Bedrock, en lecture seule et borné :

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

async def main():
    options = ClaudeAgentOptions(
        cwd="/work/session-a",
        allowed_tools=["Read", "Glob", "Grep"],
        permission_mode="dontAsk",
        max_turns=20,
        env={
            "CLAUDE_CODE_USE_BEDROCK": "1",
            "AWS_REGION": "eu-west-3",
            "ANTHROPIC_MODEL": "eu.anthropic.claude-sonnet-5",
        },
    )
    async for message in query(prompt="Résume les fichiers de ce répertoire", options=options):
        if isinstance(message, ResultMessage):
            print(message.subtype, message.total_cost_usd)

asyncio.run(main())

En Python, env se superpose à l’environnement hérité : le rôle d’instance reste visible. ANTHROPIC_MODEL bascule aussi les tâches d’arrière-plan sur ce modèle. La politique IAM doit autoriser bedrock:InvokeModel, bedrock:InvokeModelWithResponseStream, bedrock:ListInferenceProfiles et bedrock:GetInferenceProfile. Une lacune fonctionnelle : l’outil WebSearch n’est pas disponible sur Bedrock. Si l’agent doit chercher sur le web, fournissez-lui un outil MCP derrière votre propre proxy sortant. Les mêmes réglages valent pour Claude Code sur les postes des développeurs, décrits dans Claude Code sur Bedrock en Europe.

Comment l’exécuter sur Vertex AI avec la multirégion UE ?

Sur Google Cloud, définissez CLAUDE_CODE_USE_VERTEX=1, ANTHROPIC_VERTEX_PROJECT_ID et CLOUD_ML_REGION=eu. La valeur eu sélectionne l’hôte multirégional aiplatform.eu.rep.googleapis.com. N’utilisez pas une région unique comme europe-west1 pour les modèles actuels : Anthropic indique que les points de terminaison régionaux ne servent que Sonnet 4.6 et les modèles antérieurs.

Les pages de Google consacrées à Claude Opus 5.5 et à Claude Sonnet 5 mentionnent la multirégion Europe pour la disponibilité comme pour le traitement ML. Le quota par défaut de la multirégion est inférieur à celui du point global. Pour Opus 5.5 : 1 000 requêtes par minute, 10 000 000 tokens en entrée et 1 000 000 tokens en sortie par minute, soit la moitié des valeurs globales. Sonnet 5 dispose de 1 250 QPM et 12 500 000 TPM en entrée sur la multirégion. Un agent qui lance beaucoup de sous-agents en parallèle peut atteindre ces plafonds.

Le repli est là aussi un piège. Si CLOUD_ML_REGION est absent ou mal formé, Claude Code se rabat sur us-east5. Fixez la valeur dans la spécification du conteneur, pas dans le profil shell d’un collègue.

Le même agent en TypeScript sur Vertex :

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Résume les fichiers de ce répertoire",
  options: {
    cwd: "/work/session-a",
    allowedTools: ["Read", "Glob", "Grep"],
    permissionMode: "dontAsk",
    maxTurns: 20,
    env: {
      ...process.env,
      CLAUDE_CODE_USE_VERTEX: "1",
      CLOUD_ML_REGION: "eu",
      ANTHROPIC_VERTEX_PROJECT_ID: "your-project-id",
      ANTHROPIC_MODEL: "claude-sonnet-5",
    },
  },
})) {
  if (message.type === "result") console.log(message.subtype, message.total_cost_usd);
}

En TypeScript, env remplace l’environnement du sous-processus. Sans ...process.env, vous perdez PATH et les identifiants Google. Le compte de service a besoin de roles/aiplatform.user. La liste des fonctionnalités d’Anthropic pour Google Cloud inclut l’outil de recherche web côté serveur, absent sur Bedrock. Vérifiez que votre version du SDK l’expose avant d’en dépendre. Les détails de résidence de Claude sur Google Cloud figurent dans notre article Claude sur Vertex AI en Europe.

Comment héberger un agent en production ?

Traitez chaque session d’agent comme un processus avec un état, pas comme une requête. Une session correspond à un sous-processus, ses transcriptions vivent sur le disque local, et rien ne survit à un redémarrage sans copie vers un stockage durable.

Le guide d’hébergement décrit quatre modèles :

Modèle	Durée de vie du conteneur	Usage type	Exigence d’état
Éphémère	Un conteneur par tâche	Extraction de factures, correctif, traduction	Fichiers de sortie seulement
Longue durée	Persistant, plusieurs sessions	Tri d’e-mails, chatbots	RAM dimensionnée pour le pic de sessions
Hybride	S’arrête au repos, reprend	Support client, recherche sur plusieurs jours	SessionStore obligatoire
Multi-agent	Plusieurs processus SDK dans un conteneur	Simulations, agents coopérants	cwd et réglages distincts par agent

Le point de départ documenté est de 1 Gio de RAM, 5 Gio de disque et 1 CPU par agent, et Anthropic le présente comme un plancher. La mémoire croît avec la durée de session : mesurez le RSS maximal d’une session réaliste et dimensionnez avec “agents par hôte = (RAM de l’hôte moins surcharge) / plafond par session”.

Pour des charges soumises au RGPD, nous appliquerions cinq contrôles :

1. Sous-réseau privé, avec sortie uniquement via un proxy interne qui n’autorise que l’hôte Bedrock runtime de votre région ou aiplatform.eu.rep.googleapis.com. Le guide de déploiement sécurisé montre un conteneur avec --network none, --cap-drop ALL, --read-only et un socket de proxy monté.
2. Transcriptions dans un bucket UE via un adaptateur SessionStore, avec alerte sur les messages mirror_error : en cas d’échec d’écriture, le SDK abandonne ce lot et continue.
3. Séparer les clients : setting_sources=[], CLAUDE_CODE_DISABLE_AUTO_MEMORY=1, un CLAUDE_CONFIG_DIR et un cwd par client. Sinon, le contexte CLAUDE.md d’un client peut fuiter dans la session d’un autre.
4. Borner chaque session avec max_turns. Le SDK n’a pas de délai d’expiration global de session.
5. Exporter la télémétrie avec CLAUDE_CODE_ENABLE_TELEMETRY=1 et les variables OTLP vers un collecteur que vous hébergez. Le texte des prompts et les entrées d’outils sont exclus par défaut.

Côté permissions, dontAsk avec une liste allowed_tools explicite est notre point de départ pour un agent sans interface. Ne combinez pas allowed_tools avec bypassPermissions en pensant que la liste restreint quoi que ce soit : la page sur les permissions prévient que ce mode approuve aussi les outils non listés, Bash compris.

Qu’est-ce qui fait le coût d’un agent européen ?

Les tokens. Selon la documentation d’hébergement d’Anthropic, le coût des tokens dépasse généralement celui des conteneurs d’un ordre de grandeur ou plus : un conteneur minimal coûte environ 0,05 USD par heure, alors qu’une seule longue session peut consommer plusieurs dollars. La route UE ajoute une majoration de 10 % par rapport aux points globaux sur Bedrock et Google Cloud pour les modèles actuels.

Prix catalogue d’Anthropic selon la page tarifaire, avec la majoration régionale documentée de 10 %. Les prix contractuels figurent sur les pages d’AWS et de Google : vérifiez-les avant de budgéter.

Modèle	Entrée par MTok (catalogue)	Sortie par MTok (catalogue)	Avec 10 % de majoration UE
Claude Sonnet 5	2 USD	10 USD	2,20 / 11 USD
Claude Opus 5.5	4 USD	20 USD	4,40 / 22 USD
Claude Haiku 4.5	1 USD	5 USD	1,10 / 5,50 USD

Notre calcul, pas un chiffre éditeur : une session qui consomme 500 000 tokens d’entrée non mis en cache et 50 000 tokens de sortie coûte environ 1,65 USD avec Sonnet 5 via un point UE, et environ 3,30 USD avec Opus 5.5. Par session, le choix du modèle pèse plus sur la facture que le choix d’hébergement.

Quatre leviers de coût à maîtriser :

• La valeur par défaut non épinglée. Sur Bedrock et Vertex, le modèle principal par défaut de Claude Code est Opus 5.5. La documentation prévient que les déploiements non épinglés sont facturés au tarif Opus. Épinglez Sonnet 5 si la tâche n’exige pas Opus.
• L’expiration du cache. Sur Bedrock et Google Cloud, la durée de vie du cache est de 5 minutes par défaut. Des sessions courtes espacées paient à chaque fois le plein tarif d’entrée. ENABLE_PROMPT_CACHING_1H=1 échange un coût d’écriture plus élevé contre davantage de lectures en cache.
• Les sous-agents. total_cost_usd les inclut, usage non. Lisez le coût dans total_cost_usd ou model_usage.
• L’absence de plafond. max_budget_usd (TypeScript maxBudgetUsd) arrête un appel dès que sa propre dépense dépasse la limite.

total_cost_usd est une estimation côté client, calculée à partir d’une grille tarifaire livrée avec le SDK. Elle ignore vos remises AWS ou Google, et la documentation déconseille de facturer des utilisateurs sur cette base. Les montants réels se lisent dans AWS Cost Explorer ou la facturation Google Cloud. Pour comparer les tarifs entre fournisseurs, voyez notre comparatif des prix de l’API Claude en Europe.

Exploiter en interne ou externaliser ?

Écrire l’agent est la petite partie. L’exploiter 24 h sur 24 coûte davantage : il faut quelqu’un pour la plateforme de conteneurs, les frontières IAM, le proxy sortant, les mises à jour du SDK, l’épinglage des modèles et l’astreinte. Si vous exploitez déjà des conteneurs avec cette rigueur, gardez-le en interne. Sinon, un prestataire peut se justifier.

Ce que l’exploitation interne implique pour ce sujet, d’après les modes de défaillance documentés :

Tâche récurrente	Pourquoi elle revient	Rôle habituel
Mises à jour du SDK et de la CLI	Le binaire intégré est lié à la version du SDK ; la documentation conseille d’appliquer les correctifs en continu et de lire le changelog avant une version mineure	Ingénieur plateforme
Revue des modèles épinglés	La valeur par défaut est passée d’Opus 5 à Opus 5.5 en v2.1.280 ; de nouveaux profils UE arrivent par modèle	Ingénieur plateforme et product owner
Revue des frontières de permissions	Listes d’outils, règles de refus et hooks dérivent quand les agents changent de mission	Sécurité
Supervision et astreinte	Pas de délai de session, croissance mémoire, mirror_error, erreurs 429 de quota	Exploitation
Politiques IAM et de sortie	Verrouillage de région, ARN des profils d’inférence, listes du proxy	Équipe cloud

Notre estimation, pas un chiffre sourcé : pour un seul agent en production manipulant des données clients, prévoyez durablement une fraction de poste d’ingénieur plateforme et une part d’astreinte.

L’externalisation a du sens quand l’agent tourne en continu sur des données personnelles, sans astreinte interne ni responsable IAM sur AWS ou Google Cloud. Elle en a moins pour un job de CI ou un agent batch interne lancé quelques fois par jour : un conteneur éphémère sans état durable laisse peu de choses à exploiter.

Si vous externalisez, exigez par écrit :

1. Un SLA sur l’exécution de l’agent, distinct du SLA du fournisseur de modèle. Le prestataire répond des conteneurs et du stockage des sessions, AWS ou Google du point de terminaison du modèle.
2. Un contrat de sous-traitant au sens du RGPD, couvrant transcriptions, répertoires de travail et télémétrie, pas seulement les prompts.
3. La liste des sous-traitants ultérieurs, avec le cloud, la région ou multirégion exacte et tout fournisseur de sandbox ou d’observabilité.
4. Le modèle d’accès : qui peut lire les transcriptions et le stockage des sessions, comment l’accès d’urgence est journalisé, et si le compte Bedrock ou Vertex est le vôtre ou le sien. Nous exigerions votre propre compte cloud.
5. La réversibilité : transcriptions dans votre bucket, infrastructure as code remise, aucun format de session propriétaire. Si l’agent tourne dans votre compte, sortir revient à révoquer un rôle.

FAQ

Le Claude Agent SDK fonctionne-t-il avec Amazon Bedrock ?

Oui. Définissez CLAUDE_CODE_USE_BEDROCK=1, fournissez des identifiants AWS et fixez AWS_REGION. Avec une région eu-*, Claude Code privilégie les profils eu. comme eu.anthropic.claude-sonnet-5. Épinglez le modèle via ANTHROPIC_MODEL pour éviter un passage silencieux à Opus 5.5. WebSearch n’est pas disponible sur Bedrock.

Combien coûte une session d’agent dans l’UE ?

Cela dépend des tokens, pas du conteneur. Au prix catalogue majoré de 10 %, Sonnet 5 coûte 2,20 USD en entrée et 11 USD en sortie par million de tokens. Notre session type de 500 000 tokens d’entrée et 50 000 de sortie revient à environ 1,65 USD. Un conteneur minimal coûte environ 0,05 USD par heure.

Claude Agent SDK ou Managed Agents : lequel pour des données européennes ?

L’Agent SDK, si votre hébergement des données repose sur Bedrock ou Google Cloud. Managed Agents exécute la boucle sur l’infrastructure d’Anthropic et figure comme non pris en charge sur ces deux clouds. Avec le SDK, la boucle tourne dans votre compte UE et vous choisissez le point de terminaison européen.

Quelle région Google Cloud choisir pour des agents Claude ?

CLOUD_ML_REGION=eu, la multirégion Europe. Opus 5.5 et Sonnet 5 y sont disponibles. Les régions uniques comme europe-west1 ne servent que Sonnet 4.6 et les modèles antérieurs. Sans région définie, Claude Code se replie sur us-east5.

total_cost_usd correspond-il à ma facture ?

Non. C’est une estimation côté client fondée sur une grille tarifaire intégrée au moment du build. Elle ignore les remises cloud et certaines règles de facturation. Pour les factures, fiez-vous à AWS Cost Explorer ou à la facturation Google Cloud ; gardez total_cost_usd pour les budgets et les alertes.

Sources

1. Documentation Claude Code : présentation de l'Agent SDK (1 octobre 2026)
2. Documentation Claude Code : démarrage rapide Agent SDK (1 octobre 2026)
3. Documentation Claude Code : héberger l'Agent SDK (1 octobre 2026)
4. Documentation Claude Code : suivi des coûts (1 octobre 2026)
5. Documentation Claude Code : permissions de l'Agent SDK (1 octobre 2026)
6. Documentation Claude Code : déploiement sécurisé (1 octobre 2026)
7. Documentation Claude Code : Amazon Bedrock (1 octobre 2026)
8. Documentation Claude Code : Google Cloud Agent Platform (1 octobre 2026)
9. AWS : fiche modèle Claude Sonnet 5 (1 octobre 2026)
10. AWS : fiche modèle Claude Opus 5.5 (1 octobre 2026)
11. AWS : régions et modèles des profils d'inférence (1 octobre 2026)
12. Google Cloud : Claude Opus 5.5 sur Agent Platform (1 octobre 2026)
13. Google Cloud : Claude Sonnet 5 sur Agent Platform (1 octobre 2026)
14. Anthropic : Claude sur Google Cloud (1 octobre 2026)
15. Anthropic : tarifs (1 octobre 2026)
16. claude-agent-sdk-python CHANGELOG (1 octobre 2026)
17. claude-agent-sdk-typescript CHANGELOG (1 octobre 2026)