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. The specialist workers run with max_loops="auto", so each one works through the autonomous loop on its question. The synthesis agent (or captain) runs a single loop.

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"

Seconds passed to each worker future’s result() call. Results are read as each worker finishes, so this does not interrupt a worker that is still running

str

default:"gpt-5.4"

Language model for question generation. The decomposer sends no temperature or top-p, so it runs on providers that reject the two together, such as Anthropic

str

default:"gpt-5.4"

Language model for every agent the variant builds: the specialist workers and the synthesis agent or captain

bool

default:"False"

Enable detailed logging and debug output

bool

default:"False"

Enable rich dashboard with progress visualization

bool

default:"False"

Print each specialist worker’s output. The synthesis agent or captain always prints

str

default:"dict-all-except-first"

Output format type for conversation history

Optional[tool_type]

Tools given to every agent the variant builds, including the synthesis agent or captain

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, when the agents are built

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.

run() does not raise when a phase fails. It returns an error string instead, such as "Error in question generation: ..." or "Failed to execute agents in loop 1: ...". If one worker raises, the error is logged, that worker’s answer is missing from the conversation, and the other workers continue.

Workflow:

Clears the conversation, so each call starts from an empty history, and adds the task
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. When img is given, the decomposer sees the image too, so the questions refer to what it shows
Parallel execution: Run the variant’s specialized agents concurrently, each on its own question and the image
Synthesis: The synthesis agent or captain receives the conversation as chat turns (the task, the generated questions and every worker’s answer) and writes the final response
Iteration: Repeat for max_loops, building upon previous results

`usage`

@property
def usage(self) -> dict

Provider token usage summed over everything the swarm has run: every question-generation call plus the usage of each agent the variant built, including the synthesis agent or captain. Keys are input_tokens, output_tokens, cached_tokens, reasoning_tokens and total_tokens. The total grows across loops and across run() calls, and each read returns a new dict. See Token usage.

swarm = HeavySwarm(variant="medium")
swarm.run("Assess the risks of a four-day work week")
print(swarm.usage["total_tokens"])

`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

An unknown variant raises ValueError earlier in __init__, when the agents are built.

`show_swarm_info()`

def show_swarm_info(self) -> None

Displays swarm configuration information in rich dashboard format. Does nothing unless show_dashboard=True. Shows:

Swarm identification (name, description)
Execution parameters (timeout, max workers)
Model configurations (question and worker models)

`execute_question_generation()`

def execute_question_generation(
    self, task: str, img: Optional[str] = None
) -> 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. Each variant has its own decomposer prompt and function schema. 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 the arguments could not be parsed). Returns an empty dict when the model makes no tool call.

str

required

The main task to analyze and decompose into specialized questions

str

Image that accompanies the task. The decomposer reads it, so a visual task is not decomposed from the sentence alone

`get_questions_only()`

def get_questions_only(
    self, task: str, img: Optional[str] = None
) -> 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

str

Image passed to the decomposer with the task

Returns:

Dict[str, str]

Clean dictionary of *_question keys for the active variant (research_question, analysis_question, alternatives_question, verification_question for the default variant; harper_question, benjamin_question, lucas_question for "medium"; one key per specialist for "heavy"), 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, img: Optional[str] = None
) -> 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

str

Image passed to the decomposer with the task

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), with one <name>_question key per specialist, for example harper_question.

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)
print(swarm.usage)

With an image

from swarms import HeavySwarm

swarm = HeavySwarm(
    name="Chart-Analysis-Swarm",
    question_agent_model_name="claude-sonnet-4-6",
    worker_model_name="claude-sonnet-4-6",
    variant="medium",
)

task = "Analyse this chart and recommend what the business should do next quarter."

# The decomposer sees the image, so the questions cite what the chart shows
questions = swarm.get_questions_only(task, img="revenue_by_region.png")
result = swarm.run(task, img="revenue_by_region.png")

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: An “analysis complete” panel

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: timeout is applied when each finished worker’s result is read; it does not stop a running worker

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

`usage`

`reliability_check()`

`show_swarm_info()`

`execute_question_generation()`

`get_questions_only()`

`get_questions_as_list()`

Question Generation Schema

Usage Example

With an image

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

​usage

​reliability_check()

​show_swarm_info()

​execute_question_generation()

​get_questions_only()

​get_questions_as_list()

​Question Generation Schema

​Usage Example

​With an image

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

`usage`

`reliability_check()`

`show_swarm_info()`

`execute_question_generation()`

`get_questions_only()`

`get_questions_as_list()`

Question Generation Schema

Usage Example

With an image

Multi-Loop Execution

Dashboard Features

Performance Optimization

Source Code