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.

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": "Calculate the mean and standard deviation of [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 des résultats avec des graphiques, des calculs ou des 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",
  "content": [
    {
      "type": "text",
      "text": "I'll calculate the mean and standard deviation for you."
    },
    {
      "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\"Mean: {mean}\")\nprint(f\"Standard deviation: {std}\")"
      }
    },
    {
      "type": "code_execution_tool_result",
      "tool_use_id": "srvtoolu_01A2B3C4D5E6F7G8H9I0J1K2",
      "content": {
        "type": "code_execution_result",
        "stdout": "Mean: 5.5\nStandard deviation: 2.8722813232690143\n",
        "stderr": "",
        "return_code": 0
      }
    },
    {
      "type": "text",
      "text": "The mean of the dataset is 5.5 and the standard deviation is approximately 2.87."
    }
  ],
  "id": "msg_01BqK2v4FnRs4xTjgL8EuZxz",
  "model": "claude-opus-4-20250514",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 45,
    "output_tokens": 187,
    "server_tool_use": {
      "execution_time_seconds": 1.5
    }
  }
}

​
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 succès, non-zéro pour é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 est 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 renvoyer la réponse telle quelle dans une requête 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 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 : 1 Go de RAM
  • Espace disque : 5 Go d’espace de stockage de travail
  • CPU : 1 CPU
  • Délai d’exécution : L’exécution est limitée par requête de messages et peut être contrôlée avec le paramètre max_execution_duration
  • Expiration du conteneur : Après 1 heure d’inactivité, le conteneur ne peut plus être accessible

​
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 travail uniquement

​
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
  • Mathématiques et calcul : sympy, mpmath
  • Utilitaires : tqdm, python-dateutil, pytz, joblib

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

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

​
Exemple

  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": "Analyze this CSV data"},
                {"type": "container_upload", "file_id": "file_abc123"}
            ]
        }],
        "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"}}

// 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 d’outil d’exécution de code via l’API Messages Batches sont facturés au même prix que ceux des requêtes API Messages régulières.

​
Utilisation et tarification

L’utilisation de l’outil d’exécution de code est suivie séparément de l’utilisation des tokens. Le temps d’exécution est d’un minimum de 5 minutes. Si des fichiers sont inclus dans la requête, le temps d’exécution est facturé même si l’outil n’est pas utilisé en raison du préchargement des fichiers sur le conteneur.

Tarification : 0,05 $ par heure de session.