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

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 versions ultérieures). 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 des 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 dispose 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 depuis le bac à sable. 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 utilise 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 en 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’un appel d’outil entier dépasse le temps d’exécution maximal.

Pour Claude Mythos Preview, l’exécution de code est prise en charge sur la Claude API et Microsoft Foundry.

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 les 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 une version ultérieure 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 versions ultérieures) nécessitent code_execution_20260120 ou une version ultérieure comme version d’exécution de code.

Les anciennes versions de l’outil ne sont pas garanties de rester compatibles avec les modèles plus récents. Lorsque vous adoptez un nouveau modèle, consultez Versions de l’outil et Prise en charge de l’API, 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 la Models API. N’utilisez pas la valeur de premier niveau capabilities.code_execution pour cela. 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 la Models API 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 d’une requête à l’autre. 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 :

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
   • Opérations sur les fichiers : créer, afficher et modifier des fichiers directement, y compris écrire du 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 conteneur isolé et sécurisé. Le conteneur n’a pas d’accès à Internet, Claude ne peut donc pas télécharger de paquets pendant l’exécution : seules les bibliothèques préinstallées sont disponibles.
5. L’API exécute chaque commande côté serveur et renvoie les résultats à Claude dans la même requête, de sorte que vous n’exécutez jamais de code et ne renvoyez jamais vous-même de blocs tool_result. Une exception se présente 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 de vos outils client.
6. Chaque requête s’exécute dans un nouveau conteneur, sauf si vous renvoyez l’ID de conteneur d’une réponse précédente (consultez Réutilisation des conteneurs).
7. Claude fournit les résultats avec tous les graphiques, calculs ou analyses générés.

Le conteneur dispose de Python préinstallé. 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 une version ultérieure 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 syntaxique de fichiers ou visualisation
• Exécution d’algorithmes ou simulation
• Demandes explicites de « lancer », « calculer » ou « exécuter »

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 simples ou les traductions

Si vous souhaitez que Claude exécute du code pour une requête 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 (comme des fichiers CSV, Excel ou des 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

1. Téléversez votre fichier à l’aide de la Files API.
2. Référencez le fichier dans votre message à l’aide d’un bloc de contenu container_upload.
3. 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 (consultez 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):
    file_metadata = client.files.retrieve_metadata(file_id)
    file_content = client.files.download(file_id)
    file_content.write_to_file(file_metadata.filename)
    print(f"Downloaded: {file_metadata.filename}")

Comment les fichiers générés sont capturés

Chaque appel bash_code_execution reçoit un nouveau répertoire vide, accessible à la commande sous le nom $OUTPUT_DIR. Lorsque la commande se termine, les fichiers situés au niveau supérieur de ce répertoire sont capturés et renvoyés sous forme d’entrées file_id dans la liste content du résultat. Les fichiers écrits ailleurs restent dans le conteneur et ne sont pas renvoyés.

La description de l’outil indique à Claude de partager les fichiers en les copiant dans $OUTPUT_DIR. Si votre application dépend de la réception d’un fichier, demandez à Claude de le copier dans $OUTPUT_DIR et de lister le répertoire dans la même commande, afin que la sortie de ls confirme la capture (Claude ne reçoit pas la liste content) :

python /tmp/make_report.py && cp /tmp/report.pdf "$OUTPUT_DIR/" && ls "$OUTPUT_DIR"

Un fichier que Claude a écrit ailleurs se trouve toujours dans le conteneur, vous pouvez donc réutiliser le conteneur et demander à Claude de le copier dans $OUTPUT_DIR.

Content Credentials sur les fichiers générés

Sur la Claude API, les fichiers image, vidéo et audio pris en charge que Claude produit dans le bac à sable d’exécution de code portent des Content Credentials C2PA lorsque vous les téléchargez via la Files API. Les formats pris en charge incluent PNG, JPEG, GIF, WebP, TIFF, HEIC, AVIF, SVG, MP4, MOV, MP3, WAV, FLAC et M4A. Les Content Credentials sont un manifeste signé cryptographiquement et intégré dans les métadonnées du fichier. Ils identifient Anthropic comme émetteur, comportent un horodatage et enregistrent la description d’action « Claude provided this file at the request of a user and may have created or modified the file contents. »

La signature ne nécessite aucune modification de vos requêtes ou de votre traitement des réponses, et le manifeste n’enregistre rien à votre sujet, ni sur votre organisation ou votre requête. Le contenu visible du fichier est inchangé. Le manifeste ajoute quelques kilo-octets, de sorte que la taille et la somme de contrôle du fichier téléchargé diffèrent de celles du fichier tel qu’il existe dans le conteneur. Les fichiers texte, les PDF et les documents bureautiques ne sont pas signés, car ce ne sont pas des formats pris en charge pour la signature. Les fichiers que vous téléversez sont stockés tels quels, y compris les Content Credentials qu’ils portent déjà.

Pour vérifier des Content Credentials, inspectez le fichier avec n’importe quel outil compatible C2PA, comme l’utilitaire en ligne de commande c2patool open source. Le réencodage, la conversion de format, les captures d’écran et les outils qui suppriment les métadonnées retirent les Content Credentials, de sorte que l’absence de Content Credentials ne signifie pas qu’un fichier n’a pas été produit avec Claude. Pour en savoir plus sur les raisons pour lesquelles des Content Credentials peuvent être absents, consultez Comment Claude marque le contenu généré par l’IA.

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

Les deux champs sont fixes : type sélectionne la version de l’outil, et name doit être code_execution.

Lorsque vous fournissez cet outil, Claude obtient automatiquement l’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 écrire du code

Lorsque Claude exécute du code, la réponse inclut également un objet container de premier niveau contenant l’id du conteneur et l’horodatage expires_at. Renvoyez cet ID dans le paramètre de requête container de premier niveau pour continuer à utiliser le même conteneur. Consultez Réutilisation des conteneurs.

Format de réponse

L’outil d’exécution de code peut renvoyer 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,
    "content": []
  }
}

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_view_result",
    "file_type": "text",
    "content": "{\n  \"setting\": \"value\",\n  \"debug\": true\n}",
    "num_lines": 4,
    "start_line": 1,
    "total_lines": 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_create_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_str_replace_result",
    "old_start": 3,
    "old_lines": 1,
    "new_start": 3,
    "new_lines": 1,
    "lines": ["-  \"debug\": true", "+  \"debug\": false"]
  }
}

