Programmatisches Tool-Calling

Programmatisches Tool-Calling ermöglicht es Claude, Code zu schreiben, der deine Tools programmatisch innerhalb eines Code-Execution-Containers aufruft, anstatt für jeden Tool-Aufruf einen Roundtrip durch das Modell zu erfordern. Dies reduziert die Latenz bei Multi-Tool-Workflows und verringert den Token-Verbrauch, indem Claude Daten filtern oder verarbeiten kann, bevor sie das Kontextfenster des Modells erreichen. Bei agentischen Such-Benchmarks wie BrowseComp und DeepSearchQA, die mehrstufige Web-Recherche und komplexe Informationsabfrage testen, verbesserte das Hinzufügen von programmatischem Tool-Calling zu grundlegenden Such-Tools die Leistung um durchschnittlich 11 % bei gleichzeitig 24 % weniger Input-Token (siehe Improved web search with dynamic filtering).

Stell dir vor, du prüfst die Budget-Einhaltung bei 20 Mitarbeitern: Der traditionelle Ansatz erfordert 20 separate Modell-Roundtrips und zieht dabei Tausende von Spesenpositionen in den Kontext. Mit programmatischem Tool-Calling führt ein einziges Skript alle 20 Abfragen aus, filtert die Ergebnisse und gibt nur die Mitarbeiter zurück, die ihr Limit überschritten haben – das reduziert das, worüber Claude nachdenken muss, von Hunderten Kilobytes auf eine Handvoll Zeilen.



Modellkompatibilität

Programmatisches Tool-Calling erfordert code_execution_20260120 oder neuer, was von den folgenden Modellen unterstützt wird:

Die vollständige Versionsmatrix des Code-Execution-Tools findest du in der Modellkompatibilitätstabelle des Code-Execution-Tools. Programmatisches Tool-Calling ist über die Claude API, Claude Platform on AWS und Microsoft Foundry verfügbar. Auf Microsoft Foundry erfordert programmatisches Tool-Calling ein Hosted on Anthropic Deployment. Es ist derzeit nicht auf Amazon Bedrock oder Google Cloud verfügbar.



Schnellstart

Hier ist ein Beispiel, in dem Claude programmatisch mehrfach eine Datenbank abfragt und die Ergebnisse aggregiert:

client = anthropic.Anthropic()

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

Die Antwort stoppt mit stop_reason: "tool_use", einer container-ID und einem tool_use-Block für query_database, dessen caller-Feld den Code-Execution-Lauf identifiziert, der ihn aufgerufen hat. Gib das Ergebnis wie in Schritt 3 des Beispiel-Workflows gezeigt zurück, damit der Code abgeschlossen werden kann.



Wie programmatisches Tool-Calling funktioniert

Wenn du ein Tool so konfigurierst, dass es aus der Code-Execution aufrufbar ist, und Claude entscheidet, dieses Tool zu verwenden:

1. Claude schreibt Python-Code, der das Tool als Funktion aufruft, möglicherweise mit mehreren Tool-Aufrufen und Vor-/Nachverarbeitungslogik
2. Claude führt diesen Code in einem Sandbox-Container über Code-Execution aus
3. Wenn eine Tool-Funktion aufgerufen wird, pausiert die Code-Execution und die API gibt einen tool_use-Block zurück
4. Du stellst das Tool-Ergebnis bereit, und die Code-Execution wird fortgesetzt (Zwischenergebnisse werden nicht in Claudes Kontextfenster geladen)
5. Sobald die gesamte Code-Execution abgeschlossen ist, erhält Claude die finale Ausgabe und arbeitet weiter an der Aufgabe

Dieser Ansatz ist besonders nützlich für:

• Verarbeitung großer Datenmengen: Filtere oder aggregiere Tool-Ergebnisse, bevor sie Claudes Kontext erreichen
• Mehrstufige Workflows: Spare Token und Latenz, indem Tools seriell oder in einer Schleife aufgerufen werden, ohne Claude zwischen den Tool-Aufrufen zu sampeln
• Bedingte Logik: Triff Entscheidungen basierend auf Zwischenergebnissen von Tools



Kernkonzepte



Das allowed_callers-Feld

