Configuration Guide

AgentRouter provides extensive configuration options to customize agent behavior, network settings, and execution parameters.

Configuration Overview

All configuration in AgentRouter is fully configurable with strict validation ranges to ensure reliability and performance.

Naming and Role Requirements

Agent Name Validation

All agent names (Manager and Worker) must follow strict naming conventions:

Must start with a letter (a-z or A-Z)
Can contain: letters, numbers, underscores (_), hyphens (-), spaces
Length: 2-50 characters
Auto-normalization: Names are automatically normalized to lowercase:
- Uppercase → lowercase (OrderProcessor → orderprocessor)
- Spaces → underscores (Order Processor → order_processor)
- Hyphens → underscores (order-processor → order_processor)
- Multiple underscores → single (order__processor → order_processor)

# These all result in the same normalized name: "customer_service_manager"
manager1 = ManagerAgent(name="customer Service Manager", ...)
manager2 = ManagerAgent(name="customer-service-manager", ...)
manager3 = ManagerAgent(name="CUSTOMER_SERVICE_MANAGER", ...)

# These will raise ValidationError
manager = ManagerAgent(name="123manager", ...)     # Cannot start with number
manager = ManagerAgent(name="_manager", ...)       # Cannot start with underscore
manager = ManagerAgent(name="m", ...)              # Too short (min 2 chars)
manager = ManagerAgent(name="mgr@service", ...)    # Special characters not allowed

Worker Role Requirement

important

The role parameter is now REQUIRED for all WorkerAgent instances (not needed for ManagerAgent).

The role parameter serves as the worker's job description and is critical for proper delegation by managers:

Requirements:

Required for: WorkerAgent only (ManagerAgent does NOT need a role)
Length: 10-2000 characters
Format: 1-3 lines of focused, precise text
Purpose: Describes exactly what the worker does

Best Practices:

Keep it concise - ideally 50-200 characters
Be specific about the worker's responsibilities
Use action verbs (processes, manages, analyzes, handles)
Focus on the worker's primary function

# ✅ GOOD role examples - Clear, concise, focused
worker = WorkerAgent(
    name="order_handler",
    role="Processes customer orders, verifies inventory, coordinates shipping",
    ...
)

worker = WorkerAgent(
    name="data_analyst",
    role="Analyzes sales data, generates reports, identifies trends",
    ...
)

# ❌ BAD role examples
worker = WorkerAgent(
    name="worker1",
    role="Helper"  # Too short and vague (< 10 chars) - ValidationError!
)

worker = WorkerAgent(
    name="worker2",
    role="This worker is responsible for many different tasks including but not limited to handling various customer service requests, processing data, generating reports, managing databases, coordinating with other teams..."  # Too long and unfocused
)

# ❌ Missing role - ValidationError!
worker = WorkerAgent(
    name="worker3"
    # Missing required role parameter
)

Agent Configuration

Manager Agent Configuration

from agentrouter import ManagerAgent

manager = ManagerAgent(
    # Required Parameters
    name="Customer Service Manager",  # Will be normalized to: customer_service_manager
    api_key="your-api-key",
    
    # Model Configuration
    model="usf-mini",                    # LLM model to use
    provider="openai",                   # LLM provider
    
    # Agent Personality
    backstory="Senior manager with 10 years experience",
    goal="Resolve customer issues efficiently",
    instruction="Analyze and delegate tasks appropriately",
    introduction="I am here to help you",
    knowledge_cutoff="January 15, 2025",
    
    # Execution Configuration
    max_iterations=30,                   # Workflow iterations (3-50)
    temperature=0.7,                     # LLM temperature (0-1)
    max_tokens=2000,                     # Max response tokens
    
    # Network Configuration
    api_timeout=60.0,                    # API timeout (5-300 seconds)
    worker_timeout=60.0,                 # Worker timeout (5-300 seconds)
    max_retries=3,                       # Retry attempts (0-10)
    retry_delay=1.0,                     # Initial retry delay (0.1-60 seconds)
    retry_multiplier=2.0,                # Backoff multiplier (1-10)
    retry_max_wait=60.0,                 # Max retry wait (1-300 seconds)
    
    # Advanced Options
    trace=False,                         # Enable execution tracing
    streaming=False,                     # Enable response streaming
)

Worker Agent Configuration

# Workers inherit configuration from parent by default
worker = manager.create_worker(
    name="Technical Support",  # Will be normalized to: technical_support
    role="Provides technical assistance, troubleshooting, and solution guidance to customers",  # REQUIRED!
    
    # Optional: Override parent configuration
    max_iterations=10,                   # Custom iteration limit
    temperature=0.5,                     # More deterministic responses
    
    # Worker-specific settings
    access_parent_history=True,          # Access parent's message history
    trim_last_parent_user_message=True,  # Trim redundant messages
)

