Task-Budgets

Mit „task budgets“ (Aufgabenbudgets), kurz Task-Budgets, kannst du Claude mitteilen, wie viele Token für eine vollständige „agentic loop“ (agentische Schleife) zur Verfügung stehen, einschließlich Nachdenken, Tool-Aufrufen, Tool-Ergebnissen und Ausgabe. Das Modell sieht einen laufenden Countdown und nutzt ihn, um Arbeit zu priorisieren und geordnet abzuschließen, während das Budget verbraucht wird.

Wann du Task-Budgets verwenden solltest

Task-Budgets funktionieren am besten für agentische Workflows, in denen Claude mehrere Tool-Aufrufe und Entscheidungen trifft, bevor es seine Ausgabe finalisiert und auf die nächste menschliche Antwort wartet. Verwende sie, wenn:

• Du möchtest, dass Claude den Token-Verbrauch bei Aufgaben mit langem Zeithorizont selbst reguliert.
• Du eine vorhersehbare Kosten- oder Latenzobergrenze pro Aufgabe durchsetzen musst.
• Du möchtest, dass das Modell geordnet abschließt (Ergebnisse zusammenfasst, Fortschritt berichtet), wenn es sich dem Budget nähert, anstatt mitten in einer Aktion abzubrechen.

Task-Budgets ergänzen den Effort-Parameter: Effort steuert, wie gründlich Claude über jeden Schritt nachdenkt, während Task-Budgets die Gesamtarbeit begrenzen, die Claude über eine agentische Schleife hinweg leisten kann.

Ein Task-Budget festlegen

Füge task_budget zu output_config hinzu und sende den Beta-Header mit:

client = anthropic.Anthropic()

with client.beta.messages.stream(
    model="claude-opus-5-5",
    max_tokens=128000,
    output_config={
        "effort": "high",
        "task_budget": {"type": "tokens", "total": 64000},
    },
    messages=[
        {"role": "user", "content": "Review the codebase and propose a refactor plan."}
    ],
    betas=["task-budgets-2026-03-13"],
) as stream:
    response = stream.get_final_message()

print(response.usage)

Das task_budget-Objekt hat drei Felder:

• type: immer "tokens".
• total: die Anzahl der Token, die Claude über die agentische Schleife hinweg verbrauchen kann, einschließlich Nachdenken, Tool-Aufrufen, Tool-Ergebnissen und Ausgabe.
• remaining (optional): der aus einer vorherigen Anfrage übernommene Budgetrest. Standardmäßig total, wenn weggelassen.

Wie der Budget-Countdown funktioniert

Claude sieht eine serverseitig eingefügte Budget-Countdown-Markierung im gesamten Gespräch. Die Markierung zeigt, wie viele Token in der aktuellen agentischen Schleife verbleiben, und wird aktualisiert, während das Modell Nachdenken, Tool-Aufrufe und Ausgabe generiert und während es Tool-Ergebnisse verarbeitet. Claude nutzt dieses Signal, um sein Tempo einzuteilen und sauber abzuschließen, während das Budget verbraucht wird.

Was als Turn zählt

Das Budget deckt einen agentischen Turn ab, auch agentische Schleife genannt: alles, was Claude als Reaktion auf eine Benutzernachricht tut, die keine Tool-Ergebnisse enthält. Ein Turn kann sich über mehrere Anfragen erstrecken.

Eine Benutzernachricht ohne Tool-Ergebnisse startet einen neuen Turn mit einem frischen Budget. Derzeit zählt der Countdown den Verlauf früherer Turns weiterhin mit, solange dieser im Kontext verbleibt. Ein häufiger Fall ist eine Folgenachricht, nachdem Claude seinen Turn beendet hat, zum Beispiel weil das Budget aufgebraucht war:

{ "role": "user", "content": "Continue." }

Eine Benutzernachricht, die tool_result-Blöcke enthält, setzt den aktuellen Turn fort, weil dein Client Tool-Aufrufe auflöst, die Teil dieses Turns sind:

{
  "role": "user",
  "content": [
    { "type": "tool_result", "tool_use_id": "toolu_01", "content": "<npm audit output>" }
  ]
}

Das gilt auch dann, wenn die Nachricht neben den Tool-Ergebnissen neue Inhalte hinzufügt:

{
  "role": "user",
  "content": [
    { "type": "tool_result", "tool_use_id": "toolu_01", "content": "<npm audit output>" },
    { "type": "text", "text": "Also check the Dockerfile." }
  ]
}

Eine serverseitige „compaction“ (Komprimierung) während eines Turns setzt das Budget nicht zurück: Token, die der Turn vor der Komprimierung verbraucht hat, werden weiterhin darauf angerechnet. Token aus der Zeit vor Beginn des Turns zählen nicht, selbst wenn eine Komprimierung zu Beginn eines Turns sie zusammenfasst. Derzeit gilt dieser Ausschluss nur für das Budget, das über eine serverseitige Komprimierung hinweg übernommen wird; der Verlauf früherer Turns zählt weiterhin, solange er im Kontext verbleibt.

Ausführliches Beispiel: Budgetzählung über Anfragen hinweg

