Outil d'exécution de code

Claude peut analyser des données, créer des visualisations, effectuer des calculs complexes, exécuter des commandes système, créer et modifier des fichiers, et traiter des fichiers téléversés directement au sein de la conversation API. L'outil d'exécution de code permet à Claude d'exécuter des commandes Bash et de manipuler des fichiers, y compris écrire du code, dans un environnement sécurisé et sandboxé.

L'exécution de code est gratuite lorsqu'elle est utilisée avec la recherche web ou la récupération web (web_search_20260209, web_fetch_20260209, ou ultérieur). Lorsque l'un de ces outils est présent dans votre requête, il n'y a aucun frais supplémentaire pour l'exécution de code dans cette requête au-delà des coûts standard en tokens. Cela couvre à la fois l'exécution de code derrière le filtrage dynamique et tout code que Claude exécute directement. La tarification standard de l'exécution de code s'applique lorsqu'ils ne sont pas inclus.

L'exécution de code alimente également le filtrage dynamique dans les outils de recherche web et de récupération web : Claude filtre les résultats à l'intérieur de l'environnement d'exécution de code avant qu'ils n'atteignent la fenêtre de contexte. Lorsque le filtrage dynamique s'exécute, l'API provisionne automatiquement l'exécution de code dont elle a besoin pour la requête, vous n'avez donc pas à ajouter l'outil d'exécution de code à votre requête pour cela.



Compatibilité des modèles

L'outil d'exécution de code est disponible sur les modèles suivants :

Chaque version de l'outil s'appuie sur la précédente :

• code_execution_20250825 prend en charge les commandes Bash et les opérations sur les fichiers et est disponible sur tous les modèles du tableau.
• code_execution_20260120 ajoute la persistance de l'état du REPL et l'appel programmatique d'outils depuis l'intérieur du sandbox. Claude Haiku 4.5 accepte les types d'outils code_execution_20260120 et code_execution_20260521, mais l'appel programmatique d'outils et la persistance de l'état du REPL qui en dépend n'y sont pas disponibles, donc les versions plus récentes s'y comportent comme code_execution_20250825.
• code_execution_20260521 est le même environnement d'exécution que code_execution_20260120. La différence est que la description de l'outil informe Claude de la limite de 90 secondes de temps réel (wall-clock) sur chaque cellule Python dans l'appel programmatique d'outils, afin que Claude puisse budgétiser les cellules de longue durée. Une cellule qui dépasse la limite renvoie un résultat d'exécution de code normal avec un return_code non nul et un message de statut detection_timeout dans sa sortie. Ceci est distinct du code d'erreur execution_time_exceeded, que l'API renvoie lorsqu'une invocation d'outil entière dépasse le temps d'exécution maximal.

Les trois versions de l'outil sont en disponibilité générale et ne nécessitent pas d'en-tête anthropic-beta. Les anciens en-têtes bêta d'exécution de code restent des options d'activation valides.

Les exemples de cette page utilisent code_execution_20250825 car tous les modèles du tableau le prennent en charge. Les outils actuels de recherche web et de récupération web (web_search_20260209, web_fetch_20260209, et ultérieurs) nécessitent code_execution_20260120 ou ultérieur comme version d'exécution de code.



Disponibilité par plateforme

L'exécution de code est disponible sur :

• Claude API (Anthropic)
• Claude Platform sur AWS
• Microsoft Foundry (nécessite un déploiement Hosted on Anthropic)

L'exécution de code n'est actuellement pas disponible sur Amazon Bedrock ou Google Cloud.



Démarrage rapide

Voici un exemple simple qui demande à Claude d'effectuer un calcul :

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Use the code execution tool to calculate the mean and standard deviation of [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]",
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

print(response.to_json())

La réponse entrelace les blocs server_tool_use (les commandes que Claude a exécutées) avec leurs blocs de résultat d'outil, suivis du texte de Claude. Le niveau supérieur inclut également un objet container dont vous pouvez réutiliser l'id entre les requêtes. Consultez Format de réponse pour les formes des blocs.



