AI Agent Integration
Omni routes incoming messages to AI agents. You define providers (the AI backend), create agents (the entity that receives messages), and configure routes (which agent handles which conversations).Concepts
Providers
Providers are the AI backends that power agents.genie, claude-code, a2a, ag-ui, agno, openclaw, webhook.
Agents
Agents are the entities that receive and process messages. See the agents CLI reference for full management commands.Routes
Routes determine which agent handles messages from which source. Routes can be scoped to an instance, a specific chat, or a specific user.Route Resolution Order
When a message arrives, Omni resolves the handler in this order:- Per-user route — if a route exists for this specific person, use it
- Per-chat route — if a route exists for this specific chat, use it
- Per-instance route — fallback to the instance-level default agent
Reply Filters
Each instance can constrain which inbound messages reach the bound agent. The default is allow-all: when an instance has no reply filter set (agent_reply_filter = null), every message routed to the agent is dispatched.
Switching to filtered mode lets you opt into specific triggers — DMs, @mentions, replies to the bot, or messages mentioning the bot’s name.
omni instances update for every reply-filter flag.
API Keys
Manage API keys for authenticating with the Omni API:Three concepts are easy to confuse on first read: a provider is reusable infrastructure (auth + base URL), an agent is a logical entity bound to one provider, and a route decides which agent handles a given conversation. You typically have a handful of providers, a few dozen agents, and routes per instance.
See also
Routes (concept)
Routing rules, priorities, and resolution order.
Instances (concept)
Per-channel configuration that scopes agent behaviour.
Agents (CLI)
omni agents, omni providers, omni routes, omni keys reference.Providers (CLI)
Per-provider config schemas and setup wizards.