Das allowed_callers-Feld 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"] – Claude wird angeleitet, dieses Tool direkt aufzurufen (Standard, wenn weggelassen)
• ["code_execution_20260120"] – Claude wird angeleitet, dieses Tool nur innerhalb der Code-Execution aufzurufen
• ["direct", "code_execution_20260120"] – Claude kann dieses Tool direkt oder innerhalb der Code-Execution aufrufen

Sowohl "code_execution_20260120" als auch "code_execution_20260521" werden in allowed_callers akzeptiert und sind austauschbar: Eine Anfrage, die eine der beiden Code-Execution-Tool-Versionen verwendet, erfüllt Tools, die einen der beiden Caller auflisten. Response-Blöcke kennzeichnen den Caller immer als code_execution_20260120, unabhängig davon, welche Version die Anfrage deklariert hat.



Das caller-Feld in Antworten

Jeder Tool-Use-Block enthält ein caller-Feld, das angibt, wie er 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 ist die id des Code-Execution-server_tool_use-Blocks, der den Aufruf getätigt hat, sodass du jedes programmatische tool_use dem Code-Execution-Lauf zuordnen kannst, der es erzeugt hat.



Container-Lebenszyklus

Programmatisches Tool-Calling verwendet dieselben Container wie Code-Execution:

• Container-Erstellung: Für jede Anfrage wird ein neuer Container erstellt, es sei denn, du verwendest einen bestehenden wieder
• Container-ID: Wird in Antworten im container-Feld zurückgegeben, zusammen mit einem expires_at-Zeitstempel
• Wiederverwendung: Übergib die Container-ID bei der nächsten Anfrage, um den Zustand beizubehalten. Während ein programmatischer Tool-Aufruf auf dein Ergebnis wartet, ist die Container-ID bei dieser Anfrage erforderlich, nicht optional: Die API lehnt die Anfrage ohne sie ab.
• Ablauf: expires_at gibt an, wie lange der Container noch verfügbar ist. Inaktive Container werden derzeit nach etwa 5 Minuten freigegeben, und kein Container kann mehr als 30 Tage nach seiner Erstellung wiederverwendet werden.



Beispiel-Workflow

So funktioniert ein vollständiger Ablauf für programmatisches Tool-Calling:



Schritt 1: Initiale Anfrage

Sende eine Anfrage mit Code-Execution und einem Tool, das programmatisches Aufrufen erlaubt. Um programmatisches Aufrufen zu aktivieren, füge das allowed_callers-Feld zu deiner Tool-Definition hinzu.

Die Anfragestruktur ist identisch mit dem Schnellstart-Beispiel: Füge code_execution in deine Tools-Liste ein, füge allowed_callers: ["code_execution_20260120"] zu jedem Tool hinzu, das Claude aus Code aufrufen soll, und sende deine User-Nachricht. Die verbleibenden Schritte in diesem Workflow verwenden die User-Nachricht "Query customer purchase history from the last quarter and identify our top 5 customers by revenue".



Schritt 2: API-Antwort mit Tool-Aufruf

Claude schreibt Code, der dein Tool 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": "import json\n\nrows = json.loads(await query_database({'sql': '<sql>'}))\ntop_customers = sorted(rows, 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": "2026-01-20T14:30:00Z"
  },
  "stop_reason": "tool_use"
}



Schritt 3: Tool-Ergebnis bereitstellen

Sende den vollständigen Gesprächsverlauf plus dein Tool-Ergebnis. Drei Details sind bei dieser Anfrage wichtig:

• Die User-Nachricht, die dein Ergebnis enthält, darf nur tool_result-Blöcke enthalten. Siehe Einschränkungen bei der Nachrichtenformatierung.
• Übergib die container-ID aus der pausierten Antwort. Die API lehnt eine Fortsetzung ab, die ausstehende programmatische Tool-Aufrufe, aber keine Container-ID hat.
• Sende dasselbe tools-Array wie bei der ursprünglichen Anfrage. Das Code-Execution-Tool muss weiterhin vorhanden sein, damit der pausierte Code fortgesetzt werden kann, und die Tools, die du bei dieser Anfrage sendest, sind die Definitionen, die Claude und der laufende Code für den Rest des Turns verwenden können.

response = client.messages.create(
    model="claude-opus-4-8",
    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}, ...]',
                }
            ],
        },
    ],
    # Dasselbe Tools-Array wie in der ursprünglichen Anfrage
    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)



