Claude Platform Docs
MessagesTools

Code-Ausführungstool

Führe Python- und Bash-Code in einem Sandbox-Container aus, um Daten zu analysieren, Dateien zu generieren und Lösungen iterativ zu verbessern.

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“ (Code-Ausführungstool) ermöglicht es Claude, Bash-Befehle auszuführen und Dateien zu bearbeiten, einschließlich des Schreibens von Code, in einer sicheren, „sandboxed“ (isolierten) Umgebung.

Die Code-Ausführung ist kostenlos, wenn sie zusammen mit Websuche oder Web Fetch (web_search_20260209, web_fetch_20260209 oder neuer) verwendet wird. Wenn eines dieser Tools in deiner Anfrage enthalten ist, fallen für die Code-Ausführung in dieser Anfrage keine zusätzlichen Kosten über die Standard-Token-Kosten hinaus an. Dies umfasst sowohl die Code-Ausführung hinter dem dynamischen Filtern als auch jeglichen Code, den Claude direkt ausführt. Wenn diese Tools nicht enthalten sind, gelten die Standardpreise für die Code-Ausführung.

Die Code-Ausführung treibt auch das „dynamic filtering“ (dynamische Filtern) in den Tools Websuche und Web Fetch an: Claude filtert Ergebnisse innerhalb der Code-Ausführungsumgebung, bevor sie das „context window“ (Kontextfenster) erreichen. Wenn dynamisches Filtern ausgeführt wird, stellt die API die für die Anfrage benötigte Code-Ausführung automatisch bereit, sodass du das Code-Ausführungstool dafür nicht zu deiner Anfrage hinzufügen musst.

Tool-Versionen

Das Code-Ausführungstool hat drei aktuelle Versionen, und jedes unterstützte Modell akzeptiert alle drei. Jede Version baut auf der vorherigen auf:

  • code_execution_20250825 unterstützt Bash-Befehle und Dateioperationen.
  • code_execution_20260120 ergänzt REPL-Zustandspersistenz und programmatische Tool-Aufrufe („programmatic tool calling“) aus der Sandbox heraus. Claude Haiku 4.5 akzeptiert die Tool-Typen code_execution_20260120 und code_execution_20260521, aber programmatische Tool-Aufrufe und die davon abhängige REPL-Zustandspersistenz sind dort nicht verfügbar, daher verhalten sich die neueren Versionen dort wie code_execution_20250825.
  • code_execution_20260521 ist dieselbe Laufzeitumgebung wie code_execution_20260120. Der Unterschied besteht darin, dass die Tool-Beschreibung Claude über das 90-Sekunden-Wall-Clock-Limit für jede Python-Zelle bei programmatischen Tool-Aufrufen informiert, sodass Claude lang laufende Zellen einplanen kann. Eine Zelle, die das Limit überschreitet, gibt ein normales Code-Ausführungsergebnis mit einem return_code ungleich null und einer detection_timeout-Statusmeldung in ihrer Ausgabe zurück. Dies ist unabhängig vom Fehlercode execution_time_exceeded, den die API zurückgibt, wenn ein gesamter Tool-Aufruf die maximale Ausführungszeit überschreitet.

Für Claude Mythos Preview wird die Code-Ausführung auf der Claude API und Microsoft Foundry unterstützt.

Keine der drei Tool-Versionen erfordert einen anthropic-beta-Header. Die veralteten Beta-Header für die Code-Ausführung bleiben gültige Opt-ins.

Die Beispiele auf dieser Seite verwenden code_execution_20250825, das die gezeigten Bash- und Dateioperationen abdeckt und sich auf jedem unterstützten Modell gleich verhält; verwende code_execution_20260120 oder neuer, wenn du programmatische Tool-Aufrufe oder REPL-Zustandspersistenz benötigst. Die aktuellen Tools Websuche und Web Fetch (web_search_20260209, web_fetch_20260209 und neuer) erfordern code_execution_20260120 oder neuer als ihre Code-Ausführungsversion.

Ältere Tool-Versionen bleiben nicht garantiert mit neueren Modellen kompatibel. Wenn du ein neues Modell einführst, prüfe Tool-Versionen und API-Unterstützung und bevorzuge die neueste Tool-Version, die deine Integration unterstützt.

