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

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": "Calculate the mean and standard deviation of [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 die 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. Die Code-Ausführung kann mehrmals während einer einzelnen Anfrage erfolgen
  4. Claude liefert Ergebnisse mit generierten Diagrammen, Berechnungen oder Analysen

​
Tool-Definition

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

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

​
Antwortformat

Hier ist ein Beispiel für eine Antwort mit Code-Ausführung:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll calculate the mean and standard deviation for you."
    },
    {
      "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\"Mean: {mean}\")\nprint(f\"Standard deviation: {std}\")"
      }
    },
    {
      "type": "code_execution_tool_result",
      "tool_use_id": "srvtoolu_01A2B3C4D5E6F7G8H9I0J1K2",
      "content": {
        "type": "code_execution_result",
        "stdout": "Mean: 5.5\nStandard deviation: 2.8722813232690143\n",
        "stderr": "",
        "return_code": 0
      }
    },
    {
      "type": "text",
      "text": "The mean of the dataset is 5.5 and the standard deviation is approximately 2.87."
    }
  ],
  "id": "msg_01BqK2v4FnRs4xTjgL8EuZxz",
  "model": "claude-opus-4-20250514",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 45,
    "output_tokens": 187,
    "server_tool_use": {
      "execution_time_seconds": 1.5
    }
  }
}

​
Ergebnisse

Die Ergebnisse der Code-Ausführung 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 bei der Verwendung des Tools ein Fehler auftritt, wird ein code_execution_tool_result_error angezeigt

{
  "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: Die Ausführungszeit hat das maximal erlaubte Limit überschritten
  • container_expired: Der Container ist abgelaufen und nicht verfügbar

​
pause_turn stop reason

Die Antwort kann einen pause_turn stop reason enthalten, der anzeigt, dass die API einen lang laufenden Durchgang pausiert hat. Sie können die Antwort unverändert in einer nachfolgenden Anfrage zurückgeben, um Claude seinen Durchgang fortsetzen zu lassen, oder den Inhalt modifizieren, wenn Sie die Konversation unterbrechen möchten.

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

​
Ressourcenbeschränkungen

  • Speicher: 1GiB RAM
  • Festplattenspeicher: 5GiB Arbeitsbereichsspeicher
  • CPU: 1 CPU
  • Ausführungs-Timeout: Die Ausführung ist pro Messages-Anfrage begrenzt und kann mit dem Parameter max_execution_duration gesteuert werden
  • Container-Ablauf: Nach 1 Stunde Inaktivität kann auf den Container nicht mehr zugegriffen werden

​
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: Beschränkt auf das Arbeitsverzeichnis

​
Vorinstallierte Bibliotheken

Die isolierte 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
  • Mathematik & Computing: sympy, mpmath
  • Hilfsprogramme: tqdm, python-dateutil, pytz, joblib

​
Arbeiten mit Dateien in der Code-Ausführung

Die Code-Ausführung kann über die Files API hochgeladene Dateien analysieren, wie CSV-Dateien, Excel-Dateien und andere Datenformate. Dies ermöglicht es Claude, Ihre Daten zu lesen, zu verarbeiten und Erkenntnisse daraus zu gewinnen.

Die Verwendung der Files API mit der 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 kann mit folgenden Dateitypen arbeiten, ist aber nicht darauf beschränkt:

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

​
Beispiel

  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-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 der 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": "Analyze this CSV data"},
                {"type": "container_upload", "file_id": "file_abc123"}
            ]
        }],
        "tools": [{
            "type": "code_execution_20250522",
            "name": "code_execution"
        }]
    }'

​
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-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 der 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 einbinden. Code-Ausführungs-Tool-Aufrufe über die Messages Batches API werden genauso berechnet wie in regulären Messages API-Anfragen.

​
Nutzung und Preisgestaltung

Die Nutzung des Code-Ausführungs-Tools wird separat von der Token-Nutzung erfasst. Die Ausführungszeit beträgt mindestens 5 Minuten. Wenn Dateien in der Anfrage enthalten sind, wird die Ausführungszeit auch dann berechnet, wenn das Tool nicht verwendet wird, da Dateien vorab auf den Container geladen werden.

Preisgestaltung: 0,05 $ pro Sitzungsstunde.