Comment fonctionne l'exécution de code

Lorsque vous ajoutez l'outil d'exécution de code à votre requête API :

1. Claude évalue si l'exécution de code aiderait à répondre à votre question
2. L'outil fournit automatiquement à Claude les capacités suivantes :
   • Commandes Bash : exécuter des commandes shell pour les opérations système
   • Opérations sur les fichiers : créer, consulter et modifier des fichiers directement, y compris écrire du code
3. Claude peut utiliser n'importe quelle combinaison de ces capacités dans une seule requête
4. Toutes les opérations s'exécutent dans un conteneur sécurisé et sandboxé. Le conteneur n'a pas d'accès à Internet, donc Claude ne peut pas télécharger de paquets à l'exécution : seules les bibliothèques préinstallées sont disponibles
5. L'API exécute chaque commande côté serveur et renvoie les résultats à Claude au sein de la même requête, vous n'exécutez donc jamais de code ni ne renvoyez de blocs tool_result vous-même. Une exception est lorsque Claude appelle l'un de vos outils clients en parallèle de l'exécution de code : l'API renvoie l'appel d'exécution de code sans son résultat. Le résultat arrive dans une réponse ultérieure, après que vous ayez renvoyé les blocs tool_result pour vos outils clients
6. Chaque requête s'exécute dans un nouveau conteneur, sauf si vous renvoyez l'ID de conteneur d'une réponse antérieure (voir Réutilisation de conteneur)
7. Claude fournit les résultats avec les graphiques, calculs ou analyses générés

Le conteneur a Python préinstallé. Claude écrit du Python avec le sous-outil d'opérations sur les fichiers et l'exécute avec une commande Bash. Avec code_execution_20260120 ou ultérieur et l'appel programmatique d'outils, l'état de l'interpréteur Python (comme les liaisons de variables) persiste également entre les requêtes qui réutilisent le conteneur.



Quand Claude exécute du code

Claude exécute du code lorsque la requête bénéficie de calculs ou de manipulation de fichiers :

• Mathématiques non triviales (grands nombres, nombreuses étapes, résultats sensibles à la précision)
• Analyse de données, analyse syntaxique de fichiers ou visualisation
• Exécution d'algorithmes ou simulation
• Demandes explicites de « run », « compute » ou « execute »

Claude répond directement sans exécuter de code pour :

• L'arithmétique simple et les faits mathématiques bien connus
• Les demandes factuelles, conversationnelles ou créatives
• Les conversions d'unités ou traductions simples

Si vous voulez que Claude exécute du code pour une demande limite, demandez-le explicitement (par exemple, « exécute du code pour vérifier ceci »).



Travailler avec des fichiers



Téléverser et analyser vos propres fichiers

Pour analyser vos propres fichiers de données (tels que CSV, Excel ou images), téléversez-les via la Files API et référencez-les dans votre requête :

L'environnement Python peut traiter divers types de fichiers téléversés via la Files API, notamment :

• CSV
• Excel (.xlsx, .xls)
• JSON
• XML
• Images (JPEG, PNG, GIF, WebP)
• Fichiers texte (.txt, .md, .py, et autres)



Téléverser et analyser des fichiers

1. Téléversez votre fichier en utilisant la Files API
2. Référencez le fichier dans votre message en utilisant un bloc de contenu container_upload
3. Incluez l'outil d'exécution de code dans votre requête API

client = anthropic.Anthropic()

# Téléverser un fichier
file_object = client.beta.files.upload(file=Path("data.csv"))

# Utiliser le file_id avec l'exécution de code
response = client.beta.messages.create(
    model="claude-opus-4-8",
    betas=["files-api-2025-04-14"],
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Analyze this CSV data"},
                {"type": "container_upload", "file_id": file_object.id},
            ],
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

print(response.to_json())



Récupérer les fichiers générés

Lorsque Claude crée des fichiers pendant l'exécution de code, l'ID de chaque fichier créé apparaît dans le résultat de l'outil d'exécution de code, et vous pouvez le télécharger avec la Files API :

