Heavy Swarm - swarms

The HeavySwarm is a multi-agent orchestration system inspired by X.AI’s Grok Heavy implementation. It decomposes a task into role-specific questions, runs those questions through specialized expert agents in parallel, and then synthesizes the outputs into a single comprehensive answer. The exact set of experts is controlled by the variant parameter.

When to Use

Complex research tasks — in-depth investigation across multiple angles
Financial analysis — investment decisions requiring multiple viewpoints
Strategic planning — comprehensive evaluation of options and trade-offs
Due diligence — thorough verification and risk assessment
Multi-faceted problems — issues that need research, analysis, and synthesis combined

Key Features

Intelligent question generation tailored to each agent role, with its own decomposer per variant
Image-aware decomposition: pass img and the questions are written from what the image shows
Three preset variants — default (5 agents), medium (4 Grok-style agents), heavy (16 agents)
Parallel execution on a thread pool; each worker runs the autonomous loop on its question
Synthesis agent that integrates expert outputs into a final answer
Token usage summed across question generation and every agent, via usage
Optional real-time rich dashboard
Multi-loop iterative refinement (each loop builds on the previous result)
Tool integration through worker_tools
Inherits SerializableMixin — to_dict() is available for telemetry / persistence

Architecture

1. Question Generation
   - The question model (question_agent_model_name) reads the task,
     and the image when one is given
   - Calls a function with one question per expert role

2. Parallel Expert Execution (variant-dependent)
   - default : Research, Analysis, Alternatives, Verification
   - medium  : Harper, Benjamin, Lucas
   - heavy   : 15 domain specialists

3. Synthesis
   - default: Synthesis-Agent; medium: Captain-Swarm; heavy: Grok
   - Receives the conversation as chat turns: task, questions, every answer
   - Produces the final report

4. Optional Multi-Loop Refinement
   - Each subsequent loop receives the previous synthesis as context

Basic Example

from swarms import HeavySwarm

swarm = HeavySwarm(
    name="Investment-Research-Team",
    description="Comprehensive investment analysis",
    question_agent_model_name="gpt-5.4",
    worker_model_name="gpt-5.4",
    show_dashboard=True,
    max_loops=1,
)

result = swarm.run(
    "Should we invest in NVIDIA stock? Provide detailed analysis."
)
print(result)

With Tool Integration

from swarms import HeavySwarm
from swarms_tools import exa_search

swarm = HeavySwarm(
    name="Market-Research-Team",
    description="Research team with web search capabilities",
    question_agent_model_name="gpt-5.4",
    worker_model_name="claude-sonnet-4-6",
    worker_tools=[exa_search],   # tools available to every worker
    show_dashboard=True,
    max_loops=2,                 # iterative refinement
)

result = swarm.run(
    "Find the best 3 gold ETFs with current data from the web"
)

Selecting a Variant

The variant parameter controls which agents are instantiated.

# 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. Passing an unknown variant raises ValueError during initialization.

Specialized Agents (default variant)

Research Agent

Comprehensive information gathering
Data collection and validation
Source verification
Literature review
Statistical data interpretation

Analysis Agent

Pattern recognition
Statistical analysis
Predictive modeling
Data interpretation
Performance metrics

Alternatives Agent

Strategic thinking
Creative problem-solving
Option generation
Trade-off evaluation
Scenario planning

Verification Agent

Fact-checking
Feasibility assessment
Risk analysis
Compliance verification
Quality assurance

Synthesis Agent

Multi-perspective integration
Comprehensive analysis
Executive summary creation
Strategic alignment
Actionable recommendations

Key Parameters

str

default:"HeavySwarm"

Identifier for the swarm instance.

str

Description of the swarm’s purpose.

int

default:"900"

Seconds passed to each worker future’s result() call. Results are read as workers finish, so it does not interrupt a running worker.

str

default:"gpt-5.4"

Model used by the question-generation agent.

str

default:"gpt-5.4"

Model used by every agent the variant builds, including the synthesis agent or captain.

bool

default:"False"

Enable detailed logging output.

bool

default:"False"

Enable the real-time rich progress dashboard.

bool

default:"False"

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

str

default:"dict-all-except-first"

Format of the returned conversation history.

Optional[tool_type]

Tools made available to every agent the variant builds.

int

default:"1"

Number of full swarm iterations. Each loop refines the previous synthesis.

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

default:"\"default\""

Which agent line-up to instantiate. See Selecting a Variant above.

Methods

`run(task, img=None)`

Execute the full multi-phase workflow.

result = swarm.run(
    task="Analyze cryptocurrency market trends",
    img=None,   # optional image input
)

Each call clears the swarm’s conversation first, so the returned transcript covers only the current task.

`usage`

Provider token counts summed over question generation and every agent, including the synthesis agent or captain. The total keeps growing across loops and run() calls. See Token usage.

swarm.run("Analyze cryptocurrency market trends")
print(swarm.usage)
# {"input_tokens": ..., "output_tokens": ..., "cached_tokens": ...,
#  "reasoning_tokens": ..., "total_tokens": ...}

