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 les 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é.

Compatibilité des modèles

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

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-sonnet-4-5",
        "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"
        }]
    }'

import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-sonnet-4-5",
    betas=["code-execution-2025-08-25"],
    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)

import { Anthropic } from '@anthropic-ai/sdk';

const anthropic = new Anthropic();

async function main() {
  const response = await anthropic.beta.messages.create({
    model: "claude-sonnet-4-5",
    betas: ["code-execution-2025-08-25"],
    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"
    }]
  });

  console.log(response);
}

main().catch(console.error);

Fonctionnement de l'exécution de code

Lorsque vous ajoutez l'outil d'exécution de code à votre demande 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 demande
4. Toutes les opérations s'exécutent dans un environnement sandbox sécurisé
5. 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-sonnet-4-5",
        "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, afficher 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-sonnet-4-5",
        "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 demande :

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

1. Téléchargez votre fichier en utilisant l'API Files
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 demande API

# First, upload a file
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"' \

# Then use the file_id with code execution
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-sonnet-4-5",
        "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 lors de l'exécution de code, vous pouvez récupérer ces fichiers en utilisant l'API Files :

from anthropic import Anthropic

# Initialize the client
client = Anthropic()

# Request code execution that creates files
response = client.beta.messages.create(
    model="claude-sonnet-4-5",
    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"
    }]
)

# Extract file IDs from the response
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':
                for file in content_item.content:
                    if hasattr(file, 'file_id'):
                        file_ids.append(file.file_id)
    return file_ids

# Download the created files
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 :

# First, upload a file
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

# Extract file_id (using jq)
FILE_ID=$(jq -r '.id' file_response.json)

# Then use it with code execution
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-sonnet-4-5",
        "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 :

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

Lorsque cet outil est fourni, Claude accède automatiquement à 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 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ération sur fichiers

Afficher le 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 fichiers :

• Afficher : 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 courantes (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 :

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 demande ultérieure pour permettre à Claude de 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 : 5 GiB de RAM
• Espace disque : 5 GiB 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 demande 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 d'espace de travail uniquement
• Portée de l'espace de travail : Comme 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 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, xlsxwriter, xlrd, pillow, python-pptx, python-docx, pypdf, pdfplumber, pypdfium2, pdf2image, pdfkit, tabula-py, reportlab[pycairo], Img2pdf
• Mathématiques et informatique : sympy, mpmath
• Utilitaires : tqdm, python-dateutil, pytz, joblib, unzip, unrar, 7zip, bc, rg (ripgrep), fd, sqlite

Réutilisation de conteneurs

Vous pouvez réutiliser un conteneur existant sur plusieurs demandes 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 demandes.

Exemple

import os
from anthropic import Anthropic

# Initialize the client
client = Anthropic(
    api_key=os.getenv("ANTHROPIC_API_KEY")
)

# First request: Create a file with a random number
response1 = client.beta.messages.create(
    model="claude-sonnet-4-5",
    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"
    }]
)

# Extract the container ID from the first response
container_id = response1.container.id

# Second request: Reuse the container to read the file
response2 = client.beta.messages.create(
    container=container_id,  # Reuse the same container
    model="claude-sonnet-4-5",
    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"}}

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

Demandes par lot

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 demandes API Messages régulières.

Utilisation et tarification

Code execution tool usage is tracked separately from token usage. Execution time has 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.

Each organization receives 50 free hours of usage with the code execution tool per day. Additional usage beyond the first 50 hours is billed at $0.05 per hour, per container.

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

En mettant à jour vers code-execution-2025-08-25, vous accédez aux capacités de manipulation de fichiers et Bash, y compris le code dans plusieurs langues. Il n'y a pas de différence de prix.

Ce qui a changé

Compatibilité rétroactive

• Tout le code d'exécution Python existant continue de fonctionner exactement comme avant
• Aucune modification requise pour les flux de travail existants Python uniquement

Étapes de mise à jour

Pour mettre à jour, vous devez apporter les modifications suivantes dans vos demandes API :

1. Mettez à jour l'en-tête bêta :

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

2. Mettez à jour le type d'outil :

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

3. Examinez 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, les nouveaux types de réponse pour les opérations Bash et fichiers seront envoyés (voir la section Format de réponse)

Utiliser l'exécution de code avec Agent Skills

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

En savoir plus dans la documentation Agent Skills et le guide API Agent Skills.