client = Anthropic()

# Demander une exécution de code qui crée des fichiers
response = client.beta.messages.create(
    model="claude-opus-4-8",
    betas=["files-api-2025-04-14"],
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Create a matplotlib visualization and save it as output.png",
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)


# Extraire les ID de fichiers de la réponse
def extract_file_ids(response: BetaMessage) -> list[str]:
    file_ids: list[str] = []
    for item in response.content:
        if item.type == "bash_code_execution_tool_result":
            content_item = item.content
            if content_item.type == "bash_code_execution_result":
                for output_block in content_item.content:
                    file_ids.append(output_block.file_id)
    return file_ids


# Télécharger les fichiers créés
for file_id in extract_file_ids(response):
    file_metadata = client.beta.files.retrieve_metadata(file_id)
    file_content = client.beta.files.download(file_id)
    file_content.write_to_file(file_metadata.filename)
    print(f"Downloaded: {file_metadata.filename}")



Définition de l'outil

L'outil d'exécution de code ne nécessite aucun paramètre supplémentaire :

{
  "type": "code_execution_20250825",
  "name": "code_execution"
}

Les deux champs sont fixes : type sélectionne la version de l'outil, et name doit être code_execution.

Lorsque cet outil est fourni, Claude obtient automatiquement l'accès à deux sous-outils :

• bash_code_execution : exécuter des commandes shell
• text_editor_code_execution : consulter, créer et modifier des fichiers, y compris écrire du code

Lorsque Claude exécute du code, la réponse inclut également un objet container de niveau supérieur avec l'id du conteneur et l'horodatage expires_at. Renvoyez cet ID dans le paramètre de requête container de niveau supérieur pour continuer à utiliser le même conteneur. Consultez Réutilisation de conteneur.



Format de réponse

L'outil d'exécution de code peut renvoyer deux types de résultats selon l'opération :



Réponse de commande Bash

{
  "type": "server_tool_use",
  "id": "srvtoolu_01B3C4D5E6F7G8H9I0J1K2L3",
  "name": "bash_code_execution",
  "input": {
    "command": "ls -la | head -5"
  }
},
{
  "type": "bash_code_execution_tool_result",
  "tool_use_id": "srvtoolu_01B3C4D5E6F7G8H9I0J1K2L3",
  "content": {
    "type": "bash_code_execution_result",
    "stdout": "total 24\ndrwxr-xr-x 2 user user 4096 Jan 1 12:00 .\ndrwxr-xr-x 3 user user 4096 Jan 1 11:00 ..\n-rw-r--r-- 1 user user  220 Jan 1 12:00 data.csv\n-rw-r--r-- 1 user user  180 Jan 1 12:00 config.json",
    "stderr": "",
    "return_code": 0,
    "content": []
  }
}



Réponses d'opérations sur les fichiers

Consulter un fichier :

{
  "type": "server_tool_use",
  "id": "srvtoolu_01C4D5E6F7G8H9I0J1K2L3M4",
  "name": "text_editor_code_execution",
  "input": {
    "command": "view",
    "path": "config.json"
  }
},
{
  "type": "text_editor_code_execution_tool_result",
  "tool_use_id": "srvtoolu_01C4D5E6F7G8H9I0J1K2L3M4",
  "content": {
    "type": "text_editor_code_execution_view_result",
    "file_type": "text",
    "content": "{\n  \"setting\": \"value\",\n  \"debug\": true\n}",
    "num_lines": 4,
    "start_line": 1,
    "total_lines": 4
  }
}

Créer un fichier :

{
  "type": "server_tool_use",
  "id": "srvtoolu_01D5E6F7G8H9I0J1K2L3M4N5",
  "name": "text_editor_code_execution",
  "input": {
    "command": "create",
    "path": "new_file.txt",
    "file_text": "Hello, World!"
  }
},
{
  "type": "text_editor_code_execution_tool_result",
  "tool_use_id": "srvtoolu_01D5E6F7G8H9I0J1K2L3M4N5",
  "content": {
    "type": "text_editor_code_execution_create_result",
    "is_file_update": false
  }
}

