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

# AI Agent Integration

> Bind AI agents to channels with providers, routing rules, and reply filters.

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

```bash theme={"dark"}
# 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](/omni/cli/agents) for full management commands.

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

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

1. **Per-user route** — if a route exists for this specific person, use it
2. **Per-chat route** — if a route exists for this specific chat, use it
3. **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.

```bash theme={"dark"}
# 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`](/omni/cli/management) for every reply-filter flag.

## API Keys

Manage API keys for authenticating with the Omni API:

```bash theme={"dark"}
omni keys create --name "Production"
omni keys list
omni keys revoke <key-id>
```

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

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

## See also

<CardGroup cols={2}>
  <Card title="Routes (concept)" icon="diagram-project" href="/omni/concepts/routes">
    Routing rules, priorities, and resolution order.
  </Card>

  <Card title="Instances (concept)" icon="puzzle-piece" href="/omni/concepts/instances">
    Per-channel configuration that scopes agent behaviour.
  </Card>

  <Card title="Agents (CLI)" icon="terminal" href="/omni/cli/agents">
    `omni agents`, `omni providers`, `omni routes`, `omni keys` reference.
  </Card>

  <Card title="Providers (CLI)" icon="plug" href="/omni/cli/providers">
    Per-provider config schemas and setup wizards.
  </Card>
</CardGroup>