MessagesOutils

Outil d'exécution de code

Exécutez du code Python et bash dans un conteneur isolé pour analyser des données, générer des fichiers et itérer sur des solutions.

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éversés directement au sein de la conversation API. L'outil d'exécution de code (« code execution tool ») permet à Claude d'exécuter des commandes Bash et de manipuler des fichiers, y compris d'écrire du code, dans un environnement sécurisé et isolé en « sandbox » (bac à sable).

L'exécution de code est gratuite lorsqu'elle est utilisée avec la recherche web ou la récupération web (web_search_20260209, web_fetch_20260209 ou ultérieur). Lorsque l'un de ces outils figure dans votre requête, aucun frais supplémentaire n'est facturé pour l'exécution de code dans cette requête au-delà des coûts standard en tokens. Cela couvre à la fois l'exécution de code derrière le filtrage dynamique et tout code que Claude exécute directement. La tarification standard de l'exécution de code s'applique lorsqu'ils ne sont pas inclus.

L'exécution de code alimente également le filtrage dynamique dans les outils de recherche web et de récupération web : Claude filtre les résultats à l'intérieur de l'environnement d'exécution de code avant qu'ils n'atteignent la « context window » (fenêtre de contexte). Lorsque le filtrage dynamique s'exécute, l'API provisionne automatiquement l'exécution de code dont elle a besoin pour la requête, vous n'avez donc pas à ajouter l'outil d'exécution de code à votre requête pour cela.

Versions de l'outil

L'outil d'exécution de code possède trois versions actuelles, et chaque modèle pris en charge accepte les trois. Chaque version s'appuie sur la précédente :

code_execution_20250825 prend en charge les commandes Bash et les opérations sur les fichiers.
code_execution_20260120 ajoute la persistance de l'état REPL et l'appel d'outils programmatique (« programmatic tool calling ») depuis l'intérieur de la sandbox. Claude Haiku 4.5 accepte les types d'outils code_execution_20260120 et code_execution_20260521, mais l'appel d'outils programmatique et la persistance de l'état REPL qui en dépend n'y sont pas disponibles, de sorte que les versions plus récentes s'y comportent comme code_execution_20250825.
code_execution_20260521 est le même environnement d'exécution que code_execution_20260120. La différence est que la description de l'outil informe Claude de la limite de 90 secondes de temps réel sur chaque cellule Python dans l'appel d'outils programmatique, afin que Claude puisse planifier les cellules de longue durée. Une cellule qui dépasse la limite renvoie un résultat d'exécution de code normal avec un return_code non nul et un message d'état detection_timeout dans sa sortie. Ceci est distinct du code d'erreur execution_time_exceeded, que l'API renvoie lorsqu'une invocation d'outil entière dépasse le temps d'exécution maximal.

Aucune des trois versions de l'outil ne nécessite d'en-tête anthropic-beta. Les anciens en-têtes bêta d'exécution de code restent des options d'activation valides.

Les exemples de cette page utilisent code_execution_20250825, qui couvre les opérations Bash et sur fichiers qu'ils illustrent et se comporte de la même manière sur chaque modèle pris en charge ; utilisez code_execution_20260120 ou ultérieur lorsque vous avez besoin de l'appel d'outils programmatique ou de la persistance de l'état REPL. Les outils actuels de recherche web et de récupération web (web_search_20260209, web_fetch_20260209 et ultérieurs) nécessitent code_execution_20260120 ou ultérieur comme version d'exécution de code.

La compatibilité des anciennes versions de l'outil avec les modèles plus récents n'est pas garantie. Lorsque vous adoptez un nouveau modèle, consultez Versions de l'outil et Compatibilité, et privilégiez la version de l'outil la plus récente que votre intégration prend en charge.

Pour vérifier si un modèle accepte l'outil d'exécution de code avant d'envoyer une requête, lisez sa valeur capabilities.server_tools.code_execution.supported depuis l'API Models. N'utilisez pas la valeur de premier niveau capabilities.code_execution à cette fin. Elle indique si le code exécuté dans cet outil peut appeler les autres outils de votre requête, comme dans l'appel d'outils programmatique. Utiliser l'API Models décrit les deux champs.

Démarrage rapide

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Use the code execution tool to 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.to_json())

