Orquestación multi-agente

Fan-out paralelo vs pipeline

Orquestar varios agentes es elegir una topología. Las dos primitivas:

• Paralelo (fan-out): lanzar N agentes a la vez sobre tareas independientes, esperar a todos (una barrera), luego agregar. Usarlo cuando se necesitan todos los resultados juntos (deduplicación global, conteo total).
• Pipeline: cada elemento recorre todas las etapas de forma independiente, sin barrera entre etapas. El elemento A puede estar en la etapa 3 mientras B sigue en la etapa 1. La opción por defecto para trabajo de múltiples etapas: el tiempo total es el de la cadena más lenta, no la suma de los más lentos por etapa.

La trampa clásica: poner una barrera (paralelo) donde bastaría un pipeline, solo porque el código parece más limpio. Una barrera solo se justifica si la etapa N necesita el resultado completo de la etapa N-1 (fusión, deduplicación, salida anticipada si es cero). De lo contrario, pipeline.

Aplicación concreta en el caso de Pierre: sus auditorías SEO multilingües (Eskimoz en 4 idiomas) son fan-outs; un agente por idioma, agregación al final. Su regla de modelos aplica: Haiku/Sonnet para los agentes masivos, Opus para la síntesis.

Verificación adversarial y paneles de jueces

Un agente que encuentra errores o hallazgos produce resultados plausibles pero falsos (alucinación, de nuevo). La solución de orquestación: hacer que cada hallazgo sea verificado por otros agentes antes de conservarlo.

Patrones de calidad:

• Verificación adversarial: para cada hallazgo, lanzar N agentes escépticos cuya instrucción es refutarlo. Conservar el hallazgo solo si la mayoría no logra refutarlo. Elimina los falsos positivos plausibles.
• Verificación multi-perspectiva: si un hallazgo puede fallar de varias formas, dar a cada verificador un ángulo diferente (exactitud, seguridad, rendimiento, reproducibilidad) en lugar de N copias idénticas.
• Panel de jueces: generar N soluciones independientes desde distintos ángulos, puntuarlas con jueces en paralelo, sintetizar a partir del ganador incorporando las mejores ideas de los demás.
• Bucle hasta el agotamiento: para una búsqueda de tamaño desconocido (errores, casos límite), relanzar los detectores hasta que K rondas consecutivas no devuelvan nada nuevo.

Principio rector: la confianza surge de perspectivas independientes que se contradicen entre sí, no de un agente seguro de sí mismo. Es exactamente el espíritu del reflejo de Pierre "reproducir vía Playwright antes de corregir": verificar antes de creer, aplicado a escala de agentes.

Workflows: orquestación determinista

Cuando la orquestación se vuelve compleja (bucles, condiciones, fan-out, presupuestos), se pasa de un agente improvisador a un workflow: un script que orquesta los subagentes de forma determinista. El flujo de control (quién se ejecuta, cuándo, en paralelo o en serie) está codificado, no lo decide el modelo.

Bloques de construcción típicos de un motor de workflow:

• agent(prompt, schema): lanzar un subagente y obtener una salida estructurada validada.
• pipeline(items, ...stages): pasar cada elemento por las etapas sin barreras.
• parallel(thunks): una barrera, todo al mismo tiempo.
• Bucles: loop-until-count (acumular hasta N), loop-until-dry (hasta el agotamiento), loop-until-budget (hasta una cuota de tokens).

La ventaja frente a un solo agente grande: la estructura (descomponer y cubrir en paralelo), la confianza (verificar antes de concluir) y la escala (migraciones o auditorías que un único contexto no podría contener). Usted permanece en el bucle: lee cada resultado antes de decidir el siguiente paso. Es el nivel más avanzado, reservado para tareas que realmente lo justifican, porque consume muchos tokens.

Barrera o sin barrera

En un pipeline multi-agente (una cadena de agentes de IA donde cada uno realiza una tarea específica), debe decidir en cada transferencia: el siguiente paso necesita esperar todos los resultados anteriores, o puede comenzar en cuanto llegue cualquier resultado. Esa decisión se llama colocar una barrera (o no).

