L’outil d’exécution de code permet à Claude d’exécuter du code Python dans un environnement sécurisé et isolé. Claude peut analyser des données, créer des visualisations, effectuer des calculs complexes et traiter des fichiers téléchargés directement dans la conversation API.

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

Cette fonctionnalité nécessite l’en-tête bêta : "anthropic-beta": "code-execution-2025-05-22"

​
Modèles pris en charge

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

  • 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-05-22" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-20250514",
        "max_tokens": 4096,
        "messages": [
            {
                "role": "user",
                "content": "Calculez la moyenne et l'écart-type de [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]"
            }
        ],
        "tools": [{
            "type": "code_execution_20250522",
            "name": "code_execution"
        }]
    }'

​
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. Claude écrit et exécute du code Python dans un environnement sandbox sécurisé
  3. L’exécution de code peut se produire plusieurs fois au cours d’une seule requête
  4. Claude fournit les résultats avec tous les graphiques, calculs ou analyses générés

​
Définition de l’outil

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

JSON
{
  "type": "code_execution_20250522",
  "name": "code_execution"
}

​
Format de réponse

Voici un exemple de réponse avec exécution de code :

{
  "role": "assistant",
  "container": {
    "id": "container_011CPR5CNjB747bTd36fQLFk",
    "expires_at": "2025-05-23T21:13:31.749448Z"
  },
  "content": [
    {
      "type": "text",
      "text": "Je vais calculer la moyenne et l'écart-type pour vous."
    },
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01A2B3C4D5E6F7G8H9I0J1K2",
      "name": "code_execution",
      "input": {
        "code": "import numpy as np\ndata = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]\nmean = np.mean(data)\nstd = np.std(data)\nprint(f\"Moyenne: {mean}\")\nprint(f\"Écart-type: {std}\")"
      }
    },
    {
      "type": "code_execution_tool_result",
      "tool_use_id": "srvtoolu_01A2B3C4D5E6F7G8H9I0J1K2",
      "content": {
        "type": "code_execution_result",
        "stdout": "Moyenne: 5.5\nÉcart-type: 2.8722813232690143\n",
        "stderr": "",
        "return_code": 0
      }
    },
    {
      "type": "text",
      "text": "La moyenne du jeu de données est 5,5 et l'écart-type est d'environ 2,87."
    }
  ],
  "id": "msg_01BqK2v4FnRs4xTjgL8EuZxz",
  "model": "claude-opus-4-20250514",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 45,
    "output_tokens": 187,
  }
}

​
Résultats

Les résultats d’exécution de code incluent :

  • stdout : Sortie des instructions print et de l’exécution réussie
  • stderr : Messages d’erreur si l’exécution du code échoue
  • return_code (0 pour le succès, non-zéro pour l’échec)
{
  "type": "code_execution_tool_result",
  "tool_use_id": "srvtoolu_01ABC123",
  "content": {
    "type": "code_execution_result",
    "stdout": "",
    "stderr": "NameError: name 'undefined_variable' is not defined",
    "return_code": 1
  }
}

​
Erreurs

S’il y a une erreur lors de l’utilisation de l’outil, il y aura un code_execution_tool_result_error

{
  "type": "code_execution_tool_result",
  "tool_use_id": "srvtoolu_01VfmxgZ46TiHbmXgy928hQR",
  "content": {
    "type": "code_execution_tool_result_error",
    "error_code": "unavailable"
  }
}

Les erreurs possibles incluent

  • unavailable : L’outil d’exécution de code n’est pas disponible
  • code_execution_exceeded : Le temps d’exécution a dépassé le maximum autorisé
  • container_expired : Le conteneur a expiré et n’est pas disponible

​
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.

​
Travailler avec des fichiers dans l’exécution de code

L’exécution de code peut analyser des fichiers téléchargés via l’API Files, tels que des fichiers CSV, des fichiers Excel et d’autres formats de données. Cela permet à Claude de lire, traiter et générer des insights à partir de vos données. Vous pouvez passer plusieurs fichiers par 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-05-22,files-api-2025-04-14"

​
Types de fichiers pris en charge

L’environnement Python est capable de travailler avec, mais sans s’y limiter, les types de fichiers suivants

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

​
Chargement de fichiers pour l’exécution de code

  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 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-05-22,files-api-2025-04-14" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-20250514",
        "max_tokens": 4096,
        "messages": [{
            "role": "user",
            "content": [
                {"type": "text", "text": "Analysez ces données CSV"},
                {"type": "container_upload", "file_id": "file_abc123"}
            ]
        }],
        "tools": [{
            "type": "code_execution_20250522",
            "name": "code_execution"
        }]
    }'

​
Récupération de fichiers créés par l’exécution de code

Lorsque Claude crée des fichiers pendant l’exécution de code (par exemple, sauvegarder des graphiques matplotlib, générer des CSV), vous pouvez récupérer ces fichiers en utilisant l’API Files :

from anthropic import Anthropic

# Initialisez le client
client = Anthropic()

# Demandez une exécution de code qui crée des fichiers
response = client.beta.messages.create(
    model="claude-opus-4-20250514",
    betas=["code-execution-2025-05-22", "files-api-2025-04-14"],
    max_tokens=4096,
    messages=[{
        "role": "user",
        "content": "Créez une visualisation matplotlib et sauvegardez-la comme output.png"
    }],
    tools=[{
        "type": "code_execution_20250522",
        "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 == '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"Téléchargé : {file_metadata.filename}")

​
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 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
  • Traitement de fichiers : pyarrow, openpyxl, xlrd, pillow
  • Mathématiques et calcul : sympy, mpmath
  • Utilitaires : tqdm, python-dateutil, pytz, joblib

​
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-20250514",
    betas=["code-execution-2025-05-22"],
    max_tokens=4096,
    messages=[{
        "role": "user",
        "content": "Écrivez un fichier avec un nombre aléatoire et sauvegardez-le dans '/tmp/number.txt'"
    }],
    tools=[{
        "type": "code_execution_20250522",
        "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-20250514",
    betas=["code-execution-2025-05-22"],
    max_tokens=4096,
    messages=[{
        "role": "user",
        "content": "Lisez le nombre de '/tmp/number.txt' et calculez son carré"
    }],
    tools=[{
        "type": "code_execution_20250522",
        "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.