Modifier un fichier (str_replace) :

{
  "type": "server_tool_use",
  "id": "srvtoolu_01E6F7G8H9I0J1K2L3M4N5O6",
  "name": "text_editor_code_execution",
  "input": {
    "command": "str_replace",
    "path": "config.json",
    "old_str": "\"debug\": true",
    "new_str": "\"debug\": false"
  }
},
{
  "type": "text_editor_code_execution_tool_result",
  "tool_use_id": "srvtoolu_01E6F7G8H9I0J1K2L3M4N5O6",
  "content": {
    "type": "text_editor_code_execution_str_replace_result",
    "old_start": 3,
    "old_lines": 1,
    "new_start": 3,
    "new_lines": 1,
    "lines": ["-  \"debug\": true", "+  \"debug\": false"]
  }
}



Résultats

Les résultats de commandes Bash (bash_code_execution_result) incluent :

• stdout : sortie d'une exécution réussie
• stderr : messages d'erreur si l'exécution échoue
• return_code : 0 en cas de succès, non nul en cas d'échec
• content : une liste avec une entrée pour chaque fichier créé par la commande. Chaque entrée porte le file_id pour récupérer le fichier avec la Files API

Les résultats d'opérations sur les fichiers ont leurs propres champs :

• View (text_editor_code_execution_view_result) : file_type, content, num_lines, start_line, total_lines
• Create (text_editor_code_execution_create_result) : is_file_update (si le fichier existait déjà)
• Edit (text_editor_code_execution_str_replace_result) : old_start, old_lines, new_start, new_lines, lines (format diff)



Erreurs

Chaque type d'outil peut renvoyer des erreurs spécifiques :

Erreurs communes (tous les outils) :

{
  "type": "bash_code_execution_tool_result",
  "tool_use_id": "srvtoolu_01VfmxgZ46TiHbmXgy928hQR",
  "content": {
    "type": "bash_code_execution_tool_result_error",
    "error_code": "unavailable"
  }
}

Codes d'erreur par type d'outil :

Un conteneur expiré ne peut pas être réutilisé : les requêtes qui le référencent renvoient une erreur au lieu de le restaurer. Renvoyez la requête sans le paramètre container pour obtenir un nouveau conteneur.



Raison d'arrêt pause_turn

La réponse peut inclure une raison d'arrêt pause_turn, qui indique que l'API a mis en pause un tour de longue durée. Vous pouvez renvoyer la réponse telle quelle dans une requête ultérieure pour laisser Claude continuer son tour, ou modifier le contenu si vous souhaitez interrompre la conversation.



Conteneurs

L'outil d'exécution de code s'exécute dans un environnement conteneurisé sécurisé conçu spécifiquement pour l'exécution de code, avec un accent particulier sur Python.



Environnement d'exécution

• Version de Python : 3.11
• Système d'exploitation : conteneur basé sur Linux
• Architecture : x86_64 (AMD64)



Limites de ressources

• Mémoire : 5 Gio de RAM
• Espace disque : 5 Gio de stockage d'espace de travail
• CPU : 1 CPU
• Temps d'exécution : une invocation d'outil qui dépasse le temps d'exécution maximal renvoie une erreur execution_time_exceeded. Avec l'appel programmatique d'outils, chaque cellule REPL a également une limite de 90 secondes de temps réel (wall-clock)



Réseau et sécurité

• Accès à Internet : complètement désactivé pour des raisons de sécurité
• Connexions externes : aucune requête réseau sortante autorisée
• Isolation du sandbox : isolation complète du système hôte et des autres conteneurs
• Accès aux fichiers : limité au répertoire de l'espace de travail uniquement
• Portée de l'espace de travail : comme les Files, les conteneurs sont limités à l'espace de travail de la clé API
• Expiration : les conteneurs expirent 30 jours après leur création



Bibliothèques préinstallées

