Code-Ausführungs-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-Unterhaltung verarbeiten. Das Code-Ausführungs-Tool ermöglicht es Claude, Bash-Befehle auszuführen und Dateien zu manipulieren, einschließlich des Schreibens von Code, in einer sicheren, sandboxed Umgebung.

Das Code-Ausführungs-Tool befindet sich derzeit in der öffentlichen Beta-Phase.Um diese Funktion zu nutzen, fügen Sie den "code-execution-2025-08-25" Beta-Header zu Ihren API-Anfragen hinzu.

Wir haben kürzlich das Code-Ausführungs-Tool aktualisiert, um Bash-Befehle und direkte Dateimanipulation zu unterstützen. Für Anweisungen zur Aktualisierung auf die neueste Tool-Version siehe Auf neueste Tool-Version aktualisieren.

Unterstützte Modelle

Das Code-Ausführungs-Tool ist verfügbar auf:

Claude Opus 4.1 (claude-opus-4-1-20250805)
Claude Opus 4 (claude-opus-4-20250514)
Claude Sonnet 4 (claude-sonnet-4-20250514)
Claude Sonnet 3.7 (claude-3-7-sonnet-20250219)
Claude Haiku 3.5 (claude-3-5-haiku-latest)

Schnellstart

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

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: code-execution-2025-08-25" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-1-20250805",
        "max_tokens": 4096,
        "messages": [
            {
                "role": "user",
                "content": "Berechne den Mittelwert und die Standardabweichung von [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]"
            }
        ],
        "tools": [{
            "type": "code_execution_20250825",
            "name": "code_execution"
        }]
    }'

Wie Code-Ausführung funktioniert

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

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

Wie man das Tool verwendet

Bash-Befehle ausführen

Bitten Sie Claude, Systeminformationen zu überprüfen und Pakete zu installieren:

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: code-execution-2025-08-25" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-1-20250805",
        "max_tokens": 4096,
        "messages": [{
            "role": "user",
            "content": "Überprüfe die Python-Version und liste installierte Pakete auf"
        }],
        "tools": [{
            "type": "code_execution_20250825",
            "name": "code_execution"
        }]
    }'

Dateien direkt erstellen und bearbeiten

Claude kann Dateien direkt in der Sandbox mit den Dateimanipulationsfähigkeiten erstellen, anzeigen und bearbeiten:

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: code-execution-2025-08-25" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-1-20250805",
        "max_tokens": 4096,
        "messages": [{
            "role": "user",
            "content": "Erstelle eine config.yaml-Datei mit Datenbankeinstellungen, dann aktualisiere den Port von 5432 auf 3306"
        }],
        "tools": [{
            "type": "code_execution_20250825",
            "name": "code_execution"
        }]
    }'

Eigene Dateien hochladen und analysieren

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

Die Verwendung der Files API mit Code-Ausführung erfordert zwei Beta-Header: "anthropic-beta": "code-execution-2025-08-25,files-api-2025-04-14"

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

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

Dateien hochladen und analysieren

Laden Sie Ihre Datei hoch mit der Files API
Referenzieren Sie die Datei in Ihrer Nachricht mit einem container_upload Inhaltsblock
Fügen Sie das Code-Ausführungs-Tool hinzu in Ihre API-Anfrage

# Zuerst eine Datei hochladen
curl https://api.anthropic.com/v1/files \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: files-api-2025-04-14" \
    --form 'file=@"data.csv"' \

# Dann die file_id mit Code-Ausführung verwenden
curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: code-execution-2025-08-25,files-api-2025-04-14" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-1-20250805",
        "max_tokens": 4096,
        "messages": [{
            "role": "user",
            "content": [
                {"type": "text", "text": "Analysiere diese CSV-Daten"},
                {"type": "container_upload", "file_id": "file_abc123"}
            ]
        }],
        "tools": [{
            "type": "code_execution_20250825",
            "name": "code_execution"
        }]
    }'

Generierte Dateien abrufen

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

from anthropic import Anthropic

# Den Client initialisieren
client = Anthropic()

# Code-Ausführung anfordern, die Dateien erstellt
response = client.beta.messages.create(
    model="claude-opus-4-1-20250805",
    betas=["code-execution-2025-08-25", "files-api-2025-04-14"],
    max_tokens=4096,
    messages=[{
        "role": "user",
        "content": "Erstelle eine matplotlib-Visualisierung und speichere sie als output.png"
    }],
    tools=[{
        "type": "code_execution_20250825",
        "name": "code_execution"
    }]
)

# Datei-IDs aus der Antwort extrahieren
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.get('type') == 'code_execution_result':
                for file in content_item.get('content', []):
                    file_ids.append(file['file_id'])
    return file_ids

