Supervisor Agent

`Supervisor Agent`

The Supervisor Agent is the hierarchical “brain” of the NappAI platform. Its primary function is AI team management: it receives a global request, analyzes which specialists (Worker Agents) are needed to solve it, and decides the execution order, information transfer, and task closure.

Unlike a standard agent, the Supervisor doesn’t just execute tools; it manages the lifecycle of other agents. This allows for the construction of multi-agent systems capable of solving problems that a single model couldn’t handle alone due to context limits or lack of specialization.

Main Use Cases

Use the Supervisor Agent to develop solutions requiring:

Multi-Agent Flows: Coordinating a team where one agent researches (Research Agent), another writes (Writer Agent), and a third translates (Translator Agent).
Intelligent Task Routing: Dynamically deciding which agent should handle a request based on its content.
Centralized Supervision Processes: Maintaining a global conversation state while different specialists intervene in specific steps.
Resilience Systems: Implementing fallback models that take control if the main supervisor encounters errors.

Fundamental Configuration

These parameters form the basis of the reasoning and structure of the supervision team.

Parameter	Technical Description	Purpose in the Flow
`Input`	The initial message or payload that triggers the supervisor’s logic.	Represents the complex request that the supervisor must break down and delegate.
`System Prompt`	Critical instructions defining behavior and delegation rules.	Critical Note: For optimal performance, this prompt must explicitly include the names of the agents to be supervised and a clear description of each one’s responsibility.
`User Prompt`	Template (e.g., `{input}`) that wraps user input before processing.	Formats the request so the supervisor interprets it correctly within its reasoning cycle.
`Model`	The main language engine (LLM) acting as the supervisor.	Responsible for making decisions on whom to delegate to and when to finalize the task.
`Worker Agents`	Connection to the list of subordinate agents available to this supervisor.	Defines the “team of specialists” the supervisor is permitted to invoke.
`Tools`	Additional tools that the supervisor itself can execute directly.	Allows the supervisor to perform quick actions without needing to delegate to a worker.

Advanced Features (`Advanced`)

The Supervisor Agent includes precise controls to manage state transfer and execution limits.

Orchestration and Routing: Flow Control

Use As Router: If activated, the agent functions exclusively as a classifier. It will only decide which worker to send the task to and pass control, without attempting to generate a final response itself.
Add Handoff Messages / Add Handoff Back Messages: Controls the insertion of technical “transfer” messages. This allows explicit tracking of when the conversation moves to a worker and when the worker returns control to the supervisor.
State Custom Schema: Allows defining a JSON schema to extend the supervisor’s memory. Useful for maintaining global variables (e.g., project_status, client_id) that all workers must be aware of.

Execution Limits: Security and Costs

Max Iterations: Sets the maximum number of “back and forth” cycles between the supervisor and workers. This prevents infinite loops in case the agents fail to reach a consensus.
Max Execution Time: Time limit in seconds for the total graph execution. Ensures the flow does not remain blocked.

Context and Memory: Session Management

Use Short Term Memory: Enables the checkpointer so the supervisor remembers decisions made in previous steps of the same session, allowing for coherent iterative flows.
Memory Top Message: Defines how many messages from the history are sent as context. A value of -1 indicates that the entire available history should be sent.

Output and Debugging: Format and Visibility

Structured Output Schema: Forces the supervisor to deliver its conclusion in a specific JSON format, ideal for integrations with other systems.
Stream / Verbose: Stream allows viewing the response in real-time. Verbose activates detailed logs of every delegation decision, essential for debugging complex multi-agent flows.

Component Outputs

Response: The final message generated after the coordination of all involved workers.
Agent: The CompiledGraph object encapsulating the entire supervision hierarchy.
Tool: A version of the supervisor converted into a tool, allowing this team to be, in turn, supervised by a higher-level agent.

Tips and Best Practices

Clarity in the System Prompt: A supervisor is only as good as its instructions. Be explicit: “You have ‘DataAnalyst’ for calculations and ‘Writer’ for texts at your disposal. If the query is about numbers, call ‘DataAnalyst’ first.”
Adjust Iterations: For simple Q&A flows, a Max Iterations of 10 is usually enough. For deep research processes, consider values closer to 50.
Use Output Structures: If the supervisor needs to feed a database, always define a Structured Output Schema to avoid parsing errors in the final response.

Supervisor Agent