Loading...
  • Erstellen
  • Admin
  • Modelle & Preise
  • Client-SDKs
  • API-Referenz
Search...
⌘K
Log in
Programmatische Tool-Aufrufe
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...

Solutions

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

Partners

  • Amazon Bedrock
  • Google Cloud's Vertex AI

Learn

  • Blog
  • 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
  • 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
Erstellen/Tool-Infrastruktur

Programmatisches Tool-Aufrufen

Claude kann Code schreiben, der Tools programmatisch innerhalb eines Code-Ausführungscontainers aufruft, anstatt mehrere Modell-Roundtrips zu erfordern.

Programmatisches Tool-Aufrufen ermöglicht es Claude, Code zu schreiben, der Ihre Tools programmatisch innerhalb eines Code-Ausführungs-Containers aufruft, anstatt mehrere Roundtrips durch das Modell für jeden Tool-Aufruf 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. Bei agentengestützten Suchbenchmarks wie BrowseComp und DeepSearchQA, die mehrstufige Webrecherche und komplexe Informationsbeschaffung testen, war das Hinzufügen von programmatischem Tool-Aufrufen auf Basis grundlegender Suchtools der Schlüsselfaktor, der die Agent-Leistung vollständig freisetzte.

Der Unterschied verstärkt sich schnell in echten Workflows. Stellen Sie sich vor, Sie überprüfen die Budgetkonformität für 20 Mitarbeiter: Der traditionelle Ansatz erfordert 20 separate Modell-Roundtrips und zieht dabei Tausende von Ausgabenpositionen in den Kontext. Mit programmatischem Tool-Aufrufen führt ein einzelnes Skript alle 20 Abfragen durch, filtert die Ergebnisse und gibt nur die Mitarbeiter zurück, die ihre Limits überschritten haben, wodurch das reduziert wird, das Claude berücksichtigen muss, von Hunderten von Kilobytes auf nur wenige Zeilen.

Für einen tieferen Blick auf die Inferenz- und Kontextkosten, die programmatisches Tool-Aufrufen adressiert, siehe Advanced tool use.

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

This feature is not eligible for Zero Data Retention (ZDR). Data is retained according to the feature's standard retention policy.

Modellkompatibilität

Programmatisches Tool-Aufrufen erfordert code_execution_20260120, das auf den folgenden Modellen unterstützt wird:

Modell
Claude Opus 4.7 (claude-opus-4-7)
Claude Opus 4.6 (claude-opus-4-6)
Claude Sonnet 4.6 (claude-sonnet-4-6)
Claude Opus 4.5 (claude-opus-4-5-20251101)
Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)

Für die vollständige Code-Ausführungs-Tool-Versionsmatrix siehe die Code-Ausführungs-Tool-Modellkompatibilitätstabelle. Programmatisches Tool-Aufrufen ist ü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:

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    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_20260120", "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_20260120"],
        },
    ],
)

print(response)

Wie programmatisches Tool-Aufrufen funktioniert

Wenn Sie ein Tool so konfigurieren, dass es von der Code-Ausführung aufgerufen werden kann, und Claude sich entscheidet, dieses Tool zu verwenden:

  1. Claude schreibt Python-Code, der das Tool als Funktion aufruft, möglicherweise mit mehreren Tool-Aufrufen und Vor-/Nachbearbeitungslogik
  2. Claude führt diesen Code in einem isolierten Container über Code-Ausführung aus
  3. Wenn eine Tool-Funktion aufgerufen wird, pausiert die Code-Ausführung und die API gibt einen tool_use-Block zurück
  4. Sie stellen das Tool-Ergebnis 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 Tool-Ergebnisse, bevor sie Claudes Kontext erreichen
  • Mehrstufige Workflows: Sparen Sie Token und Latenz, indem Sie Tools nacheinander oder in einer Schleife aufrufen, ohne Claude zwischen Tool-Aufrufen zu samplen
  • Bedingte Logik: Treffen Sie Entscheidungen basierend auf Zwischenergebnissen von Tools

Benutzerdefinierte Tools werden in asynchrone Python-Funktionen konvertiert, um paralleles Tool-Aufrufen zu unterstützen. Wenn Claude Code schreibt, der Ihre Tools 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 Tool aufrufen können:

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

Mögliche Werte:

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

Wählen Sie für jedes Tool entweder ["direct"] oder ["code_execution_20260120"], anstatt beide zu aktivieren, da dies Claude eine klarere Anleitung gibt, wie das Tool am besten verwendet wird.

Das Feld caller in Antworten

Jeder Tool-Use-Block enthält ein Feld caller, das angibt, wie es aufgerufen wurde:

Direkter Aufruf (traditionelle Tool-Nutzung):

{
  "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_20260120",
    "tool_id": "srvtoolu_abc123"
  }
}

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

Container-Lebenszyklus