Una barrera es un punto de sincronización. Ningún agente posterior a la barrera comienza hasta que todos los agentes anteriores hayan terminado. Esta es la opción correcta cuando el siguiente paso genuinamente necesita el panorama completo antes de poder actuar. Un funcionamiento sin barrera (también llamado streaming o fan-in sin espera) permite que los resultados fluyan de uno en uno a medida que llegan, de modo que el trabajo posterior comienza de inmediato.

Hágase una sola pregunta: "¿Puede el siguiente paso producir un resultado correcto con solo datos parciales?" Si la respuesta es sí, omita la barrera. Si es no, agregue una. Equivocarse en cualquier dirección tiene un costo: una barrera innecesaria serializa lo que podría ejecutarse en paralelo, desperdiciando tiempo; una barrera faltante corrompe los resultados porque los agentes posteriores actúan sobre información incompleta.

• Use una barrera cuando esté agregando puntuaciones, combinando conjuntos de datos, escribiendo un resumen final, o en cualquier operación que no está definida sobre un subconjunto.
• Sin barrera necesaria cuando cada resultado es accionable de forma independiente: traducción de documentos, redimensión de imágenes, envío de notificaciones individuales, o transmisión de respuestas parciales a un usuario.
• Las barreras parciales también son válidas: espere los primeros N resultados (un quorum) y luego proceda, descartando los rezagados.

Iterar hasta agotar

Algunas tareas tienen una frontera desconocida: no se sabe cuántos elementos existen hasta haber terminado de recopilarlos. La paginación, los recorridos recursivos de directorios y el rastreo iterativo de la web comparten esta forma. El patrón adecuado es un bucle de agotamiento: repetir una ronda de búsqueda o recuperación, recopilar los nuevos resultados y detenerse solo cuando una ronda no devuelva nada nuevo.

En un contexto multiagente (donde varias instancias de Claude se pasan trabajo entre sí), el agente orquestador ejecuta el bucle y distribuye cada lote a los agentes trabajadores. El orquestador mantiene un conjunto visto, una colección deduplicada de todo lo que ya se ha procesado, y compara cada nueva ronda con él. Cuando el conjunto deja de crecer, el bucle termina.

Claude Code admite este patrón mediante comandos de shell encadenados y llamadas a subagentes. Un bucle mínimo en una tarea de Claude Code tiene este aspecto:

1. Ejecutar una búsqueda o llamada a la API y capturar la salida.
2. Comparar la salida con el conjunto visto.
3. Si la diferencia no está vacía, agregar los nuevos elementos al conjunto visto, enviar el trabajo y volver al paso 1.
4. Si la diferencia está vacía, detenerse e informar.

Dos salvaguardas son obligatorias: un límite máximo de rondas (por ejemplo, 50 iteraciones) para evitar bucles infinitos causados por errores o comportamientos inesperados de la API, y trabajadores idempotentes (trabajadores que producen el mismo resultado si procesan accidentalmente el mismo elemento dos veces). Sin estas protecciones, un bucle de agotamiento puede ejecutarse indefinidamente o corromper los resultados.

Worktrees para agentes en paralelo

Cuando ejecutas varios agentes Claude Code a la vez, todos operan de forma predeterminada sobre los mismos archivos del repositorio. Si dos agentes editan el mismo archivo de manera simultánea, uno sobreescribirá el trabajo del otro. Los Git worktrees resuelven esto: un worktree es un directorio de trabajo adicional vinculado al mismo repositorio, extraído en su propia rama, de modo que cada agente dispone de archivos aislados sin ninguna superposición.

Creas un worktree con git worktree add. Cada worktree tiene su propia rama y su propia copia de los archivos de trabajo en disco. Los agentes se ejecutan en directorios separados y nunca tocan los archivos de los demás. Cuando su trabajo termina, fusionas las ramas de la manera habitual.

Claude Code admite este patrón directamente. El comando /worktrees (y el flag --worktree al lanzar un sub-agente) indica a un agente en qué ruta de worktree debe operar. El agente orquestador crea los worktrees, asigna uno a cada sub-agente y luego espera a que todos terminen antes de fusionar.

• Sin colisiones de archivos: cada agente escribe únicamente en su propio directorio.
• Sin conflictos de ramas: cada worktree está en su propia rama.
• Punto de fusión limpio: el orquestador fusiona todas las ramas después de que los agentes informan su finalización.
• Limpieza sencilla: git worktree remove elimina el directorio y lo desregistra.

