A low-latency workflow where inputs are dynamically routed to the most appropriate LLM instance or configuration, optimizing efficiency and specialization.

​
Quick Start

1

Install Package

First, install the PraisonAI Agents package:
pip install praisonaiagents
2

Set API Key

Set your OpenAI API key as an environment variable in your terminal:
export OPENAI_API_KEY=your_api_key_here
3

Create a file

Create a new file app.py with the basic setup:
from praisonaiagents.agent import Agent
from praisonaiagents.task import Task
from praisonaiagents.agents import PraisonAIAgents
import time

def get_time_check():
    current_time = int(time.time())
    result = "even" if current_time % 2 == 0 else "odd"
    print(f"Time check: {current_time} is {result}")
    return result

# Create specialized agents
router = Agent(
    name="Router",
    role="Input Router",
    goal="Evaluate input and determine routing path",
    instructions="Analyze input and decide whether to proceed or exit",
    tools=[get_time_check]
)

processor1 = Agent(
    name="Processor 1",
    role="Secondary Processor",
    goal="Process valid inputs that passed initial check",
    instructions="Process data that passed the routing check"
)

processor2 = Agent(
    name="Processor 2",
    role="Final Processor",
    goal="Perform final processing on validated data",
    instructions="Generate final output for processed data"
)

# Create tasks with routing logic
routing_task = Task(
    name="initial_routing",
    description="check the time and return according to what is returned",
    expected_output="pass or fail based on what is returned",
    agent=router,
    is_start=True,
    task_type="decision",
    condition={
        "pass": ["process_valid"],
        "fail": ["process_invalid"]
    }
)

processing_task = Task(
    name="process_valid",
    description="Process validated input",
    expected_output="Processed data ready for final step",
    agent=processor1,
)

final_task = Task(
    name="process_invalid",
    description="Generate final output",
    expected_output="Final processed result",
    agent=processor2
)

# Create and run workflow
workflow = PraisonAIAgents(
    agents=[router, processor1, processor2],
    tasks=[routing_task, processing_task, final_task],
    process="workflow",
    verbose=True
)

print("\nStarting Routing Workflow...")
print("=" * 50)

results = workflow.start()

print("\nWorkflow Results:")
print("=" * 50)
for task_id, result in results["task_results"].items():
    if result:
        task_name = result.description
        print(f"\nTask: {task_name}")
        print(f"Result: {result.raw}")
        print("-" * 50)
4

Start Agents

Type this in your terminal to run your agents:
python app.py
Requirements
  • Python 3.10 or higher
  • OpenAI API key. Generate OpenAI API key here. Use Other models using this guide.
  • Basic understanding of Python

​
Understanding Agentic Routing

What is Agentic Routing?

Agentic routing enables:
  • Dynamic decision-making in workflows
  • Conditional task execution paths
  • Automated process branching
  • Intelligent workflow management

​
Features

Dynamic Routing

Route tasks based on real-time decisions and conditions.

Conditional Logic

Implement complex branching logic in workflows.

Task Management

Handle task dependencies and execution order.

Process Control

Control workflow execution with detailed monitoring.

​
Configuration Options

# Create a router agent
router = Agent(
    name="Router",
    role="Input Router",
    goal="Evaluate input and determine routing path",
    instructions="Analyze input and decide whether to proceed or exit",
    tools=[get_time_check],  # Custom tools for routing decisions
    verbose=True  # Enable detailed logging
)

# Task with routing configuration
routing_task = Task(
    name="initial_routing",
    description="Route based on conditions",
    expected_output="Routing decision",
    agent=router,
    is_start=True,
    task_type="decision",
    condition={
        "pass": ["next_task"],
        "fail": ["alternate_task"]
    }
)

​
RouterAgent - Advanced Dynamic Routing

The RouterAgent is a specialized agent that provides intelligent model selection based on task requirements, optimizing for both performance and cost.

​
RouterAgent Features

Dynamic Model Selection

Automatically selects the best model based on:
  • Task complexity and requirements
  • Context length needs
  • Cost constraints
  • Performance requirements

Cost Optimization

Minimizes costs by:
  • Using cheaper models for simple tasks
  • Switching to powerful models only when needed
  • Tracking cost per task
  • Providing cost analytics

Fallback Handling

Ensures reliability with:
  • Automatic model fallbacks
  • Error recovery
  • Retry mechanisms
  • Quality validation

Performance Tracking

Monitors and optimizes:
  • Response times
  • Success rates
  • Model performance
  • Task outcomes

​
Using RouterAgent

The RouterAgent must be imported from praisonaiagents.agent.router_agent, not directly from praisonaiagents.
from praisonaiagents.agent.router_agent import RouterAgent
from praisonaiagents.llm.model_router import ModelRouter
from praisonaiagents import Task, PraisonAIAgents

# Option 1: Simple RouterAgent with model list
router_agent = RouterAgent(
    name="Smart Router",
    role="Task Router",  # Use 'role' not 'description'
    goal="Route tasks to optimal models",
    backstory="I analyze tasks and select the most appropriate model",
    models=["gpt-4o-mini", "gpt-4o", "claude-3-5-sonnet-20241022"],
    routing_strategy="cost-optimized",  # "auto", "manual", "cost-optimized", "performance-optimized"
    verbose=True
)

