Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
This feature is eligible for Zero Data Retention (ZDR). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned.
Los presupuestos de tareas te permiten decirle a Claude cuántos tokens tiene para un bucle agentico completo, incluyendo pensamiento, llamadas a herramientas, resultados de herramientas y salida. El modelo ve una cuenta regresiva en tiempo real y la utiliza para priorizar el trabajo y terminar elegantemente a medida que se consume el presupuesto.
Los presupuestos de tareas están en beta pública en Claude Opus 4.7. Establece el encabezado beta task-budgets-2026-03-13 para optar por participar.
Los presupuestos de tareas 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:
Los presupuestos de tareas complementan el parámetro de esfuerzo: el esfuerzo controla cuán profundamente Claude razona sobre cada paso, mientras que los presupuestos de tareas limitan el trabajo total que Claude puede hacer en un bucle agentico.
Was this page helpful?
Añade task_budget a output_config e incluye el encabezado beta:
client = anthropic.Anthropic()
response = client.beta.messages.create(
model="claude-opus-4-7",
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"],
)El objeto task_budget tiene tres campos:
type: siempre "tokens".total: el número de tokens que Claude puede gastar en el bucle agentico completo, incluyendo pensamiento, llamadas a herramientas, resultados de herramientas y salida.remaining (opcional): el remanente del presupuesto llevado de una solicitud anterior. Por defecto es total cuando se omite.Claude ve un marcador de cuenta regresiva de presupuesto inyectado del lado del servidor a lo largo de la conversación. El marcador muestra cuántos tokens quedan en el bucle agentico 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 utiliza esta señal para regularse a sí mismo y terminar elegantemente a medida que se consume el presupuesto.
La cuenta regresiva refleja los tokens que Claude ha procesado en el bucle agentico actual, no los tokens que reenvías entre turnos. Si tu cliente envía el historial de conversación completo en cada solicitud de seguimiento, tu recuento de tokens del lado del cliente puede diferir del presupuesto que Claude está rastreando. Si también decrementas remaining mientras reenvías el historial completo, el modelo ve un presupuesto subreportado y la cuenta regresiva cae más rápido de lo que debería, causando que Claude se envuelva más temprano de lo que el presupuesto realmente permite. Establece un presupuesto generoso y deja que el modelo se autorregule contra la cuenta regresiva en lugar de intentar reflejarlo del lado del cliente.
El presupuesto de tarea cuenta lo que Claude ve (pensamiento, llamadas a herramientas y resultados, y texto), no lo que está en tu carga útil de solicitud. En un bucle agentico 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 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" }
}
]
}Supongamos 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 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 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 grep) añadido. Claude escribe un informe de hallazgos finales de 6,000 tokens y se detiene con stop_reason: "end_turn". remaining ≈ 81,000.
Poner los tres turnos lado a lado hace que la distinción entre tamaño de carga útil y gasto de presupuesto sea explícita:
| Turno | Carga útil de solicitud (aprox. tokens de entrada que enviaste) | Tokens contados contra presupuesto este turno | Presupuesto remaining después |
|---|---|---|---|
| 1 | ~20 | 5,000 (pensamiento + tool_use) | ~95,000 |
| 2 | ~7,800 (historial turno 1 + resultado de herramienta) | 6,800 (2,800 resultado de herramienta + 4,000 pensamiento y tool_use) | ~88,200 |
| 3 | ~13,000 (historial completo + segundo resultado de herramienta) | 7,200 (1,200 resultado de herramienta + 6,000 text) | ~81,000 |
| Total | ~20,820 enviados en solicitudes | 19,000 contados contra 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 vez. El presupuesto gastó 19,000 de 100,000 tokens, aunque la carga útil acumulativa que tu cliente transmitió fue más grande y la entrada almacenada en caché del indicador en los turnos 2 y 3 fue aún más grande.
remainingSi tu bucle agentico compacta o reescribe 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 se quedó 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 tareas son una sugerencia suave, no un límite duro. 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 aplicado en tokens de salida total sigue siendo max_tokens, que trunca la respuesta con stop_reason: "max_tokens" cuando se alcanza.
Para un límite duro en costo o latencia, combina presupuestos de tareas con un valor razonable de max_tokens:
task_budget para darle a Claude un objetivo contra el cual regularse.max_tokens como el techo absoluto que previene la generación descontrolada.Porque task_budget abarca el bucle agentico completo (potencialmente muchas solicitudes) mientras que max_tokens limita cada solicitud individual, los dos valores son independientes; uno no es requerido estar en o por debajo del otro.
Un presupuesto que es demasiado pequeño para la tarea puede causar 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 agentica de varias horas), puede rechazar intentar la tarea en absoluto, reducir su alcance agresivamente, o deterse temprano con un resultado parcial en lugar de comenzar trabajo que no puede terminar. Si observas rechazos inesperados o paradas prematuras después de establecer un presupuesto, aumenta el presupuesto antes de depurar otros parámetros. Dimensiona presupuestos contra tu distribución de longitud de tarea real en lugar de un valor predeterminado fijo; ver Elegir un presupuesto.
El presupuesto correcto depende de cuánto trabajo tu bucle agentico actualmente hace. En lugar de adivinar, mide tu uso de tokens existente primero y luego ajusta desde allí.
Ejecuta una muestra representativa de tareas sin task_budget establecido y registra los tokens totales que Claude gasta por tarea. Para un bucle agentico, suma usage.output_tokens más tokens de pensamiento y resultado de herramienta en 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:
response = client.beta.messages.create(
model="claude-opus-4-7",
max_tokens=128000,
messages=messages,
tools=tools,
betas=["task-budgets-2026-03-13"],
)
# Count what Claude generated this turn (output covers text + thinking + tool calls).
# Tool-result tokens also count against the budget; add the token count of the
# tool_result blocks you append below if you want client-side tracking to match
# the server-side countdown.
total_spend += response.usage.output_tokens
if response.stop_reason == "end_turn":
return total_spend
# Append the assistant turn and your tool results, then continue the loop.
messages += [
{"role": "assistant", "content": response.content},
{"role": "user", "content": run_tools(response.content)},
]Ejecuta esto en 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 puede modificar el comportamiento del modelo, luego prueba hacia arriba o hacia abajo según sea necesario.
El task_budget.total mínimo aceptado es 20,000 tokens; los valores por debajo del mínimo devuelven un error 400.
max_tokens: Ortogonal a presupuestos de tareas. max_tokens es un límite duro por solicitud en tokens generados, mientras que task_budget es un límite asesor en el bucle agentico completo (potencialmente abarcando muchas solicitudes). En esfuerzo xhigh o max, establece max_tokens a al menos 64k para darle a Claude espacio para pensar y actuar en cada solicitud.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.| Modelo | Soporte |
|---|---|
| Claude Opus 4.7 | Beta pública (establece encabezado task-budgets-2026-03-13) |
| Claude Opus 4.6 | No soportado |
| Claude Sonnet 4.6 | No soportado |
| Claude Haiku 4.5 | No soportado |
Los presupuestos de tareas no son soportados en superficies Claude Code o Cowork en el lanzamiento. Usa presupuestos de tareas directamente a través de la API de Mensajes en Claude Opus 4.7.