Despachar agentes en paralelo

Cuando una tarea puede dividirse en partes independientes, ejecutar esas partes una tras otra desperdicia tiempo. El fan-out consiste en lanzar varios agentes (o subprocesos) al mismo tiempo, cada uno gestionando una porción distinta del trabajo, y luego recopilar todos los resultados cuando terminan. Claude Code admite este patrón mediante la herramienta Agent, que permite a un agente orquestador crear agentes hijos.

La regla fundamental es la independencia: las tareas que se distribuyen en fan-out no deben depender del resultado de las demás. Si la tarea B necesita que la tarea A termine primero, ambas deben permanecer en secuencia. Buenos candidatos para el fan-out incluyen: auditar archivos separados, traducir el mismo contenido a varios idiomas, ejecutar el mismo prompt sobre distintos conjuntos de datos o recuperar varias URLs en paralelo.

Un flujo de trabajo fan-out típico tiene tres etapas:

1. Descomponer: el orquestador divide el objetivo en N subtareas independientes.
2. Despachar: llama a la herramienta Agent N veces, una llamada por subtarea, sin esperar entre llamadas.
3. Recopilar: cuando todos los agentes responden, el orquestador fusiona o resume los resultados.

En Claude Code también es posible hacer fan-out a nivel de shell usando --print (modo no interactivo) y procesos en segundo plano, y luego unir las salidas. Esto funciona bien para tareas simples donde se controla directamente el entorno de shell.

Escalar un fan-out con presupuesto controlado

Un fan-out ocurre cuando un orquestador (el agente coordinador) lanza múltiples sub-agentes en paralelo para abordar distintas partes de un problema al mismo tiempo. Cada sub-agente consume tokens, por lo que el costo total de una ejecución de fan-out equivale a la suma de los tokens de entrada y salida de cada agente. Sin planificación, los costos se disparan rápidamente.

El primer mecanismo es la selección del modelo por tarea. No todos los sub-agentes necesitan el modelo más capaz. Asigne claude-opus-4-8 únicamente a las tareas que requieren razonamiento profundo, como decisiones de arquitectura o análisis ambiguos. Use claude-sonnet-4-6 para trabajos de complejidad media, como la generación de código, y claude-haiku-4-5 para tareas simples de alto volumen, como clasificación, formateo o extracción. Esto por sí solo puede reducir el costo de una ejecución en un 80 % o más.

El segundo mecanismo es el recorte de contexto. La entrada de cada agente se factura en su totalidad. Pase únicamente la parte del contexto que ese agente realmente necesita: un archivo relevante, un resumen breve o un objeto estructurado en lugar del historial completo de la conversación. El prompt caching (reutilizar un prefijo común entre agentes) reduce aún más los cargos por contexto repetido cuando varios agentes comparten un prompt de sistema extenso o un documento de referencia.

Controles presupuestarios prácticos que debe aplicar antes de lanzar una flota de agentes:

• Establezca max_tokens por agente en el mínimo necesario para ese tipo de tarea.
• Limite el número de agentes en paralelo: mayor concurrencia aumenta el costo sin mejorar siempre la calidad.
• Agregue un paso de estimación en seco: cuente los tokens de las entradas previstas antes de comprometerse con una ejecución completa.
• Use la terminación anticipada: si un resultado intermedio ya cumple el criterio de éxito, cancele los agentes restantes.
• Registre el uso de tokens por llamada de agente y establezca un techo absoluto en el bucle del orquestador.

Schemas para datos de agente limpios

En un pipeline multi-agente (una cadena de modelos de IA que se pasan resultados entre si), la salida de un agente se convierte en la entrada del siguiente. Si esa salida es texto libre, el agente receptor debe adivinar la estructura, lo que provoca errores silenciosos. La solución es la salida estructurada: forzar al modelo a devolver los datos en un formato estricto y legible por máquinas, como JSON.

Claude admite la salida estructurada mediante el uso de herramientas. Se define un JSON Schema (una descripción formal de los campos, tipos y propiedades requeridas que se esperan) y se pasa como definición de herramienta. Claude rellena ese schema en lugar de escribir texto. El resultado es un objeto JSON que el código puede analizar y validar sin ninguna manipulación de cadenas.

