Supervisor Agent

`Supervisor Agent`

El Supervisor Agent es el “cerebro” jerárquico de la plataforma NappAI. Su función principal es la gestión de equipos de IA: recibe una solicitud global, analiza qué especialistas (Worker Agents) son necesarios para resolverla y decide el orden de ejecución, la transferencia de información y el cierre de la tarea.

A diferencia de un agente estándar, el Supervisor no solo ejecuta herramientas, sino que gestiona el ciclo de vida de otros agentes, permitiendo construir sistemas multi-agente capaces de resolver problemas que un solo modelo no podría abordar por sí solo debido a límites de contexto o especialización.

Casos de Uso Principales

Utilice el Supervisor Agent para desarrollar soluciones que requieran:

Flujos Multi-Agente: Coordinar un equipo donde un agente investiga (Research Agent), otro redacta (Writer Agent) y un tercero traduce (Translator Agent).
Enrutamiento Inteligente de Tareas: Decidir dinámicamente qué agente debe atender una solicitud basándose en el contenido de la misma.
Procesos con Supervisión Centralizada: Mantener un estado global de la conversación mientras diferentes especialistas intervienen en pasos específicos.
Sistemas de Resiliencia: Implementar modelos de respaldo (fallback) que tomen el control si el supervisor principal encuentra errores.

Configuración Fundamental

Estos parámetros constituyen la base del razonamiento y la estructura del equipo de supervisión.

Parámetro	Descripción Técnica	Propósito en el Flujo
`Input`	El mensaje inicial o payload que activa la lógica del supervisor.	Representa la solicitud compleja que el supervisor debe desglosar y delegar.
`System Prompt`	Instrucciones críticas que definen el comportamiento y las reglas de delegación.	Nota Crítica: Para un funcionamiento óptimo, este prompt debe incluir explícitamente los nombres de los agentes a supervisar y una descripción clara de la responsabilidad de cada uno.
`User Prompt`	Plantilla (ej. `{input}`) que envuelve la entrada del usuario antes de ser procesada.	Formatea la solicitud para que el supervisor la interprete correctamente en su ciclo de razonamiento.
`Model`	El motor de lenguaje (LLM) principal que actuará como supervisor.	Es el encargado de tomar las decisiones de a quién delegar y cuándo dar por finalizada la tarea.
`Worker Agents`	Conexión a la lista de agentes subordinados disponibles para este supervisor.	Define el “equipo de especialistas” que el supervisor tiene permitido invocar.
`Tools`	Herramientas adicionales que el propio supervisor puede ejecutar directamente.	Permite al supervisor realizar acciones rápidas sin necesidad de delegar en un worker.

Funcionalidades Avanzadas (`Avanzado`)

El Supervisor Agent incluye controles precisos para gestionar la transferencia de estado y los límites de ejecución.

Orchestration and Routing: Control del Flujo

Use As Router: Si se activa, el agente funcionará exclusivamente como un clasificador. Solo decidirá a qué worker enviar la tarea y pasará el control, sin intentar generar una respuesta final por sí mismo.
Add Handoff Messages / Add Handoff Back Messages: Controla la inserción de mensajes técnicos de “transferencia”. Permite rastrear explícitamente cuándo la conversación pasa a un worker y cuándo el worker devuelve el control al supervisor.
State Custom Schema: Permite definir un esquema JSON para extender la memoria del supervisor. Útil para mantener variables globales (ej. status_proyecto, cliente_id) que todos los workers deben conocer.

Execution Limits: Seguridad y Costos

Max Iterations: Establece el número máximo de ciclos de “ida y vuelta” entre el supervisor y los workers. Evita bucles infinitos en caso de que los agentes no lleguen a un consenso.
Max Execution Time: Límite de tiempo en segundos para la ejecución total del grafo. Garantiza que el flujo no quede bloqueado.

Context and Memory: Gestión de Sesión

Use Short Term Memory: Habilita el checkpointer para que el supervisor recuerde las decisiones tomadas en pasos anteriores de la misma sesión, permitiendo flujos iterativos coherentes.
Memory Top Message: Define cuántos mensajes del historial se envían como contexto. El valor -1 indica que se debe enviar todo el historial disponible.

Output and Debugging: Formato y Visibilidad

Structured Output Schema: Fuerza al supervisor a entregar su conclusión en un formato JSON específico, ideal para integraciones con otros sistemas.
Stream / Verbose: Stream permite ver la respuesta en tiempo real. Verbose activa logs detallados de cada decisión de delegación, esencial para la depuración de flujos multi-agente complejos.

Salidas del Componente

Response: El mensaje final generado tras la coordinación de todos los workers involucrados.
Agent: El objeto CompiledGraph que encapsula toda la jerarquía de supervisión.
Tool: Versión del supervisor convertida en herramienta, permitiendo que este equipo sea, a su vez, supervisado por un agente de nivel superior.

Consejos y Mejores Prácticas

Claridad en el System Prompt: Un supervisor es tan bueno como sus instrucciones. Sea explícito: “Tienes a tu disposición a ‘AnalistaDatos’ para cálculos y a ‘Redactor’ para textos. Si la duda es sobre números, llama primero a ‘AnalistaDatos’.”
Ajuste las Iteraciones: Para flujos simples de pregunta-respuesta, una Max Iterations de 10 es suficiente. Para procesos de investigación profunda, considere valores cercanos a 50.
Use Estructuras de Salida: Si el supervisor debe alimentar una base de datos, defina siempre un Structured Output Schema para evitar errores de parseo en la respuesta final.

Supervisor Agent