`get_questions_only(task, img=None)` and `get_questions_as_list(task, img=None)`

Run only the decomposer and return its questions as a dict of *_question keys or as an ordered list. Useful for previewing what each worker will be asked.

questions = swarm.get_questions_only("Analyze market trends for EVs")

`to_dict()`

Inherited from SerializableMixin. Returns a JSON-friendly snapshot of the swarm’s config. The agents, conversation, dashboard, and worker_tools attributes are excluded via _to_dict_exclude to keep the snapshot lightweight.

snapshot = swarm.to_dict()

Question Generation

The question agent emits a JSON object whose schema depends on the variant. For the default variant it looks like:

{
    "thinking": "Reasoning for how to break down the task",
    "research_question": "Question for Research Agent",
    "analysis_question": "Question for Analysis Agent",
    "alternatives_question": "Question for Alternatives Agent",
    "verification_question": "Question for Verification Agent"
}

The "medium" and "heavy" variants return one <name>_question key per specialist instead, such as harper_question. Each variant has its own decomposer prompt and schema, and the decomposer sends no temperature or top-p, so it also runs on Anthropic models. When you pass img, the decomposer is told an image accompanies the task and reads it. Example generated questions for “Invest in NVIDIA?”:

{
    "thinking": "Need to evaluate financials, market position, alternatives, and risks",
    "research_question": "Research NVIDIA's financial performance, product pipeline, and market position in AI chips",
    "analysis_question": "Analyze NVIDIA's revenue growth, profit margins, and competitive advantages in the AI accelerator market",
    "alternatives_question": "What are alternative semiconductor investments with similar growth potential?",
    "verification_question": "Verify NVIDIA's claimed AI leadership and assess risks to their market dominance"
}

With max_loops > 1 the swarm iterates, each loop feeding the previous synthesis back as context:

swarm = HeavySwarm(
    name="Deep-Analysis-Team",
    worker_model_name="claude-sonnet-4-6",
    max_loops=3,
)

result = swarm.run("Complex strategic decision")

Per-loop semantics:

Loop 1: original task only
Loop 2: "Previous loop results: <output>\n\nOriginal task: <task>\n\n" followed by an instruction to refine and build on the previous loop
Loop 3: same shape — refine, fill gaps, deepen the analysis

The conversation is kept across loops within one run(), so a later synthesis also sees the earlier loops’ questions and answers.

Dashboard Features

When show_dashboard=True, the HeavySwarmDashboard renders rich progress panels: Configuration Panel:

Swarm name and description
Model configuration (question + worker)
Timeout and worker counts

Reliability Check Phase:

Animated progress bars
Per-component validation status

Question Generation Phase:

Real-time generation progress

Agent Execution Phase:

Per-agent progress bars
Status (INITIALIZING, PROCESSING QUERY, EXECUTING, GENERATING RESPONSE, COMPLETE, or ERROR / TIMEOUT)
Variant-aware agent labels

Synthesis Phase:

Integration progress
Final report generation
Completion confirmation

Use Cases

Investment Analysis

swarm = HeavySwarm(
    name="Investment-Committee",
    description="Comprehensive investment evaluation team",
    worker_model_name="claude-sonnet-4-6",
    show_dashboard=True,
)

analysis = swarm.run(
    "Evaluate Tesla as a long-term investment. Consider financials, "
    "market position, competition, risks, and alternatives."
)

Market Research with Live Web Data

from swarms_tools import exa_search

swarm = HeavySwarm(
    name="Market-Intel-Team",
    worker_model_name="gpt-5.4",
    worker_tools=[exa_search],
    max_loops=2,
)

research = swarm.run(
    "Research the enterprise AI market: size, growth, key players, "
    "trends, and opportunities. Use current web data."
)

Strategic Planning

swarm = HeavySwarm(
    name="Strategy-Team",
    description="Strategic planning and analysis",
    worker_model_name="claude-sonnet-4-6",
    max_loops=2,
    show_dashboard=True,
)

strategy = swarm.run(
    "Should our company enter the AI agent services market? "
    "Analyze market, competition, requirements, risks, and alternatives."
)

Heavy Variant for Deep Research

swarm = HeavySwarm(
    name="Deep-Research-Team",
    worker_model_name="gpt-5.4",
    variant="heavy",       # 16 agents
    max_loops=2,
)

report = swarm.run(
    "Build a long-form briefing on the global AI compute supply chain, "
    "covering geopolitics, fabrication capacity, chip design, and downstream demand."
)

Performance Notes

Parallel Execution

All workers fan out on a thread pool that carries the tracing context into each thread. self.max_workers is set to int(os.cpu_count() * 0.9); it is not a constructor parameter.

with ContextThreadPoolExecutor(max_workers=self.max_workers) as executor:
    future_to_agent = {
        executor.submit(execute_agent, task): task[0]
        for task in agent_tasks
    }

Timeout