Razones clave para imponer schemas en cadenas de agentes:

• Fiabilidad: los agentes posteriores reciben claves y tipos predecibles, no texto ambiguo.
• Validación: se puede rechazar o reintentar una respuesta en el momento en que falta un campo requerido, antes de que los datos incorrectos se propaguen.
• Observabilidad: los registros estructurados son más fáciles de buscar, comparar y monitorear en producción.
• Composabilidad: cualquier agente que use el mismo schema puede intercambiarse sin reescribir el código de enlace del pipeline.

En Claude Code, la API de Claude (la interfaz HTTP que el agente llama de forma programática) permite pasar un array tools con una herramienta cuyo input_schema define exactamente lo que se desea recibir. Establecer tool_choice en {"type":"tool","name":"tu_herramienta"} obliga a Claude a llamar esa herramienta en cada ocasión, garantizando una salida estructurada en cada solicitud.

Retomar y cachear un flujo de trabajo

Un flujo de trabajo multi-agente (un pipeline donde varios sub-agentes de IA manejan diferentes tareas en secuencia) puede ser costoso de volver a ejecutar desde cero cada vez que se modifica un paso. La solución es la reanudación parcial: volver a ejecutar solo los pasos cuyos datos de entrada cambiaron, y reutilizar las salidas de todo lo demás.

Claude Code admite esto mediante dos mecanismos complementarios. El caché de prompts (una función de la API de Anthropic) almacena el cálculo a nivel de tokens para un prompt de sistema largo y estable, o para un bloque de contexto, de modo que el modelo evita reprocesarlo en la siguiente llamada. Esto reduce tanto la latencia como el costo. Los aciertos de caché se facturan a aproximadamente el 10 % de la tarifa normal de tokens de entrada. El caché se indexa por el texto exacto del prefijo: incluso un solo carácter cambiado en el bloque cacheado lo invalida.

A nivel del flujo de trabajo, usted controla la reanudación mediante puntos de control (checkpoints): salidas guardadas de cada paso del agente escritas en disco o en un almacén. Al volver a ejecutar el pipeline, cada paso verifica si su checkpoint sigue siendo válido (entradas sin cambios) antes de llamar al modelo. Los patrones habituales incluyen:

• Verificación por hash de contenido: calcular el hash de las entradas del paso y compararlo con el hash almacenado en el checkpoint. Si coinciden, el paso se omite.
• Verificación por marca de tiempo: omitir el paso si el archivo de checkpoint es más reciente que todos los archivos fuente que el paso lee.
• Invalidación explícita: pasar un indicador --from step-name al orquestador para forzar la re-ejecución a partir de un paso específico.
• Grafo de dependencias: modelar qué pasos dependen de qué salidas; invalidar solo los pasos descendentes cuando cambia una salida ascendente.

En Claude Code, puede escribir esta lógica en un orquestador shell o Node que llama a claude con el indicador --print (no interactivo, imprime la respuesta y termina) y escribe cada salida en un archivo. En la siguiente ejecución, lea primero el archivo y omita por completo la llamada a claude si el checkpoint es reciente.

El crítico de completitud

En un pipeline multiagente (una cadena de agentes IA donde cada uno realiza una tarea concreta), el último cuello de botella rara vez es contenido incorrecto. Es contenido faltante. Un crítico de completitud es un agente final cuya única función es preguntarse: "¿Qué debería estar aquí y no está?" Revisa la salida de todos los agentes anteriores comparándola con el brief original y señala las omisiones antes de que el resultado llegue al usuario.

Este agente tiene un propósito deliberadamente acotado. No reescribe, no mejora el tono ni verifica hechos. Solo compara el alcance del brief con el alcance de la salida y devuelve una lista estructurada de omisiones. Mantenerlo acotado lo hace rápido, económico (un modelo Haiku suele ser suficiente) y fácil de probar.

Ejemplos habituales de lo que detecta un crítico de completitud:

• Una sección mencionada en el brief que nunca aparece en la salida
• Un ejemplo prometido en la introducción pero nunca redactado
• Una restricción (número de palabras, audiencia, idioma) que se abandonó en silencio
• Un punto de acción de un resumen de reunión que quedó reformulado hasta desaparecer

