HeavySwarm - swarms

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

from swarms.structs.heavy_swarm import HeavySwarm

Parameters

name

str

default:"HeavySwarm"

Name identifier for the swarm instance

description

str

Description of the swarm’s purpose and capabilities

timeout

int

default:"900"

Maximum execution time per agent in seconds

question_agent_model_name

str

default:"gpt-5.4"

Language model for question generation

worker_model_name

str

default:"gpt-5.4"

Language model for specialized worker agents

verbose

bool

default:"False"

Enable detailed logging and debug output

show_dashboard

bool

default:"False"

Enable rich dashboard with progress visualization

agent_prints_on

bool

default:"False"

Enable individual agent output printing

output_type

str

default:"dict-all-except-first"

Output format type for conversation history

worker_tools

Optional[tool_type]

Tools available to worker agents for enhanced functionality

max_loops

int

default:"1"

Maximum number of execution loops for the entire swarm. Each loop builds upon previous results for iterative refinement

variant

Literal["default", "medium", "heavy"]

default:"\"default\""

Which agent line-up to instantiate. See Selecting a Variant below. Passing an unknown variant raises ValueError during initialization

Selecting a Variant

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

# 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()`

def run(self, task: str, img: Optional[str] = None) -> str

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

task

str

required

The main task to analyze and iterate upon

img

str

Image input if needed for visual analysis tasks

Returns:

result

str

Comprehensive final answer from the synthesis step after all loops complete

Workflow:

For first loop: Execute original task with full orchestration
For subsequent loops: Combine previous results with original task as context
Question generation: Generate specialized questions for the active variant’s agents
Parallel execution: Run the variant’s specialized agents concurrently
Synthesis: Integrate all agent results into a comprehensive response
Iteration: Repeat for max_loops, building upon previous results

`reliability_check()`

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()`

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:

{
    "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

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:

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:

Configuration Panel: Swarm parameters and settings
Reliability Checks: Animated validation with progress tracking
Question Generation: Real-time progress for specialized questions
Agent Execution: Individual progress bars for each agent
Synthesis Phase: Integration and final report generation
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

​Overview

​Class Definition

​Parameters

​Selecting a Variant

​"medium" roster

​"heavy" roster

​Specialized Agents (default variant)

​Research Agent

​Analysis Agent

​Alternatives Agent

​Verification Agent

​Synthesis Agent

​Methods

​run()

​reliability_check()

​show_swarm_info()

​Question Generation Schema

​Usage Example

​Multi-Loop Execution

​Dashboard Features

​Performance Optimization

​Source Code

Overview

Class Definition

Parameters

Selecting a Variant

`"medium"` roster

`"heavy"` roster

Specialized Agents (default variant)

Research Agent

Analysis Agent

Alternatives Agent

Verification Agent

Synthesis Agent

Methods

`run()`

`reliability_check()`

`show_swarm_info()`

Question Generation Schema

Usage Example

Multi-Loop Execution

Dashboard Features

Performance Optimization

Source Code