Das Code-Ausführungs-Tool ermöglicht es Claude, Python-Code in einer sicheren, sandboxed Umgebung auszuführen. Claude kann Daten analysieren, Visualisierungen erstellen, komplexe Berechnungen durchführen und hochgeladene Dateien direkt innerhalb der API-Konversation verarbeiten.

Das Code-Ausführungs-Tool befindet sich derzeit in der Beta-Phase.

Diese Funktion erfordert den Beta-Header: "anthropic-beta": "code-execution-2025-05-22"

​
Unterstützte Modelle

Das Code-Ausführungs-Tool ist verfügbar für:

  • 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-05-22" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-20250514",
        "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_20250522",
            "name": "code_execution"
        }]
    }'

​
Wie die Code-Ausführung funktioniert

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

  1. Claude bewertet, ob Code-Ausführung bei der Beantwortung Ihrer Frage helfen würde
  2. Claude schreibt und führt Python-Code in einer sicheren Sandbox-Umgebung aus
  3. Code-Ausführung kann mehrmals während einer einzigen Anfrage auftreten
  4. Claude liefert Ergebnisse mit allen generierten Diagrammen, Berechnungen oder Analysen

​
Tool-Definition

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

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

​
Antwortformat

Hier ist ein Beispiel einer Antwort mit Code-Ausführung:

{
  "role": "assistant",
  "container": {
    "id": "container_011CPR5CNjB747bTd36fQLFk",
    "expires_at": "2025-05-23T21:13:31.749448Z"
  },
  "content": [
    {
      "type": "text",
      "text": "Ich werde den Mittelwert und die Standardabweichung für Sie berechnen."
    },
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01A2B3C4D5E6F7G8H9I0J1K2",
      "name": "code_execution",
      "input": {
        "code": "import numpy as np\ndata = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]\nmean = np.mean(data)\nstd = np.std(data)\nprint(f\"Mittelwert: {mean}\")\nprint(f\"Standardabweichung: {std}\")"
      }
    },
    {
      "type": "code_execution_tool_result",
      "tool_use_id": "srvtoolu_01A2B3C4D5E6F7G8H9I0J1K2",
      "content": {
        "type": "code_execution_result",
        "stdout": "Mittelwert: 5.5\nStandardabweichung: 2.8722813232690143\n",
        "stderr": "",
        "return_code": 0
      }
    },
    {
      "type": "text",
      "text": "Der Mittelwert des Datensatzes ist 5,5 und die Standardabweichung beträgt etwa 2,87."
    }
  ],
  "id": "msg_01BqK2v4FnRs4xTjgL8EuZxz",
  "model": "claude-opus-4-20250514",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 45,
    "output_tokens": 187,
  }
}

​
Ergebnisse

Code-Ausführungsergebnisse umfassen:

  • stdout: Ausgabe von print-Anweisungen und erfolgreicher Ausführung
  • stderr: Fehlermeldungen, wenn die Code-Ausführung fehlschlägt
  • return_code (0 für Erfolg, ungleich null für Fehler)
{
  "type": "code_execution_tool_result",
  "tool_use_id": "srvtoolu_01ABC123",
  "content": {
    "type": "code_execution_result",
    "stdout": "",
    "stderr": "NameError: name 'undefined_variable' is not defined",
    "return_code": 1
  }
}

​
Fehler

Wenn ein Fehler bei der Verwendung des Tools auftritt, wird es ein code_execution_tool_result_error geben

{
  "type": "code_execution_tool_result",
  "tool_use_id": "srvtoolu_01VfmxgZ46TiHbmXgy928hQR",
  "content": {
    "type": "code_execution_tool_result_error",
    "error_code": "unavailable"
  }
}

Mögliche Fehler umfassen

  • unavailable: Das Code-Ausführungs-Tool ist nicht verfügbar
  • code_execution_exceeded: Ausführungszeit überschritt das maximal erlaubte Limit
  • container_expired: Der Container ist abgelaufen und nicht verfügbar

​
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 Konversation unterbrechen möchten.

​
Arbeiten mit Dateien in der Code-Ausführung

Die Code-Ausführung kann Dateien analysieren, die über die Files API hochgeladen wurden, wie CSV-Dateien, Excel-Dateien und andere Datenformate. Dies ermöglicht es Claude, Ihre Daten zu lesen, zu verarbeiten und Erkenntnisse daraus zu generieren. Sie können mehrere Dateien pro Anfrage übergeben.

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

​
Unterstützte Dateitypen

Die Python-Umgebung ist in der Lage, mit den folgenden Dateitypen zu arbeiten, ist aber nicht darauf beschränkt

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

​
Laden von Dateien für die Code-Ausführung

  1. Laden Sie Ihre Datei hoch mit der Files API
  2. Referenzieren Sie die Datei in Ihrer Nachricht mit einem container_upload Inhaltsblock
  3. Fügen Sie das Code-Ausführungs-Tool in Ihre API-Anfrage ein
# 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-05-22,files-api-2025-04-14" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-20250514",
        "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_20250522",
            "name": "code_execution"
        }]
    }'

​
Abrufen von Dateien, die durch Code-Ausführung erstellt wurden

Wenn Claude während der Code-Ausführung Dateien erstellt (z.B. Speichern von matplotlib-Plots, Generieren von CSVs), 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-20250514",
    betas=["code-execution-2025-05-22", "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_20250522",
        "name": "code_execution"
    }]
)

# Datei-IDs aus der Antwort extrahieren
def extract_file_ids(response):
    file_ids = []
    for item in response.content:
        if item.type == '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}")

​
Container

Das Code-Ausführungs-Tool läuft in einer sicheren, containerisierten Umgebung, die speziell für die Python-Code-Ausführung entwickelt wurde.

​
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 auf Arbeitsbereich-Verzeichnis nur
  • Arbeitsbereich-Scoping: Wie Files, sind Container auf den Arbeitsbereich des API-Schlüssels beschränkt
  • Ablauf: Container laufen 1 Stunde nach der 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
  • Dateiverarbeitung: pyarrow, openpyxl, xlrd, pillow
  • Mathematik & Computing: sympy, mpmath
  • Utilities: tqdm, python-dateutil, pytz, joblib

​
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-20250514",
    betas=["code-execution-2025-05-22"],
    max_tokens=4096,
    messages=[{
        "role": "user",
        "content": "Schreibe eine Datei mit einer Zufallszahl und speichere sie unter '/tmp/number.txt'"
    }],
    tools=[{
        "type": "code_execution_20250522",
        "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-20250514",
    betas=["code-execution-2025-05-22"],
    max_tokens=4096,
    messages=[{
        "role": "user",
        "content": "Lies die Zahl aus '/tmp/number.txt' und berechne ihr Quadrat"
    }],
    tools=[{
        "type": "code_execution_20250522",
        "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.