Um zu prüfen, ob ein Modell das Code-Ausführungstool akzeptiert, bevor du eine Anfrage sendest, lies seinen Wert capabilities.server_tools.code_execution.supported aus der Models API aus. Verwende dafür nicht den Top-Level-Wert capabilities.code_execution. Dieser gibt an, ob Code, der in diesem Tool ausgeführt wird, die anderen Tools deiner Anfrage aufrufen kann, wie bei programmatischen Tool-Aufrufen. Verwendung der Models API beschreibt beide Felder.

Schnellstart

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

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())

Die Antwort verschachtelt server_tool_use-Blöcke (die Befehle, die Claude ausgeführt hat) mit ihren Tool-Ergebnisblöcken, gefolgt vom Text von Claude. Die oberste Ebene enthält außerdem ein container-Objekt, dessen id du über Anfragen hinweg wiederverwenden kannst. Siehe Antwortformat für die Struktur der Blöcke.

Wie die Code-Ausführung funktioniert

Wenn du das Code-Ausführungstool zu deiner API-Anfrage hinzufügst:

  1. Claude bewertet, ob die 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 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 einem sicheren Sandbox-Container. Der Container hat keinen Internetzugang, daher kann Claude zur Laufzeit keine Pakete herunterladen: Nur die vorinstallierten Bibliotheken sind verfügbar.
  5. Die API führt jeden Befehl serverseitig aus und gibt die Ergebnisse innerhalb derselben Anfrage an Claude zurück, sodass du niemals selbst Code ausführst oder tool_result-Blöcke zurücksendest. Eine Ausnahme ist, wenn Claude eines deiner Client-Tools zusammen mit der Code-Ausführung aufruft: Die API gibt den Code-Ausführungsaufruf ohne sein Ergebnis zurück. Das Ergebnis kommt in einer späteren Antwort, nachdem du die tool_result-Blöcke für deine Client-Tools zurückgesendet hast.
  6. Jede Anfrage läuft in einem neuen Container, es sei denn, du übergibst die Container-ID einer früheren Antwort zurück (siehe Container-Wiederverwendung).
  7. Claude liefert Ergebnisse mit allen generierten Diagrammen, Berechnungen oder Analysen.

Im Container ist Python vorinstalliert. Claude schreibt Python mit dem Sub-Tool für Dateioperationen und führt es mit einem Bash-Befehl aus. Mit code_execution_20260120 oder neuer und programmatischen Tool-Aufrufen bleibt auch der Zustand des Python-Interpreters (wie Variablenbindungen) über Anfragen hinweg erhalten, die den Container wiederverwenden.

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äzisionsempfindliche Ergebnisse)
  • Datenanalyse, Datei-Parsing oder Visualisierung
  • Ausführung von Algorithmen oder Simulationen
  • Ausdrückliche Aufforderungen zum „Ausführen“, „Berechnen“ oder „Durchführen“

Claude antwortet direkt, ohne Code auszuführen, 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, bitte ausdrücklich darum (zum Beispiel „führe Code aus, um dies zu überprüfen“).

Mit Dateien arbeiten

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 über die Files API hochgeladene Dateitypen verarbeiten, 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-Ausführungstool in deine API-Anfrage ein.
client = anthropic.Anthropic()

# Lade eine Datei hoch
file_object = client.files.upload(file=Path("data.csv"))

# Verwende die file_id mit Code-Ausführung
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())

Generierte Dateien abrufen

Wenn Claude während der Code-Ausführung Dateien in seinem Ausgabeverzeichnis speichert (siehe Wie generierte Dateien erfasst werden), erscheint die ID jeder Datei im Ergebnis des Code-Ausführungstools, und du kannst sie mit der Files API herunterladen:

client = Anthropic()

# Fordere eine Code-Ausführung an, die Dateien erstellt
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"}],
)


# Extrahiere die Datei-IDs aus der Antwort
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


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

Wie generierte Dateien erfasst werden

Jeder bash_code_execution-Aufruf erhält ein neues, leeres Verzeichnis, das dem Befehl als $OUTPUT_DIR zur Verfügung steht. Wenn der Befehl abgeschlossen ist, werden die Dateien auf der obersten Ebene dieses Verzeichnisses erfasst und als file_id-Einträge in der content-Liste des Ergebnisses zurückgegeben. Dateien, die an einer anderen Stelle geschrieben werden, bleiben im Container und werden nicht zurückgegeben.

Die Tool-Beschreibung weist Claude an, Dateien zu teilen, indem es sie nach $OUTPUT_DIR kopiert. Wenn deine Anwendung darauf angewiesen ist, eine Datei zu erhalten, fordere Claude auf, sie nach $OUTPUT_DIR zu kopieren und das Verzeichnis im selben Befehl aufzulisten, sodass die ls-Ausgabe die Erfassung bestätigt (Claude erhält die content-Liste nicht):

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

