# Provider Configuration Reference

CleverAgents supports multiple AI provider backends through the `ProviderRegistry`.
Each provider is configured via environment variables or the `agents config set` command.

## Supported Providers

| Provider | `ProviderType` | API Key Environment Variable |
|----------|---------------|------------------------------|
| OpenAI | `openai` | `OPENAI_API_KEY` |
| Anthropic | `anthropic` | `ANTHROPIC_API_KEY` |
| Google / Gemini | `google` / `gemini` | `GOOGLE_API_KEY` / `GEMINI_API_KEY` |
| Azure OpenAI | `azure` | `AZURE_OPENAI_API_KEY` |
| **OpenRouter** | **`openrouter`** | **`OPENROUTER_API_KEY`** |
| Groq | `groq` | `GROQ_API_KEY` |
| Together AI | `together` | `TOGETHER_API_KEY` |
| Cohere | `cohere` | `COHERE_API_KEY` |

---

## OpenRouter

[OpenRouter](https://openrouter.ai) provides a unified API gateway to hundreds of
models from different providers (Anthropic, OpenAI, Google, Meta, Mistral, and more).
This makes it ideal for cost optimisation and model diversity without managing
multiple API keys.

### Configuration

Set the following environment variables:

```bash
# Required
export OPENROUTER_API_KEY="sk-or-v1-..."

# Optional: default model (defaults to anthropic/claude-sonnet-4-20250514)
export CLEVERAGENTS_DEFAULT_MODEL="openai/gpt-4o"

# Optional: set OpenRouter as the default provider
export CLEVERAGENTS_DEFAULT_PROVIDER="openrouter"

# Optional: organisation identifier sent in HTTP headers
export OPENROUTER_ORGANIZATION="myapp.example.com"
```

Or use the CLI:

```bash
agents config set provider.openrouter.api_key "sk-or-v1-..."
agents config set provider.openrouter.model "anthropic/claude-3-haiku"
```

### Config Keys

| Config Key | Environment Variable | Description |
|------------|---------------------|-------------|
| `provider.openrouter.api_key` | `OPENROUTER_API_KEY` | OpenRouter API key (required) |
| `provider.openrouter.model` | `CLEVERAGENTS_DEFAULT_MODEL` | Default model slug (optional) |
| `provider.openrouter.organization` | `OPENROUTER_ORGANIZATION` | Organisation name sent in `HTTP-Referer` / `X-Title` headers (optional) |

### Capabilities

| Feature | Supported |
|---------|-----------|
| Streaming | ✅ Yes |
| Tool calls | ✅ Yes |
| Vision / image input | ✅ Yes (model-dependent) |
| JSON mode | ✅ Yes (model-dependent) |
| Max context length | 128 000 tokens (varies by model) |

### Selecting a Model

OpenRouter model slugs follow the format `<provider>/<model-name>`. Examples:

```bash
# Anthropic via OpenRouter
agents config set provider.openrouter.model "anthropic/claude-sonnet-4-20250514"

# OpenAI via OpenRouter
agents config set provider.openrouter.model "openai/gpt-4o"

# Meta Llama via OpenRouter
agents config set provider.openrouter.model "meta-llama/llama-3.1-70b-instruct"
```

Browse the full model catalogue at <https://openrouter.ai/models>.

### Fallback Priority

When no explicit provider is configured, CleverAgents selects the first available
provider in the following fallback order:

1. OpenAI
2. Anthropic
3. Google
4. Azure
5. **OpenRouter** ← position 5
6. Groq
7. Together AI
8. Cohere

### Example Usage

```python
from cleveragents.providers.registry import ProviderRegistry, ProviderType

registry = ProviderRegistry()

# Create a LangChain LLM directly
llm = registry.create_llm(
    provider_type=ProviderType.OPENROUTER,
    model_id="anthropic/claude-3-haiku",
)

# Or create a full AIProviderInterface adapter
provider = registry.create_ai_provider(
    provider_type="openrouter",
    model_id="openai/gpt-4o",
)
```