> ## Documentation Index
> Fetch the complete documentation index at: https://docs.swarms.world/llms.txt
> Use this file to discover all available pages before exploring further.

# HeavySwarm

> A sophisticated multi-agent system that decomposes tasks into specialized questions and executes them with synthesis

## Overview

The `HeavySwarm` class is a sophisticated multi-agent orchestration system that decomposes a complex task into specialized questions, runs a team of agents on them in parallel, and synthesizes the results into a comprehensive response. The `variant` parameter selects the agent line-up — from a five-agent default team up to a sixteen-agent deep-research team — and `max_loops` enables iterative refinement.

## Class Definition

```python theme={null}
from swarms.structs.heavy_swarm import HeavySwarm
```

## Parameters

<ParamField path="name" type="str" default="HeavySwarm">
  Name identifier for the swarm instance
</ParamField>

<ParamField path="description" type="str" default="A swarm of agents that can analyze a task and generate specialized questions for each agent role">
  Description of the swarm's purpose and capabilities
</ParamField>

<ParamField path="timeout" type="int" default="900">
  Maximum execution time per agent in seconds
</ParamField>

<ParamField path="question_agent_model_name" type="str" default="gpt-5.4">
  Language model for question generation
</ParamField>

<ParamField path="worker_model_name" type="str" default="gpt-5.4">
  Language model for specialized worker agents
</ParamField>

<ParamField path="verbose" type="bool" default="False">
  Enable detailed logging and debug output
</ParamField>

<ParamField path="show_dashboard" type="bool" default="False">
  Enable rich dashboard with progress visualization
</ParamField>

<ParamField path="agent_prints_on" type="bool" default="False">
  Enable individual agent output printing
</ParamField>

<ParamField path="output_type" type="str" default="dict-all-except-first">
  Output format type for conversation history
</ParamField>

<ParamField path="worker_tools" type="Optional[tool_type]" optional>
  Tools available to worker agents for enhanced functionality
</ParamField>

<ParamField path="max_loops" type="int" default="1">
  Maximum number of execution loops for the entire swarm. Each loop builds upon previous results for iterative refinement
</ParamField>

<ParamField path="variant" type="Literal[&#x22;default&#x22;, &#x22;medium&#x22;, &#x22;heavy&#x22;]" default="&#x22;default&#x22;">
  Which agent line-up to instantiate. See **Selecting a Variant** below. Passing an unknown variant raises `ValueError` during initialization
</ParamField>

## Selecting a Variant

The `variant` parameter controls which agents are created and how many specialized questions the task is decomposed into.

```python theme={null}
# Five-agent default (Research / Analysis / Alternatives / Verification + Synthesis)
swarm = HeavySwarm(variant="default")

# Four-agent Grok-style team (Captain + Harper, Benjamin, Lucas)
swarm = HeavySwarm(variant="medium")

# Sixteen-agent deep team (Grok captain + 15 domain specialists)
swarm = HeavySwarm(variant="heavy")
```

`SwarmVariant` is exported from `swarms.agents.heavy_swarm_agents`.

| `variant`   | Agents                                                        | Questions generated |
| ----------- | ------------------------------------------------------------- | ------------------- |
| `"default"` | 5 — Research, Analysis, Alternatives, Verification, Synthesis | 4                   |
| `"medium"`  | 4 — Captain Swarm + Harper, Benjamin, Lucas                   | 3                   |
| `"heavy"`   | 16 — Grok captain + 15 domain specialists                     | 15                  |

### `"medium"` roster

| Agent         | Role                                                                           |
| ------------- | ------------------------------------------------------------------------------ |
| Captain Swarm | Leader and orchestrator                                                        |
| Harper        | Research and facts — evidence gathering and fact verification                  |
| Benjamin      | Logic, math, and code — rigorous reasoning and computational verification      |
| Lucas         | Creative and divergent thinking — contrarian analysis and blind-spot detection |

### `"heavy"` roster

A Grok captain decomposes the task into 15 domain-specific questions; the 15 specialists answer them in parallel, then the captain synthesizes a single response.

| Agent     | Domain                                         |
| --------- | ---------------------------------------------- |
| Grok      | Lead coordinator and synthesizer               |
| Harper    | Creative writing and storytelling              |
| Benjamin  | Data, finance and economics                    |
| Lucas     | Coding, programming and technical builds       |
| Olivia    | Literature, arts and culture                   |
| James     | History, politics and philosophy               |
| Charlotte | Math, statistics and logic                     |
| Henry     | Engineering, robotics and innovation           |
| Mia       | Biology, health and medicine                   |
| William   | Business strategy and entrepreneurship         |
| Sebastian | Physics, astronomy and hard sciences           |
| Jack      | Psychology and human behavior                  |
| Owen      | Environment, sustainability and global systems |
| Luna      | Space exploration and futurism                 |
| Elizabeth | Ethics, policy and critical thinking           |
| Noah      | Long-term innovation and systems thinking      |

## Specialized Agents (default variant)

With the default variant, the HeavySwarm creates and manages 5 specialized agents:

### Research Agent

Expert in comprehensive information gathering, data collection, market research, and source verification. Specializes in systematic literature reviews, competitive intelligence, and statistical data interpretation.

**System Prompt Focus:**

* Comprehensive task analysis
* Evidence-based research
* Source credibility assessment
* Reproducible methodologies