Eine Datei, die Claude an einer anderen Stelle geschrieben hat, befindet sich weiterhin im Container, sodass du den Container wiederverwenden und Claude bitten kannst, sie nach $OUTPUT_DIR zu kopieren.

Content Credentials für generierte Dateien

Auf der Claude API tragen unterstützte Bild-, Video- und Audiodateien, die Claude in der Code-Ausführungs-Sandbox erzeugt, C2PA-Content-Credentials, wenn du sie über die Files API herunterlädst. Unterstützte Formate umfassen PNG, JPEG, GIF, WebP, TIFF, HEIC, AVIF, SVG, MP4, MOV, MP3, WAV, FLAC und M4A. Das Credential ist ein kryptografisch signiertes Manifest, das in die Metadaten der Datei eingebettet ist. Es identifiziert Anthropic als Aussteller, trägt einen Zeitstempel und erfasst die Aktionsbeschreibung „Claude provided this file at the request of a user and may have created or modified the file contents.“

Die Signierung erfordert keine Änderungen an deinen Anfragen oder deiner Antwortverarbeitung, und das Manifest erfasst nichts über dich, deine Organisation oder deine Anfrage. Der sichtbare Inhalt der Datei bleibt unverändert. Das Manifest fügt einige Kilobyte hinzu, sodass sich Größe und Prüfsumme der heruntergeladenen Datei von der Datei unterscheiden, wie sie im Container existiert. Textdateien, PDFs und Office-Dokumente werden nicht signiert, da sie keine unterstützten Formate für die Signierung sind. Dateien, die du hochlädst, werden unverändert gespeichert, einschließlich aller Content Credentials, die sie bereits tragen.

Um ein Credential zu überprüfen, untersuche die Datei mit einem beliebigen C2PA-kompatiblen Tool, wie dem Open-Source-Kommandozeilenprogramm c2patool. Neukodierung, Formatkonvertierung, Screenshots und Tools, die Metadaten entfernen, entfernen das Credential, sodass ein fehlendes Credential nicht bedeutet, dass eine Datei nicht mit Claude erzeugt wurde. Mehr dazu, warum ein Credential fehlen kann, findest du unter Wie Claude KI-generierte Inhalte kennzeichnet.

Tool-Definition

Das Code-Ausführungstool erfordert keine zusätzlichen Parameter:

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

Beide Felder sind festgelegt: type wählt die Tool-Version aus, und name muss code_execution sein.

Wenn du dieses Tool bereitstellst, 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

Wenn Claude Code ausführt, enthält die Antwort außerdem ein Top-Level-container-Objekt mit der id des Containers und dem Zeitstempel expires_at. Übergib diese ID im Top-Level-Anfrageparameter container zurück, um denselben Container weiter zu verwenden. Siehe Container-Wiederverwendung.

Antwortformat

Das Code-Ausführungstool kann je nach Operation zwei Arten von Ergebnissen zurückgeben:

Antwort auf Bash-Befehle

Output
{
  "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": []
  }
}

Antworten auf Dateioperationen

Datei anzeigen:

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

Datei erstellen:

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

Datei bearbeiten (str_replace):

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

Ergebnisse

Ergebnisse von Bash-Befehlen (bash_code_execution_result) enthalten:

  • stdout: Ausgabe bei erfolgreicher Ausführung
  • stderr: Fehlermeldungen, wenn die Ausführung fehlschlägt
  • return_code: 0 bei Erfolg, ungleich null bei Fehlschlag
  • content: Eine Liste mit einem Eintrag für jede Datei, die der Befehl in $OUTPUT_DIR hinterlassen hat (siehe Wie generierte Dateien erfasst werden). Jeder Eintrag enthält die file_id, um die Datei mit der Files API abzurufen

Ergebnisse von Dateioperationen haben eigene Felder:

  • Anzeigen (text_editor_code_execution_view_result): file_type, content, num_lines, start_line, total_lines
  • Erstellen (text_editor_code_execution_create_result): is_file_update (ob die Datei bereits existierte)
  • Bearbeiten (text_editor_code_execution_str_replace_result): old_start, old_lines, new_start, new_lines, lines (Diff-Format)

Fehler

Jeder Tool-Typ kann spezifische Fehler zurückgeben:

Häufige Fehler (alle Tools):

