Agentic Routing

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

Quick Start

Install Package

First, install the PraisonAI Agents package:

pip install praisonaiagents

Set API Key

Set your OpenAI API key as an environment variable in your terminal:

export OPENAI_API_KEY=your_api_key_here

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)

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:

Parameter	Type	Description	Default
`models`	List[str] or Dict	List of model names or model configuration	None
`model_router`	ModelRouter	Custom ModelRouter instance	None
`routing_strategy`	str	Strategy: “auto”, “manual”, “cost-optimized”, “performance-optimized"	"auto”
`primary_model`	str	Primary model to use	None
`fallback_model`	str	Fallback model for errors	None
`**kwargs`	Any	Standard 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>

Getting Started

Core Concepts

Workflows

Features

Models

Tools

Other Features

Monitoring

Developers

Getting Started (No Code)

API Reference

Quick Start

Understanding Agentic Routing

What is Agentic Routing?

Features

Dynamic Routing

Conditional Logic

Task Management

Process Control

Configuration Options

RouterAgent - Advanced Dynamic Routing

RouterAgent Features

Dynamic Model Selection

Cost Optimization

Fallback Handling

Performance Tracking

Using RouterAgent

RouterAgent with Custom ModelRouter

Using RouterAgent with Tasks and Workflows

RouterAgent Initialization Parameters

Real-World Example: Multi-Provider Cost Optimization

Important Notes

Getting Started

Core Concepts

Workflows

Features

Models

Tools

Other Features

Monitoring

Developers

Getting Started (No Code)

API Reference

​Quick Start

​Understanding Agentic Routing

What is Agentic Routing?

​Features

Dynamic Routing

Conditional Logic

Task Management

Process Control

​Configuration Options

​RouterAgent - Advanced Dynamic Routing

​RouterAgent Features

Dynamic Model Selection

Cost Optimization

Fallback Handling

Performance Tracking

​Using RouterAgent

​RouterAgent with Custom ModelRouter

​Using RouterAgent with Tasks and Workflows

​RouterAgent Initialization Parameters

​Real-World Example: Multi-Provider Cost Optimization

​Important Notes

Quick Start

Understanding Agentic Routing

Features

Configuration Options

RouterAgent - Advanced Dynamic Routing

RouterAgent Features

Using RouterAgent

RouterAgent with Custom ModelRouter

Using RouterAgent with Tasks and Workflows

RouterAgent Initialization Parameters

Real-World Example: Multi-Provider Cost Optimization

Important Notes