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.