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

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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

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:

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

   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:

   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 - Base agent class
• Model Router - Detailed routing strategies
• Model Capabilities - Model feature comparison
• LLM Configuration - Configure LLM providers