Routing Logic

Routing Logic is an optional Nexus surface where you write plain-English rules that override or refine how each message is routed between agents and tools.

Routing Logic rules are NOT mandatory. Most Nexus bots route correctly with no rules at all - routing reads each agent's Trigger and picks based on that. Reach for Routing Logic only when you want a deterministic override on top of trigger-based routing.

How routing actually works

Every turn, one of three things happens: the message is answered directly, it is handed off to one of your agents (single agents, or a multi agent enabled as a delegation target in Routing targets below), or a tool is called.

The primary signal is each agent's Trigger - the natural-language description you write at the top of an agent's profile that says when that agent should take over. Routing reads every agent's Trigger and picks the best match against the current user message.

Example Trigger: "When the user wants to book or schedule a test ride, request a quote, ask for a callback, share contact details, or says they are interested in buying a bike soon."

If your Triggers are sharp and non-overlapping, this is enough - you don't need anything else.

Routing Logic rules are the override layer. Add a rule when:

• Two agents have overlapping Triggers and routing keeps picking the wrong one.
• You want a topic to always go to a specific agent, with no LLM judgement involved (sensitive topics, regulated content, escalations).
• You need a compound condition that's hard to express in a Trigger ("if region = X and topic = Y, route to…").

When a rule applies, it overrides the trigger-based pick. When no rule applies, the router falls back to the Triggers.

The same model applies to tools: any tool can be called directly, using each tool's description (and the agents the tool is attached to) as routing signals. Write a Routing Logic rule when you need a topic to always go through a specific tool.

Scope what routing can read. The routing decision reads memory and user properties as context. To restrict which variables the router — and the fallback reply — are allowed to see, set Allowed variables on the super agent. Leave it empty for no restriction (the default).

Start trigger = the agent's Trigger

The field labelled Trigger at the top of each agent's profile is sometimes called the agent's Start trigger. It's the same thing - the natural-language description that routing reads to decide when this agent should activate. Don't confuse it with Routing Logic:

	Start trigger (per agent)	Routing Logic (Configuration)
Where it lives	At the top of each agent's profile, in the Trigger section	On the Configuration → Routing logic sub-page
What it does	The primary routing signal - read on every turn to pick the best matching agent	Optional override rules that pin specific topics to specific agents/tools
Mandatory?	Yes - every agent needs a Trigger	No - bots route fine with no rules

You almost always start by writing sharp Triggers. Reach for Routing Logic only after you've seen routing-logic-vs-trigger collisions in real conversations.

When to use Routing Logic vs Conversation Rules

People often mix these up. Here's the rule of thumb:

You want to…	Use
Force a topic to always go to a specific agent or tool	Routing Logic
Set tone, style, "always do / never do" guidelines	Conversation Rules

Routing Logic = hard constraints on routing decisions. Conversation Rules = soft guidance on how to talk.

When the two collide, Routing Logic wins.

Routing targets

Above the Rules list, the Routing Logic page has a Routing targets section - this is what actually gates who your agent is allowed to delegate to. Rules and Triggers decide when a handoff should happen; Routing targets decides whether the target is even eligible.

It's split into two independent groups:

• Single agents - every enabled agent in the bot. Two modes:

  • All (default) - every enabled agent is a valid delegation target. New agents are included automatically as they go live - nothing to maintain.
  • Selected - pick specific agents from a searchable list (each shown with its Trigger as a hint). At least one must be selected, or the page blocks Save.
  • There's no Off for single agents - since single agents are also how the bot answers directly, they can't be switched off as delegation targets entirely.

• Multi agents - every multi agent (flow) in the bot. Three modes:

  • Off - multi agents are excluded from delegation entirely; the bot never hands off to one.
  • All - every multi agent is a valid delegation target, auto-including new ones.
  • Selected - pick specific multi agents from a searchable list.

This section only appears once your bot has agentic flows enabled; until then, only the plain-text Rules editor below is shown.

Routing targets is an allowlist layer underneath both Triggers and Routing Logic rules - it doesn't replace either. An agent has to (a) be a valid target here, and (b) actually get picked by a Trigger match or a Routing Logic rule, before a handoff happens.

