Skip to main content
Swarm Type: MultiAgentRouter

​
Overview

The MultiAgentRouter acts as an intelligent task dispatcher, distributing work across agents based on their capabilities and current workload. This architecture analyzes incoming tasks and automatically routes them to the most suitable agents, optimizing both efficiency and quality of outcomes. Key features:
  • Intelligent Routing: Automatically assigns tasks to best-suited agents
  • Capability Matching: Matches task requirements with agent specializations
  • Load Balancing: Distributes workload efficiently across available agents
  • Dynamic Assignment: Adapts routing based on agent performance and availability

​
Use Cases

  • Customer service request routing
  • Content categorization and processing
  • Technical support ticket assignment
  • Multi-domain question answering

​
API Usage

​
Basic MultiAgentRouter Example

  • Shell (curl)
  • Python (requests)
  • JavaScript (fetch)
  • Go
  • Rust
curl -X POST "https://api.swarms.world/v1/swarm/completions" \
  -H "x-api-key: $SWARMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support Router",
    "description": "Route customer inquiries to specialized support agents",
    "swarm_type": "MultiAgentRouter",
    "task": "Handle multiple customer inquiries: 1) Billing question about overcharge, 2) Technical issue with mobile app login, 3) Product recommendation for enterprise client, 4) Return policy question",
    "agents": [
      {
        "agent_name": "Billing Specialist",
        "description": "Handles billing, payments, and account issues",
        "system_prompt": "You are a billing specialist. Handle all billing inquiries, payment issues, refunds, and account-related questions with empathy and accuracy.",
        "model_name": "gpt-4o",
        "max_loops": 1,
        "temperature": 0.3
      },
      {
        "agent_name": "Technical Support",
        "description": "Resolves technical issues and troubleshooting",
        "system_prompt": "You are a technical support specialist. Diagnose and resolve technical issues, provide step-by-step troubleshooting, and escalate complex problems.",
        "model_name": "gpt-4o",
        "max_loops": 1,
        "temperature": 0.2
      },
      {
        "agent_name": "Sales Consultant",
        "description": "Provides product recommendations and sales support",
        "system_prompt": "You are a sales consultant. Provide product recommendations, explain features and benefits, and help customers find the right solutions.",
        "model_name": "gpt-4o",
        "max_loops": 1,
        "temperature": 0.4
      },
      {
        "agent_name": "Policy Advisor",
        "description": "Explains company policies and procedures",
        "system_prompt": "You are a policy advisor. Explain company policies, terms of service, return procedures, and compliance requirements clearly.",
        "model_name": "gpt-4o",
        "max_loops": 1,
        "temperature": 0.1
      }
    ],
    "max_loops": 1
  }'
Example Response: 
{
    "job_id": "swarms-R17nZFDesmLHxCRoeyF3NVYvPaXk",
    "status": "success",
    "swarm_name": "Customer Support Router",
    "description": "Route customer inquiries to specialized support agents",
    "swarm_type": "MultiAgentRouter",
    "output": [
        {
            "role": "Billing Specialist",
            "content": "I'll handle the billing question about the overcharge. Let me review your account and explain the charges..."
        },
        {
            "role": "Technical Support",
            "content": "I'll help you resolve the mobile app login issue. Let's troubleshoot this step by step..."
        },
        {
            "role": "Sales Consultant",
            "content": "I'll provide product recommendations for your enterprise client. Based on their needs..."
        },
        {
            "role": "Policy Advisor",
            "content": "I'll explain our return policy clearly. Here are the key points you need to know..."
        }
    ],
    "number_of_agents": 4,
    "service_tier": "standard",
    "execution_time": 18.5,
    "usage": {
        "input_tokens": 45,
        "output_tokens": 2100,
        "total_tokens": 2145,
        "billing_info": {
            "cost_breakdown": {
                "agent_cost": 0.04,
                "input_token_cost": 0.000135,
                "output_token_cost": 0.0315,
                "token_counts": {
                    "total_input_tokens": 45,
                    "total_output_tokens": 2100,
                    "total_tokens": 2145
                },
                "num_agents": 4,
                "service_tier": "standard",
                "night_time_discount_applied": true
            },
            "total_cost": 0.071635,
            "discount_active": true,
            "discount_type": "night_time",
            "discount_percentage": 75
        }
    }
}

​
Best Practices

  • Design agents with clear, distinct specializations
  • Use for tasks that can be categorized and routed
  • Ensure agents have complementary capabilities
  • Ideal for customer service and support workflows
⌘I