Task-Budgets

Task-Budgets ermöglichen es Ihnen, Claude mitzuteilen, wie viele Token er für eine vollständige agentengesteuerte Schleife hat, einschließlich Thinking, Tool-Aufrufe, Tool-Ergebnisse und Ausgabe. Das Modell sieht einen laufenden Countdown und nutzt ihn, um die Arbeit zu priorisieren und elegant zu beenden, während das Budget aufgebraucht wird.

Wann Task-Budgets verwendet werden

Task-Budgets funktionieren am besten für agentengesteuerte Workflows, bei denen Claude mehrere Tool-Aufrufe und Entscheidungen trifft, bevor er seine Ausgabe abschließt, um auf die nächste menschliche Antwort zu warten. Verwenden Sie sie, wenn:

• Sie möchten, dass Claude die Token-Ausgaben bei langfristigen Aufgaben selbst reguliert.
• Sie haben eine vorhersehbare Kosten- oder Latenzgrenze pro Aufgabe, die Sie durchsetzen möchten.
• Sie möchten, dass das Modell elegant beendet wird (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 kontrolliert, wie gründlich Claude über jeden Schritt nachdenkt, während Task-Budgets die Gesamtarbeit begrenzen, die Claude über eine agentengesteuerte Schleife hinweg leisten kann.

Festlegen eines Task-Budgets

Fügen Sie task_budget zu output_config hinzu und beziehen Sie den Beta-Header ein:

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-7",
    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"],
)

Das task_budget-Objekt hat drei Felder:

• type: immer "tokens".
• total: die Anzahl der Token, die Claude über die agentengesteuerte Schleife hinweg ausgeben kann, einschließlich Thinking, Tool-Aufrufe, Tool-Ergebnisse und Ausgabe.
• remaining (optional): der Budgetrest, der von einer vorherigen Anfrage übertragen wird. Standardmäßig total, wenn weggelassen.

Wie der Budget-Countdown funktioniert

Claude sieht einen Budget-Countdown-Marker, der serverseitig während des gesamten Gesprächs eingefügt wird. Der Marker zeigt, wie viele Token in der aktuellen agentischen Schleife verbleiben, und wird aktualisiert, wenn das Modell Thinking, Tool-Aufrufe und Ausgabe generiert und Tool-Ergebnisse verarbeitet. Claude nutzt dieses Signal, um sich selbst zu regulieren und elegant zu beenden, während das Budget aufgebraucht wird.

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

Das Task-Budget zählt, was Claude sieht (Thinking, Tool-Aufrufe und Ergebnisse sowie Text), nicht was in Ihrer Request-Payload ist. In einer agentischen Schleife sendet Ihr Client die vollständige Gesprächshistorie bei jeder Anfrage erneut, sodass die Payload Turn für Turn wächst, aber das Budget nur um die Token dekrementiert wird, die Claude diesen Turn sieht.

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

Turn 1. Sie senden 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 (Thinking plus Tool-Aufruf) summiert sich auf 5.000 generierte Token. Der Countdown, den Claude während der Generierung sah, endete in der Nähe von remaining ≈ 95.000.

Turn 2. Ihr Client führt das Tool aus und sendet dann die vollständige Historie 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 Turn-1-Benutzer- und Assistant-Nachrichten werden nicht erneut gezählt, aber das 2.800-Token-Tool-Ergebnis ist neuer Inhalt, den Claude diesen Turn sieht und gegen das Budget zählt. Claude gibt weitere 4.000 Token für Thinking und einen zweiten Tool-Aufruf aus (grep -rn "eval(" src/). Der Countdown endet in der Nähe von remaining ≈ 88.200.

Turn 3. Vollständige Historie erneut 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.

Die drei Turns nebeneinander zu stellen macht den Unterschied zwischen Payload-Größe und Budget-Ausgaben explizit:

Ihr Client hat die Turn-1-Benutzernachricht dreimal und die Turn-1-Assistant-Nachricht zweimal gesendet, aber jede wurde einmal gezählt. Das Budget gab 19.000 von 100.000 Token aus, obwohl die kumulative Payload, die Ihr Client übertragen hat, größer war und die Prompt-gecachte Eingabe auf Turns 2 und 3 noch größer war.

Budget über Komprimierung mit remaining übertragen

Wenn Ihre agentengesteuerte Schleife den Kontext zwischen Anfragen komprimiert oder umschreibt (z. B. durch Zusammenfassung früherer Turns), hat der Server keine Erinnerung daran, wie viel Budget vor der Komprimierung ausgegeben wurde. Übergeben Sie remaining bei der nächsten Anfrage, damit der Countdown von dort aus fortgesetzt wird, wo Sie aufgehört haben, anstatt auf total zurückzusetzen:

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

Für Schleifen, die die vollständige unkomprimierte Historie bei jedem Turn erneut senden, lassen Sie remaining weg und lassen Sie den Server den Countdown verfolgen.

