Task-Budgets

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



Wann du Task-Budgets verwenden solltest

Task-Budgets eignen sich am besten für agentische Workflows, bei 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 langfristigen Aufgaben selbst reguliert.
• Du eine vorhersehbare Kosten- oder Latenzobergrenze pro Aufgabe durchsetzen möchtest.
• Du möchtest, dass das Modell elegant abschließt (Ergebnisse zusammenfasst, Fortschritt meldet), 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 setze den Beta-Header:

client = anthropic.Anthropic()

with client.beta.messages.stream(
    model="claude-opus-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 ausgeben kann, einschließlich Denken, Tool-Aufrufen, Tool-Ergebnissen und Ausgabe.
• remaining (optional): der Budget-Rest, der von einer vorherigen Anfrage übernommen wurde. Standardmäßig total, wenn nicht angegeben.



Wie der Budget-Countdown funktioniert

Claude sieht einen Budget-Countdown-Marker, der serverseitig während der gesamten Konversation eingefügt wird. Der Marker zeigt an, wie viele Token in der aktuellen agentischen Schleife verbleiben, und wird aktualisiert, während das Modell Denken, Tool-Aufrufe und Ausgabe generiert und Tool-Ergebnisse verarbeitet. Claude nutzt dieses Signal, um sein Tempo zu steuern und elegant abzuschließen, während das Budget verbraucht wird.



Durchgerechnetes Beispiel: Budget-Zählung über Turns hinweg

Das Task-Budget zählt, was Claude sieht (Denken, Tool-Aufrufe und -Ergebnisse sowie Text), nicht was in deinem Request-Payload steht. In einer agentischen Schleife sendet dein Client bei jeder Anfrage die vollständige Konversation erneut, sodass der Payload von Turn zu Turn wächst, aber das Budget wird nur um die Token dekrementiert, die Claude in diesem Turn sieht.

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

Turn 1. Du sendest die initiale 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, dieser Assistant-Turn (Denken plus Tool-Aufruf) umfasst insgesamt 5.000 generierte Token. Der Countdown, den Claude während der Generierung gesehen hat, endete bei remaining ≈ 95.000.

Turn 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 User- und Assistant-Nachrichten aus Turn 1 werden nicht noch einmal gezählt, aber das 2.800-Token-Tool-Ergebnis ist neuer Inhalt, den Claude in diesem Turn sieht, und zählt gegen das Budget. Claude verbraucht weitere 4.000 Token für Denken und einen zweiten Tool-Aufruf (grep -rn "eval(" src/). Der Countdown endet bei remaining ≈ 88.200.

Turn 3. Vollständiger Verlauf erneut gesendet mit dem zweiten Tool-Ergebnis (1.200 Token grep-Ausgabe) angehängt. Claude schreibt einen 6.000-Token-Abschlussbericht und stoppt mit stop_reason: "end_turn". remaining ≈ 81.000.

Wenn man die drei Turns nebeneinander stellt, wird der Unterschied zwischen Payload-Größe und Budget-Verbrauch deutlich:

Dein Client hat die Turn-1-User-Nachricht dreimal und die Turn-1-Assistant-Nachricht zweimal gesendet, aber jede wurde nur einmal gezählt. Das Budget hat 19.000 von 100.000 Token verbraucht, obwohl der kumulative Payload, den dein Client übertragen hat, größer war und der prompt-gecachte Input in Turn 2 und 3 noch größer war.



Ein Budget über Kompaktierung hinweg mit remaining weiterführen

Wenn deine agentische Schleife zwischen Anfragen Kontext kompaktiert oder umschreibt (zum Beispiel durch Zusammenfassen früherer Turns), hat der Server keine Erinnerung daran, wie viel Budget vor der Kompaktierung verbraucht wurde. Übergib remaining bei der nächsten Anfrage, damit der Countdown dort fortgesetzt wird, wo du aufgehört hast, anstatt auf total zurückgesetzt zu werden:

# Vor der Kompaktierung verbrauchte Token, clientseitig erfasst
tokens_spent_so_far = 45000

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

Für Schleifen, die bei jedem Turn den vollständigen, nicht kompaktierten Verlauf erneut senden, lass remaining weg und lass den Server den Countdown verfolgen.



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 ein neues task_budget in output_config bei der nächsten Anfrage. Beachte die Caching-Konsequenz: Der Budget-Wert fließt in den gerenderten Prompt ein, sodass ein geänderter Wert nicht mit Cache-Einträgen übereinstimmt, die unter dem alten Wert erstellt wurden (siehe Feature-Unterstützung unten).



Task-Budgets sind beratend, 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 mit stop_reason: "max_tokens" abschneidet, wenn es erreicht wird.

Für eine harte Obergrenze bei Kosten oder Latenz kombiniere Task-Budgets mit einem angemessenen 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 gleich oder kleiner als der andere 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 stimme dann von dort aus ab.



Miss deine aktuelle Nutzung

Führe eine repräsentative Stichprobe von Aufgaben ohne gesetztes task_budget aus und zeichne die Gesamtzahl der Token auf, die Claude pro Aufgabe verbraucht. Für eine agentische Schleife summiere 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",
    max_tokens=4096,
    messages=[
        {"role": "user", "content": "Review the codebase and propose a refactor plan."}
    ],
)

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

Führe dies über eine repräsentative Menge von Aufgaben aus und zeichne die Verteilung auf. 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.

Das minimal akzeptierte task_budget.total ist modellspezifisch; bei jedem Modell, das derzeit Task-Budgets unterstützt (siehe Feature-Unterstützung), beträgt es 20.000 Token, und Werte unterhalb des Minimums geben einen 400-Fehler zurück.



Interaktion mit anderen Parametern

• max_tokens: Orthogonal zu Task-Budgets. max_tokens ist eine harte Obergrenze pro Anfrage für generierte Token, während task_budget eine beratende Obergrenze über die gesamte agentische Schleife ist (die potenziell viele Anfragen umfasst). Bei xhigh- oder max-Effort setze 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 stimmt die Tiefe ab, Task-Budgets stimmen die Breite ab.
• Adaptives Denken: Task-Budgets schließen Denk-Token in die Zählung ein, sodass adaptives Denken natürlich herunterskaliert, wenn das Budget aufgebraucht wird.
• Prompt-Caching: Der Budget-Countdown-Marker wird serverseitig pro Turn eingefügt, sodass er über Anfragen hinweg nicht übereinstimmt. Wenn dein Client task_budget.remaining bei jeder Folgeanfrage dekrementiert, invalidiert der geänderte Wert jedes Cache-Präfix, das ihn enthält. Um das Caching zu erhalten, setze das Budget einmal bei der initialen Anfrage und lass das Modell sich anhand des serverseitigen Countdowns selbst regulieren, anstatt das Budget clientseitig zu verändern.



Feature-Unterstützung

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



Nächste Schritte