Presupuestos de tarea

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

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)

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.

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:

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

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

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

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

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:

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

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:

# 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,
    },
}

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

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:

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)

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). 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: 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: 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: 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

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 Messages API en un modelo compatible.

Próximos pasos

Compatibility