Skip to main content
Swarm Type: HierarchicalSwarm

Overview

The HierarchicalSwarm implements a multi-level organizational structure where supervisor agents coordinate and manage specialized worker agents. This architecture mirrors real-world organizational hierarchies, allowing for complex task decomposition, quality control, and efficient resource allocation across multiple levels of responsibility. Key features:
  • Multi-Level Structure: Supervisor and worker agent hierarchy
  • Task Decomposition: Complex tasks broken down into manageable subtasks
  • Parallel Execution: Workers run their orders at the same time
  • Resource Coordination: Efficient allocation and management of agent resources

Architecture

The supervisor plans the task and hands an order to each worker it picks. The workers run their orders in parallel, and the swarm returns their outputs. There is no review or synthesis step: the API doesn’t enable the director’s feedback pass, so no agent reads the others’ work within a loop. With max_loops above 1, each later loop gives the director the previous loop’s results to plan from.
The “Supervisor” in the diagram is a director agent that HierarchicalSwarm creates for you automatically — it is not one of the entries in agents. Every agent you list in agents runs as a worker the director can delegate to, even if you name one of them “coordinator” or set its role. To have one agent merge the others’ work, use AgentRearrange with a flow that ends at that agent (e.g. "a, b, c -> synthesizer"), SequentialWorkflow, or a Graph Workflow. Tune the director itself with the top-level director_model_name and director_settings fields (see Configuring the Director below).

Use Cases

  • Complex project management and coordination
  • Multi-stage research and analysis workflows
  • Content creation with editorial oversight
  • Quality assurance and validation processes

API Usage

Basic HierarchicalSwarm Example

Example Response:
output always starts with a System turn listing the team and a Director turn holding the director’s orders, and each loop ends with a System turn such as --- Loop 1/1 completed ---. The worker turns in between are the actual answers. The director’s turn is named after director_settings.agent_name when you set it.

Configuring the Director

HierarchicalSwarm runs a director agent that decomposes the task and delegates it to your worker agents. The director is created by the swarm itself rather than supplied in the agents array, so it is configured through two top-level SwarmSpec fields. director_settings keys: To pick the director’s model, use director_model_name; model_name is not accepted inside director_settings:
A lower temperature on the director produces more consistent task decomposition and delegation, while worker agents can keep a higher temperature for creative output.

Errors

Besides the errors every swarm can return (see the Swarm Completions Reference), a HierarchicalSwarm returns 502 when the director doesn’t produce valid orders, for example because its max_tokens is too small for the order list. No worker runs and nothing is charged:

Best Practices

  • Design clear supervisor-worker relationships
  • Give each worker a self-contained responsibility, since workers don’t see each other’s output
  • Use a capable director_model_name — the director’s plan determines how well the workers perform
  • Lower the director’s temperature for more deterministic task decomposition
  • Use for complex projects requiring oversight and coordination
  • Ideal for research, content creation, and project management