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échargés directement dans 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 l’écriture de code, dans un environnement sécurisé et isolé.

L’outil d’exécution de code est actuellement en version bêta publique.

Pour utiliser cette fonctionnalité, ajoutez l’en-tête bêta "code-execution-2025-08-25" à vos requêtes API.

Nous avons récemment mis à niveau l’outil d’exécution de code pour prendre en charge les commandes Bash et la manipulation directe de fichiers. Pour des instructions sur la mise à niveau vers la dernière version de l’outil, voir Mise à niveau vers la dernière version de l’outil.

Modèles pris en charge

L’outil d’exécution de code est disponible sur :

Claude Opus 4.1 (claude-opus-4-1-20250805)
Claude Opus 4 (claude-opus-4-20250514)
Claude Sonnet 4 (claude-sonnet-4-20250514)
Claude Sonnet 3.7 (claude-3-7-sonnet-20250219)
Claude Haiku 3.5 (claude-3-5-haiku-latest)

Démarrage rapide

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

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: code-execution-2025-08-25" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-1-20250805",
        "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"
        }]
    }'

Comment fonctionne l’exécution de code

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

Claude évalue si l’exécution de code aiderait à répondre à votre question
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, visualiser et modifier des fichiers directement, y compris l’écriture de code
Claude peut utiliser n’importe quelle combinaison de ces capacités dans une seule requête
Toutes les opérations s’exécutent dans un environnement sandbox sécurisé
Claude fournit les résultats avec tous les graphiques générés, calculs ou analyses

Comment utiliser l’outil

Exécuter des commandes Bash

Demandez à Claude de vérifier les informations système et d’installer des paquets :

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: code-execution-2025-08-25" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-1-20250805",
        "max_tokens": 4096,
        "messages": [{
            "role": "user",
            "content": "Check the Python version and list installed packages"
        }],
        "tools": [{
            "type": "code_execution_20250825",
            "name": "code_execution"
        }]
    }'

Créer et modifier des fichiers directement

Claude peut créer, visualiser et modifier des fichiers directement dans le sandbox en utilisant les capacités de manipulation de fichiers :

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: code-execution-2025-08-25" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-1-20250805",
        "max_tokens": 4096,
        "messages": [{
            "role": "user",
            "content": "Create a config.yaml file with database settings, then update the port from 5432 to 3306"
        }],
        "tools": [{
            "type": "code_execution_20250825",
            "name": "code_execution"
        }]
    }'

Télécharger et analyser vos propres fichiers

Pour analyser vos propres fichiers de données (CSV, Excel, images, etc.), téléchargez-les via l’API Files et référencez-les dans votre requête :

L’utilisation de l’API Files avec l’exécution de code nécessite deux en-têtes bêta : "anthropic-beta": "code-execution-2025-08-25,files-api-2025-04-14"

L’environnement Python peut traiter divers types de fichiers téléchargés via l’API Files, notamment :

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

Télécharger et analyser des fichiers

Téléchargez votre fichier en utilisant l’API Files
Référencez le fichier dans votre message en utilisant un bloc de contenu container_upload
Incluez l’outil d’exécution de code dans votre requête API

# D'abord, téléchargez un fichier
curl https://api.anthropic.com/v1/files \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: files-api-2025-04-14" \
    --form 'file=@"data.csv"' \

# Ensuite, utilisez le file_id avec l'exécution de code
curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: code-execution-2025-08-25,files-api-2025-04-14" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-1-20250805",
        "max_tokens": 4096,
        "messages": [{
            "role": "user",
            "content": [
                {"type": "text", "text": "Analyze this CSV data"},
                {"type": "container_upload", "file_id": "file_abc123"}
            ]
        }],
        "tools": [{
            "type": "code_execution_20250825",
            "name": "code_execution"
        }]
    }'

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 en utilisant l’API Files :

from anthropic import Anthropic

# Initialisez le client
client = Anthropic()

# Demandez l'exécution de code qui crée des fichiers
response = client.beta.messages.create(
    model="claude-opus-4-1-20250805",
    betas=["code-execution-2025-08-25", "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"
    }]
)

