Swarms - swarms

What are Swarms?

A Swarm is a collection of multiple agents working together to accomplish complex tasks. Just as individual agents combine LLM + Tools + Memory, swarms combine multiple agents with different specializations, perspectives, and capabilities to solve problems that would be difficult or impossible for a single agent.

Why Swarms? Complex tasks often require different types of expertise, perspectives, and approaches. Swarms enable you to decompose problems and leverage specialized agents working in harmony.

The Power of Multi-Agent Systems

Swarms unlock capabilities beyond what single agents can achieve:

Specialization

Each agent can be optimized for a specific task or domain

Parallel Processing

Multiple agents can work simultaneously for faster execution

Diverse Perspectives

Different agents provide varied viewpoints and approaches

Scalability

Add more agents as complexity grows

Fault Tolerance

If one agent fails, others can continue

Quality Improvement

Agents can review and refine each other’s work

Swarm Architectures

Swarms provides multiple pre-built architectures for different collaboration patterns:

Sequential Workflow

Pattern: Agents execute tasks in a linear chain, where each agent builds upon the previous agent’s output. Best For: Step-by-step processes, data transformation pipelines, content creation workflows

from swarms import Agent, SequentialWorkflow

# Create specialized agents
researcher = Agent(
    agent_name="Researcher",
    system_prompt="Research topics and gather comprehensive information.",
    model_name="gpt-5.4",
)

writer = Agent(
    agent_name="Writer",
    system_prompt="Transform research into engaging, well-structured content.",
    model_name="gpt-5.4",
)

editor = Agent(
    agent_name="Editor",
    system_prompt="Review and polish content for clarity and correctness.",
    model_name="gpt-5.4",
)

# Create sequential workflow: Researcher -> Writer -> Editor
workflow = SequentialWorkflow(agents=[researcher, writer, editor])

# Execute the workflow
final_article = workflow.run("Write an article about quantum computing")
print(final_article)

Flow Visualization:

Researcher → Writer → Editor → Final Output

Concurrent Workflow

Pattern: All agents receive the same task and execute simultaneously, providing diverse perspectives. Best For: Analysis tasks, getting multiple viewpoints, parallel data processing

from swarms import Agent, ConcurrentWorkflow

# Create expert analysts
market_analyst = Agent(
    agent_name="Market-Analyst",
    system_prompt="Analyze market trends and competitive landscape.",
    model_name="gpt-5.4",
)

financial_analyst = Agent(
    agent_name="Financial-Analyst",
    system_prompt="Analyze financial metrics and profitability.",
    model_name="gpt-5.4",
)

risk_analyst = Agent(
    agent_name="Risk-Analyst",
    system_prompt="Identify and assess potential risks.",
    model_name="gpt-5.4",
)

# Run all agents concurrently
workflow = ConcurrentWorkflow(
    agents=[market_analyst, financial_analyst, risk_analyst]
)

# All agents analyze the same task simultaneously
analysis_results = workflow.run(
    "Analyze the investment potential of renewable energy sector"
)

Flow Visualization:

                    ┌──→ Market Analyst
Initial Task ───────┼──→ Financial Analyst ───→ Combined Results
                    └──→ Risk Analyst

Agent Rearrange

Pattern: Define complex, non-linear relationships between agents using a simple syntax. Best For: Dynamic workflows, flexible routing, complex dependencies

from swarms import Agent, AgentRearrange

# Define agents
researcher = Agent(agent_name="researcher", model_name="gpt-5.4")
writer = Agent(agent_name="writer", model_name="gpt-5.4")
editor = Agent(agent_name="editor", model_name="gpt-5.4")
reviewer = Agent(agent_name="reviewer", model_name="gpt-5.4")

# Define flow: researcher sends to both writer and editor,
# then both send to reviewer
flow = "researcher -> writer, editor; writer -> reviewer; editor -> reviewer"

swarm = AgentRearrange(
    agents=[researcher, writer, editor, reviewer],
    flow=flow,
)

result = swarm.run("Create a technical whitepaper on blockchain")

Flow Visualization:

             ┌──→ Writer ───┐
Researcher ──┤              ├──→ Reviewer → Final Output
             └──→ Editor ───┘

Mixture of Agents (MoA)

Pattern: Multiple expert agents process tasks in parallel, then an aggregator synthesizes their outputs. Best For: Complex decision-making, leveraging diverse expertise, state-of-the-art performance

from swarms import Agent, MixtureOfAgents

