HeavySwarm

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 import HeavySwarm

Parameters

str

default:"HeavySwarm"

Name identifier for the swarm instance

str

Description of the swarm’s purpose and capabilities

int

default:"900"

Maximum execution time per agent in seconds

str

default:"gpt-5.4"

Language model for question generation

str

default:"gpt-5.4"

Language model for specialized worker agents

bool

default:"False"

Enable detailed logging and debug output

bool

default:"False"

Enable rich dashboard with progress visualization

bool

default:"False"

Enable individual agent output printing

str

default:"dict-all-except-first"

Output format type for conversation history

Optional[tool_type]

Tools available to worker agents for enhanced functionality

Optional[int]

default:"1"

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

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:

str

required

The main task to analyze and iterate upon

str

Image input if needed for visual analysis tasks

Returns:

Any

The conversation history formatted according to output_type (default "dict-all-except-first", which returns a list of message dicts covering the question-generation, agent, and synthesis output — excluding the initial task message — not just the synthesis agent’s final string). Pass output_type="str-all-except-first" for a plain string, or output_type="final" / "last" to get only the last message’s content.

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

`execute_question_generation()`

def execute_question_generation(self, task: str) -> Dict[str, str]

Generates the active variant’s specialized questions for a task using the configured question_agent_model_name, without running the worker agents or synthesis. Returns the raw parsed tool-call output, including thinking, the per-agent *_question keys, tool_call_id, and function_name (or an error key if generation/parsing failed).

str

required

The main task to analyze and decompose into specialized questions

`get_questions_only()`

def get_questions_only(self, task: str) -> Dict[str, str]

Generates the specialized questions for a task and returns only the clean *_question keys (filters out thinking, tool_call_id, and function_name). Useful for previewing or debugging question generation without running the full swarm.

str

required

The main task or query to decompose into specialized questions

Returns:

Dict[str, str]

Clean dictionary of *_question keys for the active variant (e.g. research_question, analysis_question, alternatives_question, verification_question for the default variant), or {"error": ...} on failure

swarm = HeavySwarm()
questions = swarm.get_questions_only("Analyze market trends for EVs")
print(questions["research_question"])

`get_questions_as_list()`

def get_questions_as_list(self, task: str) -> List[str]

Generates the specialized questions for a task and returns them as an ordered list instead of a dict — convenient for iteration or display. Internally calls get_questions_only().

str

required

The main task or query to decompose into specialized questions

Returns:

List[str]

Ordered list of the active variant’s questions (for the default variant: research, analysis, alternatives, verification, in that order), or a single-item list containing an error message on failure

swarm = HeavySwarm()
questions = swarm.get_questions_as_list("Optimize supply chain efficiency")
for i, question in enumerate(questions):
    print(f"Agent {i+1}: {question}")

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

Core Classes

Multi-Agent Harnesses

Tools & Utilities

Deployment

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

`execute_question_generation()`

`get_questions_only()`

`get_questions_as_list()`

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

​execute_question_generation()

​get_questions_only()

​get_questions_as_list()

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

`execute_question_generation()`

`get_questions_only()`

`get_questions_as_list()`

Question Generation Schema

Usage Example

Multi-Loop Execution

Dashboard Features

Performance Optimization

Source Code