# Extrayez les ID 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.get('type') == 'code_execution_result':
                for file in content_item.get('content', []):
                    file_ids.append(file['file_id'])
    return file_ids

# Téléchargez 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}")

Combiner les opérations

Un flux de travail complexe utilisant toutes les capacités :

# D'abord, téléchargez un fichier
curl https://api.anthropic.com/v1/files \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: files-api-2025-04-14" \
    --form 'file=@"data.csv"' \
    > file_response.json

# Extrayez le file_id (en utilisant jq)
FILE_ID=$(jq -r '.id' file_response.json)

# Ensuite, utilisez-le avec l'exécution de code
curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: code-execution-2025-08-25,files-api-2025-04-14" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-1-20250805",
        "max_tokens": 4096,
        "messages": [{
            "role": "user",
            "content": [
                {
                    "type": "text", 
                    "text": "Analyze this CSV data: create a summary report, save visualizations, and create a README with the findings"
                },
                {
                    "type": "container_upload", 
                    "file_id": "'$FILE_ID'"
                }
            ]
        }],
        "tools": [{
            "type": "code_execution_20250825",
            "name": "code_execution"
        }]
    }'

Définition de l’outil

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

JSON
{
  "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 : Visualiser, créer et modifier des fichiers, y compris l’écriture de code

Format de réponse

L’outil d’exécution de code peut retourner 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

Visualiser 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 de l’exécution réussie
stderr : Messages d’erreur si l’exécution échoue
return_code : 0 pour le succès, non-zéro pour l’échec

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

Visualiser : file_type, content, numLines, startLine, totalLines
Créer : is_file_update (si le fichier existait déjà)
Modifier : oldStart, oldLines, newStart, newLines, lines (format diff)

Erreurs

Chaque type d’outil peut retourner 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 :

Outil	Code d’erreur	Description
Tous les outils	`unavailable`	L’outil est temporairement indisponible
Tous les outils	`execution_time_exceeded`	L’exécution a dépassé la limite de temps maximale
Tous les outils	`container_expired`	Le conteneur a expiré et n’est plus disponible
Tous les outils	`invalid_tool_input`	Paramètres invalides fournis à l’outil
Tous les outils	`too_many_requests`	Limite de taux dépassée pour l’utilisation de l’outil
text_editor	`file_not_found`	Le fichier n’existe pas (pour les opérations view/edit)
text_editor	`string_not_found`	Le `old_str` n’a pas été trouvé dans le fichier (pour str_replace)

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 fournir 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 plus élevé sur Python.

Environnement d’exécution

Version Python : 3.11.12
Système d’exploitation : Conteneur basé sur Linux
Architecture : x86_64 (AMD64)

Limites de ressources

Mémoire : 1GiB RAM
Espace disque : 5GiB de stockage d’espace de travail
CPU : 1 CPU

Réseau et sécurité

Accès Internet : Complètement désactivé pour la 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 d’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 1 heure après la création

Bibliothèques pré-installées

L’environnement Python en 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, 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 à travers plusieurs requêtes API en fournissant l’ID de conteneur d’une réponse précédente. Cela vous permet de maintenir les fichiers créés entre les requêtes.

Exemple

import os
from anthropic import Anthropic

# Initialisez le client
client = Anthropic(
    api_key=os.getenv("ANTHROPIC_API_KEY")
)

# Première requête : Créez un fichier avec un nombre aléatoire
response1 = client.beta.messages.create(
    model="claude-opus-4-1-20250805",
    betas=["code-execution-2025-08-25"],
    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"
    }]
)

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

# Deuxième requête : Réutilisez le conteneur pour lire le fichier
response2 = client.beta.messages.create(
    container=container_id,  # Réutilisez le même conteneur
    model="claude-opus-4-1-20250805",
    betas=["code-execution-2025-08-25"],
    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"
    }]
)

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

// Exécution de code streamée
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 pendant l'exécution du code

// Résultats d'exécution streamés
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 d’outil d’exécution de code via l’API Messages Batches sont facturés de la même manière que ceux dans les requêtes API Messages régulières.

Utilisation et tarification