Das Task-Budget zählt, was Claude sieht (Nachdenken, Tool-Aufrufe und -Ergebnisse sowie Text), nicht, was in deinem Anfrage-Payload steht. In einer agentischen Schleife sendet dein Client bei jeder Anfrage das vollständige Gespräch erneut, sodass der Payload immer weiter wächst, aber das Budget verringert sich nur um das, was neu ist: die Token, die Claude generiert, und die Inhalte, die es zuvor noch nicht gesehen hat. Das folgende Beispiel ist ein agentischer Turn, der aus drei Anfragen besteht: Die erste enthält die Benutzernachricht, und die nächsten beiden senden jeweils den Verlauf mit einem angehängten Tool-Ergebnis erneut.

Betrachte eine Schleife mit task_budget: {type: "tokens", total: 100000} und einem einzelnen bash-Tool.

Anfrage 1. Du sendest die erste Anfrage:

{
  "messages": [
    { "role": "user", "content": "Audit this repo for security issues and report findings." }
  ]
}

Claude denkt nach, gibt dann einen Tool-Aufruf aus und stoppt mit stop_reason: "tool_use":

{
  "role": "assistant",
  "content": [
    {
      "type": "thinking",
      "thinking": "I'll start by listing dependencies to look for known-vulnerable packages..."
    },
    {
      "type": "tool_use",
      "id": "toolu_01",
      "name": "bash",
      "input": { "command": "cat package.json && npm audit --json" }
    }
  ]
}

Angenommen, diese Assistentennachricht (Nachdenken plus Tool-Aufruf) umfasst insgesamt 5.000 generierte Token. Der Countdown, den Claude während der Generierung gesehen hat, endete bei etwa remaining ≈ 95.000.

Anfrage 2. Dein Client führt das Tool aus und sendet dann den vollständigen Verlauf mit dem angehängten Tool-Ergebnis erneut:

{
  "messages": [
    { "role": "user", "content": "Audit this repo for security issues and report findings." },
    {
      "role": "assistant",
      "content": [
        { "type": "thinking", "thinking": "I'll start by listing dependencies..." },
        {
          "type": "tool_use",
          "id": "toolu_01",
          "name": "bash",
          "input": { "command": "cat package.json && npm audit --json" }
        }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "tool_result",
          "tool_use_id": "toolu_01",
          "content": "<2,800 tokens of npm audit output>"
        }
      ]
    }
  ]
}

Die erneut gesendeten Nachrichten aus Anfrage 1 werden nicht noch einmal gezählt, aber das Tool-Ergebnis mit 2.800 Token ist neuer Inhalt und wird auf das Budget angerechnet. Claude verbraucht weitere 4.000 Token für Nachdenken und einen zweiten Tool-Aufruf (grep -rn "eval(" src/). Der Countdown endet bei etwa remaining ≈ 88.200.

Anfrage 3. Der vollständige Verlauf wird erneut gesendet, mit dem zweiten angehängten Tool-Ergebnis (1.200 Token grep-Ausgabe). Claude schreibt einen abschließenden Ergebnisbericht mit 6.000 Token und stoppt mit stop_reason: "end_turn". remaining ≈ 81.000.

Stellt man die drei Anfragen nebeneinander, wird der Unterschied zwischen Payload-Größe und Budgetverbrauch deutlich:

Dein Client hat die ursprüngliche Benutzernachricht dreimal und die erste Assistentennachricht zweimal gesendet, aber jede wurde nur einmal gezählt. Das Budget hat 19.000 von 100.000 Token verbraucht, obwohl der kumulierte Payload, den dein Client übertragen hat, größer war und der per „prompt caching“ (Prompt-Caching) zwischengespeicherte Input in den Anfragen 2 und 3 noch größer.

Ein Budget mit remaining über eine Compaction hinweg übertragen

Wenn dein eigener Code den Nachrichtenverlauf zwischen Anfragen komprimiert oder umschreibt (zum Beispiel, indem er frühere Nachrichten zusammenfasst), weiß der Server nicht, wie viel Budget vor der Komprimierung verbraucht wurde. Gib bei der nächsten Anfrage remaining an, damit der Countdown dort weitermacht, wo du aufgehört hast, anstatt auf total zurückgesetzt zu werden:

# Vor der Komprimierung verbrauchte Tokens, clientseitig erfasst
tokens_spent_so_far = 45000

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

In diesem Beispiel entsprechen die vor der Komprimierung verbrauchten Token der Nutzung aller Nachrichten, die du bisher aus dem Verlauf entfernt hast, gemessen wie in Miss deine aktuelle Nutzung. Lass alles weg, was noch in den von dir gesendeten Nachrichten enthalten ist, einschließlich einer von dir hinzugefügten Zusammenfassung, da der Server diese Token selbst zählt. Aktualisiere diesen Wert nur, wenn du den Verlauf auf diese Weise ersetzt; verringere ihn nicht pro Anfrage. Gib das resultierende remaining bei jeder Anfrage an, nicht nur bei derjenigen, die komprimiert.