L'environnement Python sandboxé inclut ces bibliothèques couramment utilisées :

• Science des données : pandas, numpy, scipy, scikit-learn, statsmodels
• Visualisation : matplotlib, seaborn
• Traitement de fichiers : pyarrow, openpyxl, xlsxwriter, xlrd, pillow, python-pptx, python-docx, pypdf, pdfplumber, pypdfium2, pdf2image, pdfkit, tabula-py, reportlab[pycairo], Img2pdf
• Mathématiques et calcul : sympy, mpmath
• Utilitaires : tqdm, python-dateutil, pytz, joblib

Le conteneur inclut également des outils en ligne de commande tels que unzip, unrar, 7zip, bc, rg (ripgrep), fd et sqlite.

Le conteneur n'a pas d'accès à Internet, donc Claude ne peut pas télécharger ou installer de paquets supplémentaires à l'exécution : seules les bibliothèques préinstallées sont disponibles.



Réutilisation de conteneur

Vous pouvez réutiliser un conteneur existant sur plusieurs requêtes API en fournissant l'ID de conteneur d'une réponse précédente. Cela vous permet de conserver les fichiers créés entre les requêtes. Avec code_execution_20260120 ou ultérieur et l'appel programmatique d'outils, l'état de l'interpréteur Python persiste également.

Les conteneurs expirent 30 jours après leur création. Après environ cinq minutes d'inactivité, un conteneur est mis en point de contrôle (checkpoint), et l'envoi d'une requête avec son ID dans la fenêtre de 30 jours le restaure. L'horodatage expires_at dans l'objet container de la réponse est une valeur glissante plus courte et ne reflète pas la limite de 30 jours. Un conteneur qui a expiré ne peut pas être réutilisé. Renvoyez la requête sans le paramètre container pour obtenir un nouveau conteneur.



Exemple

client = anthropic.Anthropic()

# Première requête : créer un fichier avec un nombre aléatoire dans un nouveau conteneur
response1 = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Write a file with a random number and save it to '/tmp/number.txt'",
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# Deuxième requête : renvoyer l'ID du conteneur pour que Claude réutilise le même conteneur
response2 = client.messages.create(
    container=response1.container.id,
    model="claude-opus-4-8",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Read the number from '/tmp/number.txt' and calculate its square",
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

print(response2.to_json())



Utiliser l'exécution de code avec d'autres outils d'exécution

Lorsque vous fournissez l'exécution de code en parallèle d'outils fournis par le client qui exécutent également du code (comme un outil Bash ou un REPL personnalisé), Claude opère dans un environnement multi-ordinateurs. L'outil d'exécution de code s'exécute dans le conteneur sandboxé d'Anthropic, tandis que vos outils fournis par le client s'exécutent dans un environnement distinct que vous contrôlez. Claude peut parfois confondre ces environnements, en tentant d'utiliser le mauvais outil ou en supposant que l'état est partagé entre eux.

Pour éviter cela, ajoutez des instructions à votre invite système qui clarifient la distinction :

When multiple code execution environments are available, be aware that:
- Variables, files, and state do NOT persist between different execution environments
- Use the code_execution tool for general-purpose computation in Anthropic's sandboxed environment
- Use client-provided execution tools (e.g., bash) when you need access to the user's local system, files, or data
- If you need to pass results between environments, explicitly include outputs in subsequent tool calls rather than assuming shared state

Ceci est particulièrement important lorsque vous combinez l'exécution de code avec la recherche web ou la récupération web, qui activent automatiquement l'exécution de code. Si votre application fournit déjà un outil shell côté client, l'exécution de code automatique crée un second environnement d'exécution que Claude doit distinguer.

Lorsque Claude appelle l'un de vos outils clients en parallèle de l'exécution de code, l'API renvoie l'appel d'exécution de code sans son résultat. Le résultat arrive dans une réponse ultérieure, après que vous ayez renvoyé les blocs tool_result pour vos outils clients.



Streaming

Avec le streaming activé ("stream": true), vous recevrez les événements d'exécution de code au fur et à mesure qu'ils se produisent. L'entrée du sous-outil est diffusée sous forme d'événements input_json_delta, et chaque bloc de résultat arrive entier dans un seul événement content_block_start :

event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "bash_code_execution"}}

