Task Budgets — Beratende Token-Obergrenzen, damit Agenten sauber zum Abschluss kommen

Experte

What you'll learn

Verstehen, was ein Task Budget ist — ein beratender, für das Modell sichtbarer Token-Countdown über eine gesamte agentische Schleife
task_budget korrekt konfigurieren — innerhalb von output_config, mit dem Beta-Header task-budgets-2026-03-13, auf einem unterstützten Modell
Erkennen, was tatsächlich gegen das Budget zählt (Tokens, die Claude in diesem Turn sieht) und was nicht (wiederholte Payload aus erneut gesendeter Historie)
Eine Budgetgröße wählen, die hilft, statt ablehnungsähnliches Verhalten auszulösen — erst messen, dann großzügig setzen
Ein Budget mit dem Feld remaining über eine Kompaktierung hinweg mitführen und die Falle der Prompt-Caching-Invalidierung vermeiden
Task Budgets, Session Budgets, Effort und max_tokens auseinanderhalten — vier Hebel, vier verschiedene Aufgaben

Agenten mit langem Horizont verbrauchen Tokens auf eine Weise, die von außen schwer vorhersehbar ist. Eine einzelne Anfrage, die sich zu einem Dutzend Runden aus Denken plus Tool-Aufruf ausweitet, kann still und leise das 10-Fache eines typischen Turns kosten. Task Budgets sind Anthropics Antwort darauf: Man gibt Claude eine beratende Token-Obergrenze für die gesamte agentische Schleife und lässt das Modell sich selbst regulieren — sein Denken dosieren, Aktionen priorisieren und mit einer Zusammenfassung abschließen, wenn das Budget zur Neige geht, statt von max_tokens mitten in einem Tool-Aufruf abgeschnitten zu werden.

Zwei Dinge unterscheiden Task Budgets von jedem anderen Kostenhebel, den Sie vielleicht schon kennen:

Der Countdown ist für das Modell sichtbar. Claude sieht eine serverseitig eingefügte laufende Markierung „verbleibende Tokens“ und passt sein Verhalten daran an. Ihr Client sieht diese Markierung nie in einem usage-Feld.
Er ist beratend, nicht erzwungen. Task Budgets sind ein weicher Hinweis; die harte Obergrenze bleibt max_tokens. Das ist ein Feature — Claude kann das Budget gelegentlich überschreiten, wenn das Unterbrechen einer laufenden Aktion störender wäre als sie abzuschließen.

Wie der Budget-Countdown funktioniert

Der Countdown spiegelt die Tokens wider, die Claude in dieser Schleife verarbeitet hat — Denken, Tool-Aufrufe, Tool-Ergebnisse und Ausgabe — nicht die Größe Ihrer Request-Payload. Wenn Ihr Client bei jedem Turn die vollständige Konversation erneut sendet, wächst die Payload monoton, aber das Budget verringert sich nur um das, was für Claude in diesem Turn neu ist.

Watch out

Der Countdown ist nur für das Modell sichtbar. API-Antworten enthalten kein Feld für das verbleibende Budget — kein task_budget-Eintrag in usage, kein SDK-Accessor dafür. Um den Verbrauch clientseitig zu verfolgen, summieren Sie output_tokens über alle Requests Ihrer Schleife.
Wenn Ihr Client bei jedem Folge-Request die vollständige Historie sendet UND dabei remaining herunterzählt, sieht das Modell ein zu niedrig angegebenes Budget und schließt früher ab, als das Budget tatsächlich erlaubt. Setzen Sie ein großzügiges Budget und lassen Sie das Modell sich gegen den serverseitigen Countdown selbst regulieren.

Ihren ersten budgetierten Request abschicken

Guided walkthrough1 of 4

Fügen Sie anthropic-beta: task-budgets-2026-03-13 zum Request hinzu. Ohne ihn wird output_config.task_budget ignoriert.

Minimaler Request — einen Codebase-Review-Agenten auf 64k Tokens budgetieren

curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: task-budgets-2026-03-13" \
-H "content-type: application/json" \
-d '{
  "model": "claude-opus-5",
  "max_tokens": 128000,
  "stream": true,
  "messages": [{
    "role": "user",
    "content": "Review the codebase and propose a refactor plan."
  }],
  "output_config": {
    "effort": "high",
    "task_budget": {"type": "tokens", "total": 64000}
  }
}'

Welche Modelle es tatsächlich unterstützen

Modell	Unterstützung
Claude Opus 5	Beta — `task-budgets-2026-03-13` setzen
Claude Fable 5	Beta — `task-budgets-2026-03-13` setzen
Claude Mythos 5	Beta — `task-budgets-2026-03-13` setzen
Claude Sonnet 5	Nicht unterstützt
Claude Opus 4.8	Beta — `task-budgets-2026-03-13` setzen
Claude Opus 4.7	Beta — `task-budgets-2026-03-13` setzen
Claude Opus 4.6	Nicht unterstützt
Claude Sonnet 4.6	Nicht unterstützt
Claude Haiku 4.5	Nicht unterstützt