Schritt 4: Nächster Tool-Aufruf oder Abschluss

Der Code setzt dort fort, wo er pausiert hat, und verarbeitet dein Ergebnis. Jede Fortsetzungsantwort pausiert entweder erneut mit weiteren programmatischen tool_use-Blöcken oder schließt die Code-Execution ab und lässt Claude den Turn fortsetzen (Schritt 5). Prüfe stop_reason und das caller-Feld jedes tool_use-Blocks, um die beiden Fälle zu unterscheiden: Eine Antwort, die für dich pausiert, hat stop_reason: "tool_use" und einen tool_use-Block, dessen caller eine Code-Execution-Version benennt, und du wiederholst Schritt 3 mit einem tool_result für jeden ausstehenden programmatischen Aufruf in einer User-Nachricht.



Schritt 5: Finale Antwort

Sobald die Code-Execution abgeschlossen ist, liefert Claude die finale Antwort:

{
  "content": [
    {
      "type": "code_execution_tool_result",
      "tool_use_id": "srvtoolu_abc123",
      "content": {
        "type": "code_execution_result",
        "stdout": "Top 5 customers: [{'customer_id': 'C1', 'revenue': 45000}, {'customer_id': 'C2', 'revenue': 38000}, {'customer_id': 'C5', 'revenue': 32000}, {'customer_id': 'C8', 'revenue': 28500}, {'customer_id': 'C3', 'revenue': 24000}]",
        "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"
}



Fortgeschrittene Muster



Batch-Verarbeitung mit Schleifen

Claude kann Code schreiben, der mehrere Elemente effizient verarbeitet:

regions = ["West", "East", "Central", "North", "South"]
results = {}
for region in regions:
    rows = json.loads(await query_database({"sql": f"<sql for {region}>"}))
    results[region] = sum(row["revenue"] for row in rows)

# Verarbeite Ergebnisse programmatisch
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 (einer pro Region) auf 1
• Verarbeitet große Ergebnismengen programmatisch, bevor sie an Claude zurückgegeben werden
• Spart Token, indem nur aggregierte Schlussfolgerungen statt Rohdaten zurückgegeben werden



Vorzeitiger Abbruch

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

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



Bedingte Tool-Auswahl

path = "/tmp/example.txt"
file_info = json.loads(await get_file_info({"path": path}))
if file_info["size"] < 10000:
    content = await read_full_file({"path": path})
else:
    content = await read_file_summary({"path": path})
print(content)



Datenfilterung

server_id = "srv-01"
log_text = await fetch_logs({"server_id": server_id})
errors = [line for line in log_text.splitlines() if "ERROR" in line]
print(f"Found {len(errors)} errors")
for error in errors[-10:]:  # Only return last 10 errors
    print(error)



Antwortformat



Programmatischer Tool-Aufruf

Wenn Code-Execution ein Tool aufruft:

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



Verarbeitung des Tool-Ergebnisses

Dein Tool-Ergebnis 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}, ...]"
    }
  ]
}



Abschluss der Code-Execution

Wenn alle Tool-Aufrufe beantwortet 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



Container-Ablauf während eines Tool-Aufrufs

Wenn dein Tool-Ergebnis nicht innerhalb von etwa 4 Minuten eintrifft, löst der ausstehende Aufruf einen TimeoutError in Claudes laufendem Code aus. Claude sieht den Fehler in stderr und versucht den Aufruf typischerweise 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 (no response after 270s).",
    "return_code": 0,
    "content": []
  }
}

Um Timeouts zu verhindern:

• Überwache das expires_at-Feld in Antworten
• Implementiere Timeouts für deine Tool-Ausführung
• Erwäge, lange Operationen in kleinere Teile aufzuteilen



Fehler bei der Tool-Ausführung

Wenn dein Tool einen Fehler zurückgibt:

