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 en curso 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 para flujos de trabajo agénticos donde Claude realiza múltiples llamadas a herramientas y 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 hacer cumplir.
• Quieres que el modelo termine de forma ordenada (resumir hallazgos, reportar 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-4-8",
    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 inyectado 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 resultados de herramientas. Claude usa esta señal para regular su ritmo y terminar de forma ordenada a medida que se consume el presupuesto.



Ejemplo práctico: conteo del presupuesto a través de turnos

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

Considera un bucle 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" }
    }
  ]
}

Supón que este turno del asistente (pensamiento más la llamada a herramienta) totaliza 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 agregado:

{
  "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 del usuario y del asistente del turno 1 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. El historial completo se reenvía de nuevo con el segundo resultado de herramienta (1,200 tokens de salida de grep) agregado. 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 del usuario del turno 1 tres veces y el mensaje del asistente del turno 1 dos veces, pero cada uno se contó una 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 bucle 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:

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

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



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 previene una generación descontrolada.

Debido a 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 esté en o por debajo del otro.



Elegir un presupuesto

El presupuesto correcto depende de cuánto trabajo hace 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 más los tokens de pensamiento y de resultados de herramientas a través de cada solicitud en el bucle:

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:
        with client.beta.messages.stream(
            model="claude-opus-4-8",
            max_tokens=128000,
            messages=messages,
            tools=tools,
            betas=["task-budgets-2026-03-13"],
        ) as stream:
            response = stream.get_final_message()
        # Cuenta lo que Claude generó en este turno (la salida abarca texto + pensamiento + llamadas a herramientas).
        # Los tokens de resultados de herramientas también cuentan contra el presupuesto; suma el recuento de tokens de los
        # bloques tool_result que agregues abajo si quieres que el seguimiento del lado del cliente coincida
        # con la cuenta regresiva del lado del servidor.
        total_spend += response.usage.output_tokens
        if response.stop_reason == "end_turn":
            return total_spend
        # Agrega el turno del asistente y tus resultados de herramientas, luego continúa el bucle.
        messages += [
            {"role": "assistant", "content": response.content},
            {"role": "user", "content": run_tools(response.content)},
        ]

Ejecuta esto a través 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 puede modificar el comportamiento del modelo, luego prueba hacia arriba o hacia abajo según sea necesario.

El mínimo aceptado para task_budget.total es de 20,000 tokens; 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 bucle agéntico completo (que potencialmente abarca muchas solicitudes). Con effort 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 qué tan profundamente razona Claude por paso. Los presupuestos de tarea controlan cuánto trabajo total hace Claude a lo largo de un bucle 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 por 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 la funcionalidad

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.