Task-Budgets

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



Wann du Task-Budgets verwenden solltest

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

• Du möchtest, dass Claude den Token-Verbrauch bei Aufgaben mit langem Horizont selbst reguliert.
• Du eine vorhersehbare Kosten- oder Latenzobergrenze pro Aufgabe durchsetzen möchtest.
• Du möchtest, dass das Modell sauber 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 gib den Beta-Header an:

client = anthropic.Anthropic()

with client.beta.messages.stream(
    model="claude-opus-4-8",
    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 Budgetrest, der aus einer vorherigen Anfrage übernommen wird. Standardmäßig total, wenn nicht angegeben.



Wie der Budget-Countdown funktioniert

Claude sieht eine serverseitig eingefügte Budget-Countdown-Markierung während der gesamten Konversation. Die Markierung zeigt, wie viele Token in der aktuellen agentischen Schleife verbleiben, und aktualisiert sich, während das Modell Denken, Tool-Aufrufe und Ausgabe generiert und während es Tool-Ergebnisse verarbeitet. Claude nutzt dieses Signal, um sein Tempo anzupassen und sauber abzuschließen, während das Budget aufgebraucht 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 Anfrage-Payload enthalten ist. 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 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, dieser Assistant-Turn (Denken plus Tool-Aufruf) umfasst insgesamt 5.000 generierte Token. Der Countdown, den Claude während der Generierung sah, endete nahe 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 erneut gezählt, aber das 2.800-Token-Tool-Ergebnis ist neuer Inhalt, den Claude in diesem Turn sieht, und wird auf das Budget angerechnet. Claude gibt weitere 4.000 Token für Denken und einen zweiten Tool-Aufruf aus (grep -rn "eval(" src/). Der Countdown endet nahe remaining ≈ 88.200.

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

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

Dein Client hat die User-Nachricht aus Turn 1 dreimal und die Assistant-Nachricht aus Turn 1 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 per Prompt-Caching zwischengespeicherte Input in Turn 2 und 3 noch größer.



Ein Budget mit remaining über eine Kompaktierung hinweg übertragen

Wenn deine agentische Schleife den Kontext zwischen Anfragen kompaktiert oder umschreibt (zum Beispiel durch Zusammenfassen früherer Turns), hat der Server keine Erinnerung daran, wie viel Budget vor der Kompaktierung ausgegeben 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:

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 überlasse dem Server die Verfolgung des Countdowns.



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 eine 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.



Miss deine aktuelle Nutzung

Führe eine repräsentative Stichprobe von Aufgaben ohne gesetztes task_budget aus und erfasse die gesamten Token, die Claude pro Aufgabe ausgibt. Für eine agentische Schleife summiere usage.output_tokens plus Denk- und Tool-Ergebnis-Token über jede Anfrage in der Schleife:

def run_task_and_count_tokens(messages: list) -> int:
    """Runs an agentic loop to completion and returns total tokens spent."""
    total_spend = 0
    while True:
        with client.beta.messages.stream(
            model="claude-opus-4-8",
            max_tokens=128000,
            messages=messages,
            tools=tools,
            betas=["task-budgets-2026-03-13"],
        ) as stream:
            response = stream.get_final_message()
        # Zähle, was Claude in diesem Zug generiert hat (Output umfasst Text + Denken + Tool-Aufrufe).
        # Tool-Result-Token zählen ebenfalls gegen das Budget; addiere die Token-Anzahl der
        # tool_result-Blöcke, die du unten anhängst, wenn das clientseitige Tracking mit
        # dem serverseitigen Countdown übereinstimmen soll.
        total_spend += response.usage.output_tokens
        if response.stop_reason == "end_turn":
            return total_spend
        # Hänge den Assistant-Zug und deine Tool-Ergebnisse an, dann setze die Schleife fort.
        messages += [
            {"role": "assistant", "content": response.content},
            {"role": "user", "content": run_tools(response.content)},
        ]

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 kann, und teste dann nach Bedarf nach oben oder unten.

Das minimal akzeptierte task_budget.total beträgt 20.000 Token; 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 hinweg 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 stellt die Tiefe ein, Task-Budgets die Breite.
• Adaptives Denken: Task-Budgets beziehen Denk-Token in die Zählung ein, sodass adaptives Denken natürlich herunterskaliert, wenn das Budget zur Neige geht.
• Prompt-Caching: Die Budget-Countdown-Markierung wird serverseitig pro Turn eingefügt, sodass sie ü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 ersten 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 mit einem unterstützten Modell.