{
  "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 behandeln.



Einschränkungen und Limitierungen



Feature-Inkompatibilitäten

• Strukturierte Ausgaben: Tools mit strict: true werden mit programmatischem Aufrufen nicht unterstützt
• Tool-Choice: Du kannst das programmatische Aufrufen eines bestimmten Tools nicht über tool_choice erzwingen
• Parallele Tool-Nutzung: disable_parallel_tool_use: true wird mit programmatischem Aufrufen nicht unterstützt



Einschränkungen beim Input-Schema

Benutzerdefinierte Tools, deren input_schema eine rekursive $ref enthält (einen Referenzzyklus, etwa ein Schema, das auf sich selbst verweist), können nicht für programmatisches Aufrufen aktiviert werden. Das Einfügen einer Code-Execution-Tool-Version in allowed_callers für ein solches Tool führt dazu, dass die Anfrage mit einem 400 invalid_request_error fehlschlägt, dessen Nachricht Circular $ref detected enthält. Dasselbe Schema wird für direktes Tool-Calling akzeptiert.

Um dies zu umgehen, führe einen der folgenden Schritte aus:

• Belasse das Tool als direkt-only, indem du allowed_callers weglässt (oder auf ["direct"] setzt). Andere Tools in derselben Anfrage können weiterhin programmatisches Aufrufen verwenden.
• Entferne den Zyklus aus dem Schema. Rolle zum Beispiel die Rekursion bis zu einer festen Tiefe aus und beschreibe jede tiefere Verschachtelung in der description der innersten Ebene, oder ersetze die rekursive Eigenschaft durch ein einfaches {"type": "object"}, dessen description die erwartete Struktur erklärt.



Tool-Einschränkungen

Die folgenden Tools können nicht programmatisch aufgerufen werden:

• Tools, die von einem MCP-Connector bereitgestellt werden



Einschränkungen bei der Nachrichtenformatierung

Beim Antworten auf programmatische Tool-Aufrufe gelten strenge Formatierungsanforderungen:

Antworten nur mit Tool-Ergebnissen: Wenn ausstehende programmatische Tool-Aufrufe auf Ergebnisse warten, darf deine Antwortnachricht nur tool_result-Blöcke enthalten. Du kannst keinen Textinhalt einfügen, auch nicht nach den Tool-Ergebnissen.

Ungültig – Text kann nicht eingefügt werden, wenn auf programmatische Tool-Aufrufe 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 Tool-Ergebnisse beim Antworten auf programmatische Tool-Aufrufe:

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

Diese Einschränkung gilt nur beim Antworten auf programmatische (Code-Execution-)Tool-Aufrufe. Bei regulären clientseitigen Tool-Aufrufen kannst du Textinhalt nach Tool-Ergebnissen einfügen.

Nur-Text-Inhalt für Tool-Ergebnisse: Der content jedes tool_result, das einen programmatischen Aufruf beantwortet, muss ein String oder text-Blöcke sein. Bild-, Dokument- und andere Content-Block-Typen werden abgelehnt.



Ratenlimits

Programmatische Tool-Aufrufe unterliegen denselben Ratenlimits wie reguläre Tool-Aufrufe. Jeder Tool-Aufruf aus der Code-Execution zählt als separater Aufruf.



Tool-Ergebnisse vor der Verwendung validieren

Bei der Implementierung benutzerdefinierter Tools, die programmatisch aufgerufen werden:

• Tool-Ergebnisse 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.
• Validiere externe Tool-Ergebnisse: Wenn dein Tool Daten aus externen Quellen zurückgibt oder Benutzereingaben akzeptiert, sei dir der Risiken von Code-Injection bewusst, falls die Ausgabe als Code interpretiert oder ausgeführt wird.



Token-Effizienz

Programmatisches Tool-Calling reduziert den Token-Verbrauch auf drei Arten:

• Tool-Ergebnisse aus programmatischen Aufrufen werden nicht zu Claudes Kontext hinzugefügt – nur die finale Code-Ausgabe
• Zwischenverarbeitung findet im Code statt – Filterung, Aggregation und andere Transformationen verbrauchen keine Modell-Token
• Mehrere Tool-Aufrufe in einer Code-Execution – reduziert den Overhead im Vergleich zu separaten Modell-Turns

Zum Beispiel verbraucht das direkte Aufrufen von 10 Tools etwa das 10-Fache an Token im Vergleich zum programmatischen Aufrufen und Zurückgeben einer Zusammenfassung.

In Anthropics internen Evaluierungen mit einem Produktions-Claude-Modell:

• Bei einem Projektmanagement-Agenten-Benchmark mit 75 Tools reduzierte das Aktivieren von programmatischem Tool-Calling die abgerechneten Input-Token um etwa 38 % ohne Änderung der Aufgabengenauigkeit.
• Bei τ²-bench (Domänen Airline, Retail und Telecom), wo jeder Turn ein oder zwei sequenzielle Tool-Aufrufe macht, ließ programmatisches Tool-Calling die Scores unverändert und kostete etwa 8 % mehr. Sequenzielle Single-Call-Workflows profitieren nicht.
• Über den Produktions-API-Traffic hinweg sehen Anfragen, deren tools-Array 10 bis 49 Tool-Definitionen enthält, typische Token-Einsparungen von 20 % bis 40 % mit aktiviertem programmatischem Tool-Calling.

Die tatsächlichen Einsparungen variieren je nach Workload-Struktur. Siehe Wann programmatisches Aufrufen verwenden.



Nutzung und Preise

Programmatisches Tool-Calling verwendet dieselbe Preisgestaltung wie Code-Execution. Siehe die Code-Execution-Preise für Details.



Best Practices



Tool-Design

• Gib detaillierte Ausgabebeschreibungen an: Da Claude Tool-Ergebnisse im Code deserialisiert, dokumentiere das Format (JSON-Struktur und Feldtypen)
• Gib strukturierte Daten zurück: JSON oder andere maschinenlesbare Formate eignen sich am besten für programmatische Verarbeitung
• Halte Antworten knapp: Gib nur notwendige Daten zurück, um den Verarbeitungs-Overhead zu minimieren



Wann programmatisches Aufrufen verwenden

Programmatisches Tool-Calling tauscht einen kleinen festen Overhead (Container-Start, Skript-Generierung) gegen große Einsparungen bei Tool-Ergebnis-Token und Modell-Roundtrips. Ob sich dieser Tausch lohnt, hängt von der Workload-Struktur ab.

Gut geeignet:

• Fan-out- oder parallele Operationen über viele Elemente (zum Beispiel das Prüfen von 50 Endpunkten oder das Nachschlagen von 20 Datensätzen)
• Große Tool-Ergebnisse, die gefiltert, aggregiert oder zusammengefasst werden können, bevor sie Claudes Kontext erreichen
• Agentische Suche und Retrieval, bei denen iteratives Abfragen und Ergebnisfilterung den Workflow dominieren

Weniger geeignet:

• Strikt sequenzielle Workflows, bei denen jeder Aufruf davon abhängt, dass Claude über das vorherige Ergebnis nachdenkt, da das Skript den Modell-Roundtrip in diesem Fall nicht überspringen kann
• Eine kleine Anzahl von Tool-Aufrufen mit kleinen Antworten, besonders beim ersten Turn einer Konversation, wo Container- und Skript-Overhead die Einsparungen übersteigen können
• Tools, die sofortiges Benutzer-Feedback zwischen Aufrufen erfordern

Wenn du unsicher bist, miss die abgerechneten Input-Token mit und ohne allowed_callers an einer repräsentativen Stichprobe deines Traffics, bevor du es breit aktivierst.



Performance-Optimierung

• Verwende Container wieder, wenn du mehrere zusammenhängende Anfragen stellst, um den Zustand beizubehalten
• Bündle ähnliche Operationen in einer einzigen Code-Execution, wenn möglich



Fehlerbehebung



Häufige Probleme

invalid_request_error beim Setzen von tool_choice

• tool_choice kann kein Tool benennen, dessen allowed_callers "direct" nicht enthält. Füge entweder "direct" zu den allowed_callers dieses Tools hinzu, oder entferne das Tool aus tool_choice und lass Claude es aus Code aufrufen.

Container-Ablauf

• Antworte auf jeden programmatischen Tool-Aufruf deutlich vor dem expires_at-Zeitstempel der pausierten Antwort. Claudes Code wartet nach etwa 4 Minuten nicht mehr auf ein Ergebnis, und inaktive Container werden derzeit nach etwa 5 Minuten freigegeben.
• Erwäge, eine schnellere Tool-Ausführung zu implementieren

Tool-Ergebnis nicht korrekt geparst

• Stelle sicher, dass dein Tool String-Daten zurückgibt, die Claude deserialisieren kann
• Gib eine klare Dokumentation des Ausgabeformats in deiner Tool-Beschreibung an



Debugging-Tipps

1. Logge alle Tool-Aufrufe und Ergebnisse, um den Ablauf nachzuverfolgen
2. Prüfe das caller-Feld, um den programmatischen Aufruf zu bestätigen
3. Überwache Container-IDs, um die korrekte Wiederverwendung sicherzustellen
4. Teste Tools unabhängig, bevor du programmatisches Aufrufen aktivierst



Warum programmatisches Tool-Calling funktioniert

Claude wurde auf großen Mengen Code trainiert, daher spielt das Präsentieren von Tools als aufrufbare Python-Funktionen diese Stärke aus:

• Tool-Komposition: Verkettete Aufrufe, Schleifen und Bedingungen sind gewöhnlicher Python-Kontrollfluss statt einer Reihe von Modell-Roundtrips
• Ergebnisverarbeitung: Claudes Code filtert und aggregiert große Tool-Ausgaben oder schreibt sie in Dateien, und nur die finale Ausgabe gelangt ins Kontextfenster
• Latenz: Das Modell wird zwischen den Tool-Aufrufen innerhalb einer Code-Execution nicht erneut gesampelt



Alternative Implementierungen

Programmatisches Tool-Calling ist ein verallgemeinerbares Muster, das auch auf deiner eigenen Infrastruktur implementiert werden kann. So vergleichen sich die Ansätze:



Clientseitige direkte Ausführung

Stelle Claude ein Code-Execution-Tool bereit und beschreibe, welche Funktionen in dieser Umgebung verfügbar sind. Wenn Claude das Tool mit Code aufruft, führt deine Anwendung ihn lokal aus, wo diese Funktionen definiert sind.

Vorteile:

• Minimale Umstrukturierung deiner Anwendung
• Volle Kontrolle über die Umgebung und Anweisungen

Nachteile:

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

Verwende dies, wenn: Deine Anwendung beliebigen Code sicher ausführen kann, du die kleinste Implementierung möchtest und Anthropics verwaltetes Angebot nicht zu deinen Anforderungen passt.



Selbstverwaltete Sandbox-Ausführung

Derselbe Ansatz aus Claudes Perspektive, aber der Code läuft in einem Sandbox-Container mit Sicherheitseinschränkungen (zum Beispiel kein Netzwerk-Egress). Wenn deine Tools externe Ressourcen benötigen, brauchst du ein Protokoll zum Ausführen von Tool-Aufrufen außerhalb der Sandbox.

Vorteile:

• Sicheres programmatisches Tool-Calling auf deiner eigenen Infrastruktur
• Volle Kontrolle über die Ausführungsumgebung

Nachteile:

• Komplex zu bauen und zu warten
• Erfordert das Verwalten sowohl der Infrastruktur als auch der Interprozesskommunikation

Verwende dies, wenn: Sicherheit kritisch ist und Anthropics verwaltete Lösung nicht zu deinen Anforderungen passt.



Von Anthropic verwaltete Ausführung

Anthropics programmatisches Tool-Calling ist eine verwaltete Version der Sandbox-Ausführung mit einer vorkonfigurierten Python-Umgebung, die auf Claude abgestimmt ist. Anthropic übernimmt Container-Management, Code-Ausführung und sichere Kommunikation für Tool-Aufrufe.

Vorteile:

• Standardmäßig sicher und geschützt
• Aktiviert mit einer Tool-Definition, ohne Infrastruktur betreiben zu müssen
• Umgebung und Anweisungen für Claude optimiert

Erwäge die Verwendung von Anthropics verwalteter Lösung, wenn du die Claude API, Claude Platform on AWS oder Microsoft Foundry verwendest. Auf Microsoft Foundry erfordert programmatisches Tool-Calling ein Hosted on Anthropic Deployment.



Datenspeicherung

Programmatisches Tool-Calling basiert auf der Code-Execution-Infrastruktur und verwendet dieselben Sandbox-Container. Container-Daten, einschließlich Ausführungsartefakten und Ausgaben, werden bis zu 30 Tage aufbewahrt.

Zur ZDR-Eignung über alle Features hinweg siehe API und Datenspeicherung.



Nächste Schritte