Task Budgets werden auf Claude Code oder Cowork-Oberflächen nicht unterstützt — nutzen Sie sie direkt über die Messages API auf einem der unterstützten Modelle. Wenn Sie stattdessen eine harte Dollar-Obergrenze für eine Managed-Agents-Session brauchen, ist das ein separates Feature: Managed Agents Session Budgets.

Ein Budget wählen — erst messen, nicht raten

Das richtige Budget hängt davon ab, wie viel Arbeit Ihre Schleife aktuell leistet. Anthropics eigene Empfehlung: erst messen, dann feinjustieren.

Guided walkthrough1 of 3

Summieren Sie für jede Aufgabe in der Stichprobe usage.output_tokens über jeden Request der Schleife, plus die Token-Größe aller Tool-Ergebnisse, die Sie zwischen den Requests angehängt haben. Das ist die Gesamtmenge, die das Modell gesehen hat.

Watch out

Ein für die Aufgabe zu kleines Budget kann ablehnungsähnliches Verhalten auslösen. Wenn Claude ein Budget sieht, das für die Arbeit klar unzureichend ist (etwa 20.000 Tokens für eine mehrstündige agentische Coding-Aufgabe), kann es die Aufgabe ablehnen, sie aggressiv verkleinern oder früh mit einem Teilergebnis stoppen — statt Arbeit zu beginnen, die es nicht abschließen kann.
Wenn Sie nach dem Hinzufügen eines Budgets unerwartete Ablehnungen oder vorzeitige Stopps beobachten, erhöhen Sie das Budget, bevor Sie andere Parameter debuggen. Dimensionieren Sie anhand Ihrer tatsächlichen Verteilung der Aufgabenlängen, nicht anhand eines festen Standardwerts.

Ein Budget über eine Kompaktierung hinweg mitführen

Wenn Ihre Schleife den Kontext zwischen Requests kompaktiert oder umschreibt — etwa frühere Turns zusammenfasst, um die Payload zu verkleinern — hat der Server keine Erinnerung an das vor der Kompaktierung verbrauchte Budget. Übergeben Sie remaining beim nächsten Request, damit der Countdown dort weiterläuft, wo Sie aufgehört haben:

Python — remaining über eine Kompaktierung hinweg mitführen

# Tokens spent before compaction, tracked client-side
tokens_spent_so_far = 45000

output_config = {
  "effort": "high",
  "task_budget": {
      "type": "tokens",
      "total": 128000,
      "remaining": 128000 - tokens_spent_so_far,
  },
}

Bei Schleifen, die bei jedem Turn die vollständige, unkompaktierte Historie erneut senden, lassen Sie remaining weg und überlassen dem Server das Verfolgen des Countdowns. Es manuell zu setzen, wenn es nicht nötig ist, lädt zu Abweichungen ein zwischen dem, was Ihr Client als verbraucht annimmt, und dem, was Claude tatsächlich gesehen hat.

Wechselwirkungen mit anderen Parametern

Wechselwirkung mit	Wie es zusammenspielt
`max_tokens`	Orthogonal. `max_tokens` ist eine harte Obergrenze pro Request; `task_budget` ist eine beratende Obergrenze über die gesamte Schleife. Keiner der beiden Werte muss auf oder unter dem anderen liegen. Kombinieren Sie sie: `task_budget` gibt Claude ein Ziel, an dem es sich orientiert, `max_tokens` verhindert unkontrollierte Generierung in einem einzelnen Request.
Effort	Komplementär. Effort steuert, wie tief Claude pro Schritt nachdenkt (Breite des Denkens). Task Budgets steuern, wie viel Gesamtarbeit die Schleife leisten darf (Breite der Iteration). Beide zusammen abstimmen.
Adaptives Denken	Task Budgets schließen Thinking-Tokens in die Zählung ein, sodass adaptives Denken natürlich herunterskaliert, wenn sich das Budget erschöpft.
Prompt Caching	Falle der Cache-Invalidierung. Die Countdown-Markierung wird pro Turn eingefügt und stimmt zwischen Requests nicht überein. Wenn Ihr Client `task_budget.remaining` bei jedem Folge-Request herunterzählt, invalidiert der geänderte Wert jedes Cache-Präfix, das ihn enthält. Setzen Sie das Budget einmal beim initialen Request und lassen Sie das Modell sich selbst regulieren.

Task Budget im Vergleich zu den anderen Budgets