Bei Schleifen, die bei jeder Anfrage den vollständigen, nicht komprimierten Verlauf erneut senden, lass remaining weg und überlass dem Server die Verfolgung des Countdowns.

Das Budget mitten in der Konversation ändern

task_budget ist eine Einstellung auf Anfrageebene. Um das Budget mitten in einer Aufgabe zu ändern, zum Beispiel um es zu erweitern, wenn der Nutzer die Anfrage ausweitet, setze bei der nächsten Anfrage ein neues task_budget in output_config. Behalte die Auswirkung auf das Caching im Hinterkopf: Der Budgetwert ist Teil des gerenderten Prompts, sodass ein geänderter Wert nicht mit Cache-Einträgen übereinstimmt, die unter dem alten Wert erstellt wurden (siehe Funktionsunterstützung unten).

Task-Budgets sind empfehlend, nicht erzwungen

Task-Budgets sind ein weicher Hinweis, keine harte Obergrenze. Claude kann das Budget gelegentlich überschreiten, wenn es sich mitten in einer Aktion befindet, deren Unterbrechung störender wäre als ihr Abschluss. Das erzwungene Limit für die gesamten Output-Token ist weiterhin max_tokens, das die Antwort bei Erreichen mit stop_reason: "max_tokens" abschneidet.

Für eine harte Obergrenze bei Kosten oder Latenz kombiniere Task-Budgets mit einem sinnvollen max_tokens-Wert:

• Verwende task_budget, um Claude ein Ziel zu geben, an dem es sein Tempo ausrichten kann.
• Verwende max_tokens als absolute Obergrenze, die unkontrollierte Generierung verhindert.

Da task_budget die gesamte agentische Schleife umfasst (potenziell viele Anfragen), während max_tokens jede einzelne Anfrage begrenzt, sind die beiden Werte unabhängig voneinander; keiner muss kleiner oder gleich dem anderen sein.

Ein Budget wählen

Das richtige Budget hängt davon ab, wie viel Arbeit deine agentische Schleife derzeit leistet. Anstatt zu raten, miss zuerst deine bestehende Token-Nutzung und passe dann von dort aus an.

Deine aktuelle Nutzung messen

Führe eine repräsentative Stichprobe von Aufgaben ohne gesetztes task_budget aus und erfasse die gesamten Token, die Claude pro Aufgabe verbraucht. Summiere für eine agentische Schleife usage.output_tokens über jede Anfrage in der Schleife, plus die Token der Tool-Ergebnisse, die du zwischen den Anfragen anhängst:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=[
        {"role": "user", "content": "Review the codebase and propose a refactor plan."}
    ],
)

# Summiere output_tokens (Text + Thinking + Tool-Aufrufe) über alle Requests in deiner Schleife.
print(response.usage.output_tokens)

Führe dies über eine repräsentative Menge von Aufgaben aus und erfasse die Verteilung. Beginne mit dem p99 deines Token-Verbrauchs pro Aufgabe, um zu verstehen, wie die Bereitstellung eines Task-Budgets das Verhalten des Modells verändern könnte, und teste dann nach Bedarf nach oben oder unten.

Der minimal akzeptierte Wert für task_budget.total beträgt 20.000 Token bei jedem Modell, das Task-Budgets unterstützt (siehe Funktionsunterstützung). Kleinere Werte führen zu einem 400-Fehler.

Zusammenspiel mit anderen Parametern

• max_tokens: Unabhängig von Task-Budgets. max_tokens ist eine harte Obergrenze pro Anfrage für generierte Token, während task_budget eine unverbindliche Obergrenze über die gesamte agentische Schleife ist (die sich potenziell über viele Anfragen erstreckt). Setze bei Effort xhigh oder max max_tokens auf mindestens 64k, um Claude bei jeder Anfrage Raum zum Denken und Handeln zu geben.
• Effort: Effort steuert, wie tief Claude pro Schritt nachdenkt. Task-Budgets steuern, wie viel Gesamtarbeit Claude über eine agentische Schleife hinweg leistet. Die beiden ergänzen sich: Effort regelt die Tiefe, Task-Budgets regeln die Breite.
• Adaptives Nachdenken: Task-Budgets beziehen Denk-Token in die Zählung ein, sodass „adaptive thinking“ (adaptives Nachdenken) mit abnehmendem Budget zurückgefahren wird.
• Prompt-Caching: Die Budget-Countdown-Markierung wird bei jeder Anfrage serverseitig eingefügt und stimmt daher zwischen Anfragen nicht überein. Wenn dein Client task_budget.remaining bei jeder Folgeanfrage verringert, macht der geänderte Wert jedes Cache-Präfix ungültig, das ihn enthält. Um das Caching zu erhalten, lege das Budget einmal bei der ersten Anfrage fest und lass das Modell sich anhand des serverseitigen Countdowns selbst regulieren, anstatt das Budget clientseitig zu verändern.

Funktionsunterstützung

Task-Budgets werden in Claude Code oder Cowork-Oberflächen nicht unterstützt. Verwende Task-Budgets direkt über die Messages API mit einem unterstützten Modell.

Nächste Schritte

Compatibility