// Tool input streamed as partial JSON
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"command\": \"python analyze.py\"}"}}

// Pause while the command runs

// Execution result delivered as a complete block
event: content_block_start
data: {"type": "content_block_start", "index": 2, "content_block": {"type": "bash_code_execution_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": {"type": "bash_code_execution_result", "stdout": "   A  B  C\n0  1  2  3\n1  4  5  6", "stderr": "", "return_code": 0, "content": []}}}



Requêtes par lots

Vous pouvez inclure l'outil d'exécution de code dans la Messages Batches API. Les appels à l'outil d'exécution de code via la Messages Batches API sont facturés au même tarif que ceux des requêtes régulières de la Messages API.



Utilisation et tarification

L'exécution de code est gratuite lorsqu'elle est utilisée avec la recherche web ou la récupération web. Lorsque web_search_20260209 (ou version ultérieure) ou web_fetch_20260209 (ou version ultérieure) est inclus dans votre requête API, aucun frais supplémentaire n'est facturé pour les appels à l'outil d'exécution de code au-delà des coûts standard des tokens d'entrée et de sortie.

Lorsqu'elle est utilisée sans ces outils, l'exécution de code est facturée en fonction du temps d'exécution, comptabilisé séparément de l'utilisation des tokens :

• Le temps d'exécution a un minimum de 5 minutes
• Chaque organisation bénéficie de 1 550 heures gratuites d'utilisation par mois
• L'utilisation supplémentaire au-delà de 1 550 heures est facturée à 0,05 $ par heure, par conteneur
• Si des fichiers sont inclus dans la requête, le temps d'exécution est facturé même si l'outil n'est pas invoqué, car les fichiers sont préchargés dans le conteneur

L'utilisation de l'exécution de code est indiquée dans la réponse :

{
  "usage": {
    "input_tokens": 105,
    "output_tokens": 239,
    "server_tool_use": {
      "code_execution_requests": 1
    }
  }
}



Mettre à niveau vers la dernière version de l'outil

La dernière version de l'outil est code_execution_20260521. Pour passer d'une des trois versions actuelles à une autre, mettez à jour la chaîne type dans votre requête : les trois renvoient les blocs de réponse documentés dans Format de réponse. Consultez Compatibilité des modèles pour savoir ce que chaque version ajoute et quels modèles la prennent en charge.

Le reste de cette section couvre la migration depuis l'ancien code_execution_20250522 (Python uniquement) vers les versions actuelles de l'outil.



Ce qui a changé



Rétrocompatibilité

• Toute exécution de code Python existante continue de fonctionner exactement comme avant
• Aucune modification requise pour les flux de travail existants en Python uniquement



Étapes de mise à niveau

Pour mettre à niveau, mettez à jour le type d'outil dans vos requêtes API :

- "type": "code_execution_20250522"
+ "type": "code_execution_20250825"

Vérifiez le traitement des réponses (si vous analysez les réponses de manière programmatique) :

• Les blocs précédents pour les réponses d'exécution Python ne seront plus envoyés
• À la place, de nouveaux types de réponse pour les opérations Bash et sur les fichiers seront envoyés (voir Format de réponse)



Conservation des données

L'exécution de code s'exécute dans des conteneurs sandbox côté serveur. Les données du conteneur, y compris les artefacts d'exécution, les fichiers téléversés et les sorties, sont conservées jusqu'à 30 jours. Cette conservation s'applique à toutes les données traitées dans l'environnement du conteneur. Les fichiers que l'exécution de code crée dans la Files API (récupérables avec client.beta.files.download()) persistent jusqu'à leur suppression explicite.

Pour l'éligibilité ZDR sur l'ensemble des fonctionnalités, consultez API et conservation des données.



Prochaines étapes