> ## 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

> Agent routing with per-user and per-chat overrides — how messages reach the right AI agent.

# 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:

```text theme={"dark"}
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:

```bash theme={"dark"}
omni routes create --instance <instance-id> --agent <agent-id>
```

### Per-Chat Override

Route a specific conversation to a different agent:

```bash theme={"dark"}
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:

```bash theme={"dark"}
omni routes create --instance <instance-id> --person <person-id> --agent <agent-id>
```

## Testing Routes

Before going live, test how Omni would resolve a route:

```bash theme={"dark"}
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](/omni/cli/routes-persons-auth).

```bash theme={"dark"}
# 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

```bash theme={"dark"}
# 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

```bash theme={"dark"}
# 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
```

<Note>
  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.
</Note>

<Tip>
  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.
</Tip>

## See also

<CardGroup cols={2}>
  <Card title="AI Agents (concept)" icon="robot" href="/omni/concepts/agents">
    How providers, agents, and routes compose.
  </Card>

  <Card title="Instances (concept)" icon="puzzle-piece" href="/omni/concepts/instances">
    Per-channel configuration and reply filters.
  </Card>

  <Card title="Routes / Auth CLI" icon="route" href="/omni/cli/routes-persons-auth">
    Full `omni routes`, `omni persons`, `omni auth` reference.
  </Card>

  <Card title="Agents CLI" icon="terminal" href="/omni/cli/agents">
    Manage agents and inspect routing decisions.
  </Card>
</CardGroup>