La profundidad de pensamiento de un agente es un parámetro

El loop no tiene un paso de planificación

Un agente es un loop: el modelo recibe contexto, emite tool calls o texto, el harness ejecuta, devuelve resultados, y el modelo vuelve a decidir. No hay un módulo separado que planifique. Lo que llamamos plan son tokens. O tokens de thinking que el modelo genera antes de la primera tool call, o texto que escribe en un archivo y después relee.

De ahí sale la consecuencia de ingeniería: si planificar es gastar tokens antes de actuar, entonces "planificar más" es una decisión de presupuesto, y los presupuestos se configuran.

En los modelos actuales el thinking es adaptativo. La documentación de adaptive thinking lo dice sin vueltas: el modelo evalúa cada request y decide por sí mismo si pensar y cuánto. La misma conversación puede tener turnos con thinking y turnos sin thinking. La perilla que sesga esa decisión es output_config.effort.

Ninguna fila de esa tabla levanta el techo de max_tokens. max describe capacidad de razonamiento, no permiso para exceder el cap.

Lo importante del mecanismo es que effort no toca solo el thinking. Según la documentación de effort, afecta todos los tokens de la respuesta: texto, thinking y tool calls. Y describe el efecto sobre el comportamiento agéntico con una precisión que conviene leer dos veces. Con effort bajo, el modelo combina múltiples operaciones en menos tool calls y procede directamente a la acción sin preámbulo. Con effort alto, hace más tool calls y explica el plan antes de actuar.

Explicar el plan antes de actuar es, literalmente, una función de effort.

Y el default cambió de lugar. En Claude Opus 5 el thinking viene prendido: omitir el parámetro thinking equivale a adaptive, a diferencia de Opus 4.8 y 4.7, donde omitirlo significaba no pensar. Apagarlo sigue siendo posible con thinking: {"type": "disabled"}, pero solo hasta effort high; combinado con xhigh o max devuelve un 400. Que la profundidad sea configuración se ve mejor acá que en cualquier párrafo: el mismo request, sin tocar una letra del prompt, piensa en un modelo y no piensa en el anterior.

Tres perillas que acotan cosas distintas

La confusión más común es tratar profundidad, techo y amplitud como si fueran la misma cosa.

El thinking cuenta contra max_tokens. Un max_tokens dimensionado para una respuesta sin thinking queda corto apenas el modelo empieza a pensar en serio, y ahí aparece stop_reason: "max_tokens". La doc plantea el diagnóstico como una pregunta, no como una receta: si esas respuestas truncadas necesitaban el razonamiento, subí el techo; si estaban sobre-pensadas, bajá el effort.

Los task budgets son la pieza menos conocida y la más específica de agentes. Son beta, están acotados por modelo —no existen en Opus 4.6, Sonnet 4.6 ni Haiku 4.5, y no corren en Claude Code— y el mínimo aceptado es de 20.000 tokens. El servidor inyecta un contador regresivo que solo ve el modelo, y el modelo lo usa para dosificarse y cerrar prolijo en vez de cortarse a la mitad de una acción. Conviene chequear la tabla de soporte del proveedor antes de asumir que están donde uno los está por probar.

Así se ve el request completo, con streaming porque un max_tokens grande sin stream se come el timeout HTTP:

with client.beta.messages.stream(
    model="claude-opus-5",
    max_tokens=128000,  # techo duro: thinking + texto + tool calls
    output_config={
        "effort": "high",
        "task_budget": {"type": "tokens", "total": 64000},
    },
    betas=["task-budgets-2026-03-13"],
    tools=tools,
    messages=messages,
) as stream:
    response = stream.get_final_message()

print(response.usage.output_tokens_details.thinking_tokens)

Dos advertencias de la doc que son mecanismo puro. La primera: el budget es un hint, no un cap; el cap sigue siendo max_tokens. La segunda es más interesante. Un budget demasiado chico para la tarea produce algo parecido a un rechazo: el modelo puede declinar, recortar el alcance de forma agresiva o parar temprano antes que empezar algo que no puede terminar. Si después de poner un budget aparecen abandonos raros, la primera hipótesis es el budget, no el prompt.

El número sale de medir, y la doc dice cómo. Corré una muestra representativa de tareas sin task_budget, sumá usage.output_tokens de cada request del loop más los tokens de los tool results que el modelo lee en ese turno, y arrancá por el p99 de esa distribución. El budget cuenta lo que el modelo genera y lo que lee, no la historia completa que vos reenviás en cada request. En el loop normal dejá remaining sin setear: el servidor lleva la cuenta solo.

Por qué pedir que piense duplica