Programmatisches Tool-Aufrufen verwendet 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 haben eine maximale Lebensdauer von 30 Tagen und werden nach 4,5 Minuten Inaktivität bereinigt
  • Container-ID: Wird in Antworten über das Feld container zurückgegeben
  • Wiederverwendung: Übergeben Sie die Container-ID, um den Status über Anfragen hinweg zu erhalten

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

Beispiel-Workflow

Hier ist, wie ein vollständiger Programmatisches-Tool-Aufrufen-Flow funktioniert:

Schritt 1: Anfängliche Anfrage

Senden Sie eine Anfrage mit Code-Ausführung und einem Tool, das programmatisches Aufrufen ermöglicht. Um programmatisches Aufrufen zu aktivieren, fügen Sie das Feld allowed_callers zu Ihrer Tool-Definition hinzu.

Geben Sie detaillierte Beschreibungen des Ausgabeformats Ihres Tools in der Tool-Beschreibung an. Wenn Sie angeben, dass das Tool JSON zurückgibt, versucht Claude, 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.

Die Anfrage-Form ist identisch mit dem Schnellstart-Beispiel: Fügen Sie code_execution in Ihre Tools-Liste ein, fügen Sie allowed_callers: ["code_execution_20260120"] zu jedem Tool hinzu, das Claude von Code aus aufrufen soll, und senden Sie Ihre Benutzernachricht.

Schritt 2: API-Antwort mit Tool-Aufruf

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

Output
{
  "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_20260120",
        "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 den vollständigen Gesprächsverlauf plus Ihr Werkzeugergebnis ein:

response = client.messages.create(
    model="claude-opus-4-7",
    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_20260120",
                        "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=[...],
)

print(response)

Schritt 4: Nächster Werkzeugaufruf oder Abschluss

Die Codeausfü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 Codeausführung abgeschlossen ist, liefert Claude die endgültige Antwort:

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

Stapelverarbeitung mit Schleifen

Claude kann Code schreiben, der mehrere Elemente effizient verarbeitet:

async def _claude_code():
    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 Ergebnismengen programmgesteuert, bevor sie an Claude zurückgegeben werden
  • Spart Token, indem nur aggregierte Schlussfolgerungen statt Rohdaten zurückgegeben werden

Frühzeitige Beendigung

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

async def _claude_code():
    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 def _claude_code():
    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 def _claude_code():
    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

Programmgesteuerter Werkzeugaufruf

Wenn die Codeausführung ein Werkzeug aufruft:

{
  "type": "tool_use",
  "id": "toolu_abc123",
  "name": "query_database",
  "input": { "sql": "<sql>" },
  "caller": {
    "type": "code_execution_20260120",
    "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}, ...]"
    }
  ]
}

Codeausfü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 dem 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_headerErforderlicher Beta-Header nicht bereitgestellt (nur Bedrock und Vertex AI; programmgesteuerte Werkzeugaufrufe sind GA auf der Claude-API von Anthropic)Fügen Sie die erforderlichen Beta-Header zu Ihrer Anfrage hinzu

Container-Ablauf während Werkzeugaufruf

Wenn Ihr Werkzeug zu lange braucht, um zu antworten, erhält die Codeausführung einen TimeoutError. Claude sieht dies in stderr und versucht normalerweise erneut:

{
  "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 Feld expires_at 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:

{
  "type": "tool_result",
  "tool_use_id": "toolu_abc123",
  "content": "Error: Query timeout - table lock exceeded 30 seconds"
}

Claudes Code empfängt diesen Fehler und kann ihn angemessen verarbeiten.

Einschränkungen und Beschränkungen

Funktionsinkompatibilitäten

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

Werkzeugbeschränkungen

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

  • Werkzeuge, die von einem MCP-Connector bereitgestellt werden

Nachrichtenformatierungsbeschränkungen

Bei der Antwort auf programmgesteuerte Werkzeugaufrufe gibt es strenge Formatierungsanforderungen:

Nur Werkzeugergebnis-Antworten: Wenn es ausstehende programmgesteuerte Werkzeugaufrufe gibt, die 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 programmgesteuerte 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?" }
  ]
}

Gültig - Nur Werkzeugergebnisse bei Antwort auf programmgesteuerte Werkzeugaufrufe:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01",
      "content": "[{\"customer_id\": \"C1\", \"revenue\": 45000}]"
    }
  ]
}

Diese Einschränkung gilt nur bei der Antwort auf programmgesteuerte (Codeausführungs-)Werkzeugaufrufe. Bei regulären clientseitigen Werkzeugaufrufen können Sie Textinhalt nach Werkzeugergebnissen einschließen.

Ratenlimits

Programmgesteuerte Werkzeugaufrufe unterliegen den gleichen Ratenlimits wie reguläre Werkzeugaufrufe. Jeder Werkzeugaufruf aus der Codeausführung zählt als separate Invokation.

Werkzeugergebnisse vor Verwendung validieren

