Code-Execution-Tool

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

Code-Ausführung ist kostenlos, wenn sie mit Websuche oder Web-Fetch verwendet wird. Wenn web_search_20260209 (oder neuer) oder web_fetch_20260209 (oder neuer) in deiner Anfrage enthalten ist, fallen für Aufrufe des Code-Execution-Tools keine zusätzlichen Kosten über die standardmäßigen Input- und Output-Token-Kosten hinaus an. Die Standardgebühren für Code-Ausführung gelten, wenn diese Tools nicht enthalten sind.

Code-Ausführung ist ein zentrales Grundelement für den Aufbau leistungsstarker Agenten. Sie ermöglicht dynamisches Filtern in den Websuche- und Web-Fetch-Tools, sodass Claude Ergebnisse verarbeiten kann, bevor sie das Kontextfenster erreichen – das verbessert die Genauigkeit und reduziert gleichzeitig den Token-Verbrauch.



Modellkompatibilität

Das Code-Execution-Tool ist für die folgenden Modelle verfügbar:



Plattformverfügbarkeit

Code-Ausführung ist verfügbar auf:

• Claude API (Anthropic)
• Claude Platform on AWS
• Microsoft Foundry (erfordert ein Hosted-on-Anthropic-Deployment)

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



Schnellstart

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "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)



So funktioniert Code-Ausführung

Wenn du das Code-Execution-Tool zu deiner API-Anfrage hinzufügst:

1. Claude bewertet, ob Code-Ausführung bei der Beantwortung deiner Frage helfen würde
2. Das Tool stellt Claude automatisch die folgenden Fähigkeiten zur Verfügung:
   • Bash-Befehle: Shell-Befehle für Systemoperationen und Paketverwaltung ausführen
   • Dateioperationen: Dateien direkt erstellen, anzeigen und bearbeiten, einschließlich des Schreibens von Code
3. Claude kann jede Kombination dieser Fähigkeiten in einer einzigen Anfrage verwenden
4. Alle Operationen laufen in einer sicheren Sandbox-Umgebung
5. Claude liefert Ergebnisse mit allen generierten Diagrammen, Berechnungen oder Analysen



Wann Claude Code ausführt

Claude führt Code aus, wenn die Anfrage von Berechnungen oder Dateiverarbeitung profitiert:

• Nicht-triviale Mathematik (große Zahlen, viele Schritte, präzisionsabhängige Ergebnisse)
• Datenanalyse, Datei-Parsing oder Visualisierung
• Algorithmusausführung oder Simulation
• Explizite Aufforderungen wie „ausführen", „berechnen" oder „execute"

Claude antwortet direkt ohne Code-Ausführung bei:

• Einfacher Arithmetik und bekannten mathematischen Fakten
• Faktischen, konversationellen oder kreativen Anfragen
• Einfachen Einheitenumrechnungen oder Übersetzungen

Wenn du möchtest, dass Claude bei einer Grenzfall-Anfrage Code ausführt, frage explizit danach (zum Beispiel: „Führe Code aus, um das zu verifizieren").



Code-Ausführung mit anderen Ausführungs-Tools verwenden

Wenn du Code-Ausführung zusammen mit clientseitig bereitgestellten Tools anbietest, die ebenfalls Code ausführen (wie ein Bash-Tool oder ein benutzerdefiniertes REPL), arbeitet Claude in einer Multi-Computer-Umgebung. Das Code-Execution-Tool läuft in Anthropics Sandbox-Container, während deine clientseitig bereitgestellten Tools in einer separaten Umgebung laufen, die du kontrollierst. Claude kann diese Umgebungen manchmal verwechseln und versuchen, das falsche Tool zu verwenden oder anzunehmen, dass der Zustand zwischen ihnen geteilt wird.

Um das zu vermeiden, füge deinem System-Prompt Anweisungen hinzu, die den Unterschied klarstellen:

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

Das ist besonders wichtig, wenn du Code-Ausführung mit Websuche oder Web-Fetch kombinierst, die Code-Ausführung automatisch aktivieren. Wenn deine Anwendung bereits ein clientseitiges Shell-Tool bereitstellt, erzeugt die automatische Code-Ausführung eine zweite Ausführungsumgebung, zwischen denen Claude unterscheiden muss.



So verwendest du das Tool



Eigene Dateien hochladen und analysieren

Um deine eigenen Datendateien (wie CSV, Excel oder Bilder) zu analysieren, lade sie über die Files API hoch und referenziere sie in deiner Anfrage:

Die Python-Umgebung kann verschiedene Dateitypen verarbeiten, die über die Files API hochgeladen wurden, darunter:

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



Dateien hochladen und analysieren

1. Lade deine Datei hoch mit der Files API
2. Referenziere die Datei in deiner Nachricht mit einem container_upload-Content-Block
3. Füge das Code-Execution-Tool in deine API-Anfrage ein

client = anthropic.Anthropic()

# Lade eine Datei hoch
file_object = client.beta.files.upload(
    file=open("data.csv", "rb"),
)

# Verwende die file_id mit der Code-Ausführung
response = client.beta.messages.create(
    model="claude-opus-4-8",
    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)



Generierte Dateien abrufen

Wenn Claude während der Code-Ausführung Dateien erstellt, kannst du diese Dateien über die Files API abrufen:

# Initialisiere den Client
client = Anthropic()

# Fordere Code-Ausführung an, die Dateien erstellt
response = client.beta.messages.create(
    model="claude-opus-4-8",
    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"}],
)


# Extrahiere Datei-IDs aus der Antwort
def extract_file_ids(response):
    file_ids = []
    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":
                # konkret typisierte Liste: List[BashCodeExecutionOutputBlock]
                for file in content_item.content:
                    file_ids.append(file.file_id)
    return file_ids


# Lade die erstellten Dateien herunter
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}")



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 des Schreibens von Code