Acá está el eje. La instrucción de planificar o de verificar es un prior que se suma a un comportamiento que ya tiene tasa base alta. Los dos se componen.

La guía de prompting de Claude Opus 5 es explícita: el modelo verifica su propio trabajo sin que se lo pidan, y si tu prompt tiene instrucciones de verificación —"incluí un paso final de verificación", "usá un subagente para verificar"— hay que sacarlas. Sacarlas reduce la sobre-verificación sin pérdida de capacidad. Es un borrado, no una reescritura. Lo mismo con las frases de auto-chequeo dentro del prompt: "revisá tu respuesta", "re-verificá antes de contestar". Esto invierte una recomendación clásica de prompting, así que una librería de prompts que la aplica de forma uniforme necesita una excepción para este modelo.

El patrón se repite una generación antes. Sobre Opus 4.6 la doc recomienda eliminar el over-prompting, porque las herramientas que sub-disparaban en modelos anteriores ahora disparan bien, y un "ante la duda, usá esta herramienta" produce sobre-disparo.

Y la guía de migración cierra el círculo para el caso de planificación: los prompts y las skills escritos para modelos anteriores suelen ser demasiado prescriptivos para los actuales y reducen la calidad de la salida. La recomendación es enunciar el objetivo, las restricciones y cómo se verifica, antes que enumerar los pasos. Los pasos numerados quedan solo donde el orden importa de verdad.

La doc ordena las palancas: primero el effort, después el prompt. Y justifica el orden en el mecanismo, porque el effort es un control calibrado en vez de una instrucción sensible al fraseo.

El prompt tiene un rol claro acá: acotar alcance. Cuando el modelo expande la tarea más allá de lo pedido, el remedio es una instrucción de alcance. Si el razonamiento sale flojo en problemas complejos, la doc es tajante: subí el effort en vez de prompt-earlo.

Plan de entrada contra loop reactivo

El thinking interleaved hace que el modo reactivo no sea ciego. El modelo piensa entre tool calls, reflexionando sobre cada resultado antes de decidir el siguiente paso, y en los modelos actuales eso pasa automáticamente, sin header ni configuración extra. O sea que el loop reactivo re-planifica en cada vuelta con información fresca.

Entonces las dos opciones se distinguen por dónde queda guardado el plan.

Un plan escrito de entrada es un artefacto: sobrevive a la compactación del context window, un humano lo puede aprobar antes de que se toque nada, y da un punto de intercepción. Un plan en vuelo es más barato y más adaptativo, y no deja dónde frenar.

Building effective agents separa los patrones por exactamente ese criterio. El prompt chaining sirve cuando la tarea se puede descomponer limpiamente en subtareas fijas. El patrón orchestrator-workers sirve para tareas complejas donde no podés predecir qué subtareas van a hacer falta. La pregunta que decide no es cuán difícil es la tarea, sino si los subpasos son predecibles antes de mirar.

Y antes de eso hay una decisión más gruesa. Los cuatro tiers, de menos a más complejo: una sola llamada a la API, un workflow con lógica en tu código, un agente con tus propias herramientas, un agente gestionado donde el proveedor corre el loop y hospeda el sandbox. La recomendación es empezar por el más simple que resuelva y agregar complejidad solo cuando mejora resultados de forma demostrable. Los cuatro criterios para justificar un agente: complejidad multi-paso difícil de especificar de antemano, valor que justifique costo y latencia, viabilidad del modelo en ese tipo de tarea, y costo del error acotado por tests, review y rollback. Si alguno da que no, el tier de arriba resuelve mejor.

Del criterio de tooling sale una heurística que se transfiere igual acá: lo difícil de revertir se planifica de entrada. Una acción con blast radius chico se puede descubrir ejecutando; una migración de esquema, no. Es el mismo criterio por el que una acción se promueve de bash a herramienta dedicada: bash le da al modelo alcance máximo, pero al harness solo le llega un string opaco. Una herramienta dedicada le da un punto de intercepción con argumentos tipados, y ahí recién se puede pedir confirmación, verificar que el archivo no cambió desde la última lectura, renderizar UI propia o paralelizar lo que es seguro paralelizar.

Delegar mueve contexto, no solo trabajo

Acá cambia la fuente y conviene decirlo. Todo lo anterior es Messages API. Los subagentes configurables son otro producto: el Claude Agent SDK y su expresión en Claude Code, donde cada subagente tiene su propio prompt, sus propias herramientas y su propio contexto. Lo que sigue vale para ese harness, no para el endpoint.

El mecanismo relevante es la frontera. Un subagente arranca con un context window nuevo, recibe solamente el prompt con el que lo despachás, y devuelve un solo mensaje final. No hereda la historia de la conversación ni los tool results del padre.

