Saltearse al contenido
Nappai Documentation

Supervisor Agent

El Supervisor Agent es un componente que actúa como el cerebro de un flujo de trabajo. Recibe una lista de agentes que pueden realizar tareas específicas (los Worker Agents) y decide cuál usar, cuándo cambiar de modelo o cuándo pasar la conversación a otro agente. Es ideal para crear procesos complejos donde varias tareas deben coordinarse sin intervención humana.

¿Cómo funciona?

Internamente el Supervisor Agent construye un grafo de ejecución (Langgraph) que conecta los agentes de trabajo y los modelos de lenguaje. Cuando se inicia, envía el mensaje inicial al modelo seleccionado, recibe la respuesta y, según la lógica definida, puede:

  1. Delegar la tarea a un Worker Agent.
  2. Cambiar a un modelo de respaldo si el principal falla.
  3. Añadir mensajes de handoff para que la conversación continúe con otro agente.
  4. Mantener un estado interno personalizado para recordar información entre iteraciones.

No necesita ninguna API externa aparte de los modelos de lenguaje que el usuario haya configurado (por ejemplo, OpenAI, Anthropic, etc.). Todo el procesamiento ocurre dentro del entorno de Nappai.

Entradas

Campos de Entrada

  • Worker Agents: Lista de agentes que pueden realizar tareas.
  • Fallback: Modelo de chat de respaldo que se usará si el modelo principal no está disponible.
  • Model: Modelo de lenguaje que el supervisor utilizará para generar respuestas.
  • Tools: Herramientas que el agente puede usar para ejecutar acciones (por ejemplo, llamadas a APIs externas).
  • Use as Router: Si se activa, el agente solo decide a quién enviar la tarea y no genera la respuesta final.
  • Add Handoff Back Messages: Si se activa, el agente añade mensajes que indican que la conversación vuelve a un agente anterior.
  • Add Handoff Messages: Si se activa, el agente añade mensajes que indican que la conversación pasa a otro agente.
  • State custom schema: Especifica campos adicionales que el agente debe mantener en su estado interno. Se escribe como un esquema JSON.
  • Enable Fallback Model: Habilita el uso del modelo de respaldo cuando el principal falla.
  • Agent Description: Descripción útil cuando el agente se usa como herramienta o hijo de otro supervisor.
  • Agent Name: Nombre del ejecutor que se usará.
  • Input: Mensaje inicial que inicia la conversación con el agente.
  • Max Execution Time: Tiempo máximo (en segundos) que el agente puede tardar en ejecutarse.
  • Max Iterations: Número máximo de iteraciones que el agente puede realizar antes de detenerse.
  • Memory top message: Cantidad de mensajes que se pasan como contexto. Usa -1 para pasar todos los mensajes.
  • Output Mode: Nombre del ejecutor que se usará para generar la salida.
  • Structured Output Schema: Esquema JSON que define el formato que debe seguir la respuesta del agente.
  • System Prompt: Mensaje de sistema que guía al modelo de lenguaje.
  • Tool Schema: Esquema JSON que define los argumentos que el agente aceptará cuando se use como herramienta.
  • Use short term memory: Activa el guardado del estado del agente en cada paso, permitiendo conversaciones con estado.
  • Stream: Si se activa, la respuesta se envía en tiempo real a medida que se genera.
  • User Prompt: Mensaje del usuario que inicia la conversación.
  • Verbose: Activa el registro detallado del proceso interno del agente.

Salidas

  • Agent: Un objeto CompiledGraph que representa el grafo de ejecución construido.
  • Response: Un objeto Message con la respuesta final del agente.
  • Tool: Un objeto BaseTool que puede usarse como herramienta en otros agentes.

Ejemplo de Uso

Supongamos que quieres crear un flujo donde un agente supervisa la generación de informes y delega la tarea de extraer datos a un Worker Agent llamado DataExtractor.

  1. Arrastra el componente Supervisor Agent al lienzo.
  2. En Worker Agents escribe DataExtractor.
  3. En Model selecciona gpt-4o.
  4. En Fallback selecciona gpt-3.5-turbo.
  5. Activa Enable Fallback Model.
  6. En Input escribe: “Genera un informe mensual de ventas.”
  7. Ejecuta el flujo.
    El Supervisor enviará la solicitud al modelo gpt-4o. Si la respuesta indica que necesita datos, delegará a DataExtractor. Si gpt-4o falla, usará gpt-3.5-turbo gracias al fallback.

Componentes Relacionados

  • Worker Agent – Agente que realiza tareas específicas (por ejemplo, extracción de datos, envío de correos).
  • LanggraphSupervisorAgentBase – Clase base que contiene la lógica común para todos los supervisores Langgraph.
  • BaseTool – Herramienta que puede ser llamada por agentes para ejecutar acciones externas.

Consejos y Mejores Prácticas

  • Elige el modelo correcto: Usa un modelo potente para tareas complejas y un modelo más ligero como fallback para ahorrar costos.
  • Define un esquema de salida: Si necesitas respuestas estructuradas (por ejemplo, JSON), especifica un Structured Output Schema para evitar errores.
  • Limita el tiempo y las iteraciones: Establece Max Execution Time y Max Iterations para evitar bucles infinitos.
  • Activa Verbose solo cuando necesites depurar: El registro detallado puede generar mucha información.
  • Usa Use short term memory cuando la conversación dependa de pasos anteriores: Así el agente recuerda el contexto sin perder rendimiento.

Consideraciones de Seguridad

  • Protege los datos sensibles: Si el agente maneja información confidencial, asegúrate de que el modelo y las herramientas estén configurados con las políticas de privacidad adecuadas.
  • Control de acceso: Limita quién puede crear y ejecutar supervisores que tengan acceso a modelos de alto costo o a datos críticos.
  • Revisa los logs: Cuando Verbose está activado, revisa los registros para detectar posibles filtraciones de información.