Step 1: Open the Routing logic page

Go to AI Agent → Configuration and click Routing logic (under Agents in the left menu). The page only appears for Nexus agents.

The page header says "Rules to help disambiguate and refine agent routing" - that's accurate. Agent Triggers alone get you a long way; add rules only when you need to tighten. Rules are numbered and capped at 30 per bot.

Step 2: Add a rule

Click Add rule. Type your rule in plain English. Keep it concise - one or two short sentences usually beats a paragraph.

Step 3: Write rules that are testable

A good rule meets all three of these:

1. It names the trigger. What user message or condition does this rule apply to?
2. It names the action. Which agent or tool should fire?
3. It can be proven by a single test conversation.

Examples that work

• "If the user mentions billing, invoices, or refunds, hand off to billing-agent. Do not answer billing questions yourself."
• "If the user asks about an order's status, route to order-status-agent and call the getOrderStatus workflow before composing a reply."
• "If the user wants to book a demo, hand off to demo-booking-agent."
• "If the user types 'agent' or 'human', transfer to a live agent immediately. Do not try to resolve the issue first."

Examples that don't work

• "Be helpful." → Not testable. Move to Conversation Rules - and even there, it's too vague.
• "Route correctly." → Doesn't name a trigger or an action.
• "If billing, route." → Names the trigger and action but ambiguously; "billing" could mean many things, and the rule doesn't say where to route.

Step 4: Reference agents and tools by slug

Each rule is a plain-text box (up to 500 characters) - there's no @-mention picker here and no linked chip. Name the agent or tool by its slug (the identifier on its profile / tool settings, not necessarily its display name) so the rule is unambiguous:

"If the user mentions billing, invoices, or refunds, hand off to billing-agent. Do not answer billing questions yourself."

Because the reference is plain text, it does not track renames. If you later rename billing-agent to billing-team, this rule keeps saying billing-agent and silently goes stale - routing will stop finding a match. After renaming an agent or tool, search your Routing Logic rules for the old slug and update them by hand.

Step 5: Save and test

Click Save. Then open any agent and click the play (▶) icon in the title bar to launch the Playground.

For each rule you wrote:

1. Send a prompt that should trigger it.
2. Confirm the expected agent's persona takes over (or the expected tool fires).
3. If the wrong thing happens, your rule wording isn't specific enough - or an agent's Trigger is competing for the same topic. Tighten the rule (more precise trigger words, clearer action), or sharpen the Triggers of the agents involved, and retry.

Best practices

• Start with Triggers, add rules when needed. A precise agent Trigger handles most routing on its own. Add a routing rule when (a) Triggers overlap and routing isn't picking the agent you want, (b) a topic is sensitive enough that you don't want it answered directly, or (c) you need a compound condition Triggers can't express.
• One rule, one concern. "If the user mentions billing or asks about an order, route to billing or fulfillment" is a compound rule. Split it into two separate rules.
• Order doesn't matter much. Rules are evaluated together as a constraint set, not top-to-bottom. Don't agonize over ordering.
• Test edge cases. Users phrase things weirdly. After the obvious test prompt works, try misspellings, partial matches, and adjacent topics that should not match.
• Prefer specific over clever. "If the user mentions cancellation" is better than "If the user wants to leave."
• Keep a list of test prompts alongside your rules. When you tweak wording later, you'll have a regression check ready.

Common pitfalls

• Vague triggers. "If the user is upset" - what counts as upset? Use concrete signals: "If the user mentions 'frustrated', 'angry', 'unacceptable', or types in all caps, …".
• Contradictory rules. Two rules pointing at different agents for overlapping triggers will produce inconsistent routing. Re-read your list whenever you add a rule.
• Fighting your own Triggers. If your rule and the agent's Trigger point in different directions ("route refunds to support-agent" but the billing-agent's Trigger claims it handles refunds), routing will feel unpredictable. Keep rules and Triggers consistent.
• Forgetting to add a "do not" clause. "Route billing to billing-agent" is good. "Route billing to billing-agent. Do not answer billing yourself." is better - the second sentence stops the message from being answered directly instead of routed.

Continue to: Single agents.