Presupuestos de tarea

Los "task budgets" (presupuestos de tarea) te permiten indicarle a Claude cuántos tokens tiene para un ciclo agéntico completo, incluyendo el pensamiento, las llamadas a herramientas, los resultados de herramientas y la salida. El modelo ve una cuenta regresiva en tiempo real y la usa para priorizar el trabajo y finalizar de manera 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:

• Quieras que Claude autorregule el gasto de tokens en tareas de largo alcance.
• Tengas un límite predecible de costo o latencia por tarea que debas hacer cumplir.
• Quieras que el modelo finalice de manera ordenada (resumir hallazgos, informar 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: effort controla con qué profundidad Claude razona sobre cada paso, mientras que los presupuestos de tarea limitan el trabajo total que Claude puede realizar a lo largo de un ciclo agéntico.



Establecer un presupuesto de tarea

Agrega task_budget a output_config e incluye el encabezado beta:

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)

El objeto task_budget tiene tres campos:

• type: siempre "tokens".
• total: el número de tokens que Claude puede gastar a lo largo del ciclo agéntico, incluyendo pensamiento, llamadas a herramientas, resultados de herramientas y salida.
• remaining (opcional): el presupuesto restante arrastrado de 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 inyectado del lado del servidor a lo largo de la conversación. El marcador muestra cuántos tokens quedan en el ciclo agéntico actual y se actualiza a medida que el modelo genera pensamiento, llamadas a herramientas y salida, y a medida que procesa resultados de herramientas. Claude usa esta señal para regular su ritmo y finalizar de manera ordenada a medida que se consume el presupuesto.



Ejemplo práctico: conteo del presupuesto a lo largo de los turnos

El presupuesto de tarea cuenta lo que Claude ve (pensamiento, llamadas y resultados de herramientas, y texto), no lo que está en la carga útil de tu solicitud. En un ciclo agéntico, tu cliente reenvía la conversación completa en cada solicitud, por lo que la carga útil crece turno a turno, pero el presupuesto solo se decrementa por los tokens que Claude ve en este turno.

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

Turno 1. Envías la solicitud inicial:

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

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

Supongamos que este turno 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.

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

{
  "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 de usuario y asistente del turno 1 reenviados no se cuentan de nuevo, pero el resultado de herramienta de 2.800 tokens es contenido nuevo que Claude ve en este turno 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.

Turno 3. Historial completo reenviado de nuevo 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 los tres turnos lado a lado hace explícita la distinción entre el tamaño de la carga útil y el gasto del presupuesto:

Tu cliente envió el mensaje de usuario del turno 1 tres veces y el mensaje del asistente del turno 1 dos veces, pero cada uno se contó una sola vez. El presupuesto gastó 19.000 de 100.000 tokens, aunque la carga útil acumulada que tu cliente transmitió fue mayor y la entrada almacenada en caché de prompts en los turnos 2 y 3 fue aún mayor.



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

Si tu ciclo agéntico compacta o reescribe el contexto entre solicitudes (por ejemplo, resumiendo turnos 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 reiniciarse a total:

# Tokens gastados antes de la compactación, registrados 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,
    },
}

Para ciclos que reenvían el historial completo sin compactar en cada turno, omite remaining y deja que el servidor rastree 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 extenderlo cuando el usuario amplía la solicitud, establece un nuevo task_budget en output_config en la siguiente solicitud. Ten en cuenta la consecuencia sobre 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 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 ciclo agéntico completo (potencialmente muchas solicitudes) mientras que max_tokens limita cada solicitud individual, los dos valores son independientes; no se requiere que uno esté en el nivel del otro ni por debajo.



Elegir un presupuesto

El presupuesto adecuado depende de cuánto trabajo realiza actualmente tu ciclo 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 ciclo agéntico, suma usage.output_tokens a lo largo de cada solicitud del ciclo, más los tokens de los resultados de herramientas que añades entre solicitudes:

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

# Suma output_tokens (texto + pensamiento + llamadas a herramientas) en cada solicitud de tu bucle.
print(response.usage.output_tokens)

Ejecuta esto sobre 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 proporcionar al modelo un presupuesto de tarea podría modificar su comportamiento, luego prueba hacia arriba o hacia abajo según sea necesario.

El mínimo aceptado para task_budget.total es específico del modelo; en todos los modelos que actualmente admiten presupuestos de tarea (consulta Compatibilidad de funciones) es de 20.000 tokens, y los valores por debajo del mínimo devuelven un error 400.



Interacción con otros parámetros

• max_tokens: Ortogonal a los presupuestos de tarea. 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 del ciclo agéntico completo (que potencialmente abarca muchas solicitudes). Con effort en xhigh o max, establece max_tokens en al menos 64k para darle a Claude espacio para pensar y actuar en cada solicitud.
• Effort: Effort controla con qué profundidad Claude razona en cada paso. Los presupuestos de tarea controlan cuánto trabajo total realiza Claude a lo largo de un ciclo agéntico. Los dos son complementarios: effort ajusta la profundidad, los presupuestos de tarea ajustan la amplitud.
• Pensamiento adaptativo: Los presupuestos de tarea incluyen los tokens de pensamiento en el conteo, por lo que el pensamiento adaptativo se reduce naturalmente a medida que el presupuesto se agota.
• Almacenamiento en caché de prompts: El marcador de cuenta regresiva del presupuesto se inyecta del lado del servidor en cada turno, por lo que no coincide entre solicitudes. Si tu cliente decrementa task_budget.remaining en cada solicitud de seguimiento, el valor cambiado invalida cualquier prefijo de caché que lo contenga. Para preservar el almacenamiento en caché, establece el presupuesto una vez en la solicitud inicial y deja que el modelo se autorregule contra la cuenta regresiva del lado del servidor en lugar de mutar el presupuesto del lado del cliente.



Compatibilidad de funciones

Los presupuestos de tarea no son compatibles con Claude Code ni con las superficies de Cowork. Usa los presupuestos de tarea directamente a través de la API de Messages en un modelo compatible.



Próximos pasos