Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
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 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é (sandbox).
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 version ultérieure). 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 de 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 lorsque ces outils 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 fenêtre de contexte. Lorsque le filtrage dynamique s'exécute, l'API provisionne automatiquement l'exécution de code nécessaire pour la requête, vous n'avez donc pas besoin d'ajouter l'outil d'exécution de code à votre requête pour cela.
L'outil d'exécution de code est disponible sur les modèles suivants :
| Modèle | Versions de l'outil |
|---|---|
| Claude Opus 5 () | code_execution_20250825, code_execution_20260120, code_execution_20260521 |
| Claude Fable 5 () | code_execution_20250825, code_execution_20260120, code_execution_20260521 |
| Claude Mythos 5 () | code_execution_20250825, code_execution_20260120, code_execution_20260521 |
| Claude Sonnet 5 () | code_execution_20250825, code_execution_20260120, code_execution_20260521 |
| Claude Opus 4.8 () | code_execution_20250825, code_execution_20260120, code_execution_20260521 |
| Claude Opus 4.7 () | code_execution_20250825, code_execution_20260120, code_execution_20260521 |
| Claude Opus 4.6 () | code_execution_20250825, code_execution_20260120, code_execution_20260521 |
| Claude Sonnet 4.6 () | code_execution_20250825, code_execution_20260120, code_execution_20260521 |
| Claude Opus 4.5 () | code_execution_20250825, code_execution_20260120, code_execution_20260521 |
| Claude Sonnet 4.5 () | code_execution_20250825, code_execution_20260120, code_execution_20260521 |
| Claude Haiku 4.5 () | code_execution_20250825, code_execution_20260120, code_execution_20260521 |
Chaque version de l'outil 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 du REPL et l'appel programmatique d'outils depuis l'intérieur du sandbox. Claude Haiku 4.5 accepte les types d'outils code_execution_20260120 et code_execution_20260521, mais l'appel programmatique d'outils et la persistance de l'état du REPL qui en dépend ne sont pas disponibles sur ce modèle, de sorte que les versions plus récentes se comportent comme code_execution_20250825 dans ce cas.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 pour chaque cellule Python dans l'appel programmatique d'outils, afin que Claude puisse budgétiser 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 de statut detection_timeout dans sa sortie. Ceci est distinct du code d'erreur execution_time_exceeded, que l'API renvoie lorsqu'une invocation d'outil complète dépasse le temps d'exécution maximal.Les trois versions de l'outil sont en disponibilité générale et ne nécessitent pas 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 de fichiers qu'ils démontrent et se comporte de la même manière sur tous les modèles du tableau ; utilisez code_execution_20260120 ou une version ultérieure lorsque vous avez besoin de l'appel programmatique d'outils ou de la persistance de l'état du 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.
L'exécution de code est disponible sur :
L'exécution de code n'est actuellement pas disponible sur Amazon Bedrock ni sur Google Cloud.
Voici un exemple qui demande à Claude d'effectuer un calcul :
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-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ésultats d'outils, 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.
Lorsque vous ajoutez l'outil d'exécution de code à votre requête API :
tool_result vous-même. Une exception existe 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 clientLe 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 programmatique d'outils, l'état de l'interpréteur Python (comme les liaisons de variables) persiste également entre les requêtes qui réutilisent le conteneur.
Claude exécute du code lorsque la requête bénéficie d'un calcul ou d'une manipulation de fichiers :
Claude répond directement sans exécuter de code pour :
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 »).
Pour analyser vos propres fichiers de données (tels que CSV, Excel ou images), téléversez-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éversés via l'API Files, notamment :
container_uploadclient = anthropic.Anthropic()
# Téléverser un fichier
file_object = client.beta.files.upload(file=Path("data.csv"))
# Utiliser le file_id avec l'exécution de code
response = client.beta.messages.create(
model="claude-opus-5",
betas=["files-api-2025-04-14"],
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())Lorsque Claude crée des fichiers pendant l'exécution de code, l'ID de chaque fichier créé apparaît dans le résultat de l'outil d'exécution de code, et vous pouvez le télécharger avec l'API Files :
client = Anthropic()
# Demander une exécution de code qui crée des fichiers
response = client.beta.messages.create(
model="claude-opus-5",
betas=["files-api-2025-04-14"],
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 identifiants de fichiers de la réponse
def extract_file_ids(response: BetaMessage) -> 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.beta.files.retrieve_metadata(file_id)
file_content = client.beta.files.download(file_id)
file_content.write_to_file(file_metadata.filename)
print(f"Downloaded: {file_metadata.filename}")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 shelltext_editor_code_execution : afficher, créer et modifier des fichiers, y compris écrire du codeLorsque Claude exécute du code, la réponse inclut également un objet container de niveau supérieur avec l'id du conteneur et l'horodatage expires_at. Transmettez cet ID dans le paramètre de requête container de niveau supérieur pour continuer à utiliser le même conteneur. Voir Réutilisation de conteneur.
L'outil d'exécution de code peut renvoyer deux types de résultats selon l'opération :
{
"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": []
}
}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"]
}
}Les résultats de commandes Bash (bash_code_execution_result) incluent :
stdout : sortie d'une exécution réussiestderr : messages d'erreur si l'exécution échouereturn_code : 0 en cas de succès, non nul en cas d'écheccontent : une liste avec une entrée pour chaque fichier créé par la commande. Chaque entrée contient le file_id permettant de récupérer le fichier avec l'API FilesLes résultats d'opérations sur les fichiers ont leurs propres champs :
text_editor_code_execution_view_result) : file_type, content, num_lines, start_line, total_linestext_editor_code_execution_create_result) : is_file_update (indique si le fichier existait déjà)text_editor_code_execution_str_replace_result) : old_start, old_lines, new_start, new_lines, lines (format diff)Chaque type d'outil peut renvoyer 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 :
| Outil | Code d'erreur | Description |
|---|---|---|
| Tous les outils | unavailable | L'outil est temporairement indisponible |
| Tous les outils | execution_time_exceeded | L'invocation de l'outil a dépassé le temps d'exécution maximal |
| Tous les outils | invalid_tool_input | Paramètres non valides fournis à l'outil |
| Tous les outils | too_many_requests | Limite de débit dépassée pour l'utilisation de l'outil |
| bash | output_file_too_large | La sortie de la commande a dépassé la taille maximale |
| text_editor | file_not_found | Le fichier n'existe pas (pour les opérations d'affichage/modification) |
Un conteneur expiré ne peut pas être réutilisé : les requêtes qui le référencent renvoient une erreur au lieu de le restaurer. Envoyez à nouveau la requête sans le paramètre container pour obtenir un nouveau conteneur.
pause_turnLa 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 permettre à Claude de poursuivre son tour, ou modifier le contenu si vous souhaitez interrompre la conversation.
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.
execution_time_exceeded. Avec l'appel programmatique d'outils, chaque cellule REPL a également une limite de 90 secondes de temps réelL'environnement Python isolé inclut ces bibliothèques couramment utilisées :
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, donc Claude ne peut pas télécharger ni installer de packages supplémentaires au moment de l'exécution : seules les bibliothèques préinstallées sont disponibles.
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 programmatique d'outils, 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 est sauvegardé (checkpoint), 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é. Envoyez à nouveau la requête sans le paramètre container pour obtenir un nouveau conteneur.
client = anthropic.Anthropic()
# Première requête : créer un fichier avec un nombre aléatoire dans un nouveau conteneur
response1 = client.messages.create(
model="claude-opus-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 : retransmettre 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",
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())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 confondre ces environnements, en tentant d'utiliser le mauvais outil ou en supposant que l'état est partagé entre eux.
Pour éviter cela, ajoutez des instructions à votre invite 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 stateCeci 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.
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.
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": []}}}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 facturés au même tarif que ceux des requêtes API Messages standard.
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 version ultérieure) ou web_fetch_20260209 (ou version ultérieure) est inclus dans votre requête API, il n'y a aucun frais supplémentaire 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 :
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
}
}
}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 Compatibilité des modèles pour savoir ce que chaque version ajoute et quels modèles la prennent en charge.
Le reste de cette section couvre la migration depuis l'ancienne version code_execution_20250522 (Python uniquement) vers les versions actuelles de l'outil.
| Composant | Ancienne version | Version actuelle |
|---|---|---|
| En-tête bêta | code-execution-2025-05-22 | Aucun requis |
| Type d'outil | code_execution_20250522 | code_execution_20250825 ou version ultérieure |
| Capacités | Python uniquement | Commandes Bash, opérations sur les fichiers |
| Types de réponse | code_execution_result | bash_code_execution_result, text_editor_code_execution_*_result |
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 la gestion des réponses (si vous analysez les réponses par programmation) :
L'exécution de code s'exécute dans des conteneurs sandbox côté serveur. Les données du conteneur, 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 l'API Files (récupérables avec client.beta.files.download()) persistent jusqu'à leur suppression explicite.
Pour l'éligibilité ZDR sur l'ensemble des fonctionnalités, consultez API et conservation des données.
Associez un modèle exécuteur plus rapide à un modèle conseiller de plus haute intelligence qui fournit des conseils stratégiques en cours de génération.
Appelez vos propres outils depuis du code qui s'exécute à l'intérieur du conteneur d'exécution de code.
Téléversez des fichiers pour analyse et téléchargez les fichiers créés par l'exécution de code.
Découvrez comment utiliser les Agent Skills pour étendre les capacités de Claude via l'API.
Was this page helpful?