Supervisor Pattern (Multi-Agente Jerárquico)

1. Visión general del concepto y problema sistémico

Al crear sistemas con múltiples agentes, los desarrolladores a menudo enfrentan el problema de la coordinación. Si los agentes simplemente envían mensajes entre sí en un chat grupal:

• Se pierde el objetivo: Los agentes comienzan a comentar las réplicas de sus colegas, olvidando la solicitud inicial del usuario.
• Crecimiento incontrolado del contexto: Cada agente ve el registro completo de mensajes de todos los demás agentes, lo que lleva a un consumo cuadrático de tokens y degradación de la atención.
• Falta de determinismo: No se puede garantizar que la tarea se haya resuelto realmente, en lugar de simplemente silenciarse.

El Supervisor Pattern implementa una jerarquía de ingeniería clásica: un orquestador central (Supervisor) interactúa con el usuario, construye un plan de ejecución, lo descompone en tareas aisladas, las asigna a agentes objetivo (Specialist Workers) y agrega el resultado final.

2. Taxonomía arquitectónica y modelo mental

                       ┌─────────────────────────┐
                       │       USER PROMPT       │
                       └────────────┬────────────┘
                                    │
                                    ▼
                       ┌─────────────────────────┐
                       │    SUPERVISOR AGENT     │
                       │  (State, Plan & Router) │
                       └───┬────────┬────────┬───┘
                           │        │        │
           ┌───────────────┘        │        └───────────────┐
           │ Task A                 │ Task B                 │ Task C
           ▼                        ▼                        ▼
┌────────────────────┐   ┌────────────────────┐   ┌────────────────────┐
│   RESEARCH AGENT   │   │    CODER AGENT     │   │     QA AGENT       │
│ (Search, Docs, RAG)│   │ (AST, Git, Patch)  │   │(Evals, Tests, Lint)│
└──────────┬─────────┘   └──────────┬─────────┘   └──────────┬─────────┘
           │                        │                        │
           └───────────────┐        │        ┌───────────────┘
                           ▼        ▼        ▼
                       ┌─────────────────────────┐
                       │   AGGREGATED ARTIFACT   │
                       └─────────────────────────┘

1. Máquina de Estados / Router: El supervisor contiene un autómata finito de estados. Después de cada paso, evalúa: ¿Completado? -> Devolver respuesta al usuario, o ¿Se necesita el siguiente paso? -> Llamar al trabajador correspondiente.
2. Encapsulación de Tareas: Cada trabajador recibe únicamente la información de entrada necesaria y su propio conjunto de herramientas (Tooling Scope). Por ejemplo, el Coder Agent no tiene acceso a la búsqueda en Google, y el Research Agent no tiene acceso a modificar el sistema de archivos.

3. Pipeline técnico y mecánica interna

Algoritmo de trabajo del supervisor:

1. Análisis de la tarea de entrada: El modelo del supervisor se invoca con un prompt del sistema que describe las competencias de cada trabajador y el esquema de retorno de decisiones (Function Calling / Structured Output).
2. Generación de la decisión de enrutamiento:

   {
     "next_worker": "coder_agent",
     "task_description": "Implementar middleware de autenticación en src/auth.ts usando Better Auth",
     "expected_artifacts": ["src/auth.ts"]
   }
   

3. Ejecución aislada del trabajador: El orquestador inicializa el contexto del trabajador, inicia su ciclo autónomo y espera el retorno del resultado.
4. Control de calidad (Evaluation Gate): Al recibir el resultado, el supervisor puede aprobarlo, redirigirlo al agente de QA para pruebas, o devolverlo al trabajador para corrección (Self-Correction Loop).

4. Escenarios prácticos de ingeniería en producción

01. Creación autónoma de funcionalidad compleja

El usuario solicita: "Agrega al proyecto la exportación de informes en PDF con gráficos". El supervisor invoca:

1. Research Worker — encuentra la biblioteca adecuada, verifica la licencia.
2. Backend Worker — crea el endpoint API y el generador de informes.
3. Frontend Worker — añade un botón en la UI y un indicador de carga.
4. Tester Worker — ejecuta pruebas de Playwright.

02. Manejo y resolución de incidentes de seguridad

El supervisor reacciona a una alerta en Sentry, pasa el stack trace al agente de diagnóstico, valida el hotfix propuesto en el agente de pruebas y crea un pull request.

5. Errores comunes, trampas y seguridad

• Deadlock Loops (Ciclos de bloqueo entre el supervisor y el trabajador): El supervisor considera que la tarea no se ha completado completamente y la devuelve al trabajador. El trabajador devuelve el mismo código. Solución: establecer max_iterations = 5 con lanzamiento de error a un humano.
• Context Bleed (Contaminación de la memoria del supervisor): Si el trabajador devuelve 10,000 líneas de código, el contexto del supervisor se llena rápidamente. Los trabajadores deben almacenar el código en el sistema de archivos y devolver solo el estado y el diff.
• Single Point of Failure: Si el modelo del supervisor alucina y elige al trabajador incorrecto, todo el sistema se desvía. Es necesario tener verificaciones claras de invariantes antes de la invocación.