# Execute tasks (not chat)
result = router_agent.execute("What is 2+2?")
print(f"Result: {result}")

# For complex tasks
result = router_agent.execute("Write a comprehensive business plan for a SaaS startup")
print(f"Result: {result}")

# Get usage report to see which models were used
usage_report = router_agent.get_usage_report()
print(f"Usage report: {usage_report}")

​
RouterAgent with Custom ModelRouter

For more control over cost thresholds and provider preferences, use a custom ModelRouter: 
from praisonaiagents.agent.router_agent import RouterAgent
from praisonaiagents.llm.model_router import ModelRouter

# Create custom ModelRouter with cost control
custom_router = ModelRouter(
    cost_threshold=0.10,  # Max cost per request
    preferred_providers=["openai", "anthropic"]
)

# Create RouterAgent with custom router
router_agent = RouterAgent(
    name="Smart Router",
    role="Task Router",
    goal="Route tasks to optimal models with cost control",
    model_router=custom_router,
    routing_strategy="auto",
    verbose=True
)

​
Using RouterAgent with Tasks and Workflows

The RouterAgent is designed to work within the PraisonAI framework: 
from praisonaiagents.agent.router_agent import RouterAgent
from praisonaiagents import Task, PraisonAIAgents

# Create router agent
router_agent = RouterAgent(
    name="Adaptive Assistant",
    role="Multi-Model Assistant",
    goal="Complete tasks using the most appropriate model",
    backstory="I intelligently route tasks to different models based on complexity",
    models=["gpt-4o-mini", "gpt-4o", "claude-3-5-sonnet-20241022"],
    routing_strategy="auto",
    verbose=True
)

# Create tasks for the router agent
simple_task = Task(
    description="What is the capital of France?",
    expected_output="A simple answer",
    agent=router_agent
)

complex_task = Task(
    description="Analyze the economic impact of renewable energy adoption in developing countries",
    expected_output="A comprehensive analysis",
    agent=router_agent
)

# Run with PraisonAIAgents
agents = PraisonAIAgents(
    agents=[router_agent],
    tasks=[simple_task, complex_task],
    process="sequential"
)

results = agents.start()

# View results
for task_id, result in results['task_results'].items():
    print(f"Task: {result.description[:50]}...")
    print(f"Result: {result.raw[:100]}...")
    print("-" * 50)

​
RouterAgent Initialization Parameters

The RouterAgent accepts these parameters:
ParameterTypeDescriptionDefault
modelsList[str] or DictList of model names or model configurationNone
model_routerModelRouterCustom ModelRouter instanceNone
routing_strategystrStrategy: “auto”, “manual”, “cost-optimized”, “performance-optimized""auto”
primary_modelstrPrimary model to useNone
fallback_modelstrFallback model for errorsNone
**kwargsAnyStandard Agent parameters (name, role, goal, etc.)-

​
Real-World Example: Multi-Provider Cost Optimization

from praisonaiagents.agent.router_agent import RouterAgent
from praisonaiagents import Task, PraisonAIAgents

# Example from examples/agents/router-agent-cost-optimization.py
router = RouterAgent(
    name="Cost-Optimized Assistant",
    role="Efficient Task Processor",
    goal="Complete tasks with optimal cost-performance balance",
    models=[
        "gpt-4o-mini",      # Cheap, fast for simple tasks
        "gpt-4o",           # Balanced for medium complexity
        "gpt-4",            # Powerful for complex tasks
        "claude-3-5-sonnet-20241022"  # Alternative provider
    ],
    routing_strategy="cost-optimized",
    primary_model="gpt-4o-mini",
    fallback_model="gpt-4o"
)

# The router will automatically:
# - Use gpt-4o-mini for simple queries
# - Upgrade to gpt-4o or gpt-4 for complex tasks
# - Fall back to gpt-4o if the primary model fails

​
Important Notes

  • The RouterAgent uses execute() or start() methods, not chat()
  • Cost threshold is set on ModelRouter, not RouterAgent directly
  • Provider preferences are configured via ModelRouter
  • Model tracking is done via get_usage_report(), not last_model_used

## Troubleshooting

<CardGroup cols={2}>
  <Card title="Routing Issues" icon="triangle-exclamation">
    If routing doesn't work as expected:
    - Verify condition mappings
    - Check task dependencies
    - Enable verbose mode for debugging
  </Card>

  <Card title="Workflow Flow" icon="diagram-project">
    If workflow is unclear:
    - Review task connections
    - Verify agent configurations
    - Check routing conditions
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="AutoAgents" icon="robot" href="./autoagents">
    Learn about automatically created and managed AI agents
  </Card>
  <Card title="Mini Agents" icon="microchip" href="./mini">
    Explore lightweight, focused AI agents
  </Card>
</CardGroup>

<Note>
  For optimal results, ensure your routing conditions are well-defined and your task dependencies are properly configured.
</Note>