Output
{
  "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:

ToolFehlercodeBeschreibung
Alle ToolsunavailableDas Tool ist vorübergehend nicht verfügbar
Alle Toolsexecution_time_exceededDer Tool-Aufruf hat die maximale Ausführungszeit überschritten
Alle Toolsinvalid_tool_inputUngültige Parameter wurden an das Tool übergeben
Alle Toolstoo_many_requestsRatenlimit für die Tool-Nutzung überschritten
bashoutput_file_too_largeDie Befehlsausgabe hat die maximale Größe überschritten
text_editorfile_not_foundDie Datei existiert nicht (bei Anzeige-/Bearbeitungsoperationen)

Ein abgelaufener Container kann nicht wiederverwendet werden: Anfragen, die darauf verweisen, geben einen Fehler zurück, anstatt ihn wiederherzustellen. Sende die Anfrage erneut ohne den Parameter container, um einen neuen Container zu erhalten.

Stop-Grund pause_turn

Die Antwort kann einen Stop-Grund pause_turn 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 fortsetzen kann, oder den Inhalt ändern, wenn du die Konversation unterbrechen möchtest.

Sende die Container-ID der Antwort mit dieser Anfrage zurück (siehe Container-Wiederverwendung). Ohne sie wird die Anfrage in einem neuen Container ausgeführt, und Dateien aus früheren Teilen des Turns gehen verloren.

Container

Das Code-Ausführungstool läuft in einer sicheren, containerisierten Umgebung, die speziell für die Code-Ausführung konzipiert ist, mit einem stärkeren Fokus auf Python.

Laufzeitumgebung

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

Ressourcenlimits

  • Arbeitsspeicher: Der Container hat 5 GiB RAM.
  • Speicherplatz: Der Container hat 5 GiB Workspace-Speicher.
  • CPU: Der Container hat 1 CPU.
  • Ausführungszeit: Ein Tool-Aufruf, der über die maximale Ausführungszeit hinaus läuft, gibt einen Fehler execution_time_exceeded zurück. Bei programmatischen Tool-Aufrufen hat jede REPL-Zelle zusätzlich ein Wall-Clock-Limit von 90 Sekunden.

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: Nur auf das Workspace-Verzeichnis beschränkt
  • Workspace-Zuordnung: Auf den Workspace der Anfrage beschränkt, wie bei der Files API
  • Ablauf: 30 Tage nach der Erstellung

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, xlsxwriter, xlrd, pillow, python-pptx, python-docx, pypdf, pdfplumber, pypdfium2, pdf2image, pdfkit, tabula-py, reportlab[pycairo], Img2pdf
  • Mathematik und Berechnung: sympy, mpmath
  • Hilfsprogramme: tqdm, python-dateutil, pytz, joblib

Der Container enthält außerdem Kommandozeilen-Tools wie unzip, unrar, 7zip, bc, rg (ripgrep), fd und sqlite.

Der Container hat keinen Internetzugang, daher kann Claude zur Laufzeit keine zusätzlichen Pakete herunterladen oder installieren: Nur die vorinstallierten Bibliotheken sind verfügbar.

Container-Wiederverwendung

Du kannst einen bestehenden Container über mehrere API-Anfragen hinweg wiederverwenden, indem du die Container-ID aus einer vorherigen Antwort angibst. So kannst du erstellte Dateien zwischen Anfragen beibehalten. Mit code_execution_20260120 oder neuer und programmatischen Tool-Aufrufen bleibt auch der Zustand des Python-Interpreters erhalten.

Container laufen 30 Tage nach der Erstellung ab. Nach etwa 5 Minuten Inaktivität wird ein Container per Checkpoint gesichert, und das Senden einer Anfrage mit seiner ID innerhalb des 30-Tage-Zeitraums stellt ihn wieder her. Der Zeitstempel expires_at im container-Objekt der Antwort ist ein kürzerer, fortlaufend aktualisierter Wert und gibt nicht das 30-Tage-Limit an. Ein abgelaufener Container kann nicht wiederverwendet werden. Sende die Anfrage erneut ohne den Parameter container, um einen neuen Container zu erhalten.

Beispiel

client = anthropic.Anthropic()

# Erste Anfrage: Erstelle eine Datei mit einer Zufallszahl in einem neuen Container
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"}],
)

# Zweite Anfrage: Gib die Container-ID zurück, damit Claude denselben Container wiederverwendet
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())

Code-Ausführung mit anderen Ausführungstools verwenden

