Exécution de code : Claude exécute le code qu'il écrit

Objectifs

À l’issue de cette leçon, vous serez capable de :

• Ajouter l’outil d’exécution de code à une requête et choisir sa version
• Charger vos fichiers dans le conteneur avec la Files API
• Réutiliser un conteneur, récupérer les fichiers produits et anticiper le coût

Arrêtez de demander au modèle d’être une calculatrice

Demander à un modèle de lire douze tableurs à l’œil et d’en tirer des chiffres, c’est s’exposer à des erreurs affirmées avec aplomb. Le laisser écrire du code pandas et l’exécuter, c’est de l’arithmétique. Ingénova a douze fichiers CSV, un par station de pompage, chacun avec un an de relevés de débit, et veut savoir si une station a dépassé sa capacité nominale, et quand.

L’outil d’exécution de code est un outil serveur : il s’exécute chez Anthropic, et vous n’écrivez aucun code de traitement. Claude écrit du Python ou des commandes Bash, les exécute dans un conteneur isolé, voit le résultat, corrige au besoin, et répond à partir de ce que le code a affiché. Le conteneur fonctionne sous Linux avec Python 3.11, 1 CPU, 5 Gio de mémoire et 5 Gio de disque ; il n’a pas d’accès à Internet, donc seules les bibliothèques préinstallées (pandas, numpy, matplotlib, scikit-learn, openpyxl…) sont disponibles.

Ajouter l’outil

Une entrée dans tools, sans schéma. La date à la fin du type est la version : il en existe trois actuelles, acceptées par tous les modèles compatibles.

OUTILS = [{"type": "code_execution_20260521", "name": "code_execution"}]

Sur Claude Haiku 4.5, les deux versions récentes sont acceptées mais se comportent comme code_execution_20250825. Recopiez toujours le type depuis la référence des outils plutôt que depuis un tutoriel : les versions évoluent.

Mettre vos fichiers dans le conteneur

Vos fichiers sont sur votre machine, pas dans le conteneur. Deux étapes : les envoyer avec la Files API, qui renvoie un identifiant, puis les référencer dans le message avec un bloc container_upload, dans le même message que la question.

fichiers = [client.files.upload(file=open(chemin, "rb")) for chemin in chemins_csv]

reponse = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    tools=OUTILS,
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "Pour chaque station, trouve les mois où le débit de pointe a dépassé la capacité nominale, et de combien. Trace un graphique."},
            *[{"type": "container_upload", "file_id": f.id} for f in fichiers],
        ],
    }],
)

Claude travaille alors dans le conteneur : il écrit son code, l’exécute, lit le résultat, affine. Les tableaux intermédiaires restent dans le conteneur au lieu d’encombrer votre contexte : votre conversation contient la question, le code et ce qu’il a affiché, pas les lignes brutes des CSV.

Lire la réponse, et continuer si besoin

La réponse entremêle du texte, les blocs server_tool_use (ce que Claude exécute) et leurs résultats (bash_code_execution_tool_result, avec un return_code). Si la boucle côté serveur atteint sa limite d’itérations, la réponse s’arrête avec stop_reason: "pause_turn" : renvoyez son contenu comme message de l’assistant, avec les mêmes tools, et Claude reprend.

Les fichiers que Claude crée (un graphique, un tableur) reviennent sous forme d’identifiants de fichiers dans les résultats ; téléchargez-les avec la Files API (client.files.download(file_id)). Avant d’écrire un fichier téléchargé sur disque, nettoyez son nom (os.path.basename) pour éviter toute traversée de répertoire.

Réutiliser le conteneur

La réponse contient un objet container, avec son id et une échéance expires_at. Renvoyez cet identifiant dans le paramètre container de la requête suivante pour retrouver le même environnement : fichiers, variables, état de l’interpréteur avec les versions récentes. Un conteneur expire 30 jours après sa création ; inactif depuis environ cinq minutes, il est mis en sommeil, et une requête avec son identifiant le restaure. L’échéance expires_at de la réponse est plus courte et glissante : elle ne reflète pas ces 30 jours.

Le coût

• Gratuit avec la recherche ou la récupération web (web_search_20260209, web_fetch_20260209 ou plus récents) : aucune charge supplémentaire pour l’exécution de code dans ces requêtes, au-delà des jetons.
• Sinon, facturation au temps d’exécution : 1 550 heures gratuites par mois et par organisation, puis 0,05 $ l’heure par conteneur, avec un minimum de 5 minutes par exécution. Si des fichiers sont joints, le temps est facturé même si l’outil n’est pas appelé, car les fichiers sont préchargés.

L’outil est disponible sur l’API Claude, Claude Platform on AWS, les modèles Claude sur Google Cloud gérés par Anthropic et les déploiements Microsoft Foundry hébergés par Anthropic.

À vous de jouer

Une question qui demande du calcul.

1. Prenez une question de votre métier qui exige un calcul sur plusieurs fichiers.
2. Envoyez les fichiers avec la Files API, posez la question avec l’outil d’exécution de code, et récupérez le graphique produit.
3. Relisez le code que Claude a exécuté : c’est votre piste d’audit.

Sources officielles : Code execution tool (documentation Claude : versions, conteneur, réutilisation, tarifs, plateformes) · Files API (documentation Claude)

Points clés à retenir

• L’exécution de code donne à Claude un conteneur isolé, sans Internet, avec Python, Bash et vos fichiers
• Les fichiers entrent par la Files API et un bloc container_upload ; les fichiers produits ressortent par la Files API
• Réutilisez l’identifiant du conteneur entre les tours ; gérez pause_turn
• Gratuit avec la recherche web récente ; sinon facturé au temps d’exécution, au-delà de 1 550 heures gratuites par mois