Skip to content
Nappai Documentation

Router Agent

The Router Agent acts as the central decision-maker or “brain” for your automation workflows. Its primary purpose is to analyze the text of a user’s request or command and determine which specialized agent should handle that specific task.

Think of it as a smart receptionist who listens to your question, understands what you need, and then directs you to the correct department. Instead of you having to manually select different tools or agents, the Router Agent automatically ensures your query is sent to the expert best equipped to answer it, whether that involves data retrieval, code execution, or general conversation.

How it Works

The Router Agent uses Artificial Intelligence (specifically Large Language Models) to understand the intent behind your text.

  1. Analysis: When you provide a text input, the agent analyzes the words and context.
  2. Decision: It compares your input against a set of predefined “intentions” or agent descriptions that you have configured.
  3. Routing: Based on the analysis, it selects the best match and sends the data to that specific agent.

This process happens instantly behind the scenes, allowing you to build complex workflows where a single starting point can branch out to many different specialized tools based on what you ask.

Connection & Credentials

This component does not require configuring external credentials (such as API keys for Google or OpenAI) directly within this node. However, the Model input typically requires you to connect a pre-configured AI Model from the Nappai library. You must ensure that a compatible Language Model is available in your workspace to be selected in the Model field.

Inputs

The following fields are available to configure this component. Each field may be visible in different operations:

  • Agent Name: The name of the agent. Used when the agent is exposed as a tool.
  • Agent Description: Description of what this agent does. Useful when using the agent as a tool.
  • Data Input: The input data to be routed. The router will analyze the data and route it to the appropriate intention.
  • System Prompt: Additional instructions appended to the router’s internal prompt.
  • Tools: Tools that the agent can use to perform actions.
  • Model: The language model to use for intention analysis.
  • Memory: Optional short-term and long-term memory for the agent.
  • Max Iterations: Maximum number of agent iterations before stopping.
  • Stream: Enable streaming to receive the agent’s response as it is being generated.
  • Stream Thinking: Enable streaming to receive the agent’s thinking as it is being generated.
  • Number of Intentions: Number of intentions to create. Each intention will have its own name and description inputs.
  • Confidence Threshold: Minimum certainty level to classify intentions (0.0 - 1.0). Recommended value: 0.7.
  • Use memory: Enable Memory to save the agent’s state at each step, allowing for stateful conversations.
  • Memory Strategy: Strategy to manage memory.
  • Memory Limit: Maximum number of messages to retrieve from memory. Use -1 for unlimited.

Outputs

This component does not produce a direct text response for the user. Instead, its “output” is the decision of which path to take next in your workflow.

When this node executes, it determines the next_node (the next agent or step in your automation). This decision is passed to the rest of the workflow, effectively acting as a gatekeeper that ensures the correct downstream tools receive the data.

Output Data Example (JSON)

While the primary output is the control flow direction, the internal state may contain metadata about the routing decision: json { “next_node”: “data_analysis_agent”, “routing_confidence”: 0.95, “selected_intention”: “analyze_sales_data” }

Connectivity

This component is typically the first node in a multi-agent workflow or placed at a branching point.

  • Incoming Connections: It usually connects to a text input source, such as a Chat Interface, File Upload, or Previous Agent that passes along a user query.
  • Outgoing Connections: It connects to various specialized agents (e.g., “Data Agent,” “Code Agent,” “Support Agent”). The specific connection activated depends on the router’s decision.
  • Logic: It makes sense to connect this after any step where a user input might be ambiguous and needs to be directed to a specialist.

Usage Example

Imagine you are building a customer support automation for an e-commerce store.

  1. Input: You connect a Chat Input component to the Router Agent.
  2. Configuration: You configure the Number of Intentions to 2:
    • Intention 1: “Check Order Status” (Connects to an Agent that queries the database).
    • Intention 2: “Return Product” (Connects to an Agent that processes return forms).
  3. Execution:
    • If the user types “Where is my package?”, the Router Agent analyzes this intent and routes it to the “Check Order Status” agent.
    • If the user types “I want to return my shirt”, it routes it to the “Return Product” agent.

This allows you to create a single, seamless user interface that handles multiple complex tasks without the user needing to know which tool handles what.

Tips and Best Practices

  • Clear Descriptions: Ensure your “Agent Description” and “Intentions” are written clearly. The router relies on these descriptions to make decisions.
  • Confidence Threshold: Use the Confidence Threshold (recommended 0.7) to prevent misrouting. If the router is less than 70% sure of the intent, you can configure it to fallback to a generic agent or ask for clarification.
  • Context Matters: Providing Context or Memory helps the router understand follow-up questions. For example, if a user says “And what about the blue one?”, the router needs previous context to know which product is being discussed.
  • Keep it Simple: Start with fewer intentions. As your workflow grows, add more specific intentions to handle niche queries.

Security Considerations

  • Data Privacy: Ensure that any sensitive data passed through the Data Input is handled securely by the downstream agents. The router itself does not store data but passes it along.
  • Access Control: Verify that the specialized agents connected to the router have the appropriate permissions to access the data they receive.