# MultiAgentRouter Documentation

The MultiAgentRouter is a sophisticated task routing system that efficiently delegates tasks to specialized AI agents. It uses a "boss" agent to analyze incoming tasks and route them to the most appropriate specialized agent based on their capabilities and expertise.

## Table of Contents

- [Installation](#installation)
- [Key Components](#key-components)
- [Arguments](#arguments)
- [Methods](#methods)
- [Usage Examples](#usage-examples)
  - [Healthcare](#healthcare-example)
  - [Finance](#finance-example)
  - [Legal](#legal-example)
  - [Research](#research-example)

## Installation

```bash
pip install swarms
```

## Key Components

### Arguments Table

| Argument             | Type                      | Default           | Description                             |
| -------------------- | ------------------------- | ----------------- | --------------------------------------- |
| name                 | str                       | "swarm-router"    | Name identifier for the router instance |
| description          | str                       | "Routes tasks..." | Description of the router's purpose     |
| agents               | List[Agent]               | []                | List of available specialized agents    |
| model                | str                       | "gpt-4o-mini"     | Base language model for the boss agent  |
| temperature          | float                     | 0.1               | Temperature parameter for model outputs |
| shared_memory_system | callable                  | None              | Optional shared memory system           |
| output_type          | Literal["json", "string"] | "json"            | Format of agent outputs                 |
| execute_task         | bool                      | True              | Whether to execute routed tasks         |

### Methods Table

| Method               | Arguments        | Returns         | Description                               |
| -------------------- | ---------------- | --------------- | ----------------------------------------- |
| route_task           | task: str        | dict            | Routes a single task to appropriate agent |
| batch_run            | tasks: List[str] | List[dict]      | Sequentially routes multiple tasks        |
| concurrent_batch_run | tasks: List[str] | List[dict]      | Concurrently routes multiple tasks        |
| query_ragent         | task: str        | str             | Queries the research agent                |
| find_agent_in_list   | agent_name: str  | Optional[Agent] | Finds agent by name                       |

## Production Examples

### Healthcare Example

```python
from swarms import Agent, MultiAgentRouter

# Define specialized healthcare agents
agents = [
    Agent(
        agent_name="DiagnosisAgent",
        description="Specializes in preliminary symptom analysis and diagnostic suggestions",
        system_prompt="""You are a medical diagnostic assistant. Analyze symptoms and provide
        evidence-based diagnostic suggestions, always noting this is for informational purposes
        only and recommending professional medical consultation.""",
        model_name="openai/gpt-4o"
    ),
    Agent(
        agent_name="TreatmentPlanningAgent",
        description="Assists in creating treatment plans and medical documentation",
        system_prompt="""You are a treatment planning assistant. Help create structured
        treatment plans based on confirmed diagnoses, following medical best practices
        and guidelines.""",
        model_name="openai/gpt-4o"
    ),
    Agent(
        agent_name="MedicalResearchAgent",
        description="Analyzes medical research papers and clinical studies",
        system_prompt="""You are a medical research analyst. Analyze and summarize medical
        research papers, clinical trials, and scientific studies, providing evidence-based
        insights.""",
        model_name="openai/gpt-4o"
    )
]

# Initialize router
healthcare_router = MultiAgentRouter(
    name="Healthcare-Router",
    description="Routes medical and healthcare-related tasks to specialized agents",
    agents=agents,
    model="gpt-4o",
    temperature=0.1
)

# Example usage
try:
    # Process medical case
    case_analysis = healthcare_router.route_task(
        """Patient presents with:
        - Persistent dry cough for 3 weeks
        - Mild fever (38.1°C)
        - Fatigue
        Analyze symptoms and suggest potential diagnoses for healthcare provider review."""
    )

    # Research treatment options
    treatment_research = healthcare_router.route_task(
        """Find recent clinical studies on treatment efficacy for community-acquired
        pneumonia in adult patients, focusing on outpatient care."""
    )

    # Process multiple cases concurrently
    cases = [
        "Case 1: Patient symptoms...",
        "Case 2: Patient symptoms...",
        "Case 3: Patient symptoms..."
    ]
    concurrent_results = healthcare_router.concurrent_batch_run(cases)

except Exception as e:
    logger.error(f"Error in healthcare processing: {str(e)}")
```

### Finance Example

```python
# Define specialized finance agents
finance_agents = [
    Agent(
        agent_name="MarketAnalysisAgent",
        description="Analyzes market trends and provides trading insights",
        system_prompt="""You are a financial market analyst. Analyze market data, trends,
        and indicators to provide evidence-based market insights and trading suggestions.""",
        model_name="openai/gpt-4o"
    ),
    Agent(
        agent_name="RiskAssessmentAgent",
        description="Evaluates financial risks and compliance requirements",
        system_prompt="""You are a risk assessment specialist. Analyze financial data
        and operations for potential risks, ensuring regulatory compliance and suggesting
        risk mitigation strategies.""",
        model_name="openai/gpt-4o"
    ),
    Agent(
        agent_name="InvestmentAgent",
        description="Provides investment strategies and portfolio management",
        system_prompt="""You are an investment strategy specialist. Develop and analyze
        investment strategies, portfolio allocations, and provide long-term financial
        planning guidance.""",
        model_name="openai/gpt-4o"
    )
]

# Initialize finance router
finance_router = MultiAgentRouter(
    name="Finance-Router",
    description="Routes financial analysis and investment tasks",
    agents=finance_agents
)

# Example tasks
tasks = [
    """Analyze current market conditions for technology sector, focusing on:
    - AI/ML companies
    - Semiconductor manufacturers
    - Cloud service providers
    Provide risk assessment and investment opportunities.""",

    """Develop a diversified portfolio strategy for a conservative investor with:
    - Investment horizon: 10 years
    - Risk tolerance: Low to medium
    - Initial investment: $500,000
    - Monthly contribution: $5,000""",

    """Conduct risk assessment for a fintech startup's crypto trading platform:
    - Regulatory compliance requirements
    - Security measures
    - Operational risks
    - Market risks"""
]

# Process tasks concurrently
results = finance_router.concurrent_batch_run(tasks)
```

### Legal Example

```python
# Define specialized legal agents
legal_agents = [
    Agent(
        agent_name="ContractAnalysisAgent",
        description="Analyzes legal contracts and documents",
        system_prompt="""You are a legal document analyst. Review contracts and legal
        documents for key terms, potential issues, and compliance requirements.""",
        model_name="openai/gpt-4o"
    ),
    Agent(
        agent_name="ComplianceAgent",
        description="Ensures regulatory compliance and updates",
        system_prompt="""You are a legal compliance specialist. Monitor and analyze
        regulatory requirements, ensuring compliance and suggesting necessary updates
        to policies and procedures.""",
        model_name="openai/gpt-4o"
    ),
    Agent(
        agent_name="LegalResearchAgent",
        description="Conducts legal research and case analysis",
        system_prompt="""You are a legal researcher. Research relevant cases, statutes,
        and regulations, providing comprehensive legal analysis and citations.""",
        model_name="openai/gpt-4o"
    )
]

# Initialize legal router
legal_router = MultiAgentRouter(
    name="Legal-Router",
    description="Routes legal analysis and compliance tasks",
    agents=legal_agents
)

# Example usage for legal department
contract_analysis = legal_router.route_task(
    """Review the following software licensing agreement:
    [contract text]

    Analyze for:
    1. Key terms and conditions
    2. Potential risks and liabilities
    3. Compliance with current regulations
    4. Suggested modifications"""
)
```

## Error Handling and Best Practices

1. Always use try-except blocks for task routing:

```python
try:
    result = router.route_task(task)
except Exception as e:
    logger.error(f"Task routing failed: {str(e)}")
```

2. Monitor agent performance:

```python
if result["execution"]["execution_time"] > 5.0:
    logger.warning(f"Long execution time for task: {result['task']['original']}")
```

3. Implement rate limiting for concurrent tasks:

```python
from concurrent.futures import ThreadPoolExecutor
with ThreadPoolExecutor(max_workers=5) as executor:
    results = router.concurrent_batch_run(tasks)
```

4. Regular agent validation:

```python
for agent in router.agents.values():
    if not agent.validate():
        logger.error(f"Agent validation failed: {agent.name}")
```

## Performance Considerations

1. Task Batching

- Group similar tasks together

- Use concurrent_batch_run for independent tasks

- Monitor memory usage with large batches

2. Model Selection

- Choose appropriate models based on task complexity

- Balance speed vs. accuracy requirements

- Consider cost implications

3. Response Caching

- Implement caching for frequently requested analyses

- Use shared memory system for repeated queries

- Regular cache invalidation for time-sensitive data

## Security Considerations

1. Data Privacy

- Implement data encryption

- Handle sensitive information appropriately

- Regular security audits

2. Access Control

- Implement role-based access

- Audit logging

- Regular permission reviews

## Monitoring and Logging

1. Performance Metrics

- Response times

- Success rates

- Error rates

- Resource utilization

2. Logging

- Use structured logging

- Implement log rotation

- Regular log analysis

3. Alerts

- Set up alerting for critical errors

- Monitor resource usage

- Track API rate limits