De ahí salen tres consecuencias directas.

Primera: delegar es una operación con pérdida. Todo lo que el subagente necesita —paths, mensajes de error, decisiones ya tomadas— tiene que estar escrito en ese prompt. La falla clásica de delegación es mandar media pregunta y recibir, con toda lógica, media respuesta.

Segunda: quién dispara la delegación lo decide la descripción, con la misma dinámica que las descripciones de herramientas. Las descripciones son el factor que más influye en que el modelo use bien una herramienta, y la falla más común es sub-describir. Conviene ser prescriptivo sobre cuándo llamarla, no solo sobre qué hace. Lo mismo aplica al subagente.

Tercera: la delegación tiene un costo que escala mal hacia abajo, y en Claude Opus 5 escala peor que antes. La doc de migración avisa que este modelo delega más fácil que Opus 4.8 —que era el problema inverso— y recomienda mantener bajo el conteo de spawns. El bloque de prompt que propone dice dos cosas concretas: no delegar trabajo que se termina en un puñado de tool calls, y no usar subagentes para verificar el propio trabajo. La verificación va en el loop principal. Si arrastrás guías de "delegá más" escritas para el modelo anterior, esas salen.

La misma economía se ve desde el lado del contexto con las skills. Una skill es una carpeta con un SKILL.md, y su mecanismo es la revelación progresiva: la descripción vive en el context window siempre, el archivo completo se lee recién cuando la tarea lo amerita. Esa descripción se paga en cada request, así que enumerar frases de disparo casi sinónimas engorda todos los pedidos y generaliza peor que nombrar categorías de intención.

Y donde escribís esas instrucciones, la especificidad tiene que coincidir con la fragilidad. Guiones exactos para decisiones de juicio sobre-restringen; prosa vaga para operaciones frágiles sub-restringe. Heurísticas en prosa donde el campo es abierto, comandos exactos solo donde hay una única secuencia segura.

Los dos modos de falla son la misma perilla

Elegí un effort por workload y medilo contra tu eval. Si no puede bloquear un deploy no es una eval, y sin eso el barrido de effort es opinión.

La columna de la API y la columna del harness no salen del mismo lugar, y conviene no mezclarlas. usage.output_tokens_details.thinking_tokens reporta cuántos de los tokens de salida facturados fueron razonamiento interno: es la métrica que convierte "me parece que piensa demasiado" en un número, y en streaming aparece solo en el message_delta final. Las tool calls repetidas y las reversiones a mitad de camino no las reporta la API: las tenés que instrumentar en tu propio log del loop.

Herramientas para probar esto

• LangGraph — Workflows and agents. Grafos de estado donde prompt chaining, routing, orchestrator-worker y agente autónomo son topologías explícitas. Es el lugar donde la decisión planificar contra reaccionar se vuelve estructura de datos.
• Claude Agent SDK (Python). La implementación de referencia del proveedor para el loop, las herramientas y los subagentes. Es la fuente de todo lo que dice la sección de delegación.
• Claude Code — Subagents. Subagentes configurables con prompt, herramientas y contexto propios. Sirve como ejemplo auditable de cómo se acota el alcance de cada subtarea.
• OpenAI Agents SDK — Handoffs. Delegación como handoff entre agentes especializados en vez de planificador central. Buen contraste de diseño para ver que delegar admite más de una forma.
• smolagents. El agente escribe el plan como código ejecutable en lugar de emitir tool calls sueltas. El extremo de baja ceremonia.
• CrewAI. Roles, tareas y procesos jerárquicos con descomposición declarativa. Útil para ver el costo de la sobre-estructura.

El orden de operaciones

Elegí el tier más simple que resuelva. Elegí un effort por workload y medilo contra la eval. Poné max_tokens con lugar para thinking más respuesta, y revisá especialmente las rutas que nunca seteaban thinking: en Opus 5 ahora piensan, y el techo se comparte. Agregá task_budget si el loop es largo, con el p99 de tu propia medición como punto de partida. Recién ahí escribí el prompt, y usalo para acotar alcance, no para pedir profundidad. Y borrá las instrucciones de verificación que arrastrás de modelos anteriores.

Un detalle mecánico que cierra todo: el valor de effort se renderiza en el prompt, así que cambiarlo entre requests invalida los cache breakpoints. La consecuencia práctica es que el effort se varía entre workloads, no dentro de una conversación que depende del cache. La profundidad de pensamiento es un parámetro con la misma rigidez que cualquier otra decisión de configuración: se elige una vez, se mide, y se sostiene.