Task-Budgets sind Hinweise, nicht erzwungen

Task-Budgets sind ein sanfter Hinweis, keine harte Obergrenze. Claude kann das Budget gelegentlich überschreiten, wenn er mitten in einer Aktion ist, die unterbrochen zu werden würde, als sie zu beenden. Die erzwungene Obergrenze für die Gesamtausgabe-Token ist immer noch max_tokens, die die Antwort mit stop_reason: "max_tokens" abschneidet, wenn erreicht.

Für eine harte Obergrenze für Kosten oder Latenz kombinieren Sie Task-Budgets mit einem angemessenen max_tokens-Wert:

• Verwenden Sie task_budget, um Claude ein Ziel zum Regulieren zu geben.
• Verwenden Sie max_tokens als absolute Obergrenze, die unkontrollierte Generierung verhindert.

Da task_budget die vollständige agentengesteuerte Schleife umfasst (möglicherweise viele Anfragen), während max_tokens jede einzelne Anfrage begrenzt, sind die beiden Werte unabhängig; einer muss nicht auf oder unter dem anderen liegen.

Budget auswählen

Das richtige Budget hängt davon ab, wie viel Arbeit Ihre agentengesteuerte Schleife derzeit leistet. Anstatt zu raten, messen Sie zunächst Ihre vorhandene Token-Nutzung und stimmen Sie dann ab.

Messen Sie Ihre aktuelle Nutzung

Führen Sie eine repräsentative Stichprobe von Aufgaben ohne gesetztes task_budget aus und notieren Sie die Gesamttoken, die Claude pro Aufgabe ausgibt. Für eine agentengesteuerte Schleife summieren Sie usage.output_tokens plus Thinking- 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:
        response = client.beta.messages.create(
            model="claude-opus-4-7",
            max_tokens=128000,
            messages=messages,
            tools=tools,
            betas=["task-budgets-2026-03-13"],
        )
        # Count what Claude generated this turn (output covers text + thinking + tool calls).
        # Tool-result tokens also count against the budget; add the token count of the
        # tool_result blocks you append below if you want client-side tracking to match
        # the server-side countdown.
        total_spend += response.usage.output_tokens
        if response.stop_reason == "end_turn":
            return total_spend
        # Append the assistant turn and your tool results, then continue the loop.
        messages += [
            {"role": "assistant", "content": response.content},
            {"role": "user", "content": run_tools(response.content)},
        ]

Führen Sie dies über eine repräsentative Menge von Aufgaben aus und notieren Sie die Verteilung. Beginnen Sie mit dem p99 Ihrer Token-Ausgaben pro Aufgabe, um zu verstehen, wie die Bereitstellung eines Task-Budgets für das Modell das Verhalten des Modells ändern kann, und testen Sie dann nach oben oder unten, wie nötig.

Das minimal akzeptierte task_budget.total ist 20.000 Token; Werte unter dem Minimum geben einen 400-Fehler zurück.

Interaktion mit anderen Parametern

• max_tokens: Orthogonal zu Task-Budgets. max_tokens ist eine harte Pro-Anfrage-Obergrenze für generierte Token, während task_budget eine Hinweis-Obergrenze über die vollständige agentengesteuerte Schleife ist (möglicherweise über viele Anfragen verteilt). Bei xhigh oder max Effort setzen Sie max_tokens auf mindestens 64k, um Claude Raum zum Denken und Handeln bei jeder Anfrage zu geben.
• Effort: Effort kontrolliert, wie tief Claude pro Schritt nachdenkt. Task-Budgets kontrollieren, wie viel Gesamtarbeit Claude über eine agentengesteuerte Schleife hinweg leistet. Die beiden sind komplementär: Effort stimmt die Tiefe ab, Task-Budgets stimmen die Breite ab.
• Adaptives Thinking: Task-Budgets beziehen Thinking-Token in die Zählung ein, daher skaliert adaptives Thinking natürlich herunter, wenn das Budget aufgebraucht wird.
• Prompt-Caching: Der Budget-Countdown-Marker wird serverseitig pro Turn eingefügt, daher stimmt er nicht über Anfragen hinweg überein. Wenn Ihr Client task_budget.remaining bei jeder Folgeanfrage dekrementiert, invalidiert der geänderte Wert jedes Cache-Präfix, das ihn enthält. Um Caching zu bewahren, setzen Sie das Budget einmal bei der ersten Anfrage und lassen Sie das Modell sich gegen den serverseitigen Countdown selbst regulieren, anstatt das Budget clientseitig zu mutieren.

Feature-Unterstützung

Task-Budgets werden auf Claude Code oder Cowork-Oberflächen beim Start nicht unterstützt. Verwenden Sie Task-Budgets direkt über die Messages API auf Claude Opus 4.7.