Skip to main content

​
Routes

Routes are rules that determine which AI agent handles incoming messages. Omni supports hierarchical routing with per-instance defaults and per-chat/per-user overrides.

​
How Routing Works

When a message arrives on a channel instance, Omni evaluates routes in this order:
The first matching route wins. This lets you set a default agent for an instance while overriding specific conversations or users.

​
Creating Routes

​
Instance-Level Default

Route all messages from an instance to a single agent:

​
Per-Chat Override

Route a specific conversation to a different agent:

​
Per-User Override

Route all messages from a specific person to a dedicated agent:

​
Testing Routes

Before going live, test how Omni would resolve a route:
This shows which agent would handle the message and why.

​
Managing Routes

For full route, person, and auth management commands, see the routes CLI reference.

​
Common Patterns

​
Default Agent + VIP Override

​
Channel-Specific Agents

Route resolution is per-message, evaluated by omni routes test exactly the same way the dispatcher evaluates it at runtime. Use omni routes test --instance <id> --chat <id> --person <id> before going live to confirm a route override resolves to the agent you expect.
Routes are cached. Use omni routes metrics to inspect cache hit rates — if they’re low after a config change, the cache may be cold; if they’re high but you’re seeing the wrong agent, you may have a stale cache and need a process restart.

​
See also

AI Agents (concept)

How providers, agents, and routes compose.

Instances (concept)

Per-channel configuration and reply filters.

Routes / Auth CLI

Full omni routes, omni persons, omni auth reference.

Agents CLI

Manage agents and inspect routing decisions.