El crítico devuelve sus hallazgos al pipeline como un diff estructurado (una lista de diferencias legible por una máquina). Un agente de segundo paso, o el orquestador en sí (el agente que coordina a todos los demás agentes), decide luego qué brechas cerrar, cuáles aceptar y cuáles escalar al humano.

Los subagentes ahora se ejecutan en segundo plano

A partir de Claude Code v2.1.198 (publicada el 1 de julio de 2026), los subagentes (instancias auxiliares de Claude a las que delegas una subtarea, como "ejecuta la suite de tests e informa de los resultados") se ejecutan en segundo plano por defecto. La conversacion principal sigue funcionando mientras el subagente trabaja, y recibes una notificacion cuando termina. Esa notificacion aparece en la vista claude agents, un panel que lista todos los subagentes que tienes en ejecucion o ya completados, para que puedas revisar el estado sin interrumpir tu propio trabajo.

Esto supone un cambio real respecto al modelo mental anterior. Antes de esta version, lanzar un subagente bloqueaba el hilo principal: pedias a Claude que delegara una tarea, y toda la sesion esperaba hasta que ese subagente devolviera un resultado antes de que pudieras escribir cualquier otra cosa. Ese modelo mental ahora esta obsoleto. Desde el 1 de julio de 2026, la delegacion es fire-and-continue (lanzar y seguir) por defecto: puedes encargar una tarea a un subagente y seguir chateando, editando archivos o lanzando un segundo subagente de inmediato, mientras el primero se ejecuta en paralelo.

La misma version elimino el asistente de creacion /agents, el antiguo comando interactivo que te guiaba paso a paso para crear un subagente. Desde el 1 de julio de 2026, quedan dos formas de crear un subagente: pedirle a Claude en lenguaje natural que cree uno por ti (por ejemplo, "crea un subagente que revise pull requests en busca de problemas de seguridad"), o editar directamente los archivos de definicion bajo .claude/agents/ en tu proyecto. Ya no existe un asistente guiado entre esas dos vias.

Los equipos de agentes (agent teams, una funcion para coordinar varios subagentes en una tarea compartida) se rediseñaron antes, el 15 de junio de 2026 en la v2.1.178. Las herramientas TeamCreate y TeamDelete, que antes te permitian crear o eliminar explicitamente un equipo con nombre, fueron eliminadas. En su lugar, cada sesion tiene ahora un equipo implicito automaticamente: no hay nada que crear ni nombrar. Ese modelo de equipo añadio la aprobacion de plan de compañero de equipo (teammate plan approval, un paso en el que el plan propuesto por un compañero debe aprobarse antes de ejecutarse) y los hooks de ciclo de vida del equipo (team lifecycle hooks, scripts que se disparan automaticamente en momentos como el inicio o el fin del equipo, permitiendote registrar o condicionar lo que ocurre).

Los flujos de trabajo dinamicos (dynamic workflows, el mecanismo de Claude Code para decidir automaticamente cuantos subagentes lanzar y como secuenciarlos para una tarea dada) ganaron dos controles orientados al usuario despues de eso. Primero, aparecio un ajuste "Dynamic workflow size" en /config a partir de la v2.1.202, el 6 de julio de 2026, que te permite limitar o ajustar cuanto pueden crecer estos flujos de trabajo automaticos. Segundo, esa misma linea de versiones añadio los atributos de OpenTelemetry workflow.run_id y workflow.name. OpenTelemetry es un formato estandar para exportar trazas y metricas que herramientas de observabilidad (como Grafana o Datadog) pueden ingerir; con estos dos atributos, una ejecucion de orquestacion (una ejecucion de un flujo de trabajo con varios subagentes) se vuelve trazable como una unidad nombrada e identificable dentro de la pila de observabilidad estandar que ya use tu equipo.

En la practica, esto cambia tres habitos. Primero, aprovecha la delegacion fire-and-continue: para subtareas independientes (un pase de lint, una actualizacion de documentacion, una consulta de investigacion en segundo plano), encargaselas a un subagente y sigue trabajando en lugar de esperar sin hacer nada. Segundo, sigue esperando de forma sincrona cuando el siguiente paso realmente depende del resultado del subagente, por ejemplo si no puedes escribir el resumen hasta que el subagente de investigacion devuelva sus hallazgos; que sea en segundo plano por defecto no significa que cada paso deba ejecutarse sin supervision. Tercero, ajusta tu bucle de revision: en lugar de vigilar un spinner bloqueante, ahora revisas periodicamente la vista claude agents en busca de notificaciones de finalizacion, lo que convierte la revision del trabajo terminado de un subagente en un paso distinto y deliberado, en lugar de algo que se te impone en el momento en que termina una tarea.

