---
title: Presupuestos de tarea
url: https://platform.claude.com/docs/es/build-with-claude/task-budgets
description: Dale a Claude un presupuesto de tokens orientativo para todo el bucle agéntico y ayuda al modelo a autorregularse en tareas agénticas largas.
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
---

Los "task budgets" (presupuestos de tarea) te permiten indicarle a Claude cuántos tokens tiene para un bucle agéntico completo, incluyendo pensamiento, llamadas a herramientas, resultados de herramientas y salida. El modelo ve una cuenta regresiva continua y la usa para priorizar el trabajo y terminar de forma ordenada a medida que se consume el presupuesto.

## Cuándo usar presupuestos de tarea

Los presupuestos de tarea funcionan mejor en flujos de trabajo agénticos donde Claude realiza múltiples llamadas a herramientas y toma decisiones antes de finalizar su salida para esperar la siguiente respuesta humana. Úsalos cuando:

* Quieres que Claude autorregule el gasto de tokens en tareas de largo horizonte.
* Tienes un techo predecible de costo o latencia por tarea que debes hacer cumplir.
* Quieres que el modelo termine de forma ordenada (resumir hallazgos, informar el progreso) a medida que se acerca al presupuesto, en lugar de cortarse a mitad de una acción.

Los presupuestos de tarea complementan el [parámetro effort](https://platform.claude.com/docs/es/build-with-claude/effort): effort controla qué tan exhaustivamente razona Claude sobre cada paso, mientras que los presupuestos de tarea limitan el trabajo total que Claude puede hacer a lo largo de un bucle agéntico.

## Establecer un presupuesto de tarea

Agrega `task_budget` a `output_config` e incluye el encabezado beta:

<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'],
  );

  // El evento message_delta final contiene el uso acumulado de tokens de la solicitud.
  $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>

El objeto `task_budget` tiene tres campos:

* `type`: siempre `"tokens"`.
* `total`: el número de tokens que Claude puede gastar a lo largo del bucle agéntico, incluyendo pensamiento, llamadas a herramientas, resultados de herramientas y salida.
* `remaining` (opcional): el remanente del presupuesto arrastrado desde una solicitud anterior. Por defecto es `total` cuando se omite.

## Cómo funciona la cuenta regresiva del presupuesto

Claude ve un marcador de cuenta regresiva del presupuesto que se inyecta del lado del servidor a lo largo de la conversación. El marcador muestra cuántos tokens quedan en el bucle agéntico actual y se actualiza a medida que el modelo genera pensamiento, llamadas a herramientas y salida, y a medida que procesa los resultados de herramientas. Claude usa esta señal para regular su ritmo y terminar de forma ordenada a medida que se consume el presupuesto.