Bei der Implementierung benutzerdefinierter Werkzeuge, die programmgesteuert 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.
  • Validieren Sie externe Werkzeugergebnisse: 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

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

  • Werkzeugergebnisse aus programmgesteuerten Aufrufen werden nicht zu Claudes Kontext hinzugefügt - nur die endgültige Code-Ausgabe wird hinzugefügt
  • Zwischenverarbeitung erfolgt im Code - Filterung, Aggregation usw. verbrauchen keine Modell-Token
  • Mehrere Werkzeugaufrufe in einer Codeausführung - reduziert den Overhead im Vergleich zu separaten Modell-Turns

Beispielsweise verbraucht das direkte Aufrufen von 10 Werkzeugen etwa 10x mehr Token als das programmgesteuerte Aufrufen und die Rückgabe einer Zusammenfassung.

Verwendung und Preisgestaltung

Programmgesteuerte Werkzeugaufrufe verwenden die gleiche Preisgestaltung wie Codeausführung. Weitere Informationen finden Sie unter Codeausführungs-Preisgestaltung.

Token-Zählung für programmgesteuerte Werkzeugaufrufe: Werkzeugergebnisse aus programmgesteuerten Invokationen zählen nicht zu Ihrer Input-/Output-Token-Nutzung. Nur das endgültige Codeausführungsergebnis und Claudes Antwort zählen.

Best Practices

Werkzeugdesign

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

Wann programmgesteuerte 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 Überlegungen 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 Codeausführungs-Overhead den Vorteil überwiegen würde

Leistungsoptimierung

  • Wiederverwendung von Containern bei mehreren verwandten Anfragen, um den Status beizubehalten
  • Batch ähnlicher Operationen in einer einzelnen Codeausführung, wenn möglich

Fehlerbehebung

Häufige Probleme

Fehler "Tool not allowed"

  • Überprüfen Sie, dass Ihre Werkzeugdefinition "allowed_callers": ["code_execution_20260120"] enthält

Container-Ablauf

  • Stellen Sie sicher, dass Sie auf Werkzeugaufrufe antworten, bevor der Container ausfällt (4,5 Minuten Inaktivität; 30-Tage-Hartlimit)
  • Überwachen Sie das Feld expires_at in Antworten
  • Erwägen Sie die Implementierung schnellerer Werkzeugausführung

Werkzeugergebnis wird nicht korrekt analysiert

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

Debugging-Tipps

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

Warum programmgesteuerte Werkzeugaufrufe funktionieren

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

  • Natürlich über Werkzeugkomposition nachzudenken: Verkettung von Operationen und Handhabung von Abhängigkeiten wie beim Schreiben von beliebigem Python-Code
  • Große Ergebnisse effizient zu verarbeiten: Filterung großer Werkzeugausgaben, Extraktion nur relevanter Daten oder Schreiben von Zwischenergebnissen in Dateien, bevor Zusammenfassungen an das Kontextfenster zurückgegeben werden
  • Latenz erheblich zu reduzieren: Beseitigung des Overheads des erneuten Samplings von Claude zwischen jedem Werkzeugaufruf in Multi-Step-Workflows

Dieser Ansatz ermöglicht Workflows, die mit traditioneller Werkzeugnutzung unpraktisch wären (wie die Verarbeitung von Dateien über 1M Token), indem Claude mit Daten programmgesteuert arbeiten kann, anstatt alles in das Gesprächsfenster zu laden.

Alternative Implementierungen

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

Clientseitige direkte Ausführung

Stellen Sie Claude ein Codeausführungs-Werkzeug zur Verfügung 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 beliebigen Code sicher ausführen kann, Sie eine einfache Lösung möchten 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 zur Ausführung von Werkzeugaufrufen außerhalb der Sandbox.

Vorteile:

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

Nachteile:

  • Komplex zu bauen und zu warten
  • Erfordert die Verwaltung sowohl der Infrastruktur als auch der Interprozess-Kommunikation

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

Anthropic-verwaltete Ausführung

Anthropics programmgesteuerte Werkzeugaufrufe sind eine verwaltete Version der Sandbox-Ausführung mit einer für Claude optimierten Python-Umgebung. Anthropic verwaltet Container-Management, Codeausführung und sichere Werkzeugaufrufe-Kommunikation.

Vorteile:

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

Erwägen Sie die Verwendung von Anthropics verwalteter Lösung, wenn Sie die Claude-API verwenden.

Datenspeicherung

Programmgesteuerte Werkzeugaufrufe basieren auf der Codeausführungsinfrastruktur und verwenden die gleichen Sandbox-Container. Container-Daten, einschließlich Ausführungsartefakte und Ausgaben, werden bis zu 30 Tage lang aufbewahrt.

Für ZDR-Berechtigung über alle Funktionen hinweg siehe API und Datenspeicherung.

Verwandte Funktionen

Code Execution Tool

Erfahren Sie mehr über die zugrunde liegende Codeausführungsfunktion, die programmgesteuerte Werkzeugaufrufe ermöglicht.

Tool Use Overview

Verstehen Sie die Grundlagen der Werkzeugnutzung mit Claude.

Define tools

Schritt-für-Schritt-Anleitung zum Definieren von Werkzeugen.

Was this page helpful?

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