Loading...
    0
    • Entwicklerleitfaden
    • API-Referenz
    • MCP
    • Ressourcen
    • Versionshinweise
    Search...
    ⌘K
    Erste Schritte
    Einführung in ClaudeSchnelleinstieg
    Modelle & Preise
    ModellübersichtModell auswählenNeuerungen in Claude 4.5Migration zu Claude 4.5ModellabschreibungenPreise
    Mit Claude entwickeln
    FunktionsübersichtMessages API verwendenKontextfensterBest Practices für Prompts
    Fähigkeiten
    Prompt-CachingKontext-BearbeitungErweitertes DenkenAufwandStreaming MessagesBatch-VerarbeitungZitateMehrsprachige UnterstützungToken-ZählungEmbeddingsVisionPDF-UnterstützungFiles APISuchergebnisseStrukturierte AusgabenGoogle Sheets Add-on
    Tools
    ÜbersichtTool-Nutzung implementierenToken-effiziente Tool-NutzungFeingranulares Tool-StreamingBash-ToolCode-Ausführungs-ToolProgrammatischer Tool-AufrufComputer-Use-ToolText-Editor-ToolWeb-Fetch-ToolWeb-Such-ToolMemory-ToolTool-Such-Tool
    Agent Skills
    ÜbersichtSchnelleinstiegBest PracticesSkills mit der API verwenden
    Agent SDK
    ÜbersichtTypeScript SDKPython SDKMigrationsleitfaden
    Leitfäden
    Streaming-EingabeBerechtigungen handhabenSitzungsverwaltungStrukturierte Ausgaben im SDKAgent SDK hostenSystem-Prompts ändernMCP im SDKBenutzerdefinierte ToolsSubagents im SDKSchrägstrich-Befehle im SDKAgent Skills im SDKKosten und Nutzung verfolgenTodo-ListenPlugins im SDK
    MCP in der API
    MCP-ConnectorRemote MCP-Server
    Claude auf Drittanbieter-Plattformen
    Amazon BedrockMicrosoft FoundryVertex AI
    Prompt Engineering
    ÜbersichtPrompt-GeneratorPrompt-Vorlagen verwendenPrompt-VerbessererKlar und direkt seinBeispiele verwenden (Multishot Prompting)Claude denken lassen (CoT)XML-Tags verwendenClaude eine Rolle geben (System Prompts)Claudeś Antwort vorausfüllenKomplexe Prompts verkettenTipps für langen KontextTipps für erweitertes Denken
    Testen & Evaluieren
    Erfolgskriterien definierenTestfälle entwickelnEvaluierungs-Tool verwendenLatenz reduzieren
    Schutzmaßnahmen verstärken
    Halluzinationen reduzierenAusgabekonsistenz erhöhenJailbreaks abschwächenStreaming-AblehnungenPrompt-Lecks reduzierenClaude im Charakter halten
    Verwaltung und Überwachung
    Admin API ÜbersichtNutzungs- und Kosten-APIClaude Code Analytics API
    Console
    Tools

    Programmatische Werkzeugaufrufe

    Claude kann Code schreiben, der Ihre Werkzeuge programmatisch innerhalb eines Code-Ausführungscontainers aufruft, anstatt mehrere Durchläufe durch das Modell für jeden Werkzeugaufruf zu erfordern.

    Programmatische Werkzeugaufrufe ermöglichen es Claude, Code zu schreiben, der Ihre Werkzeuge programmatisch innerhalb eines Code-Ausführungs-Containers aufruft, anstatt mehrere Durchläufe durch das Modell für jeden Werkzeugaufruf zu erfordern. Dies reduziert die Latenz für Multi-Tool-Workflows und verringert den Token-Verbrauch, indem Claude Daten filtern oder verarbeiten kann, bevor sie das Kontextfenster des Modells erreichen.

    Programmatische Werkzeugaufrufe befinden sich derzeit in der öffentlichen Beta.

    Um diese Funktion zu nutzen, fügen Sie den "advanced-tool-use-2025-11-20" Beta-Header zu Ihren API-Anfragen hinzu.

    Diese Funktion erfordert, dass das Code-Ausführungswerkzeug aktiviert ist.

    Modellkompatibilität

    Programmatische Werkzeugaufrufe sind auf den folgenden Modellen verfügbar:

    ModellWerkzeugversion
    Claude Opus 4.5 (claude-opus-4-5-20251101)code_execution_20250825
    Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)code_execution_20250825

    Programmatische Werkzeugaufrufe sind über die Claude API und Microsoft Foundry verfügbar.

    Schnellstart

    Hier ist ein einfaches Beispiel, bei dem Claude programmatisch mehrmals eine Datenbank abfragt und Ergebnisse aggregiert:

    curl https://api.anthropic.com/v1/messages \
        --header "x-api-key: $ANTHROPIC_API_KEY" \
        --header "anthropic-version: 2023-06-01" \
        --header "anthropic-beta: advanced-tool-use-2025-11-20" \
        --header "content-type: application/json" \
        --data '{
            "model": "claude-sonnet-4-5",
            "max_tokens": 4096,
            "messages": [
                {
                    "role": "user",
                    "content": "Query sales data for the West, East, and Central regions, then tell me which region had the highest revenue"
                }
            ],
            "tools": [
                {
                    "type": "code_execution_20250825",
                    "name": "code_execution"
                },
                {
                    "name": "query_database",
                    "description": "Execute a SQL query against the sales database. Returns a list of rows as JSON objects.",
                    "input_schema": {
                        "type": "object",
                        "properties": {
                            "sql": {
                                "type": "string",
                                "description": "SQL query to execute"
                            }
                        },
                        "required": ["sql"]
                    },
                    "allowed_callers": ["code_execution_20250825"]
                }
            ]
        }'

    Wie programmatische Werkzeugaufrufe funktionieren

    Wenn Sie ein Werkzeug so konfigurieren, dass es von der Code-Ausführung aufgerufen werden kann, und Claude beschließt, dieses Werkzeug zu verwenden:

    1. Claude schreibt Python-Code, der das Werkzeug als Funktion aufruft, möglicherweise mit mehreren Werkzeugaufrufen und Vor-/Nachbearbeitungslogik
    2. Claude führt diesen Code in einem Sandbox-Container über Code-Ausführung aus
    3. Wenn eine Werkzeugfunktion aufgerufen wird, pausiert die Code-Ausführung und die API gibt einen tool_use-Block zurück
    4. Sie stellen das Werkzeugergebnis bereit, und die Code-Ausführung wird fortgesetzt (Zwischenergebnisse werden nicht in Claudes Kontextfenster geladen)
    5. Sobald die gesamte Code-Ausführung abgeschlossen ist, erhält Claude die endgültige Ausgabe und setzt die Arbeit an der Aufgabe fort

    Dieser Ansatz ist besonders nützlich für:

    • Große Datenverarbeitung: Filtern oder aggregieren Sie Werkzeugergebnisse, bevor sie Claudes Kontext erreichen
    • Multi-Step-Workflows: Sparen Sie Token und Latenz, indem Sie Werkzeuge nacheinander oder in einer Schleife aufrufen, ohne Claude zwischen Werkzeugaufrufen zu samplen
    • Bedingte Logik: Treffen Sie Entscheidungen basierend auf Zwischenwerkzeugergebnissen

    Benutzerdefinierte Werkzeuge werden in asynchrone Python-Funktionen konvertiert, um parallele Werkzeugaufrufe zu unterstützen. Wenn Claude Code schreibt, der Ihre Werkzeuge aufruft, verwendet es await (z. B. result = await query_database("<sql>")) und fügt automatisch die entsprechende asynchrone Wrapper-Funktion ein.

    Die asynchrone Wrapper wird in den Code-Beispielen in dieser Dokumentation aus Gründen der Klarheit weggelassen.

    Kernkonzepte

    Das Feld allowed_callers

    Das Feld allowed_callers gibt an, welche Kontexte ein Werkzeug aufrufen können:

    {
      "name": "query_database",
      "description": "Execute a SQL query against the database",
      "input_schema": {...},
      "allowed_callers": ["code_execution_20250825"]
    }

    Mögliche Werte:

    • ["direct"] - Nur Claude kann dieses Werkzeug direkt aufrufen (Standard, wenn weggelassen)
    • ["code_execution_20250825"] - Nur von innerhalb der Code-Ausführung aufrufbar
    • ["direct", "code_execution_20250825"] - Von direkt und von Code-Ausführung aufrufbar

    Wir empfehlen, für jedes Werkzeug entweder ["direct"] oder ["code_execution_20250825"] zu wählen, anstatt beide zu aktivieren, da dies Claude eine klarere Anleitung gibt, wie das Werkzeug am besten verwendet wird.

    Das Feld caller in Antworten

    Jeder Werkzeugverwendungsblock enthält ein caller-Feld, das angibt, wie er aufgerufen wurde:

    Direkter Aufruf (traditionelle Werkzeugverwendung):

    {
      "type": "tool_use",
      "id": "toolu_abc123",
      "name": "query_database",
      "input": {"sql": "\<sql\>"},
      "caller": {"type": "direct"}
    }

    Programmatischer Aufruf:

    {
      "type": "tool_use",
      "id": "toolu_xyz789",
      "name": "query_database",
      "input": {"sql": "\<sql\>"},
      "caller": {
        "type": "code_execution_20250825",
        "tool_id": "srvtoolu_abc123"
      }
    }

    Die tool_id verweist auf das Code-Ausführungswerkzeug, das den programmatischen Aufruf getätigt hat.

    Container-Lebenszyklus

    Programmatische Werkzeugaufrufe verwenden die gleichen Container wie Code-Ausführung:

    • Container-Erstellung: Ein neuer Container wird für jede Sitzung erstellt, es sei denn, Sie verwenden einen vorhandenen erneut
    • Ablauf: Container verfallen nach etwa 4,5 Minuten Inaktivität (kann sich ändern)
    • Container-ID: Wird in Antworten über das container-Feld zurückgegeben
    • Wiederverwendung: Übergeben Sie die Container-ID, um den Status über Anfragen hinweg zu erhalten

    Wenn ein Werkzeug programmatisch aufgerufen wird und der Container auf Ihr Werkzeugergebnis wartet, müssen Sie antworten, bevor der Container abläuft. Überwachen Sie das expires_at-Feld. Wenn der Container abläuft, kann Claude den Werkzeugaufruf als Timeout behandeln und ihn erneut versuchen.

    Beispiel-Workflow

    Hier ist ein Beispiel für einen vollständigen programmatischen Werkzeugaufrufs-Workflow:

    Schritt 1: Anfängliche Anfrage

    Senden Sie eine Anfrage mit Code-Ausführung und einem Werkzeug, das programmatische Aufrufe ermöglicht. Um programmatische Aufrufe zu aktivieren, fügen Sie das Feld allowed_callers zu Ihrer Werkzeugdefinition hinzu.

    Geben Sie detaillierte Beschreibungen des Ausgabeformats Ihres Werkzeugs in der Werkzeugbeschreibung an. Wenn Sie angeben, dass das Werkzeug JSON zurückgibt, wird Claude versuchen, das Ergebnis in Code zu deserialisieren und zu verarbeiten. Je mehr Details Sie über das Ausgabeschema bereitstellen, desto besser kann Claude die Antwort programmatisch verarbeiten.

    response = client.beta.messages.create(
        model="claude-sonnet-4-5",
        betas=["advanced-tool-use-2025-11-20"],
        max_tokens=4096,
        messages=[{
            "role": "user",
            "content": "Query customer purchase history from the last quarter and identify our top 5 customers by revenue"
        }],
        tools=[
            {
                "type": "code_execution_20250825",
                "name": "code_execution"
            },
            {
                "name": "query_database",
                "description": "Execute a SQL query against the sales database. Returns a list of rows as JSON objects.",
                "input_schema": {...},
                "allowed_callers": ["code_execution_20250825"]
            }
        ]
    )

    Schritt 2: API-Antwort mit Werkzeugaufruf

    Claude schreibt Code, der Ihr Werkzeug aufruft. Die API pausiert und gibt zurück:

    {
      "role": "assistant",
      "content": [
        {
          "type": "text",
          "text": "I'll query the purchase history and analyze the results."
        },
        {
          "type": "server_tool_use",
          "id": "srvtoolu_abc123",
          "name": "code_execution",
          "input": {
            "code": "results = await query_database('<sql>')\ntop_customers = sorted(results, key=lambda x: x['revenue'], reverse=True)[:5]\nprint(f'Top 5 customers: {top_customers}')"
          }
        },
        {
          "type": "tool_use",
          "id": "toolu_def456",
          "name": "query_database",
          "input": {"sql": "\<sql\>"},
          "caller": {
            "type": "code_execution_20250825",
            "tool_id": "srvtoolu_abc123"
          }
        }
      ],
      "container": {
        "id": "container_xyz789",
        "expires_at": "2025-01-15T14:30:00Z"
      },
      "stop_reason": "tool_use"
    }

    Schritt 3: Werkzeugergebnis bereitstellen

    Fügen Sie die vollständige Gesprächsverlauf plus Ihr Werkzeugergebnis ein:

    response = client.beta.messages.create(
        model="claude-sonnet-4-5",
        betas=["advanced-tool-use-2025-11-20"],
        max_tokens=4096,
        container="container_xyz789",  # Reuse the container
        messages=[
            {"role": "user", "content": "Query customer purchase history from the last quarter and identify our top 5 customers by revenue"},
            {
                "role": "assistant",
                "content": [
                    {"type": "text", "text": "I'll query the purchase history and analyze the results."},
                    {
                        "type": "server_tool_use",
                        "id": "srvtoolu_abc123",
                        "name": "code_execution",
                        "input": {"code": "..."}
                    },
                    {
                        "type": "tool_use",
                        "id": "toolu_def456",
                        "name": "query_database",
                        "input": {"sql": "\<sql\>"},
                        "caller": {
                            "type": "code_execution_20250825",
                            "tool_id": "srvtoolu_abc123"
                        }
                    }
                ]
            },
            {
                "role": "user",
                "content": [
                    {
                        "type": "tool_result",
                        "tool_use_id": "toolu_def456",
                        "content": "[{\"customer_id\": \"C1\", \"revenue\": 45000}, {\"customer_id\": \"C2\", \"revenue\": 38000}, ...]"
                    }
                ]
            }
        ],
        tools=[...]
    )

    Schritt 4: Nächster Werkzeugaufruf oder Abschluss

    Die Code-Ausführung wird fortgesetzt und verarbeitet die Ergebnisse. Wenn zusätzliche Werkzeugaufrufe erforderlich sind, wiederholen Sie Schritt 3, bis alle Werkzeugaufrufe erfüllt sind.

    Schritt 5: Endgültige Antwort

    Sobald die Code-Ausführung abgeschlossen ist, stellt Claude die endgültige Antwort bereit:

    {
      "content": [
        {
          "type": "code_execution_tool_result",
          "tool_use_id": "srvtoolu_abc123",
          "content": {
            "type": "code_execution_result",
            "stdout": "Top 5 customers by revenue:\n1. Customer C1: $45,000\n2. Customer C2: $38,000\n3. Customer C5: $32,000\n4. Customer C8: $28,500\n5. Customer C3: $24,000",
            "stderr": "",
            "return_code": 0,
            "content": []
          }
        },
        {
          "type": "text",
          "text": "I've analyzed the purchase history from last quarter. Your top 5 customers generated $167,500 in total revenue, with Customer C1 leading at $45,000."
        }
      ],
      "stop_reason": "end_turn"
    }

    Erweiterte Muster

    Batch-Verarbeitung mit Schleifen

    Claude kann Code schreiben, der mehrere Elemente effizient verarbeitet:

    # async wrapper omitted for clarity
    regions = ["West", "East", "Central", "North", "South"]
    results = {}
    for region in regions:
        data = await query_database(f"<sql for {region}>")
        results[region] = sum(row["revenue"] for row in data)
    
    # Process results programmatically
    top_region = max(results.items(), key=lambda x: x[1])
    print(f"Top region: {top_region[0]} with ${top_region[1]:,} in revenue")

    Dieses Muster:

    • Reduziert Modell-Roundtrips von N (eine pro Region) auf 1
    • Verarbeitet große Ergebnissätze programmatisch, bevor sie zu Claude zurückkehren
    • Spart Token, indem nur aggregierte Schlussfolgerungen statt Rohdaten zurückgegeben werden

    Frühzeitige Beendigung

    Claude kann die Verarbeitung beenden, sobald Erfolgskriterien erfüllt sind:

    # async wrapper omitted for clarity
    endpoints = ["us-east", "eu-west", "apac"]
    for endpoint in endpoints:
        status = await check_health(endpoint)
        if status == "healthy":
            print(f"Found healthy endpoint: {endpoint}")
            break  # Stop early, don't check remaining

    Bedingte Werkzeugauswahl

    # async wrapper omitted for clarity
    file_info = await get_file_info(path)
    if file_info["size"] < 10000:
        content = await read_full_file(path)
    else:
        content = await read_file_summary(path)
    print(content)

    Datenfilterung

    # async wrapper omitted for clarity
    logs = await fetch_logs(server_id)
    errors = [log for log in logs if "ERROR" in log]
    print(f"Found {len(errors)} errors")
    for error in errors[-10:]:  # Only return last 10 errors
        print(error)

    Antwortformat

    Programmatischer Werkzeugaufruf

    Wenn Code-Ausführung ein Werkzeug aufruft:

    {
      "type": "tool_use",
      "id": "toolu_abc123",
      "name": "query_database",
      "input": {"sql": "\<sql\>"},
      "caller": {
        "type": "code_execution_20250825",
        "tool_id": "srvtoolu_xyz789"
      }
    }

    Werkzeugergebnis-Verarbeitung

    Ihr Werkzeugergebnis wird an den laufenden Code zurückgegeben:

    {
      "role": "user",
      "content": [
        {
          "type": "tool_result",
          "tool_use_id": "toolu_abc123",
          "content": "[{\"customer_id\": \"C1\", \"revenue\": 45000, \"orders\": 23}, {\"customer_id\": \"C2\", \"revenue\": 38000, \"orders\": 18}, ...]"
        }
      ]
    }

    Code-Ausführung abgeschlossen

    Wenn alle Werkzeugaufrufe erfüllt sind und der Code abgeschlossen ist:

    {
      "type": "code_execution_tool_result",
      "tool_use_id": "srvtoolu_xyz789",
      "content": {
        "type": "code_execution_result",
        "stdout": "Analysis complete. Top 5 customers identified from 847 total records.",
        "stderr": "",
        "return_code": 0,
        "content": []
      }
    }

    Fehlerbehandlung

    Häufige Fehler

    FehlerBeschreibungLösung
    invalid_tool_inputWerkzeugeingabe stimmt nicht mit Schema übereinValidieren Sie das input_schema Ihres Werkzeugs
    tool_not_allowedWerkzeug erlaubt den angeforderten Aufrufertyp nichtÜberprüfen Sie, dass allowed_callers die richtigen Kontexte enthält
    missing_beta_headerPTC-Beta-Header nicht bereitgestelltFügen Sie beide Beta-Header zu Ihrer Anfrage hinzu

    Container-Ablauf während Werkzeugaufruf

    Wenn Ihr Werkzeug zu lange dauert, erhält die Code-Ausführung einen TimeoutError. Claude sieht dies in stderr und wird normalerweise erneut versuchen:

    {
      "type": "code_execution_tool_result",
      "tool_use_id": "srvtoolu_abc123",
      "content": {
        "type": "code_execution_result",
        "stdout": "",
        "stderr": "TimeoutError: Calling tool ['query_database'] timed out.",
        "return_code": 0,
        "content": []
      }
    }

    Um Timeouts zu vermeiden:

    • Überwachen Sie das expires_at-Feld in Antworten
    • Implementieren Sie Timeouts für Ihre Werkzeugausführung
    • Erwägen Sie, lange Operationen in kleinere Teile zu unterteilen

    Werkzeugausführungsfehler

    Wenn Ihr Werkzeug einen Fehler zurückgibt:

    # Provide error information in the tool result
    {
        "type": "tool_result",
        "tool_use_id": "toolu_abc123",
        "content": "Error: Query timeout - table lock exceeded 30 seconds"
    }

    Claudes Code erhält diesen Fehler und kann ihn entsprechend verarbeiten.

    Einschränkungen und Beschränkungen

    Funktionsinkompatibilitäten

    • Strukturierte Ausgaben: Werkzeuge mit strict: true werden nicht mit programmatischen Aufrufen unterstützt
    • Werkzeugauswahl: Sie können programmatische Aufrufe eines bestimmten Werkzeugs nicht über tool_choice erzwingen
    • Parallele Werkzeugverwendung: disable_parallel_tool_use: true wird nicht mit programmatischen Aufrufen unterstützt

    Werkzeugbeschränkungen

    Die folgenden Werkzeuge können derzeit nicht programmatisch aufgerufen werden, aber die Unterstützung kann in zukünftigen Versionen hinzugefügt werden:

    • Websuche
    • Web-Abruf
    • Werkzeuge, die von einem MCP-Connector bereitgestellt werden

    Nachrichtenformatierungsbeschränkungen

    Wenn Sie auf programmatische Werkzeugaufrufe antworten, gibt es strenge Formatierungsanforderungen:

    Nur Werkzeugergebnis-Antworten: Wenn ausstehende programmatische Werkzeugaufrufe auf Ergebnisse warten, muss Ihre Antwortnachricht nur tool_result-Blöcke enthalten. Sie können keinen Textinhalt einschließen, auch nicht nach den Werkzeugergebnissen.

    // ❌ UNGÜLTIG - Kann keinen Text einschließen, wenn auf programmatische Werkzeugaufrufe geantwortet wird
    {
      "role": "user",
      "content": [
        {"type": "tool_result", "tool_use_id": "toolu_01", "content": "[{\"customer_id\": \"C1\", \"revenue\": 45000}]"},
        {"type": "text", "text": "What should I do next?"}  // This will cause an error
      ]
    }
    
    // ✅ GÜLTIG - Nur Werkzeugergebnisse bei Antwort auf programmatische Werkzeugaufrufe
    {
      "role": "user",
      "content": [
        {"type": "tool_result", "tool_use_id": "toolu_01", "content": "[{\"customer_id\": \"C1\", \"revenue\": 45000}]"}
      ]
    }

    Diese Einschränkung gilt nur bei Antwort auf programmatische (Code-Ausführungs-)Werkzeugaufrufe. Für reguläre clientseitige Werkzeugaufrufe können Sie Textinhalt nach Werkzeugergebnissen einschließen.

    Rate Limits

    Programmatische Werkzeugaufrufe unterliegen den gleichen Rate Limits wie reguläre Werkzeugaufrufe. Jeder Werkzeugaufruf von Code-Ausführung zählt als separate Invokation.

    Werkzeugergebnisse vor Verwendung validieren

    Bei der Implementierung benutzerdefinierter Werkzeuge, die programmatisch aufgerufen werden:

    • Werkzeugergebnisse werden als Strings zurückgegeben: Sie können beliebigen Inhalt enthalten, einschließlich Code-Snippets oder ausführbarer Befehle, die von der Ausführungsumgebung verarbeitet werden können.
    • Externe Werkzeugergebnisse validieren: Wenn Ihr Werkzeug Daten aus externen Quellen zurückgibt oder Benutzereingaben akzeptiert, beachten Sie Code-Injection-Risiken, wenn die Ausgabe als Code interpretiert oder ausgeführt wird.

    Token-Effizienz

    Programmatische Werkzeugaufrufe können den Token-Verbrauch erheblich reduzieren:

    • Werkzeugergebnisse von programmatischen Aufrufen werden nicht zu Claudes Kontext hinzugefügt - nur die endgültige Code-Ausgabe
    • Zwischenverarbeitung erfolgt im Code - Filterung, Aggregation usw. verbrauchen keine Modell-Token
    • Mehrere Werkzeugaufrufe in einer Code-Ausführung - reduziert den Overhead im Vergleich zu separaten Modell-Durchläufen

    Beispielsweise verbraucht das direkte Aufrufen von 10 Werkzeugen etwa 10x die Token des programmatischen Aufrufs und der Rückgabe einer Zusammenfassung.

    Verwendung und Preisgestaltung

    Programmatische Werkzeugaufrufe verwenden die gleiche Preisgestaltung wie Code-Ausführung. Weitere Informationen finden Sie unter Code-Ausführungs-Preisgestaltung.

    Token-Zählung für programmatische Werkzeugaufrufe: Werkzeugergebnisse von programmatischen Invokationen zählen nicht zu Ihrer Eingabe-/Ausgabe-Token-Nutzung. Nur das endgültige Code-Ausführungsergebnis und Claudes Antwort zählen.

    Best Practices

    Werkzeugdesign

    • Geben Sie detaillierte Ausgabebeschreibungen an: Da Claude Werkzeugergebnisse im Code deserialisiert, dokumentieren Sie klar das Format (JSON-Struktur, Feldtypen usw.)
    • Geben Sie strukturierte Daten zurück: JSON oder andere leicht analysierbare Formate funktionieren am besten für programmatische Verarbeitung
    • Halten Sie Antworten prägnant: Geben Sie nur notwendige Daten zurück, um den Verarbeitungsaufwand zu minimieren

    Wann programmatische Aufrufe verwendet werden sollten

    Gute Anwendungsfälle:

    • Verarbeitung großer Datensätze, bei denen Sie nur Aggregate oder Zusammenfassungen benötigen
    • Multi-Step-Workflows mit 3+ abhängigen Werkzeugaufrufen
    • Operationen, die Filterung, Sortierung oder Transformation von Werkzeugergebnissen erfordern
    • Aufgaben, bei denen Zwischendaten Claudes Argumentation nicht beeinflussen sollten
    • Parallele Operationen über viele Elemente (z. B. Überprüfung von 50 Endpunkten)

    Weniger ideale Anwendungsfälle:

    • Einzelne Werkzeugaufrufe mit einfachen Antworten
    • Werkzeuge, die sofortiges Benutzer-Feedback benötigen
    • Sehr schnelle Operationen, bei denen der Code-Ausführungs-Overhead den Vorteil überwiegen würde

    Leistungsoptimierung

    • Verwenden Sie Container erneut, wenn Sie mehrere verwandte Anfragen stellen, um den Status zu erhalten
    • Batch ähnliche Operationen in einer einzigen Code-Ausführung, wenn möglich

    Fehlerbehebung

    Häufige Probleme

    Fehler "Tool not allowed"

    • Überprüfen Sie, dass Ihre Werkzeugdefinition "allowed_callers": ["code_execution_20250825"] enthält
    • Überprüfen Sie, dass Sie die richtigen Beta-Header verwenden

    Container-Ablauf

    • Stellen Sie sicher, dass Sie auf Werkzeugaufrufe innerhalb der Container-Lebensdauer (~4,5 Minuten) antworten
    • Überwachen Sie das expires_at-Feld in Antworten
    • Erwägen Sie, schnellere Werkzeugausführung zu implementieren

    Beta-Header-Probleme

    • Sie benötigen den Header: "advanced-tool-use-2025-11-20"

    Werkzeugergebnis wird nicht korrekt analysiert

    • Stellen Sie sicher, dass Ihr Werkzeug String-Daten zurückgibt, die Claude deserialisieren kann
    • Geben Sie klare Ausgabeformat-Dokumentation in Ihrer Werkzeugbeschreibung an

    Debugging-Tipps

    1. Protokollieren Sie alle Werkzeugaufrufe und Ergebnisse, um den Fluss zu verfolgen
    2. Überprüfen Sie das caller-Feld, um programmatische Invokation zu bestätigen
    3. Überwachen Sie Container-IDs, um ordnungsgemäße Wiederverwendung sicherzustellen
    4. Testen Sie Werkzeuge unabhängig, bevor Sie programmatische Aufrufe aktivieren

    Warum programmatische Werkzeugaufrufe funktionieren

    Claudes Training umfasst umfangreiche Exposition gegenüber Code, was es effektiv bei der Argumentation durch und Verkettung von Funktionsaufrufen macht. Wenn Werkzeuge als aufrufbare Funktionen innerhalb einer Code-Ausführungsumgebung dargestellt werden, kann Claude diese Stärke nutzen, um:

    • Natürlich über Werkzeugkomposition zu argumentieren: Operationen verketten und Abhängigkeiten so natürlich wie das Schreiben von Python-Code handhaben
    • Große Ergebnisse effizient zu verarbeiten: Große Werkzeugausgaben filtern, nur relevante Daten extrahieren oder Zwischenergebnisse in Dateien schreiben, bevor Zusammenfassungen zum Kontextfenster zurückkehren
    • Latenz erheblich zu reduzieren: Eliminieren Sie den Overhead des erneuten Samplns von Claude zwischen jedem Werkzeugaufruf in Multi-Step-Workflows

    Dieser Ansatz ermöglicht Workflows, die mit traditioneller Werkzeugverwendung unpraktisch wären – wie die Verarbeitung von Dateien über 1M Token – indem Claude programmatisch mit Daten arbeiten kann, anstatt alles in den Gesprächskontext zu laden.

    Alternative Implementierungen

    Programmatische Werkzeugaufrufe sind ein verallgemeinerbares Muster, das außerhalb von Anthropics verwalteter Code-Ausführung implementiert werden kann. Hier ist ein Überblick über die Ansätze:

    Clientseitige direkte Ausführung

    Geben Sie Claude ein Code-Ausführungswerkzeug und beschreiben Sie, welche Funktionen in dieser Umgebung verfügbar sind. Wenn Claude das Werkzeug mit Code aufruft, führt Ihre Anwendung es lokal aus, wo diese Funktionen definiert sind.

    Vorteile:

    • Einfach zu implementieren mit minimalem Umstrukturieren
    • Vollständige Kontrolle über die Umgebung und Anweisungen

    Nachteile:

    • Führt nicht vertrauenswürdigen Code außerhalb einer Sandbox aus
    • Werkzeugaufrufe können Vektoren für Code-Injection sein

    Verwenden Sie, wenn: Ihre Anwendung sicher beliebigen Code ausführen kann, Sie eine einfache Lösung wünschen und Anthropics verwaltetes Angebot nicht Ihren Anforderungen entspricht.

    Selbstverwaltete Sandbox-Ausführung

    Gleicher Ansatz aus Claudes Perspektive, aber Code läuft in einem Sandbox-Container mit Sicherheitsbeschränkungen (z. B. kein Netzwerk-Egress). Wenn Ihre Werkzeuge externe Ressourcen benötigen, benötigen Sie ein Protokoll für die Ausführung von Werkzeugaufrufen außerhalb der Sandbox.

    Vorteile:

    • Sichere programmatische Werkzeugaufrufe auf Ihrer eigenen Infrastruktur
    • Vollständige Kontrolle über die Ausführungsumgebung

    Nachteile:

    • Komplex zu bauen und zu warten
    • Erfordert die Verwaltung von Infrastruktur und Inter-Process-Kommunikation

    Verwenden Sie, wenn: Sicherheit ist kritisch und Anthropics verwaltete Lösung passt nicht zu Ihren Anforderungen.

    Anthropic-verwaltete Ausführung

    Anthropics programmatische Werkzeugaufrufe sind eine verwaltete Version der Sandbox-Ausführung mit einer Python-Umgebung, die für Claude optimiert ist. Anthropic verwaltet Container-Management, Code-Ausführung und sichere Werkzeugaufrufs-Kommunikation.

    Vorteile:

    • Standardmäßig sicher und geschützt
    • Einfach zu aktivieren mit minimaler Konfiguration
    • Umgebung und Anweisungen für Claude optimiert

    Wir empfehlen die Verwendung von Anthropics verwalteter Lösung, wenn Sie die Claude API verwenden.

    Verwandte Funktionen

    Code Execution Tool

    Erfahren Sie mehr über die zugrunde liegende Code-Ausführungsfunktion, die programmatische Werkzeugaufrufe ermöglicht.

    Tool Use Overview

    Verstehen Sie die Grundlagen der Werkzeugverwendung mit Claude.

    Implement Tool Use

    Schritt-für-Schritt-Anleitung zur Implementierung von Werkzeugen.

    Token-Efficient Tool Use

    Optimieren Sie Ihre Werkzeugimplementierungen für bessere Leistung.

    • Modellkompatibilität
    • Schnellstart
    • Wie programmatische Werkzeugaufrufe funktionieren
    • Kernkonzepte
    • Das Feld
    • Das Feld in Antworten
    • Container-Lebenszyklus
    • Beispiel-Workflow
    • Schritt 1: Anfängliche Anfrage
    • Schritt 2: API-Antwort mit Werkzeugaufruf
    • Schritt 3: Werkzeugergebnis bereitstellen
    • Schritt 4: Nächster Werkzeugaufruf oder Abschluss
    • Schritt 5: Endgültige Antwort
    • Erweiterte Muster
    • Batch-Verarbeitung mit Schleifen
    • Frühzeitige Beendigung
    • Bedingte Werkzeugauswahl
    • Datenfilterung
    • Antwortformat
    • Programmatischer Werkzeugaufruf
    • Werkzeugergebnis-Verarbeitung
    • Code-Ausführung abgeschlossen
    • Fehlerbehandlung
    • Häufige Fehler
    • Container-Ablauf während Werkzeugaufruf
    • Werkzeugausführungsfehler
    • Einschränkungen und Beschränkungen
    • Funktionsinkompatibilitäten
    • Werkzeugbeschränkungen
    • Nachrichtenformatierungsbeschränkungen
    • Rate Limits
    • Werkzeugergebnisse vor Verwendung validieren
    • Token-Effizienz
    • Verwendung und Preisgestaltung
    • Best Practices
    • Werkzeugdesign
    • Wann programmatische Aufrufe verwendet werden sollten
    • Leistungsoptimierung
    • Fehlerbehebung
    • Häufige Probleme
    • Debugging-Tipps
    • Warum programmatische Werkzeugaufrufe funktionieren
    • Alternative Implementierungen
    • Clientseitige direkte Ausführung
    • Selbstverwaltete Sandbox-Ausführung
    • Anthropic-verwaltete Ausführung
    • Verwandte Funktionen

    Solutions

    • AI agents
    • Code modernization
    • Coding
    • Customer support
    • Education
    • Financial services
    • Government
    • Life sciences

    Partners

    • Amazon Bedrock
    • Google Cloud's Vertex AI

    Learn

    • Blog
    • Catalog
    • Courses
    • Use cases
    • Connectors
    • Customer stories
    • Engineering at Anthropic
    • Events
    • Powered by Claude
    • Service partners
    • Startups program

    Company

    • Anthropic
    • Careers
    • Economic Futures
    • Research
    • News
    • Responsible Scaling Policy
    • Security and compliance
    • Transparency

    Learn

    • Blog
    • Catalog
    • Courses
    • Use cases
    • Connectors
    • Customer stories
    • Engineering at Anthropic
    • Events
    • Powered by Claude
    • Service partners
    • Startups program

    Help and security

    • Availability
    • Status
    • Support
    • Discord

    Terms and policies

    • Privacy policy
    • Responsible disclosure policy
    • Terms of service: Commercial
    • Terms of service: Consumer
    • Usage policy