<Note>
  **La cuenta regresiva solo es visible para el modelo.** Las respuestas de la API no incluyen un campo de presupuesto restante: no hay información de `task_budget` en el objeto `usage` de la respuesta, y el SDK no tiene un método de acceso para ello. Para hacer un seguimiento del gasto del lado del cliente, suma el uso de tokens de las solicitudes de tu bucle como se muestra en [Mide tu uso actual](https://platform.claude.com/docs/es/build-with-claude/task-budgets#measure-your-current-usage), o pasa tu propia cifra hacia adelante con `remaining` al [arrastrar un presupuesto a través de la compactación](https://platform.claude.com/docs/es/build-with-claude/task-budgets#carrying-a-budget-across-compaction-with-remaining).
</Note>

<Warning>
  **La cuenta regresiva refleja los tokens que Claude ha procesado en el bucle agéntico actual, no los tokens que reenvías entre solicitudes.** Si tu cliente envía el historial completo de la conversación en cada solicitud de seguimiento, tu recuento de tokens del lado del cliente podría diferir del presupuesto que Claude está rastreando. Si además reduces `remaining` mientras reenvías el historial completo, el modelo ve un presupuesto subestimado y la cuenta regresiva baja más rápido de lo que debería, lo que hace que Claude concluya antes de lo que el presupuesto realmente permite. Establece un presupuesto generoso y deja que el modelo se autorregule según la cuenta regresiva en lugar de intentar replicarla del lado del cliente.
</Warning>

### Qué cuenta como un turno

El presupuesto cubre un turno agéntico, también llamado bucle agéntico: todo lo que Claude hace en respuesta a un mensaje de usuario que no contiene resultados de herramientas. Un turno puede abarcar varias solicitudes.

Un mensaje de usuario que no contiene resultados de herramientas inicia un nuevo turno con un presupuesto nuevo. Actualmente, la cuenta regresiva sigue contando el historial de turnos anteriores mientras permanezca en el contexto. Un caso común es un seguimiento después de que Claude ha terminado su turno, por ejemplo porque se agotó el presupuesto:

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

Un mensaje de usuario que contiene bloques `tool_result` continúa el turno actual, porque tu cliente está resolviendo llamadas a herramientas que forman parte de ese turno:

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

Esto se mantiene incluso cuando el mensaje agrega contenido nuevo junto con los resultados de herramientas:

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

La [compactación](https://platform.claude.com/docs/es/build-with-claude/compaction-threshold) del lado del servidor durante un turno no restablece el presupuesto: los tokens que el turno consumió antes de la compactación siguen contando en su contra. Los tokens de antes de que comenzara el turno no cuentan, incluso cuando una compactación al inicio de un turno los resume. Actualmente, esa exclusión se aplica solo al presupuesto arrastrado a través de una compactación del lado del servidor; el historial de turnos anteriores sigue contando mientras permanezca en el contexto.

### Ejemplo práctico: conteo del presupuesto a lo largo de las solicitudes

El presupuesto de tareas cuenta lo que Claude **ve** (pensamiento, llamadas y resultados de herramientas, y texto), no lo que hay en el contenido de tu solicitud. En un bucle agéntico, tu cliente reenvía la conversación completa en cada solicitud, por lo que el contenido sigue creciendo, pero el presupuesto solo disminuye según lo que es nuevo: los tokens que Claude genera y el contenido que no ha visto antes. El siguiente ejemplo es un [turno agéntico](https://platform.claude.com/docs/es/build-with-claude/task-budgets#what-counts-as-a-turn) compuesto por tres solicitudes: la primera contiene el mensaje del usuario, y las dos siguientes reenvían cada una el historial con un resultado de herramienta añadido.

Considera un bucle con `task_budget: {type: "tokens", total: 100000}` y una única herramienta `bash`.

**Solicitud 1.** Envías la solicitud inicial:

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

Claude piensa, luego emite una llamada a herramienta y se detiene con `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" }
    }
  ]
}
```

Supón que este mensaje del asistente (pensamiento más la llamada a herramienta) suma 5,000 tokens generados. La cuenta regresiva que Claude vio durante la generación terminó cerca de `remaining` ≈ 95,000.

**Solicitud 2.** Tu cliente ejecuta la herramienta y luego reenvía el historial completo con el resultado de la herramienta añadido:

```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>"
        }
      ]
    }
  ]
}
```

Los mensajes reenviados de la solicitud 1 no se vuelven a contar, pero el resultado de herramienta de 2,800 tokens es contenido nuevo y cuenta contra el presupuesto. Claude gasta otros 4,000 tokens en pensamiento y una segunda llamada a herramienta (`grep -rn "eval(" src/`). La cuenta regresiva termina cerca de `remaining` ≈ 88,200.

**Solicitud 3.** Se reenvía de nuevo el historial completo con el segundo resultado de herramienta (1,200 tokens de salida de grep) añadido. Claude escribe un informe final de hallazgos de 6,000 tokens y se detiene con `stop_reason: "end_turn"`. `remaining` ≈ 81,000.

Poner las tres solicitudes una al lado de la otra hace explícita la diferencia entre el tamaño del contenido y el gasto del presupuesto:

| Solicitud | Contenido de la solicitud (tokens de entrada enviados, aprox.)   | Tokens contados contra el presupuesto en esta solicitud                       | `remaining` del presupuesto después |
| --------- | ---------------------------------------------------------------- | ----------------------------------------------------------------------------- | ----------------------------------- |
| 1         | \~20                                                             | 5,000 (pensamiento + `tool_use`)                                              | \~95,000                            |
| 2         | \~7,800 (mensajes de la solicitud 1 + resultado de herramienta)  | 6,800 (2,800 de resultado de herramienta + 4,000 de pensamiento y `tool_use`) | \~88,200                            |
| 3         | \~13,000 (historial completo + segundo resultado de herramienta) | 7,200 (1,200 de resultado de herramienta + 6,000 de `text`)                   | \~81,000                            |
| **Total** | **\~20,820 enviados a lo largo de las solicitudes**              | **19,000 contados contra el presupuesto**                                     | N/A                                 |

Tu cliente envió el mensaje original del usuario tres veces y el primer mensaje del asistente dos veces, pero cada uno se contó una sola vez. El presupuesto gastó 19,000 de 100,000 tokens, aunque el contenido acumulado que transmitió tu cliente fue mayor y la entrada almacenada en caché de prompts en las solicitudes 2 y 3 fue aún mayor.

### Arrastrar un presupuesto a través de la compactación con `remaining`

Si tu propio código compacta o reescribe el historial de mensajes entre solicitudes (por ejemplo, resumiendo mensajes anteriores), el servidor no tiene memoria de cuánto presupuesto se gastó antes de la compactación. Pasa `remaining` en la siguiente solicitud para que la cuenta regresiva continúe desde donde la dejaste en lugar de restablecerse a `total`:

<CodeGroup exclude="shell">
  ```python Python
  # Tokens gastados antes de la compactación, rastreados del lado del cliente
  tokens_spent_so_far = 45000

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

  ```typescript TypeScript
  // Tokens gastados antes de la compactación, rastreados del lado del cliente
  const tokensSpentSoFar = 45000;

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

  ```csharp C#
  // Tokens gastados antes de la compactación, rastreados del lado del cliente
  var tokensSpentSoFar = 45000;

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

  ```go Go
  // Tokens gastados antes de la compactación, rastreados del lado del cliente
  tokensSpentSoFar := int64(45000)

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

  ```java Java
  // Tokens gastados antes de la compactación, rastreados del lado del cliente
  long tokensSpentSoFar = 45000;

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

  ```php PHP
  // Tokens gastados antes de la compactación, rastreados del lado del cliente
  $tokensSpentSoFar = 45000;

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

  ```ruby Ruby
  # Tokens gastados antes de la compactación, rastreados del lado del cliente
  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>

En este ejemplo, los tokens gastados antes de la compactación son el uso de todos los mensajes que has eliminado del historial hasta el momento, medido como en [Mide tu uso actual](https://platform.claude.com/docs/es/build-with-claude/task-budgets#measure-your-current-usage). Excluye todo lo que siga presente en los mensajes que envías, incluido cualquier resumen que hayas agregado, porque el servidor cuenta esos tokens por sí mismo. Actualiza esta cifra solo cuando reemplaces el historial de esta manera; no la decrementes en cada solicitud. Pasa el `remaining` resultante en cada solicitud, no solo en la que realiza la compactación.

Para bucles que reenvían el historial completo sin compactar en cada solicitud, omite `remaining` y deja que el servidor lleve la cuenta regresiva.

## Cambiar el presupuesto a mitad de la conversación

`task_budget` es una configuración a nivel de solicitud. Para cambiar el presupuesto a mitad de una tarea, por ejemplo para ampliarlo cuando el usuario amplía la solicitud, establece un nuevo `task_budget` en `output_config` en la siguiente solicitud. Ten en cuenta la consecuencia para el almacenamiento en caché: el valor del presupuesto participa en el prompt renderizado, por lo que un valor cambiado no coincide con las entradas de caché creadas bajo el valor anterior (consulta [Compatibilidad de funciones](https://platform.claude.com/docs/es/build-with-claude/task-budgets#feature-support) más abajo).

## Los presupuestos de tarea son orientativos, no obligatorios

Los presupuestos de tarea son una **sugerencia suave, no un límite estricto**. Claude puede ocasionalmente exceder el presupuesto si está en medio de una acción que sería más disruptivo interrumpir que terminar. El límite obligatorio sobre el total de tokens de salida sigue siendo `max_tokens`, que trunca la respuesta con `stop_reason: "max_tokens"` cuando se alcanza.

Para un límite estricto de costo o latencia, combina los presupuestos de tarea con un valor razonable de `max_tokens`:

* Usa `task_budget` para darle a Claude un objetivo contra el cual regular su ritmo.
* Usa `max_tokens` como el techo absoluto que evita la generación descontrolada.

Dado que `task_budget` abarca el bucle agéntico completo (potencialmente muchas solicitudes) mientras que `max_tokens` limita cada solicitud individual, los dos valores son independientes; no se requiere que uno sea igual o menor que el otro.

<Warning>
  **Un presupuesto demasiado pequeño para la tarea puede causar un comportamiento similar a un rechazo.** Cuando Claude ve un presupuesto que es claramente insuficiente para el trabajo que se le pide (por ejemplo, un presupuesto de 20,000 tokens para una tarea de codificación agéntica de varias horas), puede negarse a intentar la tarea por completo, reducir su alcance agresivamente o detenerse antes con un resultado parcial en lugar de comenzar un trabajo que no puede terminar. Si observas rechazos inesperados o detenciones prematuras después de establecer un presupuesto, aumenta el presupuesto antes de depurar otros parámetros. Dimensiona los presupuestos según tu distribución real de longitud de tareas en lugar de un valor predeterminado fijo; consulta [Elegir un presupuesto](https://platform.claude.com/docs/es/build-with-claude/task-budgets#choosing-a-budget).
</Warning>

## Elegir un presupuesto

El presupuesto correcto depende de cuánto trabajo realiza actualmente tu bucle agéntico. En lugar de adivinar, mide primero tu uso de tokens existente y luego ajusta a partir de ahí.

### Mide tu uso actual

Ejecuta una muestra representativa de tareas **sin** `task_budget` establecido y registra el total de tokens que Claude gasta por tarea. Para un bucle agéntico, suma `usage.output_tokens` a lo largo de cada solicitud del bucle, más los tokens de los resultados de herramientas que agregas entre solicitudes:

<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."}
      ],
  )

  # Suma output_tokens (texto + pensamiento + llamadas a herramientas) de todas las solicitudes de tu bucle.
  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." }]
  });

  // Suma output_tokens (texto + pensamiento + llamadas a herramientas) de todas las solicitudes de tu bucle.
  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." }],
  });

  // Suma OutputTokens (texto + pensamiento + llamadas a herramientas) de todas las solicitudes de tu bucle.
  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)
  }

  // Suma OutputTokens (texto + pensamiento + llamadas a herramientas) de todas las solicitudes de tu bucle.
  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);
  // Suma outputTokens (texto + pensamiento + llamadas a herramientas) de todas las solicitudes de tu bucle.
  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.'],
      ],
  );

  // Suma outputTokens (texto + pensamiento + llamadas a herramientas) de todas las solicitudes de tu bucle.
  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." }
    ]
  )

  # Suma output_tokens (texto + pensamiento + llamadas a herramientas) de todas las solicitudes de tu bucle.
  puts response.usage.output_tokens
  ```
</CodeGroup>

Ejecuta esto a lo largo de un conjunto representativo de tareas y registra la distribución. Comienza con el p99 de tu gasto de tokens por tarea para entender cómo proporcionarle al modelo un presupuesto de tarea podría modificar su comportamiento, y luego prueba hacia arriba o hacia abajo según sea necesario.

El valor mínimo aceptado de `task_budget.total` es de **20,000 tokens** en todos los modelos compatibles con presupuestos de tareas (consulta [Compatibilidad de funciones](https://platform.claude.com/docs/es/build-with-claude/task-budgets#feature-support)). Los valores más pequeños devuelven un error 400.

## Interacción con otros parámetros

* **`max_tokens`:** Es independiente de los presupuestos de tareas. `max_tokens` es un límite estricto por solicitud sobre los tokens generados, mientras que `task_budget` es un límite orientativo a lo largo de todo el bucle agéntico (que potencialmente abarca muchas solicitudes). Con esfuerzo `xhigh` o `max`, establece `max_tokens` en al menos 64k para darle a Claude margen para pensar y actuar en cada solicitud.
* **[Esfuerzo](https://platform.claude.com/docs/es/build-with-claude/effort):** El esfuerzo controla con qué profundidad razona Claude en cada paso. Los presupuestos de tareas controlan cuánto trabajo total realiza Claude a lo largo de un bucle agéntico. Ambos son complementarios: el esfuerzo ajusta la profundidad y los presupuestos de tareas ajustan la amplitud.
* **[Pensamiento adaptativo](https://platform.claude.com/docs/es/build-with-claude/thinking):** Los presupuestos de tareas incluyen los tokens de pensamiento en el recuento, por lo que el "adaptive thinking" (pensamiento adaptativo) se reduce a medida que se agota el presupuesto.
* **[Almacenamiento en caché de prompts](https://platform.claude.com/docs/es/build-with-claude/prompt-caching):** El marcador de cuenta regresiva del presupuesto se inyecta del lado del servidor en cada solicitud, por lo que no coincide entre solicitudes. Si tu cliente decrementa `task_budget.remaining` en cada solicitud de seguimiento, el valor modificado invalida cualquier prefijo de caché que lo contenga. Para conservar el "prompt caching" (almacenamiento en caché de prompts), establece el presupuesto una sola vez en la solicitud inicial y deja que el modelo se autorregule según la cuenta regresiva del lado del servidor en lugar de modificar el presupuesto del lado del cliente.

## Compatibilidad de funciones

| Modelo            | Compatibilidad                                           |
| ----------------- | -------------------------------------------------------- |
| Claude Fable 5.1  | Beta (establece el encabezado `task-budgets-2026-03-13`) |
| Claude Mythos 5.1 | Beta (establece el encabezado `task-budgets-2026-03-13`) |
| Claude Opus 5.5   | Beta (establece el encabezado `task-budgets-2026-03-13`) |
| Claude Opus 5     | Beta (establece el encabezado `task-budgets-2026-03-13`) |
| Claude Fable 5    | Beta (establece el encabezado `task-budgets-2026-03-13`) |
| Claude Mythos 5   | Beta (establece el encabezado `task-budgets-2026-03-13`) |
| Claude Sonnet 5.5 | Beta (establece el encabezado `task-budgets-2026-03-13`) |
| Claude Sonnet 5   | No compatible                                            |
| Claude Haiku 5.5  | Beta (establece el encabezado `task-budgets-2026-03-13`) |
| Claude Opus 4.8   | Beta (establece el encabezado `task-budgets-2026-03-13`) |
| Claude Opus 4.7   | Beta (establece el encabezado `task-budgets-2026-03-13`) |
| Claude Opus 4.6   | No compatible                                            |
| Claude Sonnet 4.6 | No compatible                                            |
| Claude Haiku 4.5  | No compatible                                            |

Los presupuestos de tarea no son compatibles con [Claude Code](https://code.claude.com/docs/es/overview) ni con las superficies de Cowork. Usa los presupuestos de tarea directamente a través de la Messages API en un [modelo compatible](https://platform.claude.com/docs/es/build-with-claude/task-budgets#feature-support).

## Próximos pasos

<CardGroup>
  <Card title="Effort" icon="gauge" href="https://platform.claude.com/docs/es/build-with-claude/effort">
    Controla con qué profundidad razona Claude en cada paso de un bucle agéntico.
  </Card>

  <Card title="Pensamiento adaptativo" icon="brain" href="https://platform.claude.com/docs/es/build-with-claude/thinking">
    Deja que Claude determine cuándo y cuánto usar el pensamiento extendido.
  </Card>

  <Card title="Compactación" icon="arrows-clockwise" href="https://platform.claude.com/docs/es/build-with-claude/compaction">
    Gestiona el contexto en conversaciones de larga duración con compactación del lado del servidor.
  </Card>

  <Card title="Almacenamiento en caché de prompts" icon="database" href="https://platform.claude.com/docs/es/build-with-claude/prompt-caching">
    Reduce el costo y la latencia en prompts repetidos almacenando en caché los prefijos de los prompts.
  </Card>
</CardGroup>