Code-Ausführungstool

Claude kann Daten analysieren, Visualisierungen erstellen, komplexe Berechnungen durchführen, Systembefehle ausführen, Dateien erstellen und bearbeiten sowie hochgeladene Dateien direkt innerhalb des API-Gesprächs verarbeiten. Das Code-Ausführungstool ermöglicht es Claude, Bash-Befehle auszuführen und Dateien zu manipulieren, einschließlich des Schreibens von Code, in einer sicheren, isolierten Umgebung.

Die Code-Ausführung ist kostenlos, wenn sie mit Web-Suche oder Web-Abruf verwendet wird. Wenn web_search_20260209 oder web_fetch_20260209 in Ihrer Anfrage enthalten ist, fallen keine zusätzlichen Gebühren für Code-Ausführungstool-Aufrufe über die Standard-Eingabe- und Ausgabe-Token-Kosten hinaus an. Standard-Code-Ausführungsgebühren gelten, wenn diese Tools nicht enthalten sind.

Die Code-Ausführung ist ein Kernprimitive für die Erstellung leistungsstarker Agenten. Sie ermöglicht dynamische Filterung in Web-Such- und Web-Abruf-Tools, wodurch Claude Ergebnisse verarbeiten kann, bevor sie das Kontextfenster erreichen, was die Genauigkeit verbessert und den Token-Verbrauch reduziert.

Modellkompatibilität

Das Code-Ausführungstool ist auf den folgenden Modellen verfügbar:

Plattformverfügbarkeit

Die Code-Ausführung ist verfügbar auf:

• Claude API (Anthropic)
• Microsoft Azure AI Foundry

Die Code-Ausführung ist derzeit nicht auf Amazon Bedrock oder Google Vertex AI verfügbar.

Schnellstart

Hier ist ein einfaches Beispiel, das Claude auffordert, eine Berechnung durchzuführen:

Wie die Code-Ausführung funktioniert

Wenn Sie das Code-Ausführungstool zu Ihrer API-Anfrage hinzufügen:

1. Claude bewertet, ob die Code-Ausführung zur Beantwortung Ihrer Frage hilfreich wäre
2. Das Tool stellt Claude automatisch die folgenden Funktionen zur Verfügung:
   • Bash-Befehle: Führen Sie Shell-Befehle für Systemvorgänge und Paketverwaltung aus
   • Dateivorgänge: Erstellen, anzeigen und bearbeiten Sie Dateien direkt, einschließlich des Schreibens von Code
3. Claude kann jede Kombination dieser Funktionen in einer einzelnen Anfrage verwenden
4. Alle Vorgänge werden in einer sicheren Sandbox-Umgebung ausgeführt
5. Claude stellt Ergebnisse mit allen generierten Diagrammen, Berechnungen oder Analysen bereit

Verwendung der Code-Ausführung mit anderen Ausführungstools

Wenn Sie die Code-Ausführung zusammen mit vom Client bereitgestellten Tools verwenden, die auch Code ausführen (wie ein Bash-Tool oder eine benutzerdefinierte REPL), arbeitet Claude in einer Multi-Computer-Umgebung. Das Code-Ausführungstool wird in Anthropics Sandbox-Container ausgeführt, während Ihre vom Client bereitgestellten Tools in einer separaten Umgebung ausgeführt werden, die Sie kontrollieren. Claude kann diese Umgebungen manchmal verwechseln und versuchen, das falsche Tool zu verwenden oder anzunehmen, dass der Zustand zwischen ihnen gemeinsam genutzt wird.

Um dies zu vermeiden, fügen Sie Anweisungen zu Ihrer Systemaufforderung hinzu, die die Unterscheidung verdeutlichen:

Wenn mehrere Code-Ausführungsumgebungen verfügbar sind, beachten Sie, dass:
- Variablen, Dateien und Zustand NICHT zwischen verschiedenen Ausführungsumgebungen bestehen bleiben
- Verwenden Sie das code_execution-Tool für allgemeine Berechnungen in Anthropics Sandbox-Umgebung
- Verwenden Sie vom Client bereitgestellte Ausführungstools (z. B. Bash), wenn Sie Zugriff auf das lokale System, die Dateien oder Daten des Benutzers benötigen
- Wenn Sie Ergebnisse zwischen Umgebungen übergeben müssen, fügen Sie Ausgaben explizit in nachfolgenden Tool-Aufrufen ein, anstatt gemeinsamen Zustand anzunehmen