Résultats

Les résultats des commandes Bash (bash_code_execution_result) incluent :

• stdout : sortie d’une exécution réussie
• stderr : messages d’erreur si l’exécution échoue
• return_code : 0 en cas de succès, non nul en cas d’échec
• content : une liste avec une entrée pour chaque fichier que la commande a laissé dans $OUTPUT_DIR (consultez Comment les fichiers générés sont capturés). Chaque entrée contient le file_id permettant de récupérer le fichier avec la Files API

Les résultats des opérations sur les fichiers ont leurs propres champs :

• Afficher (text_editor_code_execution_view_result) : file_type, content, num_lines, start_line, total_lines
• Créer (text_editor_code_execution_create_result) : is_file_update (indique si le fichier existait déjà)
• Modifier (text_editor_code_execution_str_replace_result) : old_start, old_lines, new_start, new_lines, lines (format diff)

Erreurs

Chaque type d’outil peut renvoyer 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 :

Un conteneur expiré ne peut pas être réutilisé : les requêtes qui y font référence renvoient une erreur au lieu de le restaurer. Renvoyez la requête sans le paramètre container pour obtenir un nouveau conteneur.

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 laisser Claude poursuivre son tour, ou modifier le contenu si vous souhaitez interrompre la conversation.

Renvoyez l’ID du conteneur de la réponse avec cette requête (voir Réutilisation des conteneurs). Sans lui, la requête s’exécute dans un nouveau conteneur, et les fichiers créés plus tôt dans le tour sont perdus.

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 particulier sur Python.

Environnement d’exécution

• Version de Python : 3.11
• Système d’exploitation : conteneur basé sur Linux
• Architecture : x86_64 (AMD64)

Limites de ressources

• Mémoire : le conteneur dispose de 5 Gio de RAM.
• Espace disque : le conteneur dispose de 5 Gio de stockage pour l’espace de travail.
• CPU : le conteneur dispose de 1 CPU.
• Temps d’exécution : un appel d’outil qui dépasse le temps d’exécution maximal renvoie une erreur execution_time_exceeded. Avec l’appel d’outils programmatique, chaque cellule REPL a également une limite de 90 secondes en temps réel.

Réseau et sécurité

• Accès à Internet : entièrement désactivé pour des raisons de sécurité
• Connexions externes : aucune requête réseau sortante autorisée
• Isolation du bac à sable : 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 : limitée à l’espace de travail de la requête, comme la Files API
• Expiration : 30 jours après la création

Bibliothèques préinstallées

L’environnement Python isolé 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

Le conteneur inclut également des outils en ligne de commande tels que unzip, unrar, 7zip, bc, rg (ripgrep), fd et sqlite.

Le conteneur n’a pas d’accès à Internet, Claude ne peut donc pas télécharger ni installer de paquets supplémentaires pendant l’exécution : seules les bibliothèques préinstallées sont disponibles.

Réutilisation des conteneurs

Vous pouvez réutiliser un conteneur existant sur plusieurs requêtes API en fournissant l’ID de conteneur d’une réponse précédente. Cela vous permet de conserver les fichiers créés entre les requêtes. Avec code_execution_20260120 ou une version ultérieure et l’appel d’outils programmatique, l’état de l’interpréteur Python persiste également.

