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

# Agents & Providers

> AI agent management, provider configuration, routing rules, and API keys.

# Agent & Provider Commands

Commands for managing AI agents, providers, routing rules, and API keys.

## `omni agents`

Manage AI agent entities.

```bash theme={"dark"}
omni agents list               # List all agents
omni agents get <id>           # Get agent details
omni agents create [options]   # Create a new agent
omni agents update <id> [opts] # Update an agent (partial patch)
omni agents delete <id>        # Delete (soft-delete, sets inactive)
```

### Creating an Agent

```bash theme={"dark"}
omni agents create --name "Support Bot" --provider <provider-id>
```

| Option                     | Description                                                                                                                                                 |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--name <name>`            | Agent name                                                                                                                                                  |
| `--provider <provider>`    | AI provider: `claude`, `agno`, `openai`, `gemini`, `custom`, `omni-internal`                                                                                |
| `--model <model>`          | Model identifier (e.g., `claude-sonnet-4-6`)                                                                                                                |
| `--type <type>`            | Agent type: `assistant`, `workflow`, `team`, `tool` (default: `assistant`)                                                                                  |
| `--agent-provider <id>`    | Link to an existing agent provider configuration                                                                                                            |
| `--provider-agent-id <id>` | Provider-internal agent identifier (e.g. an Agno agent name). Stored at `metadata.providerAgentId` and used by the dispatcher to resolve the runtime agent. |
| `--config-path <path>`     | Path to the agent config file (DB column `config_path`)                                                                                                     |
| `--metadata <json>`        | Additional metadata as JSON. Merged into `metadata`; `--provider-agent-id` wins if both set `providerAgentId`.                                              |

```bash theme={"dark"}
# Bind to an Agno-hosted agent by its provider-internal ID
omni agents create \
  --name "Support" \
  --provider agno \
  --agent-provider <agent-provider-id> \
  --provider-agent-id support-bot \
  --metadata '{"team": "ops"}'

# Point an agent at a config file on disk
omni agents create \
  --name "Triage" \
  --provider claude \
  --model claude-sonnet-4-6 \
  --config-path /etc/omni/agents/triage.yaml
```

### Updating an Agent

`omni agents update <id>` is a partial patch — omitted fields are preserved. Metadata is merged shallowly so you can change one key without rewriting the whole object.

| Option                     | Description                                                             |
| -------------------------- | ----------------------------------------------------------------------- |
| `--name <name>`            | Rename the agent                                                        |
| `--model <model>`          | Switch the model                                                        |
| `--provider <provider>`    | Switch provider type                                                    |
| `--agent-provider <id>`    | Re-link to a different agent provider                                   |
| `--type <type>`            | Change agent type                                                       |
| `--active` / `--inactive`  | Toggle active state                                                     |
| `--provider-agent-id <id>` | Update `metadata.providerAgentId`. Wins over any value in `--metadata`. |
| `--config-path <path>`     | Update the agent config file path                                       |
| `--metadata <json>`        | Shallow-merge into existing metadata. Omitted keys are preserved.       |

```bash theme={"dark"}
# Switch to a new model and bump metadata
omni agents update <id> --model claude-sonnet-4-6 --metadata '{"version": 2}'

# Repoint at a different provider-side agent
omni agents update <id> --provider-agent-id support-bot-v2

# Mark inactive without deleting
omni agents update <id> --inactive
```

***

## `omni providers`

Manage AI/agent providers — the backends that power agents.

```bash theme={"dark"}
omni providers list              # List available providers
omni providers get <id>          # Get provider details
omni providers create [options]  # Create a new provider
omni providers update <id>       # Update provider config
omni providers delete <id>       # Delete a provider
omni providers test <id>         # Test provider health
omni providers setup             # Interactive setup wizard
```

### Supported Provider Types

| Type          | Description                             |
| ------------- | --------------------------------------- |
| `genie`       | Automagik Genie orchestration framework |
| `claude-code` | Anthropic Claude Code CLI agent         |
| `a2a`         | Agent-to-Agent protocol                 |
| `ag-ui`       | Agent UI protocol                       |
| `agno`        | Agno agent framework                    |
| `openclaw`    | Open Claw open-source agent             |
| `webhook`     | Custom webhook-based agent              |

### Agno-Specific Commands

For Agno providers, list resources from the Agno backend:

```bash theme={"dark"}
omni providers agents <id>      # List agents from Agno provider
omni providers teams <id>       # List teams
omni providers workflows <id>   # List workflows
```

***

## `omni routes`

Manage agent routing rules. See [Routes concept page](/omni/concepts/routes) for detailed routing documentation.

```bash theme={"dark"}
omni routes list --instance <id>        # List routes for an instance
omni routes get <route-id>              # Get route details
omni routes create [options]            # Create a new route
omni routes update <route-id> [opts]    # Update a route
omni routes delete <route-id>           # Delete a route
omni routes test [options]              # Test route resolution
omni routes metrics                     # View route cache metrics
```

***

## `omni keys`

Manage API keys for authenticating with the Omni API.

```bash theme={"dark"}
omni keys create --name "Production"    # Create a new API key
omni keys list                          # List all keys
omni keys get <id>                      # Get key details
omni keys update <id> --name "Staging"  # Update a key
omni keys revoke <id>                   # Revoke (disable) a key
omni keys delete <id>                   # Permanently delete a key
```

<Tip>
  Most agent and provider commands accept `--json` and pipe cleanly into `jq`. Use `omni agents list --json | jq '.[] | select(.active == true) | .id'` to script over the live agent set.
</Tip>

## See also

<CardGroup cols={2}>
  <Card title="Routes & Auth" icon="route" href="/omni/cli/routes-persons-auth">
    Full reference for `omni routes`, `omni persons`, and `omni auth`.
  </Card>

  <Card title="Providers (deep)" icon="plug" href="/omni/cli/providers">
    Per-provider create/update flag tables, schemas, and setup wizards.
  </Card>

  <Card title="Agents (concept)" icon="robot" href="/omni/concepts/agents">
    How agents, providers, and routes relate.
  </Card>

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