La réponse entrelace des blocs server_tool_use (les commandes exécutées par Claude) avec leurs blocs de résultat d'outil, suivis du texte de Claude. Le niveau supérieur inclut également un objet container dont vous pouvez réutiliser l'id entre les requêtes. Consultez Format de réponse pour la structure des blocs.

Fonctionnement de 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
- Opérations sur les fichiers : créer, afficher et modifier des fichiers directement, y compris écrire du 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 conteneur sandbox sécurisé. Le conteneur n'a pas d'accès à Internet, Claude ne peut donc pas télécharger de paquets à l'exécution : seules les bibliothèques préinstallées sont disponibles
L'API exécute chaque commande côté serveur et renvoie les résultats à Claude au sein de la même requête, vous n'exécutez donc jamais de code ni ne renvoyez vous-même de blocs tool_result. Une exception survient lorsque Claude appelle l'un de vos outils client en parallèle de l'exécution de code : l'API renvoie l'appel d'exécution de code sans son résultat. Le résultat arrive dans une réponse ultérieure, après que vous avez renvoyé les blocs tool_result pour vos outils client
Chaque requête s'exécute dans un nouveau conteneur, sauf si vous retransmettez l'ID de conteneur d'une réponse précédente (voir Réutilisation des conteneurs)
Claude fournit les résultats avec tous les graphiques, calculs ou analyses générés

Python est préinstallé dans le conteneur. Claude écrit du Python avec le sous-outil d'opérations sur les fichiers et l'exécute avec une commande Bash. Avec code_execution_20260120 ou ultérieur et l'appel d'outils programmatique, l'état de l'interpréteur Python (comme les liaisons de variables) persiste également entre les requêtes qui réutilisent le conteneur.

Quand Claude exécute du code

Claude exécute du code lorsque la requête bénéficie d'un calcul ou d'une manipulation de fichiers :

Mathématiques non triviales (grands nombres, nombreuses étapes, résultats sensibles à la précision)
Analyse de données, analyse de fichiers ou visualisation
Exécution d'algorithmes ou simulation
Demandes explicites d'« exécuter », de « calculer » ou de « lancer »

Claude répond directement sans exécuter de code pour :

L'arithmétique simple et les faits mathématiques bien connus
Les demandes factuelles, conversationnelles ou créatives
Les conversions d'unités ou traductions simples

Si vous souhaitez que Claude exécute du code pour une demande limite, demandez-le explicitement (par exemple, « exécute du code pour vérifier cela »).

Travailler avec des fichiers

Téléverser et analyser vos propres fichiers

Pour analyser vos propres fichiers de données (tels que CSV, Excel ou images), téléversez-les via la Files API et référencez-les dans votre requête.

L'environnement Python peut traiter divers types de fichiers téléversés via la Files API, notamment :

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

Téléverser et analyser des fichiers

Téléversez votre fichier à l'aide de la Files API
Référencez le fichier dans votre message à l'aide d'un bloc de contenu container_upload
Incluez l'outil d'exécution de code dans votre requête API

client = anthropic.Anthropic()

# Téléverser un fichier
file_object = client.files.upload(file=Path("data.csv"))

# Utiliser le file_id avec l'exécution de code
response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Analyze this CSV data"},
                {"type": "container_upload", "file_id": file_object.id},
            ],
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

print(response.to_json())

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

Lorsque Claude enregistre des fichiers dans son répertoire de sortie pendant l'exécution de code (voir Comment les fichiers générés sont capturés), l'ID de chaque fichier apparaît dans le résultat de l'outil d'exécution de code, et vous pouvez le télécharger avec la Files API :

client = Anthropic()

# Demander une exécution de code qui crée des fichiers
response = client.messages.create(
    model="claude-opus-5-5",
    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"}],
)


# Extraire les ID de fichiers de la réponse
def extract_file_ids(response: Message) -> list[str]:
    file_ids: list[str] = []
    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 output_block in content_item.content:
                    file_ids.append(output_block.file_id)
    return file_ids


# Télécharger les fichiers créés
for file_id in extract_file_ids(response):

Versions de l'outil

Démarrage rapide

Fonctionnement de l'exécution de code

Quand Claude exécute du code

Travailler avec des fichiers

Téléverser et analyser vos propres fichiers

Téléverser et analyser des fichiers

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