Skip to content
Nappai Documentation

Supervisor Agent

The Supervisor Agent is a ready‑made tool that lets you create a powerful “supervisor” in your Nappai dashboard. It takes a list of worker agents, a language model, and optional settings, and builds a single agent that can route tasks, handle failures, and keep track of the conversation. Think of it as a traffic controller that decides which worker should do what and what to do if something goes wrong.

How it Works

When you drop the Supervisor Agent into a workflow, it pulls together all the inputs you provide. It builds a compiled graph that connects the chosen language model, any tools, and the worker agents you list. If you enable fallback options, it also keeps a backup model ready to step in if the primary one fails. The agent can remember past messages, stream responses as they’re generated, and even add hand‑off messages to the conversation history so other agents know what’s happening. All of this happens locally inside Nappai; no external API calls are required beyond the language model you choose.

Inputs

  • Worker Agents: The list of worker agents that the supervisor will manage.
  • Fallback: A backup chat model to use when the primary model fails or isn’t available.
  • Model (required): The language model that the supervisor will use to generate responses.
  • Tools: A list of tools that the supervisor can call to perform actions.
  • Use as Router: If set to True, the supervisor will act only as a router and will not generate the final output.
  • Add Handoff Back Messages: If True, the supervisor will add hand‑off back messages to the conversation.
  • Add Handoff Messages: If True, the supervisor will add hand‑off messages to the conversation history.
  • State custom schema: Define additional fields for the agent’s internal state. Provide a JSON schema with the fields you want to add.
  • Enable Fallback Model: Whether to enable a fallback model. When enabled, connect a backup chat model to use in case the primary model fails or isn’t available.
  • Agent Description: A useful description when using the agent as a tool or child of a supervisor schema.
  • Agent Name: The name of the executor to use.
  • Input: The initial input message for the agent to start the conversation.
  • Max Execution Time: The maximum execution time in seconds for the agent.
  • Max Iterations: The maximum number of iterations to run the agent for.
  • Memory top message: The number of messages to pass to the agent as context. Use -1 to pass all messages.
  • Output Mode: The name of the executor to use.
  • Structured Output Schema: Define the format for the agent’s response. Provide a JSON schema for the expected output.
  • System Prompt: System prompt for the agent.
  • Tool Schema: Defines the input schema for this agent when it is used as a tool by another agent. Provide a JSON schema for the arguments.
  • Use short term memory: Enable the checkpointer to save the agent’s state at each step, allowing for stateful conversations.
  • Stream: Enable streaming to receive the agent’s response as it is being generated.
  • User Prompt: User prompt for the agent.
  • Verbose: Enable verbose logging to see the agent’s thought process and actions in detail.

Outputs

  • Agent: A compiled graph that can be executed in Nappai.
  • Response: The final message produced by the agent.
  • Tool: A base tool that can be used by other agents.

Usage Example

  1. Add the Supervisor Agent to your workflow.
  2. Configure the inputs:
    • Choose a language model (e.g., GPT‑4).
    • List the worker agents you want to supervise (e.g., “DataFetcher”, “ReportGenerator”).
    • Optionally set a fallback model and enable fallback.
    • Provide a system prompt that tells the supervisor how to behave.
  3. Run the workflow. The supervisor will start the conversation, decide which worker should handle each request, and return the final response.
  4. Use the outputs: Connect the Response output to a display component, or use the Agent output to chain another supervisor.
  • Worker Agent – A simple agent that performs a single task.
  • LanggraphAgent – A general-purpose agent that can be used as a worker.
  • Tool – A reusable tool that can be called by any agent.
  • Fallback Agent – An agent that activates when the primary model fails.

Tips and Best Practices

  • Keep the Model input to a single, reliable model to avoid confusion.
  • Use Structured Output Schema to enforce consistent responses that downstream components can parse easily.
  • Enable Stream if you want real‑time feedback in the dashboard.
  • Turn on Verbose only when debugging; it can produce a lot of logs.
  • If you have many worker agents, consider setting Use as Router to true so the supervisor only routes tasks and doesn’t generate the final answer.

Security Considerations

  • The supervisor can pass user data to the chosen language model. Make sure the model complies with your organization’s data‑privacy policies.
  • If you enable Enable Fallback Model, ensure the fallback model is also secure and compliant.
  • Use Verbose sparingly in production, as it may expose internal thoughts or sensitive data in logs.