Skip to content

feat: add 16-agent Grok 4.20 Heavy mode to HeavySwarm #1509

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kyegomez merged 2 commits into from
Apr 1, 2026
Merged

feat: add 16-agent Grok 4.20 Heavy mode to HeavySwarm #1509

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c9c6ea0
feat: add 16-agent Grok 4.20 Heavy mode to HeavySwarm
Steve-Dusty Apr 1, 2026
fddbd25
docs: add Grok Heavy 16-agent mode to HeavySwarm documentation
Steve-Dusty Apr 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
213 changes: 199 additions & 14 deletions docs/swarms/structs/heavy_swarm.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,11 @@

HeavySwarm is a sophisticated multi-agent orchestration system that decomposes complex tasks into specialized questions and executes them using specialized agents in parallel. The results are then synthesized into a comprehensive response.

HeavySwarm supports two agent architectures:
HeavySwarm supports three agent architectures:

- **Default mode** — 5 task-phase agents (Research, Analysis, Alternatives, Verification, Synthesis)
- **Grok mode** (`use_grok_agents=True`) — 4 thinking-style agents inspired by the [Grok 4.20 Heavy architecture](https://x.com/elonmusk/status/2034710771075273177) (Captain Swarm, Harper, Benjamin, Lucas)
- **Grok Heavy mode** (`use_grok_heavy=True`) — 16 domain-specialist agents inspired by the [Grok 4.20 Heavy 16-agent system](https://x.com/xai/status/2024121909286494435) (Grok captain + 15 specialists)

## Installation

Expand Down Expand Up @@ -68,15 +69,44 @@ The Grok mode is inspired by the [Grok 4.20 Heavy architecture](https://x.com/el

**Flow:** Captain Swarm decomposes → Harper, Benjamin, Lucas work in parallel → Captain Swarm mediates conflicts and synthesizes

#### Key Differences from Default Mode

| Aspect | Default Mode | Grok Mode |
|--------|-------------|-----------|
| **Decomposition** | By task phase (research → analyze → verify) | By thinking style (facts vs logic vs creativity) |
| **Agent count** | 5 (4 workers + 1 synthesizer) | 4 (3 specialists + 1 leader) |
| **Synthesis** | Generic integration agent | Captain Swarm mediates conflicts between agents |
| **Contrarian check** | Not present | Lucas specifically challenges assumptions and detects biases |
| **Question schema** | 4 questions (research, analysis, alternatives, verification) | 3 questions (harper, benjamin, lucas) |
### Grok Heavy Mode — Domain-Specialist Agents (`use_grok_heavy=True`)

The Grok Heavy mode mirrors the [Grok 4.20 Heavy 16-agent system](https://x.com/xai/status/2024121909286494435) and decomposes work by **domain expertise** — each agent is a specialist in a distinct field.

| Agent | Domain | Specialization |
|-------|--------|----------------|
| **Grok** (Captain) | Orchestration | Leads, coordinates, synthesizes all 15 specialist outputs |
| **Harper** | Creative Writing | Storytelling, narrative framing, communication strategy |
| **Benjamin** | Finance | Data analysis, financial modeling, economic forecasting |
| **Lucas** | Technology | Coding, programming, software architecture, technical builds |
| **Olivia** | Culture | Literature, arts, cultural context, humanistic perspectives |
| **James** | History | Historical analysis, political science, philosophical frameworks |
| **Charlotte** | Mathematics | Statistical analysis, formal logic, mathematical proofs |
| **Henry** | Engineering | Robotics, hardware, innovation, systems engineering |
| **Mia** | Medicine | Biology, health sciences, clinical research, public health |
| **William** | Business | Strategy, entrepreneurship, market analysis, competitive intelligence |
| **Sebastian** | Physics | Astronomy, hard sciences, fundamental research |
| **Jack** | Psychology | Human behavior, cognitive science, decision-making |
| **Owen** | Environment | Sustainability, climate science, global systems |
| **Luna** | Space | Space exploration, futurism, emerging frontiers |
| **Elizabeth** | Ethics | Policy analysis, ethical frameworks, critical thinking |
| **Noah** | Systems | Long-term innovation, systems thinking, civilizational impact |

**Flow:** Grok decomposes task into 15 domain-specific questions → 15 specialists work in parallel → Grok synthesizes with cross-domain convergence analysis

> **Note:** Harper, Benjamin, and Lucas have different roles in Grok Heavy mode compared to Grok mode. In Grok mode they represent thinking styles (facts/logic/creativity); in Grok Heavy mode they represent domain expertise (creative writing/finance/technology).

#### Key Differences Across All Three Modes

| Aspect | Default Mode | Grok Mode | Grok Heavy Mode |
|--------|-------------|-----------|-----------------|
| **Decomposition** | By task phase (research → analyze → verify) | By thinking style (facts vs logic vs creativity) | By domain expertise (15 specialist fields) |
| **Agent count** | 5 (4 workers + 1 synthesizer) | 4 (3 specialists + 1 leader) | 16 (15 specialists + 1 captain) |
| **Synthesis** | Generic integration agent | Captain Swarm mediates conflicts | Grok synthesizes with cross-domain convergence |
| **Contrarian check** | Not present | Lucas challenges assumptions | Elizabeth provides ethical/critical analysis |
| **Question schema** | 4 questions | 3 questions | 15 questions |
| **Best for** | Systematic, phased analysis | Debate-style reasoning | Deep multi-domain analysis |
| **Flag** | (default) | `use_grok_agents=True` | `use_grok_heavy=True` |

## API Reference

Expand Down Expand Up @@ -104,6 +134,7 @@ HeavySwarm(
random_loops_per_agent: bool = False,
max_loops: int = 1,
use_grok_agents: bool = False,
use_grok_heavy: bool = False,
)
```

Expand All @@ -126,7 +157,8 @@ HeavySwarm(
| `worker_tools` | `Optional[tool_type]` | `None` | Tools available to worker agents for enhanced functionality |
| `random_loops_per_agent` | `bool` | `False` | Enable random number of loops per agent (1-10 range) |
| `max_loops` | `int` | `1` | Maximum number of execution loops for iterative refinement |
| `use_grok_agents` | `bool` | `False` | Enable Grok 4.20 Heavy architecture with Captain Swarm, Harper, Benjamin, and Lucas agents instead of the default Research/Analysis/Alternatives/Verification agents |
| `use_grok_agents` | `bool` | `False` | Enable Grok 4-agent mode with Captain Swarm, Harper, Benjamin, and Lucas agents instead of the default Research/Analysis/Alternatives/Verification agents |
| `use_grok_heavy` | `bool` | `False` | Enable Grok Heavy 16-agent mode with Grok captain and 15 domain specialists (Harper, Benjamin, Lucas, Olivia, James, Charlotte, Henry, Mia, William, Sebastian, Jack, Owen, Luna, Elizabeth, Noah). Mutually exclusive with `use_grok_agents` |

##### Raises

Expand All @@ -136,6 +168,8 @@ HeavySwarm(

- `ValueError`: If `question_agent_model_name` is None

- `ValueError`: If both `use_grok_agents` and `use_grok_heavy` are True (mutually exclusive)

##### Example

```python
Expand Down Expand Up @@ -205,6 +239,23 @@ Generate and extract only the specialized questions without metadata or executio
- `benjamin_question` (str): Question for logical reasoning and mathematical verification
- `lucas_question` (str): Question for creative/contrarian analysis and blind-spot detection

**Grok Heavy mode keys** (`use_grok_heavy=True`):
- `harper_question` (str): Question for creative writing and storytelling analysis
- `benjamin_question` (str): Question for data, finance, and economics analysis
- `lucas_question` (str): Question for coding, programming, and technical analysis
- `olivia_question` (str): Question for literature, arts, and cultural analysis
- `james_question` (str): Question for historical, political, and philosophical analysis
- `charlotte_question` (str): Question for mathematical, statistical, and logical analysis
- `henry_question` (str): Question for engineering, robotics, and innovation analysis
- `mia_question` (str): Question for biology, health, and medical analysis
- `william_question` (str): Question for business strategy and entrepreneurship analysis
- `sebastian_question` (str): Question for physics, astronomy, and hard sciences analysis
- `jack_question` (str): Question for psychology and human behavior analysis
- `owen_question` (str): Question for environment, sustainability, and global systems analysis
- `luna_question` (str): Question for space exploration and futurism analysis
- `elizabeth_question` (str): Question for ethics, policy, and critical thinking analysis
- `noah_question` (str): Question for long-term innovation and systems thinking analysis

- `error` (str): Error message if question generation fails (on error only)

**Example:**
Expand All @@ -221,6 +272,12 @@ questions = grok_swarm.get_questions_only("Analyze market trends for EVs")
print(questions['harper_question'])
print(questions['benjamin_question'])
print(questions['lucas_question'])

# Grok Heavy mode
heavy_swarm = HeavySwarm(use_grok_heavy=True, worker_model_name="gpt-4.1", question_agent_model_name="gpt-4.1")
questions = heavy_swarm.get_questions_only("Analyze market trends for EVs")
for key, question in questions.items():
print(f"{key}: {question}")
```

##### `get_questions_as_list(task: str) -> List[str]`
Expand Down Expand Up @@ -248,6 +305,23 @@ Generate specialized questions and return them as an ordered list.
- `[1]` Benjamin question for logical reasoning and mathematical verification
- `[2]` Lucas question for creative/contrarian analysis and blind-spot detection

**Grok Heavy mode** (15 questions):
- `[0]` Harper — creative writing and storytelling
- `[1]` Benjamin — data, finance, and economics
- `[2]` Lucas — coding, programming, and technology
- `[3]` Olivia — literature, arts, and culture
- `[4]` James — history, politics, and philosophy
- `[5]` Charlotte — math, statistics, and logic
- `[6]` Henry — engineering, robotics, and innovation
- `[7]` Mia — biology, health, and medicine
- `[8]` William — business strategy and entrepreneurship
- `[9]` Sebastian — physics, astronomy, and hard sciences
- `[10]` Jack — psychology and human behavior
- `[11]` Owen — environment, sustainability, and global systems
- `[12]` Luna — space exploration and futurism
- `[13]` Elizabeth — ethics, policy, and critical thinking
- `[14]` Noah — long-term innovation and systems thinking

- Single-item list containing error message (on error)

**Example:**
Expand Down Expand Up @@ -295,6 +369,7 @@ Perform comprehensive reliability and configuration validation checks.
| `ValueError` | If `loops_per_agent` is 0 or negative (agents won't execute) |
| `ValueError` | If `worker_model_name` is None (agents can't be created) |
| `ValueError` | If `question_agent_model_name` is None (questions can't be generated) |
| `ValueError` | If both `use_grok_agents` and `use_grok_heavy` are True (mutually exclusive) |

**Example:**

Expand All @@ -308,7 +383,7 @@ except ValueError as e:

##### `create_agents() -> Dict[str, Agent]`

Create and cache specialized agents with detailed role-specific prompts. The agents created depend on the `use_grok_agents` setting.
Create and cache specialized agents with detailed role-specific prompts. The agents created depend on the `use_grok_agents` and `use_grok_heavy` settings.

**Parameters:**

Expand All @@ -333,6 +408,27 @@ Create and cache specialized agents with detailed role-specific prompts. The age
| `'benjamin'`| Benjamin | Logic, math, and code specialist |
| `'lucas'` | Lucas | Creative and divergent thinking specialist |

**Returns (Grok Heavy mode, `use_grok_heavy=True`):**

| Key | Agent Instance | Description |
|---------------|---------------|-----------------------------------------------------|
| `'captain'` | Grok | Captain — leads, coordinates, and synthesizes all specialist outputs |
| `'harper'` | Harper | Creative writing and storytelling specialist |
| `'benjamin'` | Benjamin | Data, finance, and economics specialist |
| `'lucas'` | Lucas | Coding, programming, and technical builds specialist |
| `'olivia'` | Olivia | Literature, arts, and culture specialist |
| `'james'` | James | History, politics, and philosophy specialist |
| `'charlotte'` | Charlotte | Math, statistics, and logic specialist |
| `'henry'` | Henry | Engineering, robotics, and innovation specialist |
| `'mia'` | Mia | Biology, health, and medicine specialist |
| `'william'` | William | Business strategy and entrepreneurship specialist |
| `'sebastian'` | Sebastian | Physics, astronomy, and hard sciences specialist |
| `'jack'` | Jack | Psychology and human behavior specialist |
| `'owen'` | Owen | Environment, sustainability, and global systems specialist |
| `'luna'` | Luna | Space exploration and futurism specialist |
| `'elizabeth'` | Elizabeth | Ethics, policy, and critical thinking specialist |
| `'noah'` | Noah | Long-term innovation and systems thinking specialist |

**Example:**

```python
Expand All @@ -346,6 +442,16 @@ grok_swarm = HeavySwarm(use_grok_agents=True, worker_model_name="gpt-4.1", quest
agents = grok_swarm.create_agents()
print(f"Captain: {agents['captain'].agent_name}")
print(f"Harper: {agents['harper'].agent_name}")

# Grok Heavy mode
heavy_swarm = HeavySwarm(use_grok_heavy=True, worker_model_name="gpt-4.1", question_agent_model_name="gpt-4.1")
agents = heavy_swarm.create_agents()
print(f"Total agents: {len(agents)}") # 16
print(f"Captain: {agents['captain'].agent_name}") # Grok
for key in ['harper', 'benjamin', 'lucas', 'olivia', 'james', 'charlotte',
'henry', 'mia', 'william', 'sebastian', 'jack', 'owen',
'luna', 'elizabeth', 'noah']:
print(f"{key}: {agents[key].agent_name}")
```

## Examples
Expand Down Expand Up @@ -467,6 +573,83 @@ for i, q in enumerate(question_list):
print(f"Agent {i+1}: {q}")
```

### Grok Heavy Mode — Quick Start

```python
from swarms import HeavySwarm

# Enable 16-agent Grok Heavy mode
swarm = HeavySwarm(
name="Grok Heavy Research Team",
description="16-agent deep multi-domain analysis",
worker_model_name="grok-4",
question_agent_model_name="grok-4",
use_grok_heavy=True,
show_dashboard=True,
loops_per_agent=1,
)

# Grok decomposes into 15 domain-specific questions,
# all 15 specialists work in parallel, then Grok synthesizes
result = swarm.run(
"What are the most transformative technologies that will reshape "
"civilization over the next 50 years? Analyze from all relevant dimensions."
)
print(result)
```

### Grok Heavy Mode — Comprehensive Policy Analysis

```python
from swarms import HeavySwarm

swarm = HeavySwarm(
name="Policy Analysis Team",
worker_model_name="gpt-4.1",
question_agent_model_name="gpt-4.1",
use_grok_heavy=True,
show_dashboard=True,
loops_per_agent=2,
)

# All 15 specialists contribute their domain expertise:
# - James analyzes historical precedents and political feasibility
# - Charlotte validates statistical claims and economic models
# - Mia assesses public health implications
# - Owen evaluates environmental impact
# - Elizabeth examines ethical and policy dimensions
# - William models business and market effects
# ... and 9 more specialists
result = swarm.run(
"Should the US implement a universal basic income? Analyze the economic "
"feasibility, social impact, political viability, and long-term consequences."
)
print(result)
```

### Grok Heavy Mode — Question Preview

```python
from swarms import HeavySwarm

swarm = HeavySwarm(
worker_model_name="gpt-4.1",
question_agent_model_name="gpt-4.1",
use_grok_heavy=True,
)

# Preview the 15 domain-specific questions Grok will generate
questions = swarm.get_questions_only("Analyze the future of space colonization")
for key, question in questions.items():
print(f"{key}: {question}\n")

# Or as a list
question_list = swarm.get_questions_as_list("Analyze the future of space colonization")
print(f"Total questions: {len(question_list)}") # 15
for i, q in enumerate(question_list):
print(f"Specialist {i+1}: {q}")
```

### Basic Usage (Default Mode)

```python
Expand Down Expand Up @@ -739,10 +922,12 @@ print(result)
| Aspect | Recommendation/Description |
|---------------------|-------------------------------------------------------------------------------------------------------------|
| **Performance** | Use `max_workers` based on your CPU cores for optimal parallel execution |
| **Cost** | Higher model versions provide better analysis but increase costs. Grok mode uses 4 agents vs 5, slightly reducing cost per run |
| **Cost** | Higher model versions provide better analysis but increase costs. Grok mode uses 4 agents vs 5, slightly reducing cost per run. Grok Heavy mode uses 16 agents, significantly increasing cost but providing the deepest analysis |
| **Timeouts** | Complex tasks may require longer `timeout` values |
| **Tools** | Integrate domain-specific tools for enhanced analysis capabilities |
| **Dashboard** | Enable `show_dashboard=True` for visual progress tracking |
| **Batch Processing**| Disable dashboard and verbose logging for efficient batch operations |
| **When to use Grok mode** | Best for tasks requiring debate-style analysis where facts, logic, and creative thinking need to be weighed against each other (e.g., strategic decisions, investment analysis, policy evaluation). Captain Swarm's conflict mediation is especially valuable when different perspectives might disagree. |
| **When to use Default mode** | Best for systematic, phased analysis where each step builds on the previous one (e.g., research reports, market studies, compliance audits). The dedicated Verification Agent provides stronger validation coverage. |
| **When to use Grok mode** | Best for tasks requiring debate-style analysis where facts, logic, and creative thinking need to be weighed against each other (e.g., strategic decisions, investment analysis, policy evaluation). Captain Swarm's conflict mediation is especially valuable when different perspectives might disagree. |
| **When to use Grok Heavy mode** | Best for complex, multi-domain tasks that benefit from deep specialist expertise across many fields (e.g., civilizational impact analysis, comprehensive policy evaluation, cross-disciplinary research). The 15 domain specialists provide unmatched breadth and depth, with Grok synthesizing cross-domain convergences. |
| **Mutual exclusion** | `use_grok_agents` and `use_grok_heavy` cannot both be `True`. Set only one to enable the desired mode. |
20 changes: 20 additions & 0 deletions examples/multi_agent/heavy_swarm_examples/heavy_swarm_grok_heavy.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
from swarms import HeavySwarm

swarm = HeavySwarm(
name="Grok Heavy Research Team",
description="16-agent Grok 4.20 Heavy mode for deep multi-domain analysis",
worker_model_name="grok-4",
question_agent_model_name="grok-4",
show_dashboard=True,
loops_per_agent=1,
agent_prints_on=False,
use_grok_heavy=True,
)

prompt = (
"What are the most transformative technologies that will reshape "
"civilization over the next 50 years? Analyze from all relevant dimensions."
)

out = swarm.run(prompt)
print(out)
Loading
Loading