Wenn du die Code-Ausführung zusammen mit vom Client bereitgestellten Tools anbietest, die ebenfalls Code ausführen (wie ein Bash-Tool oder eine benutzerdefinierte REPL), arbeitet Claude in einer Multi-Computer-Umgebung. Das Code-Ausführungstool läuft im Sandbox-Container von Anthropic, während deine vom Client bereitgestellten Tools in einer separaten Umgebung laufen, die du kontrollierst. Claude kann manchmal das falsche Tool verwenden oder so handeln, als ob der Zustand zwischen diesen Umgebungen geteilt würde.

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

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

Dies ist besonders wichtig, wenn du die Code-Ausführung mit Websuche oder Web Fetch kombinierst, die 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, die Claude von der ersten unterscheiden muss.

Wenn Claude eines deiner Client-Tools zusammen mit der Code-Ausführung aufruft, gibt die API den Code-Ausführungsaufruf ohne sein Ergebnis zurück. Das Ergebnis kommt in einer späteren Antwort, nachdem du die tool_result-Blöcke für deine Client-Tools zurückgesendet hast.

Streaming

Wenn Streaming aktiviert ist ("stream": true), erhältst du Code-Ausführungsereignisse, sobald sie auftreten. Die Eingabe des Sub-Tools wird als input_json_delta-Ereignisse gestreamt, und jeder Ergebnisblock kommt vollständig in einem einzigen content_block_start-Ereignis an:

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

Batch-Anfragen

Du kannst das Code-Ausführungstool in die Messages Batches API einbinden. Aufrufe des Code-Ausführungstools über die Messages Batches API werden genauso abgerechnet wie jene in regulären Messages-API-Anfragen.

Nutzung und Preise

Die Code-Ausführung ist kostenlos, wenn sie zusammen 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 Gebühren über die standardmäßigen Kosten für Eingabe- und Ausgabe-Token hinaus an.

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 beträgt mindestens 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 USD pro Stunde und Container abgerechnet.
  • Wenn Dateien in der Anfrage enthalten sind, wird die Ausführungszeit auch dann abgerechnet, 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
    }
  }
}

Auf die neueste Tool-Version aktualisieren

Die neueste Tool-Version ist code_execution_20260521. Um zwischen den drei aktuellen Versionen zu wechseln, aktualisiere den type-String in deiner Anfrage: Alle drei geben die unter Antwortformat dokumentierten Antwortblöcke zurück. Siehe Tool-Versionen für die Neuerungen jeder Version und API-Unterstützung für die Modelle, die sie unterstützen.

Der Rest dieses Abschnitts behandelt die Migration vom veralteten, nur Python unterstützenden code_execution_20250522 zu den aktuellen Tool-Versionen.

Was sich geändert hat

KomponenteVeraltetAktuell
Beta-Headercode-execution-2025-05-22Nicht erforderlich
Tool-Typcode_execution_20250522code_execution_20250825 oder neuer
FähigkeitenNur PythonBash-Befehle, Dateioperationen
Antworttypencode_execution_resultbash_code_execution_result, text_editor_code_execution_*_result

Abwärtskompatibilität

  • Alle bestehenden Python-Code-Ausführungen funktionieren genau wie zuvor weiter
  • Keine Änderungen an bestehenden, nur Python nutzenden Workflows erforderlich

Schritte zur Aktualisierung

Um zu aktualisieren, ändere 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 API sendet die bisherigen Blöcke für Python-Ausführungsantworten nicht mehr.
  • Stattdessen sendet die API neue Antworttypen für Bash- und Dateioperationen (siehe Antwortformat).

Datenaufbewahrung

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

Nächste Schritte

Kombiniere ein schnelleres Ausführungsmodell mit einem intelligenteren Advisor-Modell, das während der Generierung strategische Orientierung bietet.

Rufe deine eigenen Tools aus Code auf, der im Code-Ausführungscontainer läuft.

Lade Dateien zur Analyse hoch und lade die Dateien herunter, die die Code-Ausführung erstellt.

Erfahre, wie du Agent Skills verwendest, um die Fähigkeiten von Claude über die API zu erweitern.

Verfügbarkeit

Code-Ausführungstool
Die Verfügbarkeitsanforderungen für Code-Ausführungstool sind auf allen unterstützten Plattformen gleich.
API
  • Messages API
Modelle
  • Alle Modelle

Zutreffende Endpunkte

  • /v1/messages mit Tool code_execution
Zero Data RetentionNicht berechtigt

Container-Daten werden bis zu 30 Tage aufbewahrt. Mehr erfahren

HIPAANicht berechtigt

War diese Seite hilfreich?