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

Concept	What It Is
Provider	An AI backend — Genie, Claude Code, A2A, Agno, webhook, etc.
Agent	An entity bound to a provider that processes messages
Route	A rule that sends messages from a specific instance/chat/user to an agent

Providers

Providers are the AI backends that power agents.

1234567891011121314# List providers
omni providers list

# Create a Genie provider
omni providers create --name "Genie" --schema genie

# Create a Claude Code provider
omni providers create --name "Claude" --schema claude-code

# Test provider health
omni providers test <provider-id>

# Interactive setup wizard
omni providers setup

Supported provider types: 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.

1234567891011# List all agents
omni agents list

# Create an agent
omni agents create --name "Support Bot" --provider <provider-id>

# Get agent details
omni agents get <agent-id>

# Delete an agent (soft-delete, sets inactive)
omni agents delete <agent-id>

Routes

Routes determine which agent handles messages from which source. Routes can be scoped to an instance, a specific chat, or a specific user.

123456789101112131415161718192021# List routes for an instance
omni routes list --instance <instance-id>

# Create a route — all messages from this instance go to this agent
omni routes create --instance <instance-id> --agent <agent-id>

# Create a per-chat route override
omni routes create --instance <instance-id> --chat <chat-id> --agent <agent-id>

# Create a per-user route override
omni routes create --instance <instance-id> --person <person-id> --agent <agent-id>

# Test route resolution
omni routes test --instance <instance-id> --chat <chat-id> --person <person-id>

# View route cache metrics
omni routes metrics

# Update or delete routes
omni routes update <route-id> --agent <new-agent-id>
omni routes delete <route-id>

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.

1234567891011121314# Default behaviour (no filter) — agent sees every message
omni instances update my-whatsapp --clear-reply-filter

# Constrain to DMs and @mentions only
omni instances update my-whatsapp \
  --reply-filter-mode filtered \
  --reply-on-dm \
  --reply-on-mention

# Match custom name patterns in group chats
omni instances update my-whatsapp \
  --reply-filter-mode filtered \
  --reply-on-name \
  --reply-name-patterns "support,help bot,assistant"

See omni instances update for every reply-filter flag.

API Keys

Manage API keys for authenticating with the Omni API:

123omni keys create --name "Production"
omni keys list
omni keys revoke <key-id>

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.

For routine deactivation prefer omni keys revoke over omni keys delete — revoked keys keep their audit trail and still appear in omni keys list, which makes incident review and rotation tracking much easier.