Les conteneurs expirent 30 jours après leur création. Après environ 5 minutes d’inactivité, un conteneur fait l’objet d’un point de contrôle, et l’envoi d’une requête avec son ID dans la fenêtre de 30 jours le restaure. L’horodatage expires_at dans l’objet container de la réponse est une valeur glissante plus courte et ne reflète pas la limite de 30 jours. Un conteneur qui a expiré ne peut pas être réutilisé. Renvoyez la requête sans le paramètre container pour obtenir un nouveau conteneur.

Exemple

client = anthropic.Anthropic()

# Première requête : créer un fichier contenant un nombre aléatoire dans un nouveau conteneur.
response1 = client.messages.create(
    model="claude-opus-5-5",
    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"}],
)

# Deuxième requête : renvoyer l'ID du conteneur pour que Claude réutilise le même conteneur.
response2 = client.messages.create(
    container=response1.container.id,
    model="claude-opus-5-5",
    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"}],
)

print(response2.to_json())

Utiliser l’exécution de code avec d’autres outils d’exécution

Lorsque vous fournissez l’exécution de code en parallèle 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 isolé d’Anthropic, tandis que vos outils fournis par le client s’exécutent dans un environnement distinct que vous contrôlez. Claude peut parfois utiliser le mauvais outil ou agir comme si l’état était partagé entre ces environnements.

Pour éviter cela, ajoutez à votre « system prompt » (invite système) des instructions 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 lorsque vous combinez l’exécution de code avec la recherche web ou la récupération web, qui activent automatiquement l’exécution de code. 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 du premier.

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 de vos outils client.

Streaming

Avec le streaming activé ("stream": true), vous recevrez les événements d’exécution de code au fur et à mesure qu’ils se produisent. L’entrée du sous-outil est diffusée sous forme d’événements input_json_delta, et chaque bloc de résultat arrive en entier dans un seul événement content_block_start :

event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "bash_code_execution"}}

// Tool input streamed as partial JSON
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"command\": \"python analyze.py\"}"}}

// Pause while the command runs

// Execution result delivered as a complete block
event: content_block_start
data: {"type": "content_block_start", "index": 2, "content_block": {"type": "bash_code_execution_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": {"type": "bash_code_execution_result", "stdout": "   A  B  C\n0  1  2  3\n1  4  5  6", "stderr": "", "return_code": 0, "content": []}}}

Requêtes par lots

Vous pouvez inclure l’outil d’exécution de code dans la Messages Batches API. Les appels de l’outil d’exécution de code via la Messages Batches API sont facturés au même prix que ceux des requêtes classiques de la Messages API.

Utilisation et tarification

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 une version ultérieure) ou web_fetch_20260209 (ou une version ultérieure) est inclus dans votre requête API, aucun frais supplémentaire n’est facturé pour les appels à l’outil d’exécution de code au-delà des coûts standard des tokens d’entrée et de sortie.

Lorsqu’elle est utilisée sans ces outils, l’exécution de code est facturée selon le temps d’exécution, suivi séparément de l’utilisation des tokens :

• Le temps d’exécution est facturé avec un minimum de 5 minutes.
• Chaque organisation bénéficie de 1 550 heures gratuites d’utilisation par mois.
• L’utilisation supplémentaire au-delà de 1 550 heures est facturée à 0,05 $ USD par heure, par conteneur.
• Si des fichiers sont inclus dans la requête, le temps d’exécution est facturé même si l’outil n’est pas appelé, car les fichiers sont préchargés dans le conteneur.

L’utilisation de l’exécution de code est suivie dans la réponse :

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

Mettre à niveau vers la dernière version de l’outil

La dernière version de l’outil est code_execution_20260521. Pour passer d’une des trois versions actuelles à une autre, mettez à jour la chaîne type dans votre requête : les trois renvoient les blocs de réponse documentés dans Format de réponse. Consultez Versions de l’outil pour savoir ce que chaque version ajoute et Prise en charge de l’API pour les modèles qui les prennent en charge.

Le reste de cette section traite de la migration de l’ancien code_execution_20250522, limité à Python, vers les versions actuelles de l’outil.

Ce qui a changé

Rétrocompatibilité

• Toute exécution de code Python existante continue de fonctionner exactement comme avant
• Aucune modification n’est requise pour les workflows existants limités à Python

Étapes de mise à niveau

Pour effectuer la mise à niveau, mettez à jour le type d’outil dans vos requêtes API :

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

Vérifiez le traitement des réponses (si vous analysez les réponses de manière programmatique) :

• L’API n’envoie plus les anciens blocs pour les réponses d’exécution Python.
• À la place, l’API envoie de nouveaux types de réponse pour les opérations Bash et sur les fichiers (consultez Format de réponse).

Conservation des données

L’exécution de code s’effectue dans des conteneurs isolés côté serveur. Les données des conteneurs, y compris les artefacts d’exécution, les fichiers téléversés et les sorties, sont conservées jusqu’à 30 jours. Cette conservation s’applique à toutes les données traitées dans l’environnement du conteneur. Les fichiers que l’exécution de code crée dans la Files API (récupérables avec client.files.download()) persistent jusqu’à leur suppression explicite.

Étapes suivantes