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 dans la conversation de l'API. L'outil d'exécution de code permet à Claude d'exécuter des commandes Bash et de manipuler des fichiers, y compris l'écriture de code, dans un environnement sécurisé et isolé (sandbox).

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, aucun frais supplémentaire n'est facturé pour les appels à l'outil d'exécution de code au-delà des coûts standard de tokens d'entrée et de sortie. Les frais standard d'exécution de code s'appliquent lorsque ces outils ne sont pas inclus.

L'exécution de code est une primitive essentielle pour construire des agents performants. Elle permet le filtrage dynamique dans les outils de recherche web et de récupération web, permettant à Claude de traiter les résultats avant qu'ils n'atteignent la fenêtre de contexte, améliorant ainsi la précision tout en réduisant la consommation de tokens.



Compatibilité des modèles

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



Disponibilité sur les plateformes

L'exécution de code est disponible sur :

• Claude API (Anthropic)
• Claude Platform on AWS
• Microsoft Foundry

L'exécution de code n'est actuellement pas disponible sur Amazon Bedrock ni sur Vertex AI.



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": "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)



Fonctionnement de 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 et la gestion des paquets
   • Opérations sur les fichiers : créer, afficher et modifier des fichiers directement, y compris l'écriture de 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 environnement sandbox sécurisé
5. Claude fournit les résultats avec les graphiques, calculs ou analyses générés



Quand Claude exécute du code

Claude exécute du code lorsque la requête bénéficie d'un calcul ou d'une manipulation de fichiers :

• Mathématiques non triviales (grands nombres, nombreuses étapes, résultats sensibles à la précision)
• Analyse de données, parsing de fichiers ou visualisation
• Exécution d'algorithmes ou simulation
• Demandes explicites d'« exécuter », « calculer » ou « lancer »

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

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

Si vous souhaitez que Claude exécute du code pour une requête limite, demandez-le explicitement (par exemple, « exécute du code pour vérifier cela »).



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.



Comment utiliser l'outil



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 l'API Files et référencez-les dans votre requête :

L'environnement Python peut traiter divers types de fichiers téléversés via l'API Files, 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 à l'aide de l'API Files
2. Référencez le fichier dans votre message à l'aide d'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=open("data.csv", "rb"),
)

# 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)



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

Lorsque Claude crée des fichiers pendant l'exécution de code, vous pouvez récupérer ces fichiers à l'aide de l'API Files :

# Initialiser le client
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 identifiants de fichiers de la réponse
def extract_file_ids(response):
    file_ids = []
    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":
                # liste à typage concret : List[BashCodeExecutionOutputBlock]
                for file in content_item.content:
                    file_ids.append(file.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"
}

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 : afficher, créer et modifier des fichiers, y compris l'écriture de code



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
  }
}



Réponses d'opérations sur les fichiers

Afficher 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_result",
    "file_type": "text",
    "content": "{\n  \"setting\": \"value\",\n  \"debug\": true\n}",
    "numLines": 4,
    "startLine": 1,
    "totalLines": 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_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_result",
    "oldStart": 3,
    "oldLines": 1,
    "newStart": 3,
    "newLines": 1,
    "lines": ["-  \"debug\": true", "+  \"debug\": false"]
  }
}



Résultats

Tous les résultats d'exécution 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

Champs supplémentaires pour les opérations sur les fichiers :

• Afficher : file_type, content, numLines, startLine, totalLines
• Créer : is_file_update (indique si le fichier existait déjà)
• Modifier : oldStart, oldLines, newStart, newLines, 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 :



Motif d'arrêt pause_turn

La réponse peut inclure un stop_reason 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 permettre à Claude de poursuivre 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.12
• 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



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 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 pour les Fichiers, 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 isolé 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, unzip, unrar, 7zip, bc, rg (ripgrep), fd, sqlite



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.



Exemple

# Première requête : créer un fichier avec un nombre aléatoire
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"}],
)

# Extraire l'ID du conteneur de la première réponse
container_id = response1.container.id

# Deuxième requête : réutiliser le conteneur pour lire le fichier
response2 = client.messages.create(
    container=container_id,  # Reuse the same container
    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)



Streaming

Avec le streaming activé, vous recevrez les événements d'exécution de code au fur et à mesure qu'ils se produisent :

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

// Code execution streamed
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"code\":\"import pandas as pd\\ndf = pd.read_csv('data.csv')\\nprint(df.head())\"}"}}

// Pause while code executes

// Execution results streamed
event: content_block_start
data: {"type": "content_block_start", "index": 2, "content_block": {"type": "code_execution_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": {"stdout": "   A  B  C\n0  1  2  3\n1  4  5  6", "stderr": ""}}}



Requêtes par lots

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



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

En passant à code-execution-2025-08-25, vous obtenez l'accès à la manipulation de fichiers et aux capacités Bash, y compris le code dans plusieurs langages. Il n'y a aucune différence de prix.



Ce qui a changé



Rétrocompatibilité

• Toute l'exécution de code Python existante continue de fonctionner exactement comme avant
• Aucune modification requise pour les workflows existants utilisant uniquement Python



Étapes de mise à niveau

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

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

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

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



Appel d'outils programmatique

Pour exécuter des outils à l'intérieur du conteneur d'exécution de code, consultez Appel d'outils programmatique.



Conservation des données

L'exécution de code s'effectue 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 l'API Files (récupérables via 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.



Utiliser l'exécution de code avec les Agent Skills

L'outil d'exécution de code permet à Claude d'utiliser les Agent Skills. Les Skills sont des capacités modulaires composées d'instructions, de scripts et de ressources qui étendent les fonctionnalités de Claude.

Pour en savoir plus, consultez Agent Skills et Utiliser les Agent Skills avec l'API.