LLM Provider Configuration

Aurora supports multiple LLM providers for its AI agents. At least one provider API key is required.

Supported Providers

OpenRouter (recommended) - Access multiple models through a single API
OpenAI - GPT models (GPT-4o, GPT-5.2, etc.)
Anthropic - Claude models (Claude 3.5 Sonnet, etc.)
Google AI - Gemini models (Gemini Pro, Ultra, etc.)

Quick Start

# Get an OpenRouter API key (recommended)
# Visit: https://openrouter.ai/keys

# Add to .env
OPENROUTER_API_KEY=sk-or-v1-...
LLM_PROVIDER_MODE=openrouter

# Restart Aurora
make down
make prod-prebuilt

Configuration

Environment Variables

LLM_PROVIDER_MODE

string

default:"openrouter"

Default LLM provider to use.Options: openrouter, openai, anthropic, google

AGENT_RECURSION_LIMIT

number

default:"240"

Maximum recursion depth for agent workflows. Prevents infinite loops.

OpenRouter (Recommended)

OpenRouter provides access to multiple LLM models through a unified API.

Setup

Get an API key: https://openrouter.ai/keys

Add to .env:

OPENROUTER_API_KEY=sk-or-v1-...
LLM_PROVIDER_MODE=openrouter

Benefits

Single API for multiple models (GPT, Claude, Gemini, etc.)
Automatic routing to cheapest/fastest provider
Fallback support if a model is unavailable
Usage tracking and billing

Supported Models

OpenRouter supports 100+ models including:

OpenAI: GPT-4o, GPT-5.2, GPT-3.5
Anthropic: Claude 3.5 Sonnet, Claude 3 Opus
Google: Gemini Pro, Gemini Ultra
Meta: Llama 3, Llama 2
Mistral: Mixtral, Mistral Large
Many more: Cohere, AI21, etc.

See full list: https://openrouter.ai/models

Usage

from chat.backend.agent.providers import get_registry

registry = get_registry()
provider = registry.get_provider("openrouter")

# Use any OpenRouter-supported model
chat_model = provider.get_chat_model("openai/gpt-5.2")
response = chat_model.invoke("Hello, world!")

Cost Optimization

OpenRouter automatically routes to the cheapest available model:

# Use cost-optimized routing
chat_model = provider.get_chat_model("openai/gpt-5.2:auto")

OpenAI

Direct integration with OpenAI’s API.

Setup

Get an API key: https://platform.openai.com/api-keys

Add to .env:

OPENAI_API_KEY=sk-...
LLM_PROVIDER_MODE=openai

Supported Models

GPT-4o: Latest GPT-4 optimization
GPT-5.2: Next-generation model (when available)
GPT-3.5: Faster, cheaper model

Usage

from chat.backend.agent.providers import get_registry

registry = get_registry()
provider = registry.get_provider("openai")

chat_model = provider.get_chat_model("gpt-5.2")
response = chat_model.invoke("Explain quantum computing")

Configuration

# .env
OPENAI_API_KEY=sk-...
LLM_PROVIDER_MODE=openai

# Optional: Use OpenAI organization
OPENAI_ORGANIZATION=org-...

Anthropic

Integration with Anthropic’s Claude models.

Setup

Get an API key: https://console.anthropic.com/

Add to .env:

ANTHROPIC_API_KEY=sk-ant-...
LLM_PROVIDER_MODE=anthropic

Supported Models

Claude 3.5 Sonnet: Best balance of performance and speed
Claude 3 Opus: Most capable model
Claude 3 Haiku: Fastest, most affordable

Usage

from chat.backend.agent.providers import get_registry

registry = get_registry()
provider = registry.get_provider("anthropic")

chat_model = provider.get_chat_model("claude-3-5-sonnet-20240620")
response = chat_model.invoke("Write a Python function to sort a list")

Configuration

# .env
ANTHROPIC_API_KEY=sk-ant-...
LLM_PROVIDER_MODE=anthropic

Google AI (Gemini)

Integration with Google’s Gemini models.

Setup

Get an API key: https://aistudio.google.com/app/apikey

Add to .env:

