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

# RouterAgent Module

> Intelligent agent that dynamically selects the optimal model based on task requirements

# RouterAgent

The `RouterAgent` class is an intelligent agent that automatically selects the most appropriate LLM model for each task based on various factors like task complexity, required capabilities, cost optimization, and performance requirements.

## Overview

`RouterAgent` extends the base `Agent` class and adds sophisticated model routing capabilities. It analyzes incoming tasks and dynamically chooses the best model from a configured set of options, optimizing for cost, performance, or specific capabilities as needed.

## Basic Usage

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

# Create a router agent with multiple models
router = RouterAgent(
    role="Intelligent Assistant",
    goal="Provide optimal responses using the best model for each task",
    backstory="You are an adaptive AI that selects the perfect model for every situation.",
    models=["gpt-4o", "gpt-4o-mini", "claude-3-5-sonnet-20241022", "deepseek-chat"],
    routing_strategy="auto"  # Automatic model selection
)

# The agent will automatically choose the best model
result = router.chat("Explain quantum computing")  # Might use GPT-4 for complex topics
result = router.chat("What's 2+2?")  # Might use GPT-4-mini for simple queries
```

## Configuration Options

### Core Parameters

* **models** (list\[str]): List of available models to route between
* **routing\_strategy** (str): Strategy for model selection
  * `"auto"`: Automatic selection based on task analysis
  * `"manual"`: User specifies model per request
  * `"cost-optimized"`: Prioritize cheaper models when possible
  * `"performance-optimized"`: Always use the best performing model
* **fallback\_model** (str): Model to use if primary selection fails
* **model\_capabilities** (dict): Custom capability definitions for models
* **cost\_threshold** (float): Maximum cost per request (for cost-optimized strategy)
* **performance\_metrics** (dict): Custom performance metrics for models

### Inherited Parameters

All parameters from the base `Agent` class are also available.

## Routing Strategies

### Automatic Routing

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Automatic routing based on task complexity
router = RouterAgent(
    role="Smart Assistant",
    models=["gpt-4o", "gpt-4o-mini", "claude-3-5-sonnet-20241022"],
    routing_strategy="auto"
)

# Complex task - likely routes to GPT-4 or Claude
complex_result = router.chat(
    "Analyze this code for security vulnerabilities and suggest improvements"
)

# Simple task - likely routes to GPT-4-mini
simple_result = router.chat("Format this date: 2024-01-15")
```

### Cost-Optimized Routing

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Prioritize cost-effective models
budget_router = RouterAgent(
    role="Cost-Conscious Assistant",
    models=["gpt-4o-mini", "deepseek-chat", "gpt-4o"],
    routing_strategy="cost-optimized",
    cost_threshold=0.01  # Maximum $0.01 per request
)

# Will use the cheapest model that can handle the task
result = budget_router.chat("Summarize this article: ...")
```

### Performance-Optimized Routing

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Always use the best model
performance_router = RouterAgent(
    role="High-Performance Assistant",
    models=["gpt-4o", "claude-3-5-sonnet-20241022", "gpt-4o-mini"],
    routing_strategy="performance-optimized"
)

# Will use the highest-performing model regardless of cost
result = performance_router.chat("Generate a complex business strategy")
```

### Manual Routing

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# User controls model selection
manual_router = RouterAgent(
    role="Configurable Assistant",
    models=["gpt-4o", "claude-3-5-sonnet-20241022", "deepseek-chat"],
    routing_strategy="manual"
)

# Specify model explicitly
# Note: Manual model selection is handled through routing_strategy
# The actual model selection happens based on task analysis
result = manual_router.chat(
    "Translate this to French"
    # Model will be selected based on manual routing logic
)
```

## Advanced Features

### Custom Model Capabilities

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Define custom capabilities for routing decisions
router = RouterAgent(
    role="Capability-Aware Assistant",
    models=["gpt-4o", "gpt-4-vision-preview", "deepseek-chat"],
    model_capabilities={
        "gpt-4o": ["reasoning", "coding", "general"],
        "gpt-4-vision-preview": ["vision", "image-analysis"],
        "deepseek-chat": ["coding", "technical"]
    }
)

# Router will select based on required capabilities
code_result = router.chat("Debug this Python code")  # Might choose deepseek-chat
image_result = router.chat("Analyze this image", images=["photo.jpg"])  # Will choose gpt-4-vision-preview
```

### Usage Tracking and Reporting

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Track model usage and costs
router = RouterAgent(
    role="Tracked Assistant",
    models=["gpt-4o", "gpt-4o-mini", "claude-3-5-sonnet-20241022"]
    # Usage tracking is built-in, no need for a parameter
)

# Use the router
for i in range(10):
    router.chat(f"Task {i}")

# Get usage report
usage_report = router.get_usage_report()
print(f"Total cost: ${usage_report['total_cost']}")
print(f"Model usage: {usage_report['model_usage']}")
```

### Fallback Handling

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Configure fallback behavior
router = RouterAgent(
    role="Resilient Assistant",
    models=["gpt-4o", "claude-3-5-sonnet-20241022"],
    fallback_model="gpt-4o-mini"
    # Retry behavior is handled by the base Agent class
)

# If primary models fail, falls back to gpt-4o-mini
result = router.chat("Process this request")
```

## Integration with Other Agents

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

# Create specialized router
router = RouterAgent(
    role="Task Router",
    goal="Route tasks to the optimal model",
    models=["gpt-4o", "gpt-4o-mini", "claude-3-5-sonnet-20241022"]
)

# Create task handler
handler = Agent(
    role="Task Handler",
    goal="Process routed tasks"
)

# Create workflow
task1 = Task(
    description="Analyze complexity and route appropriately",
    agent=router
)

task2 = Task(
    description="Process the routed result",
    agent=handler,
    context=[task1]
)

# Execute workflow
agents = AgentTeam(
    agents=[router, handler],
    tasks=[task1, task2]
)
agents.start()
```

## Best Practices

1. **Model Selection**: Choose models that complement each other:
   ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
   # Good mix: powerful + efficient + specialized
   models = ["gpt-4o", "gpt-4o-mini", "claude-3-5-sonnet-20241022"]
   ```

2. **Strategy Selection**:
   * Use `"auto"` for general-purpose applications
   * Use `"cost-optimized"` for high-volume, budget-conscious apps
   * Use `"performance-optimized"` for critical applications
   * Use `"manual"` when you need explicit control

3. **Capability Definition**: Define clear capabilities for better routing:
   ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
   model_capabilities = {
       "gpt-4o": ["complex-reasoning", "coding", "creative-writing"],
       "gpt-4o-mini": ["simple-tasks", "quick-responses", "basic-qa"],
       "deepseek-chat": ["coding", "technical", "debugging"]
   }
   ```

4. **Monitoring**: Usage is automatically tracked:
   ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
   router = RouterAgent(
       models=["gpt-4o", "gpt-4o-mini"]
   )
   # Get usage report anytime
   usage = router.get_usage_report()
   ```

## Performance Considerations

* Initial task analysis adds 0.1-0.5s overhead
* Model switching has minimal latency impact
* Usage tracking adds \~1% memory overhead
* Capability matching is O(n) where n is number of models

## See Also

* [Agent](/api/praisonaiagents/agent/agent) - Base agent class
* [Model Router](/features/model-router) - Detailed routing strategies
* [Model Capabilities](/features/model-capabilities) - Model feature comparison
* [LLM Configuration](/configuration/llm-config) - Configure LLM providers