Fan-out masivo que realmente termina

Un fan-out (lanzar muchos agentes a la vez para trabajar en piezas independientes de una tarea) suena simple hasta que lo intentas a gran escala. Este curso que estás leyendo ahora mismo se construyó con un fan-out de 166 agentes, un agente por lección, y lograr que eso terminara de verdad (los 166 archivos aterrizando en disco, correctos y completos) exigió cuatro reglas ganadas a pulso. Rompe cualquiera de ellas y la ejecución se estanca, pierde trabajo en silencio o quema dinero sin ningún beneficio.

Regla 1: nunca le pidas a un solo agente que produzca un entregable grande completo en una única respuesta. Esta es la regla anti-monolito. Si le dices a un agente "escribe las 166 lecciones y devuélvemelas", chocará con el límite de salida por mensaje (la cantidad máxima de texto que un modelo puede generar en una respuesta) a mitad de camino, la respuesta se corta, no se escribe nada en disco, y toda la tarea parece imposible aunque cada lección individual fuera fácil. La solución es fraccionar por eje: un agente por idioma, un agente por archivo, un agente por lección. Cada agente escribe su propio archivo en disco usando su propia llamada a la herramienta Write, y el orquestador padre solo recoge una línea de estado minúscula ("listo, p9l13.js, 3200 bytes") en lugar del contenido completo. La ventana de contexto del padre nunca tiene que contener 166 lecciones a la vez, solo 166 recibos de una línea.

Regla 2: conoce el techo de concurrencia antes de planificar la ejecución. Los orquestadores no ejecutan agentes en paralelo de forma ilimitada. En julio de 2026, los flujos de trabajo de Claude Code ejecutan como máximo unos 16 agentes simultáneamente, poniendo en cola el resto para arrancar en cuanto se liberan plazas, con un tope de por vida de 1000 agentes por flujo de trabajo. Eso significa que una tarea de 166 agentes se ejecuta en unas 10-11 oleadas de 16, no como una única ráfaga instantánea. Más allá de unos 80 agentes lanzados en una sola ráfaga, aparece la limitación del lado del servidor (la infraestructura ralentizando o rechazando peticiones para protegerse), y no solo con los modelos caros, también con modelos más baratos como Sonnet o Haiku. La jugada práctica es dividir las tareas grandes en oleadas deliberadas (por ejemplo, lotes de 15-20) en lugar de disparar todo de golpe y esperar que el planificador lo resuelva.

Regla 3: verifica la cobertura por artefacto, no por las afirmaciones del agente. Los agentes se equivocan al contar, sobre todo bajo carga: uno puede declarar éxito mientras escribe en la ruta equivocada, se salta un archivo o trunca en silencio. Nunca confíes en el flujo de mensajes "¡listo!" como prueba de que la tarea está completa. En su lugar, cuando termine la oleada, compara el conjunto de claves o nombres de archivo esperados (la lista que planificaste antes del lanzamiento) contra lo que realmente existe en disco. Para una ejecución de 166 lecciones eso significa listar los 166 nombres de archivo esperados y compararlos con un listado del directorio. En la práctica esto suele revelar 1-2 huecos, no docenas, así que la solución es rellenarlos a mano o con un agente de reintento dirigido, en lugar de relanzar toda la tarea de 166 agentes.

Regla 4: cambia a la Batch API en cuanto una tarea sea embarazosamente paralela y supere unas 50 llamadas. "Embarazosamente paralela" significa que cada unidad de trabajo es completamente independiente de las demás, sin estado compartido, sin requisito de orden. La Batch API (el endpoint de procesamiento masivo asíncrono de Anthropic) corre en su propio grupo de límite de tasa, completamente separado de tu cuota interactiva normal, con un descuento del 50 por ciento respecto al precio estándar. La contrapartida es que los resultados vuelven de forma asíncrona (envías todo el lote y luego consultas o esperas a que termine) en lugar de transmitirse turno a turno. Para una ejecución puntual de 166 lecciones, el fan-out interactivo fue la decisión correcta porque la velocidad de iteración importaba más que el costo; para una tarea recurrente de 50 o más llamadas independientes sin urgencia, la Batch API es la opción por defecto más adecuada.

