Documentation Index
Fetch the complete documentation index at: https://docs.praison.ai/llms.txt
Use this file to discover all available pages before exploring further.
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: ...")
# 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
-
Model Selection: Choose models that complement each other:
# Good mix: powerful + efficient + specialized
models = ["gpt-4o", "gpt-4o-mini", "claude-3-5-sonnet-20241022"]
-
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
-
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"]
}
-
Monitoring: Usage is automatically tracked:
router = RouterAgent(
models=["gpt-4o", "gpt-4o-mini"]
)
# Get usage report anytime
usage = router.get_usage_report()
- 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