Senke die Kosten toolintensiver Workflows

Die Demo in diesem Video wurde im September 2026 aufgezeichnet. Sie lief auf Claude Sonnet 5 (claude-sonnet-5). Bei neueren Modellen können die Ergebnisse abweichen.

Ein Agent, der Tools verwendet, sendet bei jeder Anfrage wieder alles, sodass seine Kosten mit jedem Tool-Aufruf steigen. Jede Anfrage enthält die Tool-Definitionen, den System-Prompt, die Frage und alle bisherigen Tool-Ergebnisse. Das sind seine Input-Tokens, und jedes davon wird abgerechnet.

Programmatic Tool Calling und Prompt-Caching senken beide diese Kosten.

Meridian ist eine fiktive Ingenieurberatung mit 40 Ingenieuren. Ihr Agent erhielt eine Frage: Welche Ingenieure hatten im Juni 2026 eine Auslastung unter 70 %? Der Agent hatte zwei Tools. list_employees liefert die Mitarbeiterliste, und get_employee_hours liefert die Stundenabrechnung eines Ingenieurs.

Die Beantwortung dieser Frage kostete den Agenten 42 Anfragen und 1.124.799 Input-Tokens. Der gesamte Durchlauf kostete 2,29 $ an Tokens.

Miss die Input-Tokens in jeder Anfrage

Gib usage.input_tokens jedes Mal aus, wenn eine Antwort zurückkommt, denn diese Zahlen zeigen dir, wo die Kosten liegen.

resp = client.messages.create(...)
print(resp.usage.input_tokens, "input tokens")

Meridians Agent führt eine klassische Schleife aus, bei der jede Antwort einen Tool-Aufruf anfordert. Hier sind zwei seiner Zahlen.

Anfrage 1 enthält nur das, was jede Anfrage sendet. Spätere Anfragen fügen Tool-Aufrufe und deren Ergebnisse hinzu. Vergleiche die beiden Zahlen, um zu sehen, welcher Teil gewachsen ist.

Halte Tool-Ergebnisse aus dem heraus, was Claude liest

Mit Programmatic Tool Calling schreibt Claude ein Skript, das deine Tools aufruft, und das Code-Execution-Tool führt es in einem Container aus. Nur das, was das Skript ausgibt, erreicht Claude. Meridians 40 Stundenabrechnungen bleiben beim Skript, und Claude erhält seine kurze Ausgabe.

Prüfe zuerst deine Tools und dein Modell. Stand Oktober 2026 unterstützt Programmatic Tool Calling keine Tools, die mit strict: true markiert sind. Es unterstützt auch nicht disable_parallel_tool_use, die tool_choice-Einstellung, die Claude auf einen Tool-Aufruf pro Antwort beschränkt. tool_choice kann Claude nicht zwingen, ein Tool aus dem Skript heraus aufzurufen.

Claude Haiku 4.5 unterstützt dieses Feature nicht. Das Feature läuft auf der Claude API, Claude Platform auf AWS und Microsoft-Foundry-Deployments, die bei Anthropic gehostet werden.

Das Aktivieren von Programmatic Tool Calling erfordert vier Änderungen.

1. Füge das Code-Execution-Tool zu deiner tools-Liste hinzu.
2. Markiere die Tools, die das Skript aufrufen darf. Gib jedem ein allowed_callers-Feld, das das Code-Execution-Tool ab Version code_execution_20260120 oder später benennt.
3. Sende die ID des Containers zurück. Lies sie aus jeder Antwort aus, die für einen Tool-Aufruf stoppt, und sende sie mit der Anfrage, die deine Tool-Ergebnisse zurückgibt.
4. Beschreibe das Ergebnis jedes Tools. Sag in der Beschreibung, welche Form es hat, denn das Skript muss es parsen. Hier ist Meridians Beschreibung für get_employee_hours.

Returns one engineer's hours for the month as JSON: {"name": str, "billable_hours": float, "utilization": float 0-1}

Hier ist Meridians Schleife nach diesen Änderungen.

CODE_EXECUTION = "code_execution_20260120"
TOOLS = [
    {"type": CODE_EXECUTION, "name": "code_execution"},
    {**LIST_EMPLOYEES, "allowed_callers": [CODE_EXECUTION]},
    {**GET_EMPLOYEE_HOURS, "allowed_callers": [CODE_EXECUTION]},
]

messages = [{"role": "user", "content": QUESTION}]
container = None
while True:
    resp = client.messages.create(
        model="claude-sonnet-5", max_tokens=4096,
        tools=TOOLS, messages=messages, container=container,
    )
    print(resp.usage.input_tokens, "input tokens")
    if resp.stop_reason not in ("tool_use", "pause_turn"):
        break
    container = resp.container.id
    messages.append({"role": "assistant", "content": resp.content})
    if resp.stop_reason == "tool_use":
        messages.append({"role": "user", "content": run_tools(resp)})