Antwortformat

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



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 bei erfolgreicher Ausführung
• stderr: Fehlermeldungen, wenn die Ausführung fehlschlägt
• return_code: 0 bei Erfolg, ungleich Null bei Fehler

Zusätzliche Felder für Dateioperationen:

• View: file_type, content, numLines, startLine, totalLines
• Create: is_file_update (ob die Datei bereits existierte)
• Edit: oldStart, oldLines, newStart, newLines, lines (Diff-Format)



Fehler

Jeder Tool-Typ kann spezifische Fehler zurückgeben:

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

Die Antwort kann einen pause_turn-Stop-Reason enthalten, der anzeigt, dass die API einen lang laufenden Turn pausiert hat. Du kannst die Antwort unverändert in einer nachfolgenden Anfrage zurückgeben, damit Claude seinen Turn fortsetzt, oder den Inhalt ändern, wenn du die Konversation unterbrechen möchtest.



Container

Das Code-Execution-Tool läuft in einer sicheren, containerisierten Umgebung, die speziell für Code-Ausführung entwickelt wurde, mit einem stärkeren Fokus auf Python.



Laufzeitumgebung

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



Ressourcenlimits

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



Netzwerk und Sicherheit

• Internetzugang: Aus Sicherheitsgründen vollständig deaktiviert
• Externe Verbindungen: Keine ausgehenden Netzwerkanfragen erlaubt
• Sandbox-Isolation: Vollständige Isolation vom Host-System und anderen Containern
• Dateizugriff: Auf das Workspace-Verzeichnis beschränkt
• Workspace-Scoping: Wie bei Files sind Container auf den Workspace des API-Keys beschränkt
• Ablauf: Container laufen 30 Tage nach Erstellung ab



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 & Berechnung: sympy, mpmath
• Utilities: tqdm, python-dateutil, pytz, joblib, unzip, unrar, 7zip, bc, rg (ripgrep), fd, sqlite



Container-Wiederverwendung

Du kannst einen bestehenden Container über mehrere API-Anfragen hinweg wiederverwenden, indem du die Container-ID aus einer vorherigen Antwort angibst. Dadurch kannst du erstellte Dateien zwischen Anfragen beibehalten.



Beispiel

# Erste Anfrage: Erstelle eine Datei mit einer Zufallszahl
response1 = client.messages.create(
    model="claude-opus-4-8",
    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"}],
)

# Extrahiere die Container-ID aus der ersten Antwort
container_id = response1.container.id

# Zweite Anfrage: Verwende den Container erneut, um die Datei zu lesen
response2 = client.messages.create(
    container=container_id,  # Reuse the same container
    model="claude-opus-4-8",
    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)



Streaming

Wenn Streaming aktiviert ist, erhältst du Code-Execution-Events, sobald 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

Du kannst das Code-Execution-Tool in die Messages Batches API einbinden. Aufrufe des Code-Execution-Tools über die Messages Batches API werden genauso berechnet wie in regulären Messages-API-Anfragen.



Nutzung und Preise

Code-Ausführung ist kostenlos, wenn sie mit Websuche oder Web-Fetch verwendet wird. Wenn web_search_20260209 (oder neuer) oder web_fetch_20260209 (oder neuer) in deiner API-Anfrage enthalten ist, fallen für Aufrufe des Code-Ausführungs-Tools keine zusätzlichen Kosten an, abgesehen von den standardmäßigen Kosten für Input- und Output-Token.

Bei Verwendung ohne diese Tools wird die Code-Ausführung nach Ausführungszeit abgerechnet, die getrennt von der Token-Nutzung erfasst wird:

• Die Ausführungszeit hat ein Minimum von 5 Minuten
• Jede Organisation erhält 1.550 kostenlose Stunden Nutzung pro Monat
• Zusätzliche Nutzung über 1.550 Stunden hinaus wird mit 0,05 $ pro Stunde, pro Container abgerechnet
• Wenn Dateien in der Anfrage enthalten sind, wird die Ausführungszeit auch dann berechnet, wenn das Tool nicht aufgerufen wird, da die Dateien vorab in den Container geladen werden

Die Nutzung der Code-Ausführung wird in der Antwort erfasst:

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



Upgrade auf die neueste Tool-Version

Durch ein Upgrade auf code-execution-2025-08-25 erhältst du Zugriff auf Dateimanipulation und Bash-Fähigkeiten, einschließlich Code in mehreren Sprachen. Es gibt keinen Preisunterschied.



Was sich geändert hat



Abwärtskompatibilität

• Alle bestehenden Python-Code-Ausführungen funktionieren weiterhin genau wie zuvor
• Keine Änderungen an bestehenden reinen Python-Workflows erforderlich



Upgrade-Schritte

Um ein Upgrade durchzuführen, aktualisiere den Tool-Typ in deinen API-Anfragen:

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

Überprüfe die Antwortverarbeitung (wenn du Antworten programmatisch parst):

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



Programmatische Tool-Aufrufe

Informationen zum Ausführen von Tools innerhalb des Code-Execution-Containers findest du unter Programmatische Tool-Aufrufe.



Datenaufbewahrung

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

Informationen zur ZDR-Eignung über alle Funktionen hinweg findest du unter API und Datenaufbewahrung.



Code-Ausführung mit Agent Skills verwenden

Das Code-Execution-Tool ermöglicht es Claude, Agent Skills zu verwenden. Skills sind modulare Fähigkeiten, die aus Anweisungen, Skripten und Ressourcen bestehen und Claudes Funktionalität erweitern.

Erfahre mehr unter Agent Skills und Agent Skills mit der API verwenden.