---
title: Task-Budgets
url: https://platform.claude.com/docs/de/build-with-claude/task-budgets
description: Gib Claude ein unverbindliches Token-Budget für die gesamte agentische Schleife, damit sich das Modell bei langen agentischen Aufgaben selbst steuern kann.
featureMetadata:
  status: beta
  betaHeader: task-budgets-2026-03-13
  supportedModels:
    - claude-fable-5-1
    - claude-mythos-5-1
    - claude-fable-5
    - claude-mythos-5
    - claude-opus-5-5
    - claude-opus-5
    - claude-opus-4-8
    - claude-opus-4-7
    - claude-sonnet-5-5
    - claude-haiku-5-5
---

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](https://platform.claude.com/docs/de/build-with-claude/effort): 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:

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
    -N \
    -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-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}
      }
    }'
  ```

  ```bash CLI
  ant beta:messages create --beta task-budgets-2026-03-13 \
    --stream --format jsonl <<'YAML' | jq 'select(.type == "message_delta").usage'
  model: claude-opus-5-5
  max_tokens: 128000
  messages:
    - role: user
      content: Review the codebase and propose a refactor plan.
  output_config:
    effort: high
    task_budget:
      type: tokens
      total: 64000
  YAML
  ```

  ```python Python
  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)
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  const stream = 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"]
  });

  const response = await stream.finalMessage();
  console.log(response.usage);
  ```

  ```csharp C#

  var client = new AnthropicClient();

  var responseUpdates = client.Beta.Messages.CreateStreaming(new MessageCreateParams
  {
      Model = Messages::Model.ClaudeOpus5_5,
      MaxTokens = 128000,
      Messages = [new() { Role = Role.User, Content = "Review the codebase and propose a refactor plan." }],
      OutputConfig = new BetaOutputConfig
      {
          Effort = Effort.High,
          TaskBudget = new BetaTokenTaskBudget { Total = 64000 },
      },
      Betas = ["task-budgets-2026-03-13"],
  });

  var response = await responseUpdates.Aggregate();
  Console.WriteLine(response.Usage);
  ```

  ```go Go
  client := anthropic.NewClient()

  stream := client.Beta.Messages.NewStreaming(context.TODO(), anthropic.BetaMessageNewParams{
  	Model:     anthropic.ModelClaudeOpus5_5,
  	MaxTokens: 128000,
  	Betas:     []anthropic.AnthropicBeta{"task-budgets-2026-03-13"},
  	Messages: []anthropic.BetaMessageParam{{
  		Role: anthropic.BetaMessageParamRoleUser,
  		Content: []anthropic.BetaContentBlockParamUnion{{
  			OfText: &anthropic.BetaTextBlockParam{Text: "Review the codebase and propose a refactor plan."},
  		}},
  	}},
  	OutputConfig: anthropic.BetaOutputConfigParam{
  		Effort: anthropic.BetaOutputConfigEffortHigh,
  		TaskBudget: anthropic.BetaTokenTaskBudgetParam{
  			Total: 64000,
  		},
  	},
  })

  message := anthropic.BetaMessage{}
  for stream.Next() {
  	event := stream.Current()
  	if err := message.Accumulate(event); err != nil {
  		panic(err)
  	}
  }
  if stream.Err() != nil {
  	panic(stream.Err())
  }

  fmt.Printf("Usage: input_tokens=%d, output_tokens=%d\n", message.Usage.InputTokens, message.Usage.OutputTokens)
  ```

  ```java Java
  AnthropicClient client = AnthropicOkHttpClient.fromEnv();

  MessageCreateParams params = MessageCreateParams.builder()
      .model(Model.CLAUDE_OPUS_5_5)
      .maxTokens(128000L)
      .addUserMessage("Review the codebase and propose a refactor plan.")
      .outputConfig(BetaOutputConfig.builder()
          .effort(BetaOutputConfig.Effort.HIGH)
          .taskBudget(BetaTokenTaskBudget.builder().total(64000L).build())
          .build())
      .addBeta("task-budgets-2026-03-13")
      .build();

  BetaMessageAccumulator accumulator = BetaMessageAccumulator.create();
  try (StreamResponse<BetaRawMessageStreamEvent> stream =
          client.beta().messages().createStreaming(params)) {
      stream.stream().forEach(accumulator::accumulate);
  }

  BetaMessage response = accumulator.message();
  IO.println(response.usage());
  ```

  ```php PHP
  use Anthropic\Beta\Messages\BetaRawMessageDeltaEvent;

  $client = new Client();

  $stream = $client->beta->messages->createStream(
      model: 'claude-opus-5-5',
      maxTokens: 128000,
      messages: [
          ['role' => 'user', 'content' => 'Review the codebase and propose a refactor plan.'],
      ],
      outputConfig: [
          'effort' => 'high',
          'taskBudget' => ['type' => 'tokens', 'total' => 64000],
      ],
      betas: ['task-budgets-2026-03-13'],
  );

  // Das letzte message_delta-Event enthält die kumulierte Token-Nutzung für den Request.
  $usage = null;
  foreach ($stream as $event) {
      if ($event instanceof BetaRawMessageDeltaEvent) {
          $usage = $event->usage;
      }
  }

  echo $usage;
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

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

  response = stream.accumulated_message

  puts response.usage
  ```
</CodeGroup>

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.

<Note>
  **Der Countdown ist nur für das Modell sichtbar.** API-Antworten enthalten kein Feld für das verbleibende Budget: Im `usage`-Objekt der Antwort gibt es keine `task_budget`-Informationen, und das SDK bietet keinen Accessor dafür. Um den Verbrauch clientseitig zu verfolgen, summiere die Token-Nutzung über die Anfragen in deiner Schleife, wie unter [Deine aktuelle Nutzung messen](https://platform.claude.com/docs/de/build-with-claude/task-budgets#measure-your-current-usage) gezeigt, oder gib deinen eigenen Wert mit `remaining` weiter, wenn du [ein Budget über eine Compaction hinweg überträgst](https://platform.claude.com/docs/de/build-with-claude/task-budgets#carrying-a-budget-across-compaction-with-remaining).
</Note>

<Warning>
  **Der Countdown spiegelt die Token wider, die Claude in der aktuellen agentischen Schleife verarbeitet hat, nicht die Token, die du zwischen Anfragen erneut sendest.** Wenn dein Client bei jeder Folgeanfrage den vollständigen Gesprächsverlauf sendet, kann deine clientseitige Token-Zählung von dem Budget abweichen, das Claude verfolgt. Wenn du zusätzlich `remaining` verringerst, während du den vollständigen Verlauf erneut sendest, sieht das Modell ein zu niedrig angegebenes Budget, und der Countdown sinkt schneller, als er sollte, wodurch Claude früher abschließt, als das Budget tatsächlich erlaubt. Lege ein großzügiges Budget fest und lass das Modell sich anhand des Countdowns selbst regulieren, anstatt zu versuchen, ihn clientseitig nachzubilden.
</Warning>

### 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:

```json
{ "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:

```json
{
  "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:

```json
{
  "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](https://platform.claude.com/docs/de/build-with-claude/compaction-threshold)“ (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](https://platform.claude.com/docs/de/build-with-claude/task-budgets#what-counts-as-a-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:

```json
{
  "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"`:

```json
{
  "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:

```json
{
  "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:

| Anfrage    | Anfrage-Payload (ca. gesendete Input-Token)              | In dieser Anfrage auf das Budget angerechnete Token           | Budget `remaining` danach |
| ---------- | -------------------------------------------------------- | ------------------------------------------------------------- | ------------------------- |
| 1          | \~20                                                     | 5.000 (Nachdenken + `tool_use`)                               | \~95.000                  |
| 2          | \~7.800 (Nachrichten aus Anfrage 1 + Tool-Ergebnis)      | 6.800 (2.800 Tool-Ergebnis + 4.000 Nachdenken und `tool_use`) | \~88.200                  |
| 3          | \~13.000 (vollständiger Verlauf + zweites Tool-Ergebnis) | 7.200 (1.200 Tool-Ergebnis + 6.000 `text`)                    | \~81.000                  |
| **Gesamt** | **\~20.820 über alle Anfragen gesendet**                 | **19.000 auf das Budget angerechnet**                         | N/A                       |

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:

<CodeGroup exclude="shell">
  ```python Python
  # 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,
      },
  }
  ```

  ```typescript TypeScript
  // Vor der Komprimierung verbrauchte Tokens, clientseitig erfasst
  const tokensSpentSoFar = 45000;

  const outputConfig = {
    effort: "high",
    task_budget: {
      type: "tokens",
      total: 128000,
      remaining: 128000 - tokensSpentSoFar
    }
  };
  ```

  ```csharp C#
  // Vor der Komprimierung verbrauchte Tokens, clientseitig erfasst
  var tokensSpentSoFar = 45000;

  var outputConfig = new BetaOutputConfig
  {
      Effort = Effort.High,
      TaskBudget = new BetaTokenTaskBudget
      {
          Total = 128000,
          Remaining = 128000 - tokensSpentSoFar,
      },
  };
  ```

  ```go Go
  // Vor der Komprimierung verbrauchte Tokens, clientseitig erfasst
  tokensSpentSoFar := int64(45000)

  outputConfig := anthropic.BetaOutputConfigParam{
  	Effort: anthropic.BetaOutputConfigEffortHigh,
  	TaskBudget: anthropic.BetaTokenTaskBudgetParam{
  		Total:     128000,
  		Remaining: anthropic.Int(128000 - tokensSpentSoFar),
  	},
  }
  ```

  ```java Java
  // Vor der Komprimierung verbrauchte Tokens, clientseitig erfasst
  long tokensSpentSoFar = 45000;

  BetaOutputConfig outputConfig = BetaOutputConfig.builder()
      .effort(BetaOutputConfig.Effort.HIGH)
      .taskBudget(BetaTokenTaskBudget.builder()
          .total(128000L)
          .remaining(128000L - tokensSpentSoFar)
          .build())
      .build();
  ```

  ```php PHP
  // Vor der Komprimierung verbrauchte Token, clientseitig erfasst
  $tokensSpentSoFar = 45000;

  $outputConfig = [
      'effort' => 'high',
      'taskBudget' => [
          'type' => 'tokens',
          'total' => 128000,
          'remaining' => 128000 - $tokensSpentSoFar,
      ],
  ];
  ```

  ```ruby Ruby
  # Vor der Komprimierung verbrauchte Token, clientseitig erfasst
  tokens_spent_so_far = 45_000

  output_config = {
    effort: :high,
    task_budget: {
      type: :tokens,
      total: 128_000,
      remaining: 128_000 - tokens_spent_so_far
    }
  }
  ```
</CodeGroup>

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](https://platform.claude.com/docs/de/build-with-claude/task-budgets#measure-your-current-usage). 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](https://platform.claude.com/docs/de/build-with-claude/task-budgets#feature-support) 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.

<Warning>
  **Ein für die Aufgabe zu kleines Budget kann zu verweigerungsähnlichem Verhalten führen.** Wenn Claude ein Budget sieht, das für die angeforderte Arbeit eindeutig unzureichend ist (zum Beispiel ein Budget von 20.000 Token für eine mehrstündige agentische Coding-Aufgabe), kann es ablehnen, die Aufgabe überhaupt zu versuchen, sie aggressiv eingrenzen oder frühzeitig mit einem Teilergebnis aufhören, anstatt Arbeit zu beginnen, die es nicht abschließen kann. Wenn du nach dem Festlegen eines Budgets unerwartete Verweigerungen oder vorzeitige Abbrüche beobachtest, erhöhe das Budget, bevor du andere Parameter debuggst. Bemiss Budgets anhand deiner tatsächlichen Verteilung der Aufgabenlängen statt anhand eines festen Standardwerts; siehe [Ein Budget wählen](https://platform.claude.com/docs/de/build-with-claude/task-budgets#choosing-a-budget).
</Warning>

## 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:

<CodeGroup exclude="shell:cURL">
  ```bash CLI
  ant messages create --transform 'usage.output_tokens' <<'YAML'
  model: claude-opus-5-5
  max_tokens: 4096
  messages:
    - role: user
      content: Review the codebase and propose a refactor plan.
  YAML
  ```

  ```python Python
  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)
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  const response = await 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.
  console.log(response.usage.output_tokens);
  ```

  ```csharp C#

  var client = new AnthropicClient();

  var response = await client.Messages.Create(new MessageCreateParams
  {
      Model = Model.ClaudeOpus5_5,
      MaxTokens = 4096,
      Messages = [new() { Role = Role.User, Content = "Review the codebase and propose a refactor plan." }],
  });

  // Summiere OutputTokens (Text + Thinking + Tool-Aufrufe) über alle Requests in deiner Schleife.
  Console.WriteLine(response.Usage.OutputTokens);
  ```

  ```go Go
  client := anthropic.NewClient()

  response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
  	Model:     anthropic.ModelClaudeOpus5_5,
  	MaxTokens: 4096,
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(anthropic.NewTextBlock("Review the codebase and propose a refactor plan.")),
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }

  // Summiere OutputTokens (Text + Thinking + Tool-Aufrufe) über alle Requests in deiner Schleife.
  fmt.Println(response.Usage.OutputTokens)
  ```

  ```java Java
  AnthropicClient client = AnthropicOkHttpClient.fromEnv();

  MessageCreateParams params = MessageCreateParams.builder()
      .model(Model.CLAUDE_OPUS_5_5)
      .maxTokens(4096L)
      .addUserMessage("Review the codebase and propose a refactor plan.")
      .build();

  Message response = client.messages().create(params);
  // Summiere outputTokens (Text + Thinking + Tool-Aufrufe) über alle Requests in deiner Schleife.
  IO.println(response.usage().outputTokens());
  ```

  ```php PHP
  $client = new Client();

  $response = $client->messages->create(
      model: 'claude-opus-5-5',
      maxTokens: 4096,
      messages: [
          ['role' => 'user', 'content' => 'Review the codebase and propose a refactor plan.'],
      ],
  );

  // Summiere outputTokens (Text + Thinking + Tool-Aufrufe) über alle Requests in deiner Schleife.
  echo $response->usage->outputTokens . "\n";
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  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.
  puts response.usage.output_tokens
  ```
</CodeGroup>

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](https://platform.claude.com/docs/de/build-with-claude/task-budgets#feature-support)). 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](https://platform.claude.com/docs/de/build-with-claude/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](https://platform.claude.com/docs/de/build-with-claude/thinking):** Task-Budgets beziehen Denk-Token in die Zählung ein, sodass „adaptive thinking“ (adaptives Nachdenken) mit abnehmendem Budget zurückgefahren wird.
* **[Prompt-Caching](https://platform.claude.com/docs/de/build-with-claude/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

| Modell            | Unterstützung                                  |
| ----------------- | ---------------------------------------------- |
| Claude Fable 5.1  | Beta (Header `task-budgets-2026-03-13` setzen) |
| Claude Mythos 5.1 | Beta (Header `task-budgets-2026-03-13` setzen) |
| Claude Opus 5.5   | Beta (Header `task-budgets-2026-03-13` setzen) |
| Claude Opus 5     | Beta (Header `task-budgets-2026-03-13` setzen) |
| Claude Fable 5    | Beta (Header `task-budgets-2026-03-13` setzen) |
| Claude Mythos 5   | Beta (Header `task-budgets-2026-03-13` setzen) |
| Claude Sonnet 5.5 | Beta (Header `task-budgets-2026-03-13` setzen) |
| Claude Sonnet 5   | Nicht unterstützt                              |
| Claude Haiku 5.5  | Beta (Header `task-budgets-2026-03-13` setzen) |
| Claude Opus 4.8   | Beta (Header `task-budgets-2026-03-13` setzen) |
| Claude Opus 4.7   | Beta (Header `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 in [Claude Code](https://code.claude.com/docs/de/overview) oder Cowork-Oberflächen nicht unterstützt. Verwende Task-Budgets direkt über die Messages API mit einem [unterstützten Modell](https://platform.claude.com/docs/de/build-with-claude/task-budgets#feature-support).

## Nächste Schritte

<CardGroup>
  <Card title="Effort" icon="gauge" href="https://platform.claude.com/docs/de/build-with-claude/effort">
    Steuere, wie gründlich Claude über jeden Schritt einer agentischen Schleife nachdenkt.
  </Card>

  <Card title="Adaptives Nachdenken" icon="brain" href="https://platform.claude.com/docs/de/build-with-claude/thinking">
    Lass Claude bestimmen, wann und wie viel erweitertes Nachdenken verwendet wird.
  </Card>

  <Card title="Compaction" icon="arrows-clockwise" href="https://platform.claude.com/docs/de/build-with-claude/compaction">
    Verwalte den Kontext in lang laufenden Gesprächen mit serverseitiger Compaction.
  </Card>

  <Card title="Prompt-Caching" icon="database" href="https://platform.claude.com/docs/de/build-with-claude/prompt-caching">
    Reduziere Kosten und Latenz bei wiederholten Prompts durch Caching von Prompt-Präfixen.
  </Card>
</CardGroup>