# Create expert agents
financial_expert = Agent(
    agent_name="Financial-Expert",
    system_prompt="Expert in financial analysis and investment strategies.",
    model_name="gpt-5.4"
)

market_expert = Agent(
    agent_name="Market-Expert",
    system_prompt="Expert in market trends and competitive analysis.",
    model_name="gpt-5.4"
)

risk_expert = Agent(
    agent_name="Risk-Expert",
    system_prompt="Expert in risk assessment and mitigation.",
    model_name="gpt-5.4"
)

# Create aggregator to synthesize expert opinions
aggregator = Agent(
    agent_name="Investment-Advisor",
    system_prompt="Synthesize expert analyses into actionable recommendations.",
    model_name="gpt-5.4"
)

# Create MoA swarm
moa_swarm = MixtureOfAgents(
    agents=[financial_expert, market_expert, risk_expert],
    aggregator_agent=aggregator,
)

recommendation = moa_swarm.run("Should we invest in NVIDIA stock?")

Hierarchical Swarm

Pattern: A director agent creates plans and distributes tasks to specialized worker agents. Best For: Complex project management, team coordination, hierarchical decision-making

from swarms import Agent, HierarchicalSwarm

# Create specialized workers
content_strategist = Agent(
    agent_name="Content-Strategist",
    system_prompt="Develop content strategies and editorial calendars.",
    model_name="gpt-5.4"
)

creative_director = Agent(
    agent_name="Creative-Director",
    system_prompt="Create compelling advertising concepts and campaigns.",
    model_name="gpt-5.4"
)

seo_specialist = Agent(
    agent_name="SEO-Specialist",
    system_prompt="Optimize content for search engines and organic growth.",
    model_name="gpt-5.4"
)

# Director coordinates the team
marketing_swarm = HierarchicalSwarm(
    name="Marketing-Team",
    description="Comprehensive marketing team for product launches",
    agents=[content_strategist, creative_director, seo_specialist],
    max_loops=2,  # Allow for feedback and refinement
)

strategy = marketing_swarm.run(
    "Develop a marketing strategy for our new SaaS product launch"
)

GroupChat

Pattern: Agents engage in conversational collaboration, discussing and debating solutions. Best For: Brainstorming, decision-making, collaborative problem-solving

from swarms import Agent, GroupChat

# Create agents with different perspectives
optimist = Agent(
    agent_name="Optimist",
    system_prompt="Present the benefits and opportunities of ideas.",
    model_name="gpt-5.4"
)

critic = Agent(
    agent_name="Critic",
    system_prompt="Identify potential problems and challenges.",
    model_name="gpt-5.4"
)

realist = Agent(
    agent_name="Realist",
    system_prompt="Provide balanced, practical perspectives.",
    model_name="gpt-5.4"
)

# Create group chat
chat = GroupChat(
    agents=[optimist, critic, realist],
    max_loops=4,  # Number of conversation rounds
)

conversation = chat.run(
    "Should we adopt AI agents for customer support?"
)

Choosing the Right Architecture

Use this decision guide to select the appropriate swarm architecture:

SequentialWorkflow - Linear Pipelines

Use when: Tasks have clear sequential dependenciesExamples:

Content creation (research → write → edit → publish)
Data processing (extract → transform → load)
Report generation (gather data → analyze → format → summarize)

ConcurrentWorkflow - Parallel Analysis

Use when: You need multiple independent analyses of the same inputExamples:

Multi-perspective analysis (market, financial, risk)
Quality assurance (multiple reviewers)
A/B testing different approaches

MixtureOfAgents - Expert Synthesis

Use when: You need to combine diverse expertise into unified outputExamples:

Investment decisions (combine multiple expert analyses)
Medical diagnosis (multiple specialist opinions)
Strategic planning (synthesize different viewpoints)

HierarchicalSwarm - Project Management

Use when: You need centralized planning with specialized executionExamples:

Marketing campaigns (director coordinates specialists)
Software development (architect guides developers)
Event planning (coordinator manages vendors)

AgentRearrange - Complex Flows

Use when: You need flexible, non-linear agent interactionsExamples:

Adaptive workflows that change based on results
Multi-stage review processes
Complex approval chains

GroupChat - Collaborative Discussion

Use when: Agents need to discuss and debate solutionsExamples:

Brainstorming sessions
Consensus building
Debate and deliberation

Real-World Examples

Content Production Pipeline

from swarms import Agent, SequentialWorkflow