### Analysis Agent

Expert in advanced statistical analysis, pattern recognition, predictive modeling, and causal relationship identification. Specializes in regression analysis, forecasting, and performance metrics development.

**System Prompt Focus:**

* Data quality assessment
* Statistical rigor
* Quantified uncertainty
* Practical interpretation

### Alternatives Agent

Expert in strategic thinking, creative problem-solving, innovation ideation, and strategic option evaluation. Specializes in design thinking, scenario planning, and exploring diverse solutions.

**System Prompt Focus:**

* Diverse option generation
* Trade-off analysis
* Risk assessment
* Implementation planning

### Verification Agent

Expert in validation, feasibility assessment, fact-checking, and quality assurance. Specializes in risk assessment, compliance verification, and implementation barrier analysis.

**System Prompt Focus:**

* Fact-checking protocols
* Feasibility validation
* Risk identification
* Evidence triangulation

### Synthesis Agent

Expert in multi-perspective integration, comprehensive analysis, and executive summary creation. Specializes in strategic alignment, conflict resolution, and holistic solution development.

**System Prompt Focus:**

* Multi-input integration
* Consensus building
* Prioritized recommendations
* Stakeholder communication

## Methods

### `run()`

```python theme={null}
def run(self, task: str, img: Optional[str] = None) -> str
```

Executes the complete HeavySwarm orchestration flow with multi-loop functionality.

**Parameters:**

<ParamField path="task" type="str" required>
  The main task to analyze and iterate upon
</ParamField>

<ParamField path="img" type="str" optional>
  Image input if needed for visual analysis tasks
</ParamField>

**Returns:**

<ResponseField name="result" type="str">
  Comprehensive final answer from the synthesis step after all loops complete
</ResponseField>

**Workflow:**

1. For first loop: Execute original task with full orchestration
2. For subsequent loops: Combine previous results with original task as context
3. Question generation: Generate specialized questions for the active variant's agents
4. Parallel execution: Run the variant's specialized agents concurrently
5. Synthesis: Integrate all agent results into a comprehensive response
6. Iteration: Repeat for max\_loops, building upon previous results

***

### `reliability_check()`

```python theme={null}
def reliability_check(self) -> None
```

Performs reliability and configuration validation checks.

**Validates:**

* worker\_model\_name is set
* question\_agent\_model\_name is set

**Raises:**

* `ValueError`: If a required model name is missing, or if `variant` is unknown

***

### `show_swarm_info()`

```python theme={null}
def show_swarm_info(self) -> None
```

Displays swarm configuration information in rich dashboard format.

Shows:

* Swarm identification (name, description)
* Execution parameters (timeout)
* Model configurations (question and worker models)
* Selected variant

## Question Generation Schema

The default variant decomposes the task into four specialized questions:

```python theme={null}
{
    "thinking": str,              # Reasoning process for question breakdown
    "research_question": str,     # Question for Research Agent
    "analysis_question": str,     # Question for Analysis Agent
    "alternatives_question": str, # Question for Alternatives Agent
    "verification_question": str  # Question for Verification Agent
}
```

The `"medium"` and `"heavy"` variants use their own schemas (3 and 15 questions respectively).

## Usage Example

```python theme={null}
from swarms.structs.heavy_swarm import HeavySwarm

# Default 5-agent variant with dashboard enabled
swarm = HeavySwarm(
    name="Market-Analysis-Swarm",
    description="Comprehensive market analysis swarm",
    question_agent_model_name="claude-sonnet-4-6",
    worker_model_name="claude-sonnet-4-6",
    show_dashboard=True,
    max_loops=3,
    verbose=True,
)

# Execute a complex task
result = swarm.run(
    task="Analyze the current cryptocurrency market trends, evaluate investment alternatives, and provide verified recommendations"
)

print(result)
```

## Multi-Loop Execution

The `max_loops` parameter enables iterative refinement:

* **Loop 1**: Initial analysis of the task
* **Loop 2+**: Refinement based on previous results
* Each loop builds upon context from previous iterations
* Enables deeper analysis and progressive refinement

**Example with 3 loops:**

```python theme={null}
swarm = HeavySwarm(
    name="DeepAnalysis",
    max_loops=3,
    show_dashboard=True,
)

result = swarm.run("Analyze AI impact on healthcare")
# Loop 1: Initial analysis
# Loop 2: Refinement based on Loop 1 insights
# Loop 3: Final comprehensive synthesis
```

## Dashboard Features

When `show_dashboard=True`, the HeavySwarm displays:

1. **Configuration Panel**: Swarm parameters and settings
2. **Reliability Checks**: Animated validation with progress tracking
3. **Question Generation**: Real-time progress for specialized questions
4. **Agent Execution**: Individual progress bars for each agent
5. **Synthesis Phase**: Integration and final report generation
6. **Completion Summary**: Mission accomplished with professional styling

All dashboard elements use Swarms-inspired red/black styling with professional formatting.

## Performance Optimization

* **Parallel Execution**: The active variant's specialized agents run concurrently
* **Thread Pool**: Workers run across a pool sized to roughly 90% of the host's CPU cores
* **Timeout Management**: Per-agent timeout controls

## Source Code

View the [source code on GitHub](https://github.com/kyegomez/swarms/blob/master/swarms/structs/heavy_swarm.py)