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 sandbox sécurisé.

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 web_fetch_20260209 est inclus dans votre requête, il n'y a pas de frais supplémentaires pour les appels à l'outil d'exécution de code au-delà des coûts standard des 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 fondamentale pour la construction d'agents haute performance. Elle permet un 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 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)
• Microsoft Azure AI Foundry

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

Démarrage rapide

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

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 packages
   • 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 tous les graphiques générés, calculs ou analyses

Utilisation de l'exécution de code avec d'autres outils d'exécution

Lorsque vous fournissez l'exécution de code aux côtés 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 séparé que vous contrôlez. Claude peut parfois confondre ces environnements, tentant d'utiliser le mauvais outil ou supposant que l'état est partagé entre eux.

Pour éviter cela, ajoutez des instructions à votre prompt 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 lors de la combinaison de l'exécution de code avec la recherche web ou la récupération web, qui activent l'exécution de code automatiquement. 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

Exécuter des commandes Bash

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

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 :

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'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 requête API

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 :

Combiner les opérations

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

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

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

Champs supplémentaires pour les opérations sur les 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 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 :

Raison d'arrêt pause_turn

La réponse peut inclure une raison d'arrêt pause_turn, ce 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 important 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 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 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 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 calcul : sympy, mpmath
• Utilitaires : tqdm, python-dateutil, pytz, joblib, unzip, unrar, 7zip, bc, rg (ripgrep), fd, sqlite

Réutilisation des conteneurs

Vous pouvez réutiliser un conteneur existant sur plusieurs requêtes API en fournissant l'ID du conteneur d'une réponse précédente. Cela vous permet de maintenir les fichiers créés entre les requêtes.

Exemple

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 tarifés de la même manière que ceux des requêtes API Messages régulières.

Utilisation et tarification

Code execution is free when used with web search or web fetch. When web_search_20260209 or web_fetch_20260209 is included in your API request, there are no additional charges for code execution tool calls beyond the standard input and output token costs.

When used without these tools, code execution is billed by execution time, tracked separately from token usage:

• Execution time has a minimum of 5 minutes
• Each organization receives 1,550 free hours of usage per month
• Additional usage beyond 1,550 hours is billed at $0.05 per hour, per container
• If files are included in the request, execution time is billed even if the tool is not invoked, due to files being preloaded onto the container

Code execution usage is tracked in the response:

"usage": {
  "input_tokens": 105,
  "output_tokens": 239,
  "server_tool_use": {
    "code_execution_requests": 1
  }
}

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

En passant à code-execution-2025-08-25, vous accédez à 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é

Compatibilité ascendante

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

Étapes de mise à niveau

Pour mettre à 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 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 Bash et les opérations sur les fichiers seront envoyés (voir la section Format de réponse)

Appel d'outils par programmation

L'outil d'exécution de code alimente l'appel d'outils par programmation, qui permet à Claude d'écrire du code qui appelle vos outils personnalisés par programmation dans le conteneur d'exécution. Cela permet des flux de travail multi-outils efficaces, le filtrage des données avant qu'elles n'atteignent le contexte de Claude, et une logique conditionnelle complexe.

# Enable programmatic calling for your tools
response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=4096,
    messages=[
        {"role": "user", "content": "Get weather for 5 cities and find the warmest"}
    ],
    tools=[
        {"type": "code_execution_20250825", "name": "code_execution"},
        {
            "name": "get_weather",
            "description": "Get weather for a city",
            "input_schema": {...},
            "allowed_callers": [
                "code_execution_20250825"
            ],  # Enable programmatic calling
        },
    ],
)

En savoir plus dans la documentation sur l'appel d'outils par programmation.

Conservation des données

L'exécution de code s'effectue dans des conteneurs sandbox côté serveur. Les données des conteneurs, y compris les artefacts d'exécution, les fichiers téléchargés et les sorties, sont conservées pendant 30 jours maximum. Cette conservation s'applique à toutes les données traitées dans l'environnement du conteneur.

Pour l'éligibilité ZDR sur toutes les fonctionnalités, consultez API et conservation des données.

Utilisation de 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 la documentation des Agent Skills et le guide de l'API des Agent Skills.