Skip to main content
Swarm Type: MultiAgentRouter

Overview

The MultiAgentRouter acts as an intelligent task dispatcher. A built-in boss agent on gpt-5.4 reads the task and each agent’s name and description, then routes the task to the most suitable agent, or splits it across several. Key features:
  • Intelligent Routing: Automatically assigns tasks to best-suited agents
  • Capability Matching: Matches task requirements with agent names and descriptions
  • Task Splitting: Can break a multi-part task into sub-tasks for different agents

Architecture

The router reads the task and dispatches it to the best-suited agent. Agents it does not pick, shown dashed, never run.

Use Cases

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

API Usage

Basic MultiAgentRouter Example

Example Response:

Output Shape

Every swarm run is executed through a SwarmRouter with output_type forced to "dict" server-side (see api/swarm_completions.py), so output is a list of {"role": ..., "content": ...} conversation turns rather than a single string. MultiAgentRouter runs an internal router step that inspects the task and hands it off via function calling — a task can be routed to a single specialist or split across several agents at once when the router decides more than one applies. output holds the task as a user turn followed by the response of the first agent the router selected. There is no routing-decision turn. When the router splits the task across several agents, all of them run (and are billed), but only the first selected agent’s response is added to output. An agent in your agents array that the router does not select never runs and contributes no turn. If you need every specialist’s answer to a multi-part task, send one request per part or use ConcurrentWorkflow.

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