# Standalone worker with full configuration
standalone_worker = WorkerAgent(
    name="Independent Worker",  # Will be normalized to: independent_worker
    api_key="different-api-key",
    model="usf-mini",
    role="Analyzes complex technical issues and provides expert-level solutions and recommendations",  # REQUIRED!
    max_iterations=15,
    # ... all other configuration options
)

Configuration Parameters

Execution Configuration

Parameter	Default	Range	Description
`max_iterations`	30	3-50	Maximum workflow iterations before forcing final response
`temperature`	0.7	0.0-1.0	LLM temperature for response randomness
`max_tokens`	2000	1-8000	Maximum tokens in response
`streaming`	False	True/False	Enable streaming responses

Network Configuration

Parameter	Default	Range	Description
`api_timeout`	60.0	5-300	Seconds before API request timeout
`worker_timeout`	60.0	5-300	Seconds before worker execution timeout
`max_retries`	3	0-10	Number of retry attempts on failure
`retry_delay`	1.0	0.1-60	Initial delay between retries (seconds)
`retry_multiplier`	2.0	1.0-10.0	Exponential backoff multiplier
`retry_max_wait`	60.0	1-300	Maximum wait time between retries

Agent Personality Configuration

Parameter	Type	Required	Description	Validation
`name`	string	Yes	Agent identifier	Must start with letter, 2-50 chars, auto-normalized
`backstory`	string	No	Agent's background and expertise	Optional string
`goal`	string	No	Primary objective of the agent	Optional string
`instruction`	string	No	Specific instructions for task execution	Optional string
`introduction`	string	No	Initial greeting or context	Optional string
`knowledge_cutoff`	string	No	Date limit for agent's knowledge	Format: "DD Month YYYY"
`role`	string	Yes (Workers)	Agent's role description	REQUIRED for workers, 10-2000 chars

Configuration Inheritance

Worker agents automatically inherit configuration from their parent unless explicitly overridden:

# Parent configuration
manager = ManagerAgent(
    api_key="parent-key",
    model="usf-mini",
    api_timeout=60.0,
    max_retries=3
)

# Worker inherits all parent settings
worker1 = manager.create_worker(
    name="Worker1",
    role="Handles customer inquiries and provides product information and support"  # REQUIRED!
    # Inherits: api_key, model, api_timeout, max_retries
)

# Worker with overrides
worker2 = manager.create_worker(
    name="Worker2",
    role="Processes refund requests, manages returns, and handles billing disputes",  # REQUIRED!
    model="usf-mini-x1",        # Override model
    api_timeout=120.0,    # Override timeout
    # Still inherits: api_key, max_retries
)

Configuration Validation

All configuration parameters are validated using Pydantic with strict ranges:

from agentrouter.config import AgentConfiguration

# Create configuration with validation
config = AgentConfiguration.create_with_overrides(
    max_iterations=30,      # ✓ Valid (3-50)
    api_timeout=60.0,       # ✓ Valid (5-300)
    worker_timeout=60.0,    # ✓ Valid (5-300)
    max_retries=3,          # ✓ Valid (0-10)
    retry_delay=1.0,        # ✓ Valid (0.1-60)
    retry_multiplier=2.0,   # ✓ Valid (1-10)
    retry_max_wait=60.0     # ✓ Valid (1-300)
)

# Invalid configuration will raise ValidationError
try:
    config = AgentConfiguration.create_with_overrides(
        max_iterations=100,  # ✗ Invalid (>50)
        api_timeout=500.0    # ✗ Invalid (>300)
    )
except ValidationError as e:
    print(f"Configuration error: {e}")

Environment Variables

Configure AgentRouter using environment variables:

# .env file
AGENTROUTER_API_KEY=your-api-key
AGENTROUTER_MODEL=usf-mini
AGENTROUTER_MAX_ITERATIONS=30
AGENTROUTER_API_TIMEOUT=60
AGENTROUTER_WORKER_TIMEOUT=60
AGENTROUTER_MAX_RETRIES=3
AGENTROUTER_TEMPERATURE=0.7

Load in Python:

import os
from dotenv import load_dotenv
from agentrouter import ManagerAgent

load_dotenv()

manager = ManagerAgent(
    name="manager",
    api_key=os.getenv("AGENTROUTER_API_KEY"),
    model=os.getenv("AGENTROUTER_MODEL", "usf-mini"),
    max_iterations=int(os.getenv("AGENTROUTER_MAX_ITERATIONS", "30")),
    api_timeout=float(os.getenv("AGENTROUTER_API_TIMEOUT", "60")),
)

Configuration Best Practices

1. Timeout Configuration

Worker timeout should be >= API timeout since workers make API calls internally:

# Good configuration
manager = ManagerAgent(
    api_timeout=60.0,
    worker_timeout=90.0  # Greater than api_timeout
)

# Warning configuration
manager = ManagerAgent(
    api_timeout=60.0,
    worker_timeout=30.0  # Less than api_timeout (may cause issues)
)