# Die erstellten Dateien herunterladen
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"Heruntergeladen: {file_metadata.filename}")

Operationen kombinieren

Ein komplexer Workflow mit allen Fähigkeiten:

# Zuerst eine Datei hochladen
curl https://api.anthropic.com/v1/files \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: files-api-2025-04-14" \
    --form 'file=@"data.csv"' \
    > file_response.json

# file_id extrahieren (mit jq)
FILE_ID=$(jq -r '.id' file_response.json)

# Dann mit Code-Ausführung verwenden
curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: code-execution-2025-08-25,files-api-2025-04-14" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-1-20250805",
        "max_tokens": 4096,
        "messages": [{
            "role": "user",
            "content": [
                {
                    "type": "text", 
                    "text": "Analysiere diese CSV-Daten: erstelle einen Zusammenfassungsbericht, speichere Visualisierungen und erstelle eine README mit den Erkenntnissen"
                },
                {
                    "type": "container_upload", 
                    "file_id": "'$FILE_ID'"
                }
            ]
        }],
        "tools": [{
            "type": "code_execution_20250825",
            "name": "code_execution"
        }]
    }'

Tool-Definition

Das Code-Ausführungs-Tool benötigt keine zusätzlichen Parameter:

JSON

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

Wenn dieses Tool bereitgestellt wird, erhält Claude automatisch Zugang zu 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-Ausführungs-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": "Hallo, Welt!"
  }
},
{
  "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 von erfolgreicher Ausführung
stderr: Fehlermeldungen bei fehlgeschlagener Ausführung
return_code: 0 für Erfolg, ungleich 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:

Tool	Fehlercode	Beschreibung
Alle Tools	`unavailable`	Das Tool ist vorübergehend nicht verfügbar
Alle Tools	`execution_time_exceeded`	Ausführung überschritt maximales Zeitlimit
Alle Tools	`container_expired`	Container ist abgelaufen und nicht mehr verfügbar
Alle Tools	`invalid_tool_input`	Ungültige Parameter an das Tool übergeben
Alle Tools	`too_many_requests`	Ratenlimit für Tool-Nutzung überschritten
text_editor	`file_not_found`	Datei existiert nicht (für Anzeigen/Bearbeiten-Operationen)
text_editor	`string_not_found`	Der `old_str` wurde in der Datei nicht gefunden (für str_replace)

`pause_turn` Stopp-Grund

Die Antwort kann einen pause_turn Stopp-Grund enthalten, der anzeigt, dass die API einen lang laufenden Turn pausiert hat. Sie können die Antwort unverändert in einer nachfolgenden Anfrage bereitstellen, um Claude seinen Turn fortsetzen zu lassen, oder den Inhalt ändern, wenn Sie die Unterhaltung unterbrechen möchten.

Container

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

Laufzeitumgebung

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

Ressourcenlimits

Arbeitsspeicher: 1GiB RAM
Festplattenspeicher: 5GiB Arbeitsbereich-Speicher
CPU: 1 CPU

Netzwerk und Sicherheit

Internetzugang: Vollständig deaktiviert aus Sicherheitsgründen
Externe Verbindungen: Keine ausgehenden Netzwerkanfragen erlaubt
Sandbox-Isolation: Vollständige Isolation vom Host-System und anderen Containern
Dateizugriff: Beschränkt nur auf Arbeitsbereich-Verzeichnis
Arbeitsbereich-Scoping: Wie Files, sind Container auf den Arbeitsbereich des API-Schlüssels beschränkt
Ablauf: Container laufen 1 Stunde nach Erstellung ab

Vorinstallierte Bibliotheken

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

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

Container-Wiederverwendung

Sie können einen bestehenden 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 zu behalten.

Beispiel

import os
from anthropic import Anthropic

# Den Client initialisieren
client = Anthropic(
    api_key=os.getenv("ANTHROPIC_API_KEY")
)

# Erste Anfrage: Eine Datei mit einer Zufallszahl erstellen
response1 = client.beta.messages.create(
    model="claude-opus-4-1-20250805",
    betas=["code-execution-2025-08-25"],
    max_tokens=4096,
    messages=[{
        "role": "user",
        "content": "Schreibe eine Datei mit einer Zufallszahl und speichere sie unter '/tmp/number.txt'"
    }],
    tools=[{
        "type": "code_execution_20250825",
        "name": "code_execution"
    }]
)

# Die Container-ID aus der ersten Antwort extrahieren
container_id = response1.container.id

# Zweite Anfrage: Den Container wiederverwenden, um die Datei zu lesen
response2 = client.beta.messages.create(
    container=container_id,  # Denselben Container wiederverwenden
    model="claude-opus-4-1-20250805",
    betas=["code-execution-2025-08-25"],
    max_tokens=4096,
    messages=[{
        "role": "user",
        "content": "Lies die Zahl aus '/tmp/number.txt' und berechne ihr Quadrat"
    }],
    tools=[{
        "type": "code_execution_20250825",
        "name": "code_execution"
    }]
)

Streaming

Mit aktiviertem Streaming erhalten Sie Code-Ausführungsereignisse, während 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-Ausführung gestreamt
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 während Code ausgeführt wird

// Ausführungsergebnisse gestreamt
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 der Messages Batches API einschließen. Code-Ausführungs-Tool-Aufrufe über die Messages Batches API werden genauso bepreist wie die in regulären Messages API-Anfragen.

Nutzung und Preise

The code execution tool usage is tracked separately from token usage. Execution time is a minimum of 5 minutes. If files are included in the request, execution time is billed even if the tool is not used due to files being preloaded onto the container. Pricing: $0.05 per session-hour.

Auf neueste Tool-Version aktualisieren

Durch die Aktualisierung auf code-execution-2025-08-25 erhalten Sie Zugang zu Dateimanipulation und Bash-Fähigkeiten, einschließlich Code in mehreren Sprachen. Es gibt keinen Preisunterschied.

Was hat sich geändert

Komponente	Legacy	Aktuell
Beta-Header	`code-execution-2025-05-22`	`code-execution-2025-08-25`
Tool-Typ	`code_execution_20250522`	`code_execution_20250825`
Fähigkeiten	Nur Python	Bash-Befehle, Dateioperationen
Antworttypen	`code_execution_result`	`bash_code_execution_result`, `text_editor_code_execution_result`

Rückwärtskompatibilität

Alle bestehende Python-Code-Ausführung funktioniert weiterhin genau wie zuvor
Keine Änderungen erforderlich für bestehende Python-only Workflows

Aktualisierungsschritte

Um zu aktualisieren, müssen Sie die folgenden Änderungen in Ihren API-Anfragen vornehmen:

Den Beta-Header aktualisieren:

- "anthropic-beta": "code-execution-2025-05-22"
+ "anthropic-beta": "code-execution-2025-08-25"

Den Tool-Typ aktualisieren:

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

Antwortbehandlung überprüfen (falls Antworten programmatisch geparst werden):
- Die vorherigen Blöcke für Python-Ausführungsantworten werden nicht mehr gesendet
- Stattdessen werden neue Antworttypen für Bash und Dateioperationen gesendet (siehe Abschnitt Antwortformat)

Erste Schritte

Modelle & Preise

Mehr über Claude erfahren

Funktionen

Werkzeuge

Model Context Protocol (MCP)

Anwendungsfälle

Prompt Engineering

Testen & bewerten

Schutzmaßnahmen verstärken

Rechtszentrum

​Unterstützte Modelle

​Schnellstart

​Wie Code-Ausführung funktioniert

​Wie man das Tool verwendet

​Bash-Befehle ausführen

​Dateien direkt erstellen und bearbeiten

​Eigene Dateien hochladen und analysieren

​Dateien hochladen und analysieren

​Generierte Dateien abrufen

​Operationen kombinieren

​Tool-Definition

​Antwortformat

​Bash-Befehl-Antwort

​Dateioperations-Antworten

​Ergebnisse

​Fehler

​pause_turn Stopp-Grund

​Container

​Laufzeitumgebung

​Ressourcenlimits

​Netzwerk und Sicherheit

​Vorinstallierte Bibliotheken

​Container-Wiederverwendung

​Beispiel

​Streaming

​Batch-Anfragen

​Nutzung und Preise

​Auf neueste Tool-Version aktualisieren

​Was hat sich geändert

​Rückwärtskompatibilität

​Aktualisierungsschritte

Unterstützte Modelle

Schnellstart

Wie Code-Ausführung funktioniert

Wie man das Tool verwendet

Bash-Befehle ausführen

Dateien direkt erstellen und bearbeiten

Eigene Dateien hochladen und analysieren

Dateien hochladen und analysieren

Generierte Dateien abrufen

Operationen kombinieren

Tool-Definition

Antwortformat

Bash-Befehl-Antwort

Dateioperations-Antworten

Ergebnisse

Fehler

`pause_turn` Stopp-Grund

Container

Laufzeitumgebung

Ressourcenlimits

Netzwerk und Sicherheit

Vorinstallierte Bibliotheken

Container-Wiederverwendung

Beispiel

Streaming

Batch-Anfragen

Nutzung und Preise

Auf neueste Tool-Version aktualisieren

Was hat sich geändert

Rückwärtskompatibilität

Aktualisierungsschritte