MultiAgentRouter

Overview

The MultiAgentRouter uses a boss agent powered by LLMs to intelligently route tasks to the most appropriate specialized agent(s). The boss agent analyzes task requirements and agent capabilities to make routing decisions, supporting both single and multiple agent assignments.

Installation

pip install -U swarms

Attributes

Optional[str]

default:"None"

Unique identifier for the router instance. When left as None, resolves to generate_id("multi-agent-router")

str

default:"swarm-router"

The name of the router

str

A description of the router’s purpose

List[Callable]

default:"None"

A list of agents to be managed by the router

str

default:"gpt-5.4"

The model to use for the boss agent

float

default:"0.1"

The temperature for the boss agent’s model

callable

default:"None"

Stored on the router as shared_memory_system. Nothing in the router reads it.

OutputType

default:"dict"

The type of output expected from the agents

bool

default:"True"

Whether to print the boss agent’s decision

str

default:"None"

Custom system prompt for the router

bool

default:"True"

Whether to skip executing agents when their assigned task is null or None

Any extra positional or keyword arguments are forwarded to the LiteLLM instance that backs the boss agent (router.function_caller).

Methods

route_task()

Routes a task to the appropriate agent(s) and returns their response.

def route_task(self, task: str) -> dict

Parameters:

task (str): The task to be routed

Returns: The formatted conversation history (shaped by output_type), containing the user task and the response(s) that were appended to it.

When the boss selects multiple agents, handle_multiple_handoffs() runs all of them concurrently but only appends the first selected agent’s response to the conversation — every other agent’s output is computed and then discarded. The boss’s reasoning is never added to the conversation either (it is only printed to the console when print_on=True), so it is not present in the returned result.

run()

Alias for route_task(). Each call is recorded as a MultiAgentRouter.run trace span when telemetry is enabled. Calling the router directly, router(task), does the same thing.

def run(self, task: str) -> dict

batch_run()

Batch route tasks to the appropriate agents sequentially.

def batch_run(self, tasks: List[str] = []) -> list

Parameters:

tasks (List[str]): List of tasks to route

Returns: Routing results for the tasks that succeeded, in input order. A task that raises is logged and left out of the list; the batch keeps going.

concurrent_batch_run()

Concurrently route tasks to the appropriate agents.

def concurrent_batch_run(self, tasks: List[str] = []) -> list

Parameters:

tasks (List[str]): List of tasks to route

Returns: Routing results for the tasks that succeeded, in input order. A task that raises is logged and left out of the list.

Every task shares the router’s single Conversation, so their histories interleave. Use batch_run() when each result’s history matters.

Usage Examples

Basic Routing

from swarms import Agent, MultiAgentRouter

# Define specialized agents
agents = [
    Agent(
        agent_name="ResearchAgent",
        description="Specializes in researching topics and providing detailed, factual information",
        system_prompt="You are a research specialist. Provide detailed, well-researched information.",
        model_name="gpt-5.4",
    ),
    Agent(
        agent_name="CodeExpertAgent",
        description="Expert in writing, reviewing, and explaining code",
        system_prompt="You are a coding expert. Write and review code with best practices.",
        model_name="gpt-5.4",
    ),
    Agent(
        agent_name="WritingAgent",
        description="Skilled in creative and technical writing",
        system_prompt="You are a writing specialist. Create and edit content.",
        model_name="gpt-5.4",
    ),
]

# Initialize router
router = MultiAgentRouter(agents=agents)

# Route a task
task = "Write a Python function to calculate fibonacci numbers"
result = router.route_task(task)

print(result)

Custom System Prompt

router = MultiAgentRouter(
    name="custom-router",
    agents=agents,
    system_prompt="You are an expert task router. Always select the most qualified agent.",
    model="claude-sonnet-4-6",
    temperature=0.2
)

result = router.run("Explain quantum computing")

Batch Processing

tasks = [
    "Research the latest AI developments",
    "Write a function to sort an array",
    "Create a blog post about technology trends"
]

# Sequential batch processing
results = router.batch_run(tasks)

# Concurrent batch processing
results_concurrent = router.concurrent_batch_run(tasks)

Multiple Agent Assignment

# The router can assign complex tasks to multiple agents
task = "Research quantum computing and write a tutorial with code examples"

# The boss agent will intelligently split this across multiple agents:
# - ResearchAgent for the research
# - CodeExpertAgent for the code examples  
# - WritingAgent for the tutorial writing

result = router.route_task(task)

# NOTE: all selected agents run concurrently, but only the FIRST selected
# agent's response is appended to the conversation and present in `result`.
# The other agents' outputs are computed but discarded.

Skip Null Tasks

router = MultiAgentRouter(
    agents=agents,
    skip_null_tasks=True  # Skip agents with null/None tasks
)

# If boss agent assigns null task to an agent, it will be skipped
result = router.route_task("Simple task")

Response Format

The boss agent returns routing decisions in this JSON format:

{
  "handoffs": [
    {
      "reasoning": "This agent is best suited because...",
      "agent_name": "ResearchAgent",
      "task": "Research the latest AI developments in detail"
    }
  ]
}

For multiple agents:

{
  "handoffs": [
    {
      "reasoning": "Research capabilities needed for background",
      "agent_name": "ResearchAgent",
      "task": "Research quantum computing fundamentals"
    },
    {
      "reasoning": "Code expertise for implementation examples",
      "agent_name": "CodeExpertAgent",
      "task": "Create code examples demonstrating quantum algorithms"
    }
  ]
}

Features

Intelligent Routing: Boss agent analyzes task requirements and agent capabilities
Single or Multiple Agents: Automatically determines if task requires one or multiple agents
Custom Routing Logic: Override system prompt to customize routing behavior
Batch Processing: Process multiple tasks sequentially or concurrently
Flexible Output: Support for various output formats (dict, string, json, etc.)
Null Task Handling: Option to skip agents with null/empty task assignments

Core Classes

Multi-Agent Harnesses

Tools & Utilities

Deployment

MultiAgentRouter

Overview

Installation

Attributes

Methods

route_task()

run()

batch_run()

concurrent_batch_run()

Usage Examples

Basic Routing

Custom System Prompt

Batch Processing

Multiple Agent Assignment

Skip Null Tasks

Response Format

Features

​Overview

​Installation

​Attributes

​Methods

​route_task()

​run()

​batch_run()

​concurrent_batch_run()

​Usage Examples

​Basic Routing

​Custom System Prompt

​Batch Processing

​Multiple Agent Assignment

​Skip Null Tasks

​Response Format

​Features

Overview

Installation

Attributes

Methods

route_task()

run()

batch_run()

concurrent_batch_run()

Usage Examples

Basic Routing

Custom System Prompt

Batch Processing

Multiple Agent Assignment

Skip Null Tasks

Response Format

Features