GOOGLE_AI_API_KEY=AIza...
LLM_PROVIDER_MODE=google

Supported Models

Gemini Pro: Balanced performance
Gemini Ultra: Most capable (when available)
Gemini Nano: On-device model

Usage

from chat.backend.agent.providers import get_registry

registry = get_registry()
provider = registry.get_provider("google")

chat_model = provider.get_chat_model("gemini-pro")
response = chat_model.invoke("What is machine learning?")

Configuration

# .env
GOOGLE_AI_API_KEY=AIza...
LLM_PROVIDER_MODE=google

# Optional: Disable thinking mode
GEMINI_DISABLE_THINKING=true

Multi-Provider Setup

You can configure multiple providers and switch between them:

# .env
OPENROUTER_API_KEY=sk-or-v1-...
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_AI_API_KEY=AIza...

# Default provider
LLM_PROVIDER_MODE=openrouter

Switch providers at runtime:

from chat.backend.agent.providers import get_registry

registry = get_registry()

# Use OpenRouter
openrouter = registry.get_provider("openrouter")
model1 = openrouter.get_chat_model("openai/gpt-5.2")

# Use OpenAI directly
openai = registry.get_provider("openai")
model2 = openai.get_chat_model("gpt-5.2")

# Use Anthropic
anthropic = registry.get_provider("anthropic")
model3 = anthropic.get_chat_model("claude-3-5-sonnet-20240620")

API Endpoints

Check Available Providers

curl http://localhost:5080/api/llm-config/available-providers

Response:

{
  "success": true,
  "provider_mode": "openrouter",
  "providers": {
    "openrouter": {"available": true, "configured": true},
    "openai": {"available": true, "configured": true},
    "anthropic": {"available": false, "configured": false},
    "google": {"available": false, "configured": false}
  }
}

Get Provider Details

curl http://localhost:5080/api/llm-config/provider-details

Response:

{
  "success": true,
  "providers": [
    {
      "name": "openrouter",
      "available": true,
      "supported_models": [
        "openai/gpt-5.2",
        "openai/gpt-4o",
        "anthropic/claude-3-5-sonnet",
        "..."
      ],
      "total_models": 120
    }
  ]
}

Test Provider

curl -X POST http://localhost:5080/api/llm-config/test-provider \
  -H "Content-Type: application/json" \
  -d '{"provider": "openai", "model": "gpt-5.2"}'

Response:

{
  "success": true,
  "provider": "openai",
  "available": true,
  "message": "Provider 'openai' is configured and ready to use"
}

Get Supported Models

# All models
curl http://localhost:5080/api/llm-config/supported-models

# Filter by provider
curl "http://localhost:5080/api/llm-config/supported-models?provider=openai"

Model Mapping

Aurora automatically maps model names across providers:

from chat.backend.agent.model_mapper import ModelMapper

# Detect provider from model name
provider = ModelMapper.detect_provider("gpt-5.2")
print(provider)  # "openai"

# Get native name for a provider
native_name = ModelMapper.get_native_name("gpt-5.2", "openrouter")
print(native_name)  # "openai/gpt-5.2"

# Get supported models for a provider
models = ModelMapper.get_supported_models_for_provider("anthropic")
print(models)  # ["claude-3-5-sonnet-20240620", "claude-3-opus-20240229", ...]

Cost Optimization

RCA Cost Optimization

RCA_OPTIMIZE_COSTS

boolean

default:"false"

Enable cost optimization for root cause analysis.When enabled, Aurora uses cheaper models for preliminary analysis and more capable models only when needed.

# .env
RCA_OPTIMIZE_COSTS=true

Model Selection Strategy

Fast tasks: Use GPT-3.5 or Claude Haiku
Standard tasks: Use GPT-4o or Claude Sonnet
Complex reasoning: Use GPT-5.2 or Claude Opus

# Example: Tiered model usage
def get_model_for_task(complexity: str):
    if complexity == "simple":
        return "openai/gpt-3.5-turbo"  # Cheap, fast
    elif complexity == "standard":
        return "openai/gpt-4o"  # Balanced
    else:
        return "openai/gpt-5.2"  # Most capable

Troubleshooting