Dies ist besonders wichtig, wenn Sie die Code-Ausführung mit Web-Suche oder Web-Abruf kombinieren, die die Code-Ausführung automatisch aktivieren. Wenn Ihre Anwendung bereits ein Client-seitiges Shell-Tool bereitstellt, erstellt die automatische Code-Ausführung eine zweite Ausführungsumgebung, die Claude unterscheiden muss.

Verwendung des Tools

Laden Sie Ihre eigenen Dateien hoch und analysieren Sie sie

Um Ihre eigenen Datendateien (CSV, Excel, Bilder usw.) zu analysieren, laden Sie diese über die Files API hoch und referenzieren Sie sie in Ihrer Anfrage:

Die Python-Umgebung kann verschiedene Dateitypen verarbeiten, die über die Files API hochgeladen werden, einschließlich:

• CSV
• Excel (.xlsx, .xls)
• JSON
• XML
• Bilder (JPEG, PNG, GIF, WebP)
• Textdateien (.txt, .md, .py, usw.)

Dateien hochladen und analysieren

1. Laden Sie Ihre Datei hoch mit der Files API
2. Referenzieren Sie die Datei in Ihrer Nachricht mit einem container_upload Content Block
3. Fügen Sie das Code Execution Tool in Ihrer API-Anfrage ein

Generierte Dateien abrufen

Wenn Claude während der Code Execution Dateien erstellt, können Sie diese Dateien mit der Files API abrufen:

Tool-Definition

Das Code Execution Tool erfordert keine zusätzlichen Parameter:

{
  "type": "code_execution_20250825",
  "name": "code_execution"
}

Wenn dieses Tool bereitgestellt wird, erhält Claude automatisch Zugriff auf zwei Sub-Tools:

• bash_code_execution: Shell-Befehle ausführen
• text_editor_code_execution: Dateien anzeigen, erstellen und bearbeiten, einschließlich Code schreiben

Antwortformat

Das Code Execution Tool kann zwei Arten von Ergebnissen zurückgeben, je nach Operation:

Bash-Befehl-Antwort

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

Dateioperations-Antworten

Datei anzeigen:

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

Datei erstellen:

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

Datei bearbeiten (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"]
  }
}

Ergebnisse

Alle Ausführungsergebnisse enthalten:

• stdout: Ausgabe aus erfolgreicher Ausführung
• stderr: Fehlermeldungen bei Ausführungsfehlern
• return_code: 0 für Erfolg, nicht-null für Fehler

Zusätzliche Felder für Dateioperationen:

• Anzeigen: file_type, content, numLines, startLine, totalLines
• Erstellen: is_file_update (ob Datei bereits existierte)
• Bearbeiten: oldStart, oldLines, newStart, newLines, lines (Diff-Format)

Fehler

Jeder Tool-Typ kann spezifische Fehler zurückgeben:

Häufige Fehler (alle Tools):

{
  "type": "bash_code_execution_tool_result",
  "tool_use_id": "srvtoolu_01VfmxgZ46TiHbmXgy928hQR",
  "content": {
    "type": "bash_code_execution_tool_result_error",
    "error_code": "unavailable"
  }
}

Fehlercodes nach Tool-Typ:

pause_turn Stop-Grund

Die Antwort kann einen pause_turn Stop-Grund enthalten, der anzeigt, dass die API einen langen Durchgang unterbrochen hat. Sie können die Antwort in einer nachfolgenden Anfrage unverändert zurückgeben, um Claude seinen Durchgang fortsetzen zu lassen, oder den Inhalt ändern, wenn Sie das Gespräch unterbrechen möchten.

Container

Das Code Execution Tool läuft in einer sicheren, containerisierten Umgebung, die speziell für Code Execution entwickelt wurde, mit einem höheren Fokus auf Python.

Laufzeitumgebung

• Python-Version: 3.11.12
• Betriebssystem: Linux-basierter Container
• Architektur: x86_64 (AMD64)

Ressourcenlimits

• Speicher: 5 GiB RAM
• Festplattenspeicher: 5 GiB Workspace-Speicher
• CPU: 1 CPU

