Model Router System

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.

Quick Start

Install Package

First, install the PraisonAI Agents package:

pip install praisonaiagents

Set API Keys

Set your API keys as environment variables:

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

Create a file

Create a new file model_router_example.py:

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!")

Run the Example

Execute your model router example:

python model_router_example.py

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.

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:

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

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.

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:

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:

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

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:

praisonai workflow create --template model-routing --output my_workflow.yaml

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

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.

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

# 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

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

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

task = Task(
    description="...",
    requirements={
        "complexity": "high",
        "context_length": 10000,
        "domain": "technical",
        "quality_priority": 0.8
    }
)

Monitor Performance

Regularly review routing decisions and performance:

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

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

Deep dive into model-specific capabilities and features

Router Agent

Learn about the RouterAgent for dynamic task routing

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.

Inspect the per-model capabilities the router uses to decide.

Retry with a backup model when the routed choice fails.

​Quick Start

​Which Strategy Should I Use?

​YAML-Based Model Configuration

​Basic Configuration

​Quick per-agent model (no router needed)

​Model Configuration Fields

​Per-Agent LLM Configuration (Named Models)

​Routing Strategies

​Complete Example

​CLI Usage

​How It Works

​Understanding Model Router

What is Model Router?

​Features

Intelligent Selection

Cost Optimization

Capability Matching

Fallback Support

​Configuration Options

​Advanced Usage

​Custom Routing Logic

​Routing Analytics

​Model Selection Criteria

Task Complexity

Context Length

Response Time

Cost Constraints

​Best Practices

​Troubleshooting

Routing Issues

Performance Problems

​Next Steps

Model Capabilities

Router Agent

​Related

Quick Start

Which Strategy Should I Use?

YAML-Based Model Configuration

Basic Configuration

Quick per-agent model (no router needed)

Model Configuration Fields

Per-Agent LLM Configuration (Named Models)

Routing Strategies

Complete Example

CLI Usage

How It Works

Understanding Model Router

Features

Configuration Options

Advanced Usage

Custom Routing Logic

Routing Analytics

Model Selection Criteria

Best Practices

Troubleshooting

Next Steps

Related