> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Model Router System

> Intelligent LLM selection based on task requirements and model capabilities for optimal performance and cost efficiency.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent

agent = Agent(name="router-demo", instructions="Pick the best model for each task.")
agent.start("Summarise this long document cheaply")
```

The user submits a task; the router picks the model that best matches requirements and cost.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Model Router"
        Task[📋 Task] --> Router[🧠 Router]
        Router --> Select[🔍 Select Model]
        Select --> Output[✅ Result]
    end

    classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef tool fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef output fill:#10B981,stroke:#7C90A0,color:#fff
    class Task input
    class Router agent
    class Select tool
    class Output output
```

## Quick Start

**1. Install Package**

First, install the PraisonAI Agents package:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
pip install praisonaiagents
```

**2. Set API Keys**

Set your API keys as environment variables:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
export OPENAI_API_KEY="${OPENAI_API_KEY:?Set OPENAI_API_KEY in your shell}"
export ANTHROPIC_API_KEY=your_anthropic_key_here
export GOOGLE_API_KEY=your_google_key_here
```

**3. Create a file**

Create a new file `model_router_example.py`:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent, Task, AgentTeam
from praisonaiagents.llm import ModelRouter

# Initialize the model router
router = ModelRouter()

# Analyze task complexity and select appropriate model
task_description = "Calculate the sum of 15 + 27"
complexity = router.analyze_task_complexity(task_description)
selected_model = router.select_model(task_description)

print(f"Task complexity: {complexity}")
print(f"Selected model: {selected_model}")

# Create an agent with the selected model
smart_agent = Agent(
    name="Smart Assistant",
    role="Adaptive AI Assistant",
    goal="Complete tasks using the most appropriate model",
    instructions="Analyze task requirements and provide accurate results",
    llm=selected_model  # Use the model selected by router
)

# Create a simple task
simple_task = Task(
    name="simple_calculation",
    description=task_description,
    expected_output="The numerical result",
    agent=smart_agent
)

# Create and run workflow
workflow = AgentTeam(
    agents=[smart_agent],
    tasks=[simple_task]
)

print("Starting Model Router Workflow...")
print("=" * 50)

results = workflow.start()
print("Done!")
```

**4. Run the Example**

Execute your model router example:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
python model_router_example.py
```

> [!NOTE]
>
> **Requirements**
>
> * Python 3.10 or higher
> * API keys for the models you want to use
> * Basic understanding of different LLM capabilities

## Which Strategy Should I Use?

Pick a `routing_strategy` based on whether you optimise for cost, quality, or let the router decide.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    Start([What matters most?]) --> Q1{Priority?}
    Q1 -->|Lowest cost| A[cost-optimized<br/>cheapest model that fits]
    Q1 -->|Best quality| B[performance-optimized<br/>most capable model]
    Q1 -->|Let router decide| C[auto<br/>match to task complexity]

    classDef start fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef question fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef answer fill:#10B981,stroke:#7C90A0,color:#fff

    class Start start
    class Q1 question
    class A,B,C answer
```

***

## YAML-Based Model Configuration

You can configure custom models directly in your `agents.yaml` or `workflow.yaml` files. This allows you to define model profiles with costs, capabilities, and complexity levels without writing Python code.

### Basic Configuration

Add a `models` section to your YAML file:

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# agents.yaml or workflow.yaml
name: My Workflow

# Custom models configuration
models:
  cheap-fast:
    provider: openai
    complexity: [simple]
    cost_per_1k: 0.0001
    capabilities: [text]
    context_window: 16000
  
  balanced:
    provider: openai
    complexity: [moderate]
    cost_per_1k: 0.001
    capabilities: [text, function-calling]
    context_window: 128000
  
  premium:
    provider: anthropic
    complexity: [complex, very_complex]
    cost_per_1k: 0.015
    capabilities: [text, vision, function-calling]
    context_window: 200000
    strengths: [reasoning, analysis, code-generation]

agents:
  researcher:
    name: Researcher
    role: Research Analyst
    goal: Research topics
    llm: balanced  # Use specific model
```

## Quick per-agent model (no router needed)

For simple per-agent model assignment without configuring the full Model Router system, use these direct forms:

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
roles:
  researcher:
    role: Researcher
    goal: Research {topic}
    llm: gpt-4o-mini            # string form

  writer:
    role: Writer  
    goal: Write about {topic}
    llm:
      model: groq/llama3-70b-8192   # dict form