print("".join(b.text for b in resp.content if b.type == "text"))

• LIST_EMPLOYEES und GET_EMPLOYEE_HOURS sind Meridians Tool-Definitionen.
• Dein eigenes run_tools führt jeden Tool-Aufruf aus und gibt die Ergebnisse zurück.
• Bei pause_turn sendet die Schleife die Antwort zurück und macht weiter.

Wenn das Skript ein Tool aufruft, ist der stop_reason der Antwort "tool_use". Dein Code führt das Tool aus, und das Ergebnis geht an das Skript, nicht an Claude. Das Skript kann Tools parallel ausführen, sodass eine Antwort mehr als einen Tool-Aufruf enthalten kann.

Hier ist dieselbe Frage, auf beide Arten beantwortet.

Beide Durchläufe verwendeten dieselbe Frage, dieselben Tools und claude-sonnet-5. Die Kosten basieren auf Preisen Stand September 2026, und die Code-Ausführungszeit wird separat von den Tokens abgerechnet.

Programmatic Tool Calling eignet sich für Abfragen, die nicht voneinander abhängen. Es hilft wenig, wenn Claude über jedes Ergebnis nachdenken muss, bevor es den nächsten Tool-Aufruf macht.

Cache Tool-Definitionen, die sich wiederholen

Mit Prompt-Caching speichert die API das Präfix deiner Anfrage, den Teil bis zu einem Cache-Punkt, den du markierst. Dieses Präfix erneut zu lesen kostet deutlich weniger.

Ein zweiter Meridian-Agent hat 14 Tools, und ihre Definitionen ergeben 3.305 Tokens, die jede Anfrage erneut sendet.

Markiere den Cache-Punkt, indem du cache_control auf das letzte Tool setzt, und die ganze Liste wird gecacht. Das braucht nur eine Zeile:

TOOLS[-1]["cache_control"] = {"type": "ephemeral"}

Bei Claude Sonnet 5 kostet das Lesen des Präfixes ein Zehntel des normalen Input-Preises. Das Schreiben kostet das 1,25-Fache des normalen Input-Preises.

Das gecachte Präfix hält standardmäßig fünf Minuten, und jede Nutzung erneuert es. Für Anfragen, die weiter auseinanderliegen, füge "ttl": "1h" zu cache_control hinzu, um es eine Stunde lang zu behalten. Das Schreiben eines einstündigen Caches kostet das Doppelte des normalen Input-Preises.

Meridian stellte dieselben acht Fragen mit und ohne Cache. Die Gesamtkosten für Input sanken von 0,0554 $ auf 0,0154 $.

Mit automatischem Caching setzt du ein cache_control-Feld auf der obersten Ebene der Anfrage, und die API platziert den Cache-Punkt für dich.

Achte auf drei Dinge, sobald Caching aktiviert ist:

1. Änderst du eine Tool-Definition, verlierst du den gesamten Cache.
2. Bei Sonnet 5 muss ein gecachtes Präfix mindestens 1.024 Tokens umfassen. Ist es kürzer, wird nichts gecacht, und kein Fehler weist darauf hin.
3. Mit aktiviertem Caching lässt input_tokens das gecachte Präfix aus, sodass die tatsächliche Gesamtsumme einer Anfrage die Summe aus input_tokens, cache_read_input_tokens und cache_creation_input_tokens ist.

Kombiniere die Features dort, wo sie passen

Füge sie in dieser Reihenfolge hinzu.

1. Beginne mit Caching. Es braucht nur eine Zeile.
2. Teste Programmatic Tool Calling. Führe einen Teil deines üblichen Traffics mit und ohne allowed_callers aus und vergleiche dann die abgerechneten Input-Tokens jedes Durchlaufs.

Finde für jede der beiden folgenden Meridian-Anfragen den Teil, der den größten Anteil der Input-Tokens ausmacht, und wähle dann das Feature, das ihn senkt.

Wichtige Erkenntnisse

• Jede Anfrage sendet alles erneut, sodass du immer wieder für alte Tool-Ergebnisse bezahlst.
• Gib usage.input_tokens jedes Mal aus, wenn eine Antwort zurückkommt, damit du weißt, welcher Teil der Anfrage am meisten kostet.
• Beginne mit Caching. Füge cache_control zum letzten Tool in deiner Liste hinzu.
• Wenn deine Tool-Aufrufe nicht voneinander abhängen, richte Programmatic Tool Calling mit dem Code-Execution-Tool und allowed_callers ein. Sende die ID des Containers mit jeder späteren Anfrage.