Ailmanac behandelt bereits drei Features in „Budget“-Form. Sie sind nicht austauschbar.

Feature	Einheit	Geltungsbereich	Durchsetzung	Benötigter Header
Task Budgets (diese Seite)	Tokens	Eine agentische Schleife (ggf. viele Requests)	Beratend — weicher Hinweis an das Modell	`anthropic-beta: task-budgets-2026-03-13`
`max_tokens`	Tokens	Ein Request	Hart — schneidet ab mit `stop_reason: max_tokens`	Keiner
`output_config.effort`	Effort-Stufe	Tiefe pro Schritt	Beratend (vom Modell gesteuert)	Keiner
Managed Agents Session Budgets	US-Cent	Eine ganze Managed-Agents-Session	Hart — Server pausiert bei `budget_reached`	Managed-Agents-Beta-Header

Stellen Sie es sich so vor: max_tokens ist eine Sicherung (brennt an einem festen Punkt durch), das Task Budget ist ein Coach, der Claude den Spielstand zuflüstert (passt das Spiel an), Effort ist der Spielstil, und das Session Budget ist der Buchhalter, der die Gehaltsobergrenze durchsetzt. Nutzen Sie alle vier zusammen, wenn Sie begrenzte, selbstregulierende, dollar-gedeckelte Agenten brauchen.

Testen Sie sich selbst

Check yourself

0/3

Sie setzen task_budget.total auf 100000 für einen Codebase-Audit-Agenten. Während des Laufs wächst die kumulierte Payload Ihres Clients über die Requests hinweg auf 250000 Tokens, weil Sie bei jedem Turn die vollständige Historie erneut senden. Was macht der Countdown, den Claude am Ende sieht?
Sie kompaktieren den Kontext zwischen Requests. Was tun Sie, damit der Countdown nicht zurückgesetzt wird?
Sie setzen task_budget.total auf 20000 für eine lange agentische Coding-Aufgabe, und Claude lehnt plötzlich ab oder stoppt früh mit einem Teilergebnis. Was ist die Lösung?

Vokabular

Task-Budget-Glossar

Drücke Enter oder die Leertaste, um die Karte umzudrehen. Nutze die Pfeiltasten links und rechts, um zwischen den Karten zu wechseln.Begriff angezeigt.

1 / 6

Kernaussagen

Key takeaways

Task Budgets sind ein FÜR DAS MODELL SICHTBARER, BERATENDER Token-Countdown über die gesamte agentische Schleife — Claude reguliert sich daran selbst
Opt-in mit dem Beta-Header task-budgets-2026-03-13 auf einem unterstützten Modell — Opus 5, Fable 5, Mythos 5, Opus 4.8 oder Opus 4.7. Sonnet, Haiku und Claude Code unterstützen es nicht
Der Countdown zählt Tokens, die CLAUDE in diesem Turn SIEHT — nicht die Größe der erneut gesendeten Payload — wiederholte Historie wird also nicht doppelt berechnet
Erst messen (p99 Ihrer Token-Verteilung pro Aufgabe), dann großzügig setzen. Zu klein dimensionierte Budgets verursachen ablehnungsähnliches Verhalten
Nutzen Sie remaining, um das Budget über eine Kompaktierung hinweg mitzuführen; lassen Sie es weg, wenn Sie unkompaktierte Historie erneut senden, und überlassen Sie dem Server das Verfolgen
Kombinieren Sie mit max_tokens als harte Sicherung und mit effort zur Feinabstimmung der Tiefe pro Schritt — vier Hebel, die vier verschiedene Aufgaben erfüllen

Weiter

Effort-Tuning — die fünf Effort-Stufen und wie sie mit Task Budgets zusammenspielen
Managed Agents Session Budgets — harte Dollar-Obergrenzen für eine Session, von der Plattform durchgesetzt
Prompt Caching — wie sich die Falle der Cache-Invalidierung bei sich ändernden Budgetwerten auswirkt
Code-Execution-Tool — die Sandbox-Laufzeit, auf die sich langlaufende Agenten oft stützen
Agenten auf Claude bauen — der vollständige Lebenszyklus der agentischen Schleife, den diese Budgets prägen

Diese Seite teilen

Wie der Budget-Countdown funktioniert​

Ihren ersten budgetierten Request abschicken​

Minimaler Request — einen Codebase-Review-Agenten auf 64k Tokens budgetieren

Welche Modelle es tatsächlich unterstützen​

Ein Budget wählen — erst messen, nicht raten​

Ein Budget über eine Kompaktierung hinweg mitführen​

Python — remaining über eine Kompaktierung hinweg mitführen

Wechselwirkungen mit anderen Parametern​

Task Budget im Vergleich zu den anderen Budgets​

Testen Sie sich selbst​