The code execution tool usage is tracked separately from token usage. Execution time is a minimum of 5 minutes. If files are included in the request, execution time is billed even if the tool is not used due to files being preloaded onto the container.

Pricing: $0.05 per session-hour.

Mise à 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 pas de différence de prix.

Ce qui a changé

Composant	Hérité	Actuel
En-tête bêta	`code-execution-2025-05-22`	`code-execution-2025-08-25`
Type d’outil	`code_execution_20250522`	`code_execution_20250825`
Capacités	Python uniquement	Commandes Bash, opérations sur les fichiers
Types de réponse	`code_execution_result`	`bash_code_execution_result`, `text_editor_code_execution_result`

Compatibilité descendante

Toute l’exécution de code Python existante continue de fonctionner exactement comme avant
Aucun changement requis pour les flux de travail Python uniquement existants

Étapes de mise à niveau

Pour effectuer la mise à niveau, vous devez apporter les modifications suivantes dans vos requêtes API :

Mettez à jour l’en-tête bêta :

- "anthropic-beta": "code-execution-2025-05-22"
+ "anthropic-beta": "code-execution-2025-08-25"

Mettez à jour le type d’outil :

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

Révisez la gestion des réponses (si vous analysez les réponses par programmation) :
- 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 la section Format de réponse)

Outil bash Outil d'utilisation d'ordinateur

On this page

Modèles pris en charge
Démarrage rapide
Comment fonctionne l’exécution de code
Comment utiliser l’outil
Exécuter des commandes Bash
Créer et modifier des fichiers directement
Télécharger et analyser vos propres fichiers
Télécharger et analyser des fichiers
Récupérer les fichiers générés
Combiner les opérations
Définition de l’outil
Format de réponse
Réponse de commande Bash
Réponses d’opérations sur les fichiers
Résultats
Erreurs
Raison d’arrêt pause_turn
Conteneurs
Environnement d’exécution
Limites de ressources
Réseau et sécurité
Bibliothèques pré-installées
Réutilisation de conteneur
Exemple
Streaming
Requêtes par lots
Utilisation et tarification
Mise à niveau vers la dernière version de l’outil
Ce qui a changé
Compatibilité descendante
Étapes de mise à niveau

Premiers pas

Modèles et tarification

En savoir plus sur Claude

Capacités

Outils

Protocole de Contexte de Modèle (MCP)

Cas d'usage

Ingénierie de prompts

Tester et évaluer

Renforcer les garde-fous

Centre juridique

​Modèles pris en charge

​Démarrage rapide

​Comment fonctionne l’exécution de code

​Comment utiliser l’outil

​Exécuter des commandes Bash

​Créer et modifier des fichiers directement

​Télécharger et analyser vos propres fichiers

​Télécharger et analyser des fichiers

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

​Combiner les opérations

​Définition de l’outil

​Format de réponse

​Réponse de commande Bash

​Réponses d’opérations sur les fichiers

​Résultats

​Erreurs

​Raison d’arrêt pause_turn

​Conteneurs

​Environnement d’exécution

​Limites de ressources

​Réseau et sécurité

​Bibliothèques pré-installées

​Réutilisation de conteneur

​Exemple

​Streaming

​Requêtes par lots

​Utilisation et tarification

​Mise à niveau vers la dernière version de l’outil

​Ce qui a changé

​Compatibilité descendante

​Étapes de mise à niveau

Modèles pris en charge

Démarrage rapide

Comment fonctionne l’exécution de code

Comment utiliser l’outil

Exécuter des commandes Bash

Créer et modifier des fichiers directement

Télécharger et analyser vos propres fichiers

Télécharger et analyser des fichiers

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

Combiner les opérations

Définition de l’outil

Format de réponse

Réponse de commande Bash

Réponses d’opérations sur les fichiers

Résultats

Erreurs

Raison d’arrêt `pause_turn`

Conteneurs

Environnement d’exécution

Limites de ressources

Réseau et sécurité

Bibliothèques pré-installées

Réutilisation de conteneur

Exemple

Streaming

Requêtes par lots

Utilisation et tarification

Mise à niveau vers la dernière version de l’outil

Ce qui a changé

Compatibilité descendante

Étapes de mise à niveau