Provider Not Available

# Check which providers are configured
curl http://localhost:5080/api/llm-config/available-providers

# Verify API key is set
docker exec aurora-server-1 printenv | grep API_KEY

# Test provider
curl -X POST http://localhost:5080/api/llm-config/test-provider \
  -H "Content-Type: application/json" \
  -d '{"provider": "openai"}'

API Key Invalid

# Check API key format
echo $OPENROUTER_API_KEY  # Should start with sk-or-v1-
echo $OPENAI_API_KEY      # Should start with sk-
echo $ANTHROPIC_API_KEY   # Should start with sk-ant-
echo $GOOGLE_AI_API_KEY   # Should start with AIza

# Test key directly
curl https://openrouter.ai/api/v1/auth/key \
  -H "Authorization: Bearer $OPENROUTER_API_KEY"

Rate Limits

If you hit rate limits:

Use multiple providers as fallbacks
Implement retry logic with exponential backoff
Upgrade API plan for higher limits
Use OpenRouter for automatic rate limit handling

Model Not Found

# Check model name is correct
curl "http://localhost:5080/api/llm-config/model-info?model=gpt-5.2"

# List supported models
curl "http://localhost:5080/api/llm-config/supported-models?provider=openai"

Best Practices

Use OpenRouter for simplicity and reliability
Configure multiple providers as fallbacks
Test provider connectivity before deploying
Monitor usage and costs regularly
Rotate API keys periodically
Use environment variables (never commit keys)
Enable RCA cost optimization in production
Set appropriate recursion limits to prevent runaway costs

Security

Never commit API keys to version control. Always use environment variables and .env files.

# Good: .env file (gitignored)
OPENROUTER_API_KEY=sk-or-v1-...

# Bad: Hardcoded in code
api_key = "sk-or-v1-..."  # NEVER DO THIS

Key Rotation

# 1. Generate new API key from provider
# 2. Update .env
OPENROUTER_API_KEY=sk-or-v1-NEW_KEY

# 3. Restart Aurora
make down
make prod-prebuilt

# 4. Verify new key works
curl -X POST http://localhost:5080/api/llm-config/test-provider \
  -d '{"provider": "openrouter"}'

# 5. Revoke old key from provider dashboard

Access Control

Restrict API keys to specific IP addresses (if supported)
Use separate keys for development and production
Monitor usage for unusual activity
Set spending limits on provider dashboards

Get Started

Core Features

Architecture

Deployment

Configuration

Integrations

Cloud Providers

Observability

Development

Guides

Reference

Help

Documentation Index

​Supported Providers

​Quick Start

​Configuration

​Environment Variables

​OpenRouter (Recommended)

​Setup

​Benefits

​Supported Models

​Usage

​Cost Optimization

​OpenAI

​Setup

​Supported Models

​Usage

​Configuration

​Anthropic

​Setup

​Supported Models

​Usage

​Configuration

​Google AI (Gemini)

​Setup

​Supported Models

​Usage

​Configuration

​Multi-Provider Setup

​API Endpoints

​Check Available Providers

​Get Provider Details

​Test Provider

​Get Supported Models

​Model Mapping

​Cost Optimization

​RCA Cost Optimization

​Model Selection Strategy

​Troubleshooting

​Provider Not Available

​API Key Invalid

​Rate Limits

​Model Not Found

​Best Practices

​Security

​Key Rotation

​Access Control

Build docs developers (and LLMs) love

Supported Providers

Quick Start

Configuration

Environment Variables

OpenRouter (Recommended)

Setup

Benefits

Supported Models

Usage

Cost Optimization

OpenAI

Setup

Supported Models

Usage

Configuration

Anthropic

Setup

Supported Models

Usage

Configuration

Google AI (Gemini)

Setup

Supported Models

Usage

Configuration

Multi-Provider Setup

API Endpoints

Check Available Providers

Get Provider Details

Test Provider

Get Supported Models

Model Mapping

Cost Optimization

RCA Cost Optimization

Model Selection Strategy

Troubleshooting

Provider Not Available

API Key Invalid

Rate Limits

Model Not Found

Best Practices

Security

Key Rotation

Access Control