2. Retry Configuration

Configure retries based on your use case:

# High reliability (production)
manager = ManagerAgent(
    max_retries=5,
    retry_delay=2.0,
    retry_multiplier=2.0,
    retry_max_wait=120.0
)

# Fast failure (development)
manager = ManagerAgent(
    max_retries=1,
    retry_delay=0.5,
    retry_multiplier=1.5,
    retry_max_wait=5.0
)

# No retries (testing)
manager = ManagerAgent(
    max_retries=0
)

3. Iteration Limits

Set appropriate iteration limits for your workflow complexity:

# Simple workflows
simple_agent = ManagerAgent(
    max_iterations=10  # Few tool calls expected
)

# Complex workflows
complex_agent = ManagerAgent(
    max_iterations=50  # Many nested tool calls
)

# Balanced default
balanced_agent = ManagerAgent(
    max_iterations=30  # Good for most use cases
)

4. Temperature Settings

Adjust temperature based on task requirements:

# Creative tasks
creative_agent = ManagerAgent(
    temperature=0.9  # More creative/varied responses
)

# Analytical tasks
analytical_agent = ManagerAgent(
    temperature=0.3  # More focused/deterministic
)

# Balanced
balanced_agent = ManagerAgent(
    temperature=0.7  # Default balance
)

Configuration Examples

Example 1: High-Performance Configuration

manager = ManagerAgent(
    name="high_perf_manager",
    api_key="api-key",
    model="usf-mini",
    
    # Fast execution
    max_iterations=20,
    api_timeout=30.0,
    worker_timeout=30.0,
    
    # Minimal retries
    max_retries=1,
    retry_delay=0.5,
    
    # Efficient responses
    temperature=0.5,
    max_tokens=1000
)

Example 2: Reliability-First Configuration

manager = ManagerAgent(
    name="reliable_manager",
    api_key="api-key",
    model="usf-mini",
    
    # Generous timeouts
    max_iterations=40,
    api_timeout=120.0,
    worker_timeout=150.0,
    
    # Aggressive retries
    max_retries=5,
    retry_delay=2.0,
    retry_multiplier=2.0,
    retry_max_wait=60.0,
    
    # Quality responses
    temperature=0.7,
    max_tokens=3000
)

Example 3: Development Configuration

manager = ManagerAgent(
    name="dev_manager",
    api_key="api-key",
    model="usf-mini",
    
    # Quick iteration
    max_iterations=10,
    api_timeout=10.0,
    worker_timeout=10.0,
    
    # No retries
    max_retries=0,
    
    # Debugging
    trace=True,  # Enable tracing
    temperature=0.5,
    max_tokens=500
)

Configuration for Different Providers

OpenAI Configuration

manager = ManagerAgent(
    name="openai_manager",
    api_key=os.getenv("OPENAI_API_KEY"),
    model="gpt-4",
    provider="openai",
    temperature=0.7,
    max_tokens=2000
)

Anthropic Configuration

manager = ManagerAgent(
    name="anthropic_manager",
    api_key=os.getenv("ANTHROPIC_API_KEY"),
    model="claude-3-opus",
    provider="anthropic",
    temperature=0.7,
    max_tokens=4000
)

Monitoring Configuration

Enable tracing for monitoring and debugging:

from agentrouter.visualization import ExecutionVisualizer

# Enable tracing
manager = ManagerAgent(
    name="traced_manager",
    api_key="api-key",
    trace=True  # Enable execution tracing
)

# Execute and visualize
result = await manager.execute(messages)

# Generate visualization
manager.visualize(format="html", output="execution.html")
manager.visualize(format="mermaid", output="flow.md")

Troubleshooting Configuration

Common Issues

Max Iterations Reached
- Increase max_iterations (up to 50)
- Optimize workflow to reduce tool calls
Timeout Errors
- Increase api_timeout and worker_timeout
- Check network connectivity
Retry Exhaustion
- Increase max_retries
- Adjust retry_delay and retry_multiplier
Worker Timeout < API Timeout
- Ensure worker_timeout >= api_timeout
- Workers need time for their API calls

Configuration Overview​

Naming and Role Requirements​

Agent Name Validation​

Worker Role Requirement​

Requirements:​

Best Practices:​

Agent Configuration​

Manager Agent Configuration​

Worker Agent Configuration​

Configuration Parameters​

Execution Configuration​

Network Configuration​

Agent Personality Configuration​

Configuration Inheritance​

Configuration Validation​

Environment Variables​

Configuration Best Practices​

1. Timeout Configuration​

2. Retry Configuration​

3. Iteration Limits​

4. Temperature Settings​

Configuration Examples​

Example 1: High-Performance Configuration​

Example 2: Reliability-First Configuration​

Example 3: Development Configuration​

Configuration for Different Providers​

OpenAI Configuration​

Anthropic Configuration​

Monitoring Configuration​

Troubleshooting Configuration​

Common Issues​