# Stage 1: Research
researcher = Agent(
    agent_name="Researcher",
    system_prompt="Research topics thoroughly using multiple sources.",
    model_name="gpt-5.4",
    tools=[web_search_tool, database_tool],
)

# Stage 2: Writing
writer = Agent(
    agent_name="Writer",
    system_prompt="Create engaging, well-structured content.",
    model_name="gpt-5.4",
)

# Stage 3: SEO Optimization
seo_optimizer = Agent(
    agent_name="SEO-Optimizer",
    system_prompt="Optimize content for search engines.",
    model_name="gpt-5.4",
)

# Stage 4: Fact Checking
fact_checker = Agent(
    agent_name="Fact-Checker",
    system_prompt="Verify all claims and citations.",
    model_name="gpt-5.4",
)

pipeline = SequentialWorkflow(
    agents=[researcher, writer, seo_optimizer, fact_checker]
)

final_article = pipeline.run("Create an article about renewable energy trends")

Investment Analysis Team

from swarms import Agent, MixtureOfAgents

# Create specialized analysts
quant_analyst = Agent(
    agent_name="Quantitative-Analyst",
    system_prompt="Analyze numerical data and statistical patterns.",
)

fundamental_analyst = Agent(
    agent_name="Fundamental-Analyst",
    system_prompt="Evaluate company fundamentals and business models.",
)

technical_analyst = Agent(
    agent_name="Technical-Analyst",
    system_prompt="Analyze price charts and trading patterns.",
)

sentiment_analyst = Agent(
    agent_name="Sentiment-Analyst",
    system_prompt="Analyze market sentiment and news.",
)

# Portfolio manager synthesizes all analyses
portfolio_manager = Agent(
    agent_name="Portfolio-Manager",
    system_prompt="Create balanced investment recommendations.",
)

investment_team = MixtureOfAgents(
    agents=[quant_analyst, fundamental_analyst, technical_analyst, sentiment_analyst],
    aggregator_agent=portfolio_manager,
)

recommendation = investment_team.run("Analyze Tesla stock for Q1 2024")

Best Practices

Agent Specialization

Design each agent with a clear, focused role. Specialized agents perform better than generalists.

Clear Communication

Use explicit system prompts that explain how agents should collaborate and what outputs are expected.

Error Handling

Implement fallback strategies for when individual agents fail or produce low-quality output.

Monitoring

Track agent performance and swarm metrics to identify bottlenecks and optimization opportunities.

Advanced Features

Swarm Router

Dynamically switch between swarm architectures:

from swarms.structs.swarm_router import SwarmRouter, SwarmType

# Use the same agents with different strategies
router = SwarmRouter(
    swarm_type=SwarmType.SequentialWorkflow,  # or ConcurrentWorkflow, MixtureOfAgents, etc.
    agents=[agent1, agent2, agent3]
)

result = router.run(task)

Conversation History

All swarm architectures maintain conversation history for debugging and analysis:

workflow = SequentialWorkflow(
    agents=[researcher, writer],
    autosave=True,  # Save conversation history
)

result = workflow.run("Create a report")

# Access conversation history
print(workflow.agent_rearrange.conversation.get_str())

Next Steps

Workflows

Deep dive into workflow orchestration patterns

Tools

Learn how to equip agents with external capabilities

Examples

Explore real-world swarm implementations

Architecture Guide

Complete reference for all swarm architectures

​What are Swarms?

​The Power of Multi-Agent Systems

Specialization

Parallel Processing

Diverse Perspectives

Scalability

Fault Tolerance

Quality Improvement

​Swarm Architectures

​Sequential Workflow

​Concurrent Workflow

​Agent Rearrange

​Mixture of Agents (MoA)

​Hierarchical Swarm

​GroupChat

​Choosing the Right Architecture

​Real-World Examples

​Content Production Pipeline

​Investment Analysis Team

​Best Practices

Agent Specialization

Clear Communication

Error Handling

Monitoring

​Advanced Features

​Swarm Router

​Conversation History

​Next Steps

Workflows

Tools

Examples

Architecture Guide

What are Swarms?

The Power of Multi-Agent Systems

Swarm Architectures

Sequential Workflow

Concurrent Workflow

Agent Rearrange

Mixture of Agents (MoA)

Hierarchical Swarm

GroupChat

Choosing the Right Architecture

Real-World Examples

Content Production Pipeline

Investment Analysis Team

Best Practices

Advanced Features

Swarm Router

Conversation History

Next Steps