swarm = HeavySwarm(timeout=900)

The timeout is passed to future.result() after as_completed() has already returned that future, so it does not cut a slow worker short.

Verbose Logging

swarm = HeavySwarm(
    verbose=True,
    agent_prints_on=True,
)

Output Structure

The swarm returns the conversation history formatted by output_type. The default "dict-all-except-first" returns a list of message dicts, without the initial task message:

[
    {"role": "Question Generator Agent", "content": {...}},
    {"role": "Research-Agent", "content": "<research findings>"},
    {"role": "Analysis-Agent", "content": "<analysis insights>"},
    {"role": "Alternatives-Agent", "content": "<alternative options>"},
    {"role": "Verification-Agent", "content": "<verification results>"},
    {"role": "Synthesis Agent", "content": "<comprehensive synthesis>"},
]

Worker messages appear in the order the workers finished. Each message also carries timestamp, message_id and category keys. Use output_type="final" to get only the synthesis.

Best Practices

Model Selection: use stronger models (Claude Sonnet, GPT-5.4) for worker agents on complex tasks.

Question Quality — a stronger question-generation model produces tighter, less overlapping expert questions.
Worker Models — balance cost vs quality for the worker pool; mixing providers via LiteLLM works out of the box.
Loop Count — start at max_loops=1. Add more only when the synthesis clearly needs refinement.
Variant Choice — default covers most tasks; reach for heavy only when you genuinely benefit from 15+ specialist perspectives.
Dashboard — leave on for demos and debugging; off for production.
Tools — supply worker_tools when the task requires real-time data (search, web fetch, etc.).

HeavySwarm is resource-intensive. Each loop runs N expert agents + a question generator + a synthesizer. Token costs scale roughly linearly with both variant and max_loops.

Reliability Checks

reliability_check() runs automatically during __init__:

# Validation: worker_model_name and question_agent_model_name must be set

try:
    swarm = HeavySwarm(worker_model_name=None)
except ValueError as e:
    print(e)

When show_dashboard=True, the validation steps animate through the dashboard. Otherwise a single confirmation panel prints. An unknown variant raises ValueError before this check, when __init__ builds the agents.

Conversation History

Access the full transcript through the conversation object:

result = swarm.run("Task")
history = swarm.conversation.conversation_history

# Format:
# [{"role": "User", "content": "Task"},
#  {"role": "Question Generator Agent", "content": {...}},
#  {"role": "Research-Agent", "content": "..."},
#  {"role": "Analysis-Agent", "content": "..."},
#  {"role": "Alternatives-Agent", "content": "..."},
#  {"role": "Verification-Agent", "content": "..."},
#  {"role": "Synthesis Agent", "content": "..."}]
# Each entry also has timestamp, message_id and category keys.

Error Handling

run() does not raise when a phase fails. It logs the error and returns a message string instead of the formatted conversation:

result = swarm.run("Task")

if isinstance(result, str) and result.startswith(
    ("Error", "Failed", "Critical error")
):
    print(f"Swarm execution failed: {result}")

If a single worker raises, the error is logged, that worker’s answer is left out of the conversation, and the other workers and the synthesis still run.

Mixture of Agents — parallel experts + aggregator (lighter weight)
Hierarchical Swarm — director-worker delegation pattern
Concurrent Workflow — simpler parallel execution
Agent Rearrange — custom flow patterns
Structures Catalog — full enumeration of every multi-agent structure

​When to Use

​Key Features

​Architecture

​Basic Example

​With Tool Integration

​Selecting a Variant

​Specialized Agents (default variant)

​Research Agent

​Analysis Agent

​Alternatives Agent

​Verification Agent

​Synthesis Agent

​Key Parameters

​Methods

​run(task, img=None)

​usage

​get_questions_only(task, img=None) and get_questions_as_list(task, img=None)

​to_dict()

​Question Generation

​Multi-Loop Refinement

​Dashboard Features

​Use Cases

​Investment Analysis

​Market Research with Live Web Data

​Strategic Planning

​Heavy Variant for Deep Research

​Performance Notes

​Parallel Execution

​Timeout

​Verbose Logging

​Output Structure

​Best Practices

​Reliability Checks

​Conversation History

​Error Handling

​Related Architectures

When to Use

Key Features

Architecture

Basic Example

With Tool Integration

Selecting a Variant

Specialized Agents (default variant)

Research Agent

Analysis Agent

Alternatives Agent

Verification Agent

Synthesis Agent

Key Parameters

Methods

`run(task, img=None)`

`usage`

`get_questions_only(task, img=None)` and `get_questions_as_list(task, img=None)`

`to_dict()`

Question Generation

Multi-Loop Refinement

Dashboard Features

Use Cases

Investment Analysis

Market Research with Live Web Data

Strategic Planning

Heavy Variant for Deep Research

Performance Notes

Parallel Execution

Timeout

Verbose Logging

Output Structure

Best Practices

Reliability Checks

Conversation History

Error Handling

Related Architectures