Dos hábitos más dan resultado en cualquier ejecución grande. Primero, dirige las etapas mecánicas (formateo, extracción, reescrituras simples, generación directa de archivos) hacia modelos más baratos como Sonnet o Haiku, y reserva el modelo más caro para las etapas que exigen criterio: revisar calidad, resolver conflictos, sintetizar la salida final. Segundo, declara siempre en voz alta cualquier límite silencioso: si solo muestreaste los 20 primeros resultados, o procesaste los primeros 50 archivos y paraste, dilo explícitamente en la salida. Nadie más adelante en la cadena debería confundir una ejecución parcial con una completa solo porque el resumen suene seguro.

Reauditar los workflows persistidos antes de relanzarlos

Un script de workflow que funcionó perfectamente la semana pasada puede costarte hoy, silenciosamente, cinco veces más, sin que se haya cambiado ni una sola línea. Esta lección cubre un modo de fallo específico de la orquestación persistida: scripts de workflow guardados, pipelines reutilizables, cualquier archivo de automatización que sobrevive a la sesión que lo escribió.

El mecanismo es la herencia. En un script de workflow, una llamada agent() sin una opción model explícita hereda el modelo de la sesión que lo ejecuta, no el modelo de la sesión que lo escribió. Escribes el script durante una sesión con un modelo de gama media y las etapas mecánicas se ejecutan implícitamente en modo barato. Relanzas el mismo archivo la semana siguiente desde una sesión con el modelo de gama alta, y cada una de esas etapas pasa a ejecutarse ahora en el cerebro más caro disponible: en silencio, con resultados idénticos en el trabajo sencillo, a varias veces el coste y la latencia. No aparece ningún error. No hay ningún aviso. La factura es el único síntoma.

El autor se topó exactamente con esto en julio de 2026: un pipeline persistido de una sesión anterior, relanzado bajo una sesión con el modelo insignia, envió toda una flota de agentes de extracción mecánica al modelo insignia porque las primeras etapas del script no llevaban ningún enrutamiento explícito. La corrección tomó dos minutos; darse cuenta tomó más tiempo. De ahí la regla que se generaliza:

Todo script persistido se reaudita antes de relanzarlo, incluso si ya se ejecutó antes. La lista de comprobación es corta:

• Cada etapa mecánica lleva un model explícito (y un effort bajo donde esté soportado). Extracción, clasificación, formateo, traducción: el modelo más pequeño que cumpla.
• Las etapas de juicio y verificación llevan un modelo fuerte elegido explícitamente, mejorado en capacidad en lugar de multiplicado en cantidad.
• Nada depende de la herencia para lo que importa: modelo, effort, rutas de salida, límites. Los valores por defecto heredados son contexto, y el contexto cambia entre sesiones.
• Los límites declarados siguen coincidiendo con la realidad: un tope de top-N o una política de omitir reintentos que tenía sentido en el momento de escribir el script puede truncar silenciosamente las entradas más grandes de hoy.

El principio más profundo va más allá del enrutamiento de modelos: una automatización persistida es una fotografía de supuestos. El modelo de la sesión, el panorama de cuotas, la estructura de directorios, los límites de tasa de la API, incluso qué archivos existen: todo eso era cierto cuando se escribió el script y nada de ello está garantizado hoy. Fija con precisión de versión lo que no debe cambiar (opciones explícitas), y reverifica en el relanzamiento lo que no se puede fijar (el entorno). Trata un workflow polvoriento como un script de despliegue polvoriento: no apuntarías el despliegue del mes pasado a la producción de hoy sin leerlo antes.

Una convención práctica que hace la auditoría casi gratuita: mantén un comentario de cabecera en cada workflow persistido indicando su tabla de enrutamiento (qué etapas corren en qué modelo y por qué) y la fecha de la última auditoría. La comprobación de relanzamiento entonces toma treinta segundos de comparar la cabecera con el código, en lugar de diez minutos de volver a deducir la intención a partir de la estructura del pipeline.