Netzwerk und Sicherheit

• Internetzugang: Vollständig deaktiviert aus Sicherheitsgründen
• Externe Verbindungen: Keine ausgehenden Netzwerkanfragen zulässig
• Sandbox-Isolation: Vollständige Isolation vom Host-System und anderen Containern
• Dateizugriff: Begrenzt auf Workspace-Verzeichnis nur
• Workspace-Bereichung: Wie Files sind Container auf den Workspace des API-Schlüssels begrenzt
• Ablauf: Container verfallen 30 Tage nach der Erstellung

Vorinstallierte Bibliotheken

Die Sandbox-Python-Umgebung enthält diese häufig verwendeten Bibliotheken:

• Data Science: pandas, numpy, scipy, scikit-learn, statsmodels
• Visualisierung: matplotlib, seaborn
• Dateiverarbeitung: pyarrow, openpyxl, xlsxwriter, xlrd, pillow, python-pptx, python-docx, pypdf, pdfplumber, pypdfium2, pdf2image, pdfkit, tabula-py, reportlab[pycairo], Img2pdf
• Mathematik & Computing: sympy, mpmath
• Dienstprogramme: tqdm, python-dateutil, pytz, joblib, unzip, unrar, 7zip, bc, rg (ripgrep), fd, sqlite

Container-Wiederverwendung

Sie können einen vorhandenen Container über mehrere API-Anfragen hinweg wiederverwenden, indem Sie die Container-ID aus einer vorherigen Antwort bereitstellen. Dies ermöglicht es Ihnen, erstellte Dateien zwischen Anfragen beizubehalten.

Beispiel

Streaming

Mit aktiviertem Streaming erhalten Sie Code-Ausführungsereignisse, wenn sie auftreten:

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

Batch-Anfragen

Sie können das Code-Ausführungs-Tool in die Messages Batches API einbeziehen. Code-Ausführungs-Tool-Aufrufe über die Messages Batches API werden genauso berechnet wie solche in regulären Messages API-Anfragen.

Nutzung und Preisgestaltung

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

Upgrade auf die neueste Tool-Version

Durch das Upgrade auf code-execution-2025-08-25 erhalten Sie Zugriff auf Dateimanipulation und Bash-Funktionen, einschließlich Code in mehreren Sprachen. Es gibt keinen Preisunterschied.

Was hat sich geändert

Rückwärtskompatibilität

• Alle vorhandenen Python-Code-Ausführungen funktionieren genau wie zuvor
• Keine Änderungen erforderlich für vorhandene Python-only-Workflows

Upgrade-Schritte

Zum Upgrade aktualisieren Sie den Tool-Typ in Ihren API-Anfragen:

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

Überprüfen Sie die Antwortbehandlung (wenn Sie Antworten programmgesteuert analysieren):

• Die vorherigen Blöcke für Python-Ausführungsantworten werden nicht mehr gesendet
• Stattdessen werden neue Antworttypen für Bash und Dateivorgänge gesendet (siehe Abschnitt Antwortformat)

Programmgesteuerte Tool-Aufrufe

Zum Ausführen von Tools innerhalb des Code-Ausführungs-Containers siehe Programmgesteuerte Tool-Aufrufe.

Datenspeicherung

Die Code-Ausführung läuft in serverseitigen Sandbox-Containern. Container-Daten, einschließlich Ausführungsartefakte, hochgeladener Dateien und Ausgaben, werden bis zu 30 Tage lang aufbewahrt. Diese Aufbewahrung gilt für alle Daten, die in der Container-Umgebung verarbeitet werden. Dateien, die die Code-Ausführung in der Files API erstellt (abrufbar über client.beta.files.download()), bleiben bestehen, bis sie explizit gelöscht werden.

Für ZDR-Berechtigung über alle Funktionen hinweg siehe API und Datenspeicherung.

Verwendung der Code-Ausführung mit Agent Skills

Das Code-Ausführungs-Tool ermöglicht Claude die Verwendung von Agent Skills. Skills sind modulare Funktionen, die aus Anweisungen, Skripten und Ressourcen bestehen und Claudes Funktionalität erweitern.

Weitere Informationen finden Sie in der Agent Skills-Dokumentation und im Agent Skills API-Leitfaden.