> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Gateway Route Bindings
> Route inbound messages to the right agent by sender, role, channel, or bot account โ with priority.
The gateway now ships in the `praisonai-bot` package. `praisonai serve gateway` still works exactly as documented here; for a standalone install see [praisonai-bot Migration](/docs/guides/praisonai-bot-migration).
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
vip_agent = Agent(name="vip-agent", instructions="Handle VIP user requests with priority.")
support_agent = Agent(name="support", instructions="Handle general support queries.")
vip_agent.start("Route messages from user 123 to me, all others to support.")
```
Route bindings let one gateway send the right message to the right agent โ by who sent it, what role they have, which channel it landed in, or which bot account received it.
The user messages a channel; route bindings map that channel to the correct agent or workflow.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
subgraph "Route Bindings"
Msg[๐ฉ Inbound Message] --> Facts[๐ง Extract Facts
peer ยท role ยท channel ยท account]
Facts --> Resolve{๐ฏ Match Binding
most-specific first}
Resolve -->|peer match| VIP[๐ VIP Agent]
Resolve -->|role match| Support[๐ Support Agent]
Resolve -->|channel match| Ops[โ๏ธ Ops Agent]
Resolve -->|fallback| Default[๐ค Default Agent]
end
classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
classDef process fill:#F59E0B,stroke:#7C90A0,color:#fff
classDef agent fill:#10B981,stroke:#7C90A0,color:#fff
class Msg input
class Facts,Resolve process
class VIP,Support,Ops,Default agent
```
## Quick Start
Start with a single default route โ no bindings needed.
```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
agents:
general:
instructions: "You are a helpful assistant"
model: gpt-4o-mini
channels:
telegram:
token: ${TELEGRAM_BOT_TOKEN}
routes:
default: general
```
Add a `bindings:` entry with `peer:` set to the user's Telegram numeric id. The VIP agent handles that user; everyone else still goes to `general`.
```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
agents:
general:
instructions: "You are a helpful assistant"
model: gpt-4o-mini
vip:
instructions: "You are the VIP concierge."
model: gpt-4o
channels:
telegram:
token: ${TELEGRAM_BOT_TOKEN}
routes:
default: general
bindings:
- { peer: "12345678", agent: vip }
```
Stack multiple bindings โ the most specific rule wins automatically.
```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
channels:
telegram:
token: ${TELEGRAM_BOT_TOKEN}
routes:
default: general
bindings:
- { peer: "12345678", agent: vip }
- { role: support, agent: support }
- { channel_id: "-100999", agent: ops }
- { chat_type: dm, agent: assistant }
```
A user with id `12345678` always gets `vip`. A support-role member who DMs the bot gets `support` (role beats chat type). The `ops` channel routes to the ops agent. All other DMs go to `assistant`. Everything else falls back to `general`.
Add `trust:` to any binding to scope the toolset the model sees โ strangers get a safe subset, your operator keeps full power.
```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
gateway:
routes:
- { chat_type: dm, agent: assistant, trust: untrusted } # safe subset for strangers
- { peer: "operator-123", agent: assistant, trust: trusted } # full toolset for the operator
- { channel_id: "ops", agent: assistant, deny_tools: [shell, delete_file] }
```
See [Gateway Tool Policy](/docs/features/gateway-tool-policy) for the full security reference.
***
## How It Works
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
participant User
participant Bot as Telegram/Discord/Slack Bot
participant Gateway
participant Resolver as resolve_route()
participant Agent
User->>Bot: Sends a message
Bot->>Gateway: Inbound facts (peer, roles, channel_id, account, chat_type)
Gateway->>Resolver: bindings + facts + default_agent
Resolver-->>Gateway: RouteMatch (agent + reason)
Gateway->>Agent: Dispatch to chosen agent
Agent-->>User: Reply
```
The gateway resolves the target agent in four deterministic steps:
| Step | What the gateway does |
| ---- | ------------------------------------------------------------------------------------------------------------------------- |
| 1 | Extracts `peer`, `roles`, `channel_id`, `account`, `chat_type` from the inbound message |
| 2 | Tries every `bindings:` rule, keeps only the ones that match |
| 3 | Sorts surviving matches: higher `priority` wins, then higher specificity, then declaration order |
| 4 | If no binding matches, falls back to `routes[chat_type]`, then `routes["default"]`, then the literal agent id `"default"` |
***
## Routes vs Bindings
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TD
Q1{Do you only need to route
by chat type โ dm / group / channel?}
Q1 -->|Yes| Routes[Use flat routes: map only]
Q1 -->|No| Q2{Do you need to route by
user, role, channel id, or bot account?}
Q2 -->|Yes| Bindings[Use bindings:
keep routes: default as fallback]
Q2 -->|Not sure| Both[Use both โ bindings: for specific cases,
routes: for fallback]
classDef question fill:#F59E0B,stroke:#7C90A0,color:#fff
classDef answer fill:#10B981,stroke:#7C90A0,color:#fff
class Q1,Q2 question
class Routes,Bindings,Both answer
```
***
## Configuration Options
Each entry in the `bindings:` list is a `RouteBinding`:
| Field | Type | Default | Description |
| ------------- | --------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agent` | `str` | *required* | Agent id to route to when this binding matches |
| `chat_type` | `Optional[str]` | `None` | `"dm"` \| `"group"` \| `"channel"` |
| `peer` | `Optional[str]` | `None` | Sender/user id (most specific) |
| `role` | `Optional[str]` | `None` | Role / guild-role membership of the sender |
| `channel_id` | `Optional[str]` | `None` | Specific chat/channel id |
| `account` | `Optional[str]` | `None` | Receiving bot account (multi-account channels) |
| `priority` | `int` | `0` | Higher wins; ties broken by specificity then declaration order |
| `trust` | `Optional[str]` | `None` | Trust tier โ `"untrusted"` \| `"standard"` \| `"trusted"`. `untrusted` applies a conservative deny-list (no shell, no file mutation, no delegation, no self-scheduling). **Unknown values fail closed to `untrusted`**. |
| `allow_tools` | `Optional[List[str]]` | `None` | Only these tool names are exposed on this route. Accepts a YAML scalar or list. |
| `deny_tools` | `Optional[List[str]]` | `None` | Tool names removed before the run on this route. Layers on top of the trust tier's deny-list. Accepts a YAML scalar or list. |
All non-`None` conditions in a binding must match the inbound message for that binding to apply. A binding with no conditions always matches.
**Specificity weights** โ when two bindings both match, the one with the higher total specificity wins:
| Field | Specificity weight |
| ------------ | ------------------ |
| `peer` | 16 (most specific) |
| `role` | 8 |
| `channel_id` | 8 |
| `account` | 4 |
| `chat_type` | 2 |
Ties on `(priority, specificity)` are broken by **declaration order** โ the first matching binding in your list wins.
***
## Common Patterns
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
from praisonaiagents.gateway import RouteBinding, RouteFacts, resolve_route
vip = Agent(name="vip", instructions="You are the VIP concierge.")
general = Agent(name="general", instructions="You are the general assistant.")
bindings = [
RouteBinding(agent="vip", peer="12345678"),
RouteBinding(agent="general", chat_type="dm"),
]
facts = RouteFacts(chat_type="dm", peer="12345678")
match = resolve_route(bindings, facts, default_agent="general")
print(match.agent) # "vip"
print(match.reason) # "matched binding (priority=0, specificity=16)"
```
**VIP customer gets a dedicated agent**
```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
channels:
telegram:
token: ${TELEGRAM_BOT_TOKEN}
routes:
default: general
bindings:
- { peer: "12345678", agent: vip }
```
**Support-role members (Discord) get the support agent; everyone else gets general**
```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
channels:
discord:
token: ${DISCORD_BOT_TOKEN}
routes:
default: general
bindings:
- { role: support, agent: support }
```
**Force an override regardless of specificity using `priority`**
```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
channels:
telegram:
token: ${TELEGRAM_BOT_TOKEN}
routes:
default: general
bindings:
- { peer: "12345678", agent: vip }
- { chat_type: dm, agent: incident_responder, priority: 100 }
```
The `incident_responder` binding has `priority: 100` so it wins over the `peer` match for user `12345678`, even though `peer` has higher specificity. Use this for incident-mode overrides.
**Lock down stranger DMs while keeping operator at full power**
```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
channels:
telegram:
token: ${TELEGRAM_BOT_TOKEN}
routes:
default: assistant
bindings:
- { chat_type: dm, agent: assistant, trust: untrusted }
- { peer: "operator-123", agent: assistant, trust: trusted }
```
Strangers who DM the bot never see shell, file-mutation, delegation, or scheduling tools. Your operator (`peer: "operator-123"`) retains the full toolset. See [Gateway Tool Policy](/docs/features/gateway-tool-policy) for the complete security reference.
***
## Best Practices
Bindings are evaluated first, but `routes.default` is the safety net when nothing matches. Without it, unmatched messages silently go to an agent named `"default"` โ which may not exist.
```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
routes:
default: general # always include this
bindings:
- { peer: "12345678", agent: vip }
```
Let the resolver pick by specificity โ `peer` beats `role` beats `channel_id` beats `account` beats `chat_type`. Reach for `priority` only when you genuinely need to override, such as an incident-mode binding that must win regardless of user identity.
Telegram numeric ids and Discord channel ids are stable. Display names and usernames change. Use the numeric id from the platform โ never a username or handle.
If your list grows past \~10 entries, consider grouping users by role at the platform level and binding on `role` instead of individual `peer` ids. A long list of peer bindings is hard to audit and easy to break.
***
## Related
The simpler chat-type routing surface โ route by dm, group, or channel.
Run one bot per role on the same platform using multiple channel entries.
Full reference for trust-tiered toolset scoping โ keep stranger DMs from running shell on your server.
Second line of defence โ require human confirmation before risky tools run.