```

**Precedence:** per-agent `llm` > `manager_llm` (for hierarchical process) > global model resolved from `llm_config[0].model` / CLI / env.

**Framework support:** Per-agent `llm` is honored by both `crewai` and the praisonai-native adapter.

> [!NOTE]
>
> **AutoGen/AG2 limitation:** This adapter currently uses only `llm_config[0]` — per-agent LLM assignment is not yet supported.

### Model Configuration Fields

| Field | Type | Description |
| - | - | - |
| `provider` | string | Provider name: `openai`, `anthropic`, `google`, `openrouter`, etc. |
| `complexity` | list | Complexity levels: `simple`, `moderate`, `complex`, `very_complex` |
| `cost_per_1k` | float | Cost per 1,000 tokens in USD |
| `capabilities` | list | Model capabilities: `text`, `vision`, `function-calling`, `streaming` |
| `context_window` | int | Maximum context window size in tokens |
| `supports_tools` | bool | Whether the model supports tool/function calling |
| `supports_streaming` | bool | Whether the model supports streaming responses |
| `strengths` | list | Model strengths: `reasoning`, `code-generation`, `analysis`, etc. |

### Per-Agent LLM Configuration (Named Models)

Each agent can specify its own LLM configuration using named models defined in the `models:` block above:

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
agents:
  # Fixed model assignment
  classifier:
    name: Classifier
    role: Request Classifier
    goal: Classify requests
    llm: cheap-fast  # Always use cheap model
  
  # Auto-routing based on task complexity
  researcher:
    name: Researcher
    role: Research Analyst
    goal: Research topics
    llm_routing: auto  # Enable auto-routing
    llm_models: [balanced, premium]  # Models to choose from
  
  # Premium model for quality output
  writer:
    name: Writer
    role: Content Writer
    goal: Write high-quality content
    llm: premium  # Always use premium
```

### Routing Strategies

Configure routing strategy in the workflow section:

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
workflow:
  verbose: true
  router: true  # Enable model routing
  routing_strategy: cost-optimized  # Options: auto, cost-optimized, performance-optimized
```

| Strategy | Description |
| - | - |
| `auto` | Automatically select based on task complexity |
| `cost-optimized` | Prefer cheaper models while meeting requirements |
| `performance-optimized` | Prefer more capable models for quality |

### Complete Example

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
name: Cost-Optimized Model Routing Workflow
description: Uses custom models with automatic routing

models:
  gpt-4o-mini:
    provider: openai
    complexity: [simple, moderate]
    cost_per_1k: 0.00075
    capabilities: [text, function-calling]
  
  claude-3-5-sonnet:
    provider: anthropic
    complexity: [moderate, complex, very_complex]
    cost_per_1k: 0.009
    capabilities: [text, vision, function-calling]
    strengths: [reasoning, code-generation, analysis]

workflow:
  verbose: true
  router: true
  routing_strategy: cost-optimized

agents:
  classifier:
    name: Classifier
    role: Request Classifier
    goal: Classify incoming requests
    llm: gpt-4o-mini

  researcher:
    name: Researcher
    role: Research Analyst
    goal: Research topics thoroughly
    llm_routing: auto
    llm_models: [gpt-4o-mini, claude-3-5-sonnet]

steps:
  - agent: classifier
    action: "Classify: {{input}}"
    
  - name: routing
    route:
      simple: [researcher]
      complex: [researcher]
      default: [researcher]
```

### CLI Usage

Create a workflow from template:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai workflow create --template model-routing --output my_workflow.yaml
```

Run with the `--router` flag for automatic model selection:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai "Your task here" --router
praisonai "Your task here" --router --router-provider anthropic
```

## How It Works

The user submits a task; the router analyses complexity, selects the best-matching model, and the agent runs on it.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Router
    participant Agent
    participant Model

    User->>Router: Task description
    Router->>Router: Analyze complexity + cost
    Router->>Agent: Selected model
    Agent->>Model: Run task
    Model-->>Agent: Completion
    Agent-->>User: Result
```

***

## Understanding Model Router

> **What is Model Router?**
>
> The Model Router:
>
> * Automatically selects the best LLM for each task
> * Considers task complexity, context length, and requirements
> * Optimizes for performance and cost
> * Supports fallback options if primary model fails
> * Provides detailed routing history and analytics

## Features

> **Intelligent Selection**
>
> Analyzes task requirements to choose the optimal model.

> **Cost Optimization**
>
> Balances performance needs with cost considerations.

> **Capability Matching**
>
> Matches task requirements with model capabilities.

> **Fallback Support**
>
> Automatically switches to backup models if needed.

## Configuration Options

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Initialize router with custom configuration
router = ModelRouter(
    config={
        # Model selection preferences
        "prefer_cost_effective": True,
        "max_cost_per_token": 0.001,
        
        # Model capabilities
        "model_capabilities": {
            "gpt-4": {
                "max_tokens": 128000,
                "strengths": ["reasoning", "coding", "analysis"],
                "cost_per_1k_tokens": 0.03
            },
            "gpt-3.5-turbo": {
                "max_tokens": 16000,
                "strengths": ["general", "fast"],
                "cost_per_1k_tokens": 0.001
            },
            "claude-3-sonnet": {
                "max_tokens": 200000,
                "strengths": ["long_context", "writing"],
                "cost_per_1k_tokens": 0.015
            }
        },
        
        # Routing rules
        "routing_rules": {
            "complex_reasoning": ["gpt-4", "claude-3-opus"],
            "simple_tasks": ["gpt-3.5-turbo", "llama-3"],
            "long_context": ["claude-3-sonnet", "gpt-4-turbo"],
            "coding": ["gpt-4", "deepseek-coder"],
            "multimodal": ["gpt-4-vision", "gemini-pro-vision"]
        },
        
        # Fallback configuration
        "fallback_enabled": True,
        "fallback_models": ["gpt-3.5-turbo", "llama-3"]
    }
)

# Use router with specific task hints
result = router.route_task(
    task_description="Analyze complex financial data",
    requirements={
        "complexity": "high",
        "domain": "finance",
        "expected_tokens": 2000
    }
)
```

## Advanced Usage

### Custom Routing Logic

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents.llm import ModelRouter, RoutingCriteria

class CustomRouter(ModelRouter):
    def custom_routing_logic(self, task, criteria):
        # Add custom logic for specific use cases
        if "legal" in task.description.lower():
            return "claude-3-opus"  # Better for legal documents
        
        if criteria.urgency == "high":
            return "gpt-3.5-turbo"  # Fastest response
        
        return super().route(task, criteria)

# Use custom router
custom_router = CustomRouter()
```

### Routing Analytics

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Get routing statistics
stats = router.get_statistics()
print(f"Total tasks routed: {stats['total_tasks']}")
print(f"Model usage breakdown: {stats['model_usage']}")
print(f"Average cost per task: ${stats['avg_cost']}")
print(f"Performance metrics: {stats['performance']}")

# Export routing history
router.export_history("routing_history.json")
```

## Model Selection Criteria

The router considers multiple factors when selecting models:

> **Task Complexity**
>
> * Simple calculations → Cost-effective models
> * Complex reasoning → Advanced models
> * Creative tasks → Specialized creative models

> **Context Length**
>
> * Short context → Standard models
> * Medium context → Enhanced context models
> * Long context → Specialized long-context models

> **Response Time**
>
> * Real-time needs → Fast models
> * Batch processing → Optimized for throughput
> * Quality priority → Best performing models

> **Cost Constraints**
>
> * Budget limits → Cost-effective options
> * Quality/cost balance → Optimal value models
> * Premium requirements → Top-tier models

## Best Practices

> **Define Clear Requirements**
>
> Provide specific task requirements to help the router make better decisions:
>
> ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> task = Task(
>     description="...",
>     requirements={
>         "complexity": "high",
>         "context_length": 10000,
>         "domain": "technical",
>         "quality_priority": 0.8
>     }
> )
> ```

> **Monitor Performance**
>
> Regularly review routing decisions and performance:
>
> ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> # Enable detailed logging
> router = ModelRouter(output="verbose", log_decisions=True)
>
> # Review performance after execution
> performance_report = router.generate_performance_report()
> ```

> **Set Cost Limits**
>
> Configure budget constraints to control costs:
>
> ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> router = ModelRouter(
>     max_cost_per_task=0.50,
>     daily_budget=100.00,
>     alert_on_threshold=True
> )
> ```

## Troubleshooting

> **Routing Issues**
>
> If wrong models are selected:
>
> * Review task requirements
> * Check routing rules configuration
> * Enable verbose logging
> * Verify model availability

> **Performance Problems**
>
> If performance is suboptimal:
>
> * Analyze routing history
> * Adjust selection criteria
> * Update model capabilities
> * Consider custom routing logic

## Next Steps

> **[Model Capabilities](https://praison.ai/docs/features/model-capabilities.md)**
>
> Deep dive into model-specific capabilities and features

> **[Router Agent](https://praison.ai/docs/features/routing.md)**
>
> Learn about the RouterAgent for dynamic task routing

> [!NOTE]
>
> The Model Router System continuously learns from usage patterns to improve selection accuracy over time. Regular monitoring and adjustment of routing rules ensures optimal performance.

## Related

> Inspect the per-model capabilities the router uses to decide.
>
> [Open](https://praison.ai/docs/features/model-capabilities.md)

> Retry with a backup model when the routed choice fails.
>
> [Open](https://praison.ai/docs/features/model-fallback.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.