Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.automagik.dev/llms.txt

Use this file to discover all available pages before exploring further.

​
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: 
Message arrives → Check per-user route → Check per-chat route → Check per-instance route → No agent (unrouted)
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: 
omni routes create --instance <instance-id> --agent <agent-id>

​
Per-Chat Override

Route a specific conversation to a different agent: 
omni routes create --instance <instance-id> --chat <chat-id> --agent <agent-id>

​
Per-User Override

Route all messages from a specific person to a dedicated agent: 
omni routes create --instance <instance-id> --person <person-id> --agent <agent-id>

​
Testing Routes

Before going live, test how Omni would resolve a route: 
omni routes test --instance <instance-id> --chat <chat-id> --person <person-id>
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. 
# List routes for an instance
omni routes list --instance <instance-id>

# Get route details
omni routes get <route-id>

# Update a route's target agent
omni routes update <route-id> --agent <new-agent-id>

# Delete a route
omni routes delete <route-id>

# View route cache metrics
omni routes metrics

​
Common Patterns

​
Default Agent + VIP Override

# Default: all messages go to support bot
omni routes create --instance $INST --agent $SUPPORT_BOT

# Override: VIP customer gets a dedicated agent
omni routes create --instance $INST --person $VIP_ID --agent $VIP_AGENT

​
Channel-Specific Agents

# WhatsApp instance → Portuguese-speaking agent
omni routes create --instance $WA_INST --agent $PT_AGENT

# Discord instance → English-speaking agent
omni routes create --instance $DC_INST --agent $EN_AGENT
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.