Hierarchical Swarm Example

HierarchicalSwarm implements a director-worker pattern where a central director agent creates comprehensive plans and distributes specific tasks to specialized worker agents. The director evaluates results and can issue new orders in feedback loops, making it ideal for complex project management and team coordination scenarios.

How Hierarchical Swarm Works

The hierarchical pattern follows a command-and-control structure:

Planning Phase: Director analyzes the task and creates a comprehensive plan
Task Distribution: Director assigns specific subtasks to appropriate worker agents
Worker Execution: Specialized workers complete their assigned tasks independently
Evaluation Phase: Director reviews all worker outputs
Feedback Loop: Director can issue refinements or new tasks based on results

Key Characteristics

Centralized Coordination: Single director ensures cohesive strategy
Specialized Workers: Each agent focuses on their area of expertise
Adaptive Planning: Director adjusts based on worker outputs
Quality Control: Director validates and refines results
Scalable Structure: Easy to add new specialized workers

Basic Example: Marketing Team

This example demonstrates a marketing team coordinated by a director:

from swarms import Agent, HierarchicalSwarm

# Define specialized worker agents
content_strategist = Agent(
    agent_name="Content-Strategist",
    system_prompt="You are a senior content strategist. Develop comprehensive content strategies, editorial calendars, and content roadmaps.",
    model_name="gpt-5.4"
)

creative_director = Agent(
    agent_name="Creative-Director", 
    system_prompt="You are a creative director. Develop compelling advertising concepts, visual directions, and campaign creativity.",
    model_name="gpt-5.4"
)

seo_specialist = Agent(
    agent_name="SEO-Specialist",
    system_prompt="You are an SEO expert. Conduct keyword research, optimize content, and develop organic growth strategies.",
    model_name="gpt-5.4"
)

brand_strategist = Agent(
    agent_name="Brand-Strategist",
    system_prompt="You are a brand strategist. Develop brand positioning, identity systems, and market differentiation strategies.",
    model_name="gpt-5.4"
)

# Create the hierarchical swarm with a director
marketing_swarm = HierarchicalSwarm(
    name="Marketing-Team-Swarm",
    description="A comprehensive marketing team with specialized agents coordinated by a director",
    agents=[content_strategist, creative_director, seo_specialist, brand_strategist],
    max_loops=2,  # Allow for feedback and refinement
    verbose=True
)

# Run the swarm on a complex marketing challenge
result = marketing_swarm.run(
    "Develop a comprehensive marketing strategy for a new SaaS product launch. "
    "The product is a project management tool targeting small to medium businesses. "
    "Coordinate the team to create content strategy, creative campaigns, SEO optimization, "
    "and brand positioning that work together cohesively."
)

print(result)

How This Example Works

Task Reception: Director receives the complex marketing challenge
Strategic Planning: Director analyzes requirements and creates a master plan:
- Content strategy needs
- Creative campaign requirements
- SEO optimization goals
- Brand positioning objectives
Task Assignment: Director assigns specific tasks to each specialist:
- Content Strategist: “Develop 3-month content calendar for product launch”
- Creative Director: “Create campaign concepts for SMB audience”
- SEO Specialist: “Research keywords for project management tools”
- Brand Strategist: “Define positioning against Asana and Monday.com”
Execution: All workers complete their tasks in parallel
Review & Coordination: Director reviews outputs and ensures alignment
Refinement Loop (max_loops=2): Director may ask for adjustments:
- “Align content calendar with campaign launch dates”
- “Incorporate top SEO keywords into brand messaging”
Final Synthesis: Director combines all work into cohesive strategy

The Director-Worker Pattern

The hierarchical pattern excels at:

Centralized Vision

The director ensures all workers contribute to a unified goal, preventing fragmented or conflicting outputs.

Efficient Delegation

Director identifies what needs to be done and assigns to the most qualified worker.

Quality Assurance

Director reviews outputs and can request improvements or corrections.

Adaptive Coordination

Based on initial results, director can adjust the plan and issue new directives.

Real-World Examples

Software Development Team

Coordinate developers, designers, and testers:

from swarms import Agent, HierarchicalSwarm

# Define development team workers
backend_engineer = Agent(
    agent_name="Backend-Engineer",
    system_prompt="You are a senior backend engineer. Design APIs, database schemas, and server architecture.",
    model_name="gpt-5.4"
)

frontend_engineer = Agent(
    agent_name="Frontend-Engineer",
    system_prompt="You are a senior frontend engineer. Design user interfaces, components, and client-side logic.",
    model_name="gpt-5.4"
)

qa_engineer = Agent(
    agent_name="QA-Engineer",
    system_prompt="You are a QA engineer. Develop test strategies, test cases, and quality assurance plans.",
    model_name="gpt-5.4"
)

devops_engineer = Agent(
    agent_name="DevOps-Engineer",
    system_prompt="You are a DevOps engineer. Design deployment pipelines, infrastructure, and monitoring.",
    model_name="gpt-5.4"
)

# Create development swarm
dev_team = HierarchicalSwarm(
    name="Development-Team",
    description="Software development team with specialized engineers",
    agents=[backend_engineer, frontend_engineer, qa_engineer, devops_engineer],
    max_loops=3,  # Multiple feedback cycles
    verbose=True
)

# Build a feature
feature = dev_team.run(
    "Build a user authentication system with OAuth2, JWT tokens, and social login. "
    "Include comprehensive testing and deployment strategy."
)

print(feature)

Research Team

Coordinate researchers across different specialties:

from swarms import Agent, HierarchicalSwarm

# Define research team workers
literature_researcher = Agent(
    agent_name="Literature-Researcher",
    system_prompt="You are a literature review specialist. Search and synthesize existing research on topics.",
    model_name="gpt-5.4"
)

data_scientist = Agent(
    agent_name="Data-Scientist",
    system_prompt="You are a data scientist. Design experiments, analyze data, and develop statistical models.",
    model_name="gpt-5.4"
)

methodologist = Agent(
    agent_name="Methodologist",
    system_prompt="You are a research methodologist. Design rigorous experimental protocols and methodologies.",
    model_name="gpt-5.4"
)

writer = Agent(
    agent_name="Academic-Writer",
    system_prompt="You are an academic writer. Write clear, rigorous research papers and publications.",
    model_name="gpt-5.4"
)

# Create research swarm
research_team = HierarchicalSwarm(
    name="Research-Team",
    description="Academic research team for conducting studies",
    agents=[literature_researcher, data_scientist, methodologist, writer],
    max_loops=2,
    verbose=True
)

# Conduct research project
paper = research_team.run(
    "Conduct a research study on the impact of remote work on employee productivity. "
    "Include literature review, methodology design, data analysis plan, and draft paper."
)

print(paper)

Event Planning Team

Coordinate event specialists:

from swarms import Agent, HierarchicalSwarm

# Define event planning team
venue_coordinator = Agent(
    agent_name="Venue-Coordinator",
    system_prompt="You are a venue coordinator. Find and evaluate event spaces, negotiate contracts, manage logistics.",
    model_name="gpt-5.4"
)

catering_specialist = Agent(
    agent_name="Catering-Specialist",
    system_prompt="You are a catering specialist. Plan menus, coordinate food service, manage dietary requirements.",
    model_name="gpt-5.4"
)

marketing_coordinator = Agent(
    agent_name="Marketing-Coordinator",
    system_prompt="You are an event marketing coordinator. Promote events, manage registrations, handle communications.",
    model_name="gpt-5.4"
)

technical_producer = Agent(
    agent_name="Technical-Producer",
    system_prompt="You are a technical producer. Manage AV equipment, streaming, presentations, and technical requirements.",
    model_name="gpt-5.4"
)

# Create event planning swarm
event_team = HierarchicalSwarm(
    name="Event-Planning-Team",
    description="Professional event planning and coordination team",
    agents=[venue_coordinator, catering_specialist, marketing_coordinator, technical_producer],
    max_loops=2,
    verbose=True
)

# Plan conference
conference_plan = event_team.run(
    "Plan a 2-day AI conference for 500 attendees. Include venue selection, "
    "catering for all meals, marketing strategy to fill seats, and technical "
    "requirements for presentations and live streaming."
)

print(conference_plan)

Customer Service Team

Coordinate support specialists:

from swarms import Agent, HierarchicalSwarm

# Define customer service team
technical_support = Agent(
    agent_name="Technical-Support",
    system_prompt="You are a technical support specialist. Troubleshoot technical issues and provide solutions.",
    model_name="gpt-5.4"
)

billing_specialist = Agent(
    agent_name="Billing-Specialist",
    system_prompt="You are a billing specialist. Handle payment issues, refunds, and account billing questions.",
    model_name="gpt-5.4"
)

product_specialist = Agent(
    agent_name="Product-Specialist",
    system_prompt="You are a product specialist. Explain features, guide usage, and provide product training.",
    model_name="gpt-5.4"
)

escalation_manager = Agent(
    agent_name="Escalation-Manager",
    system_prompt="You are an escalation manager. Handle complex cases, customer complaints, and special requests.",
    model_name="gpt-5.4"
)

# Create support swarm
support_team = HierarchicalSwarm(
    name="Customer-Support-Team",
    description="Customer service team handling diverse support needs",
    agents=[technical_support, billing_specialist, product_specialist, escalation_manager],
    max_loops=2,
    verbose=True
)

# Handle complex customer case
resolution = support_team.run(
    "Customer reports login issues, billing discrepancy, and confusion about new features. "
    "They're frustrated and considering cancellation. Resolve all issues comprehensively."
)

print(resolution)

Feedback Loop Examples

The max_loops parameter enables iterative refinement:

Single Loop (max_loops=1)

# Director plans → Workers execute → Director synthesizes → Done
swarm = HierarchicalSwarm(
    agents=[agent1, agent2, agent3],
    max_loops=1,  # One-pass execution
)

Multiple Loops (max_loops=2+)

# Loop 1: Director plans → Workers execute → Director reviews
# Loop 2: Director requests refinements → Workers improve → Director finalizes
swarm = HierarchicalSwarm(
    agents=[agent1, agent2, agent3],
    max_loops=3,  # Multiple refinement cycles
)

Real Feedback Example

from swarms import Agent, HierarchicalSwarm

# Create agents
designer = Agent(
    agent_name="Designer",
    system_prompt="Design user interfaces and visual elements.",
    model_name="gpt-5.4"
)

developer = Agent(
    agent_name="Developer",
    system_prompt="Implement designs and build functionality.",
    model_name="gpt-5.4"
)

# Create swarm with feedback loops
swarm = HierarchicalSwarm(
    name="Design-Dev-Team",
    agents=[designer, developer],
    max_loops=3,  # Allow for iteration
    verbose=True
)

result = swarm.run("Build a user-friendly dashboard for analytics")

# Behind the scenes:
# Loop 1:
#   Director: "Designer, create dashboard mockup. Developer, review technical feasibility."
#   Workers execute
#   Director: "Design looks good but developer flagged performance concerns"
#
# Loop 2:
#   Director: "Designer, simplify complex charts. Developer, optimize data loading."
#   Workers execute
#   Director: "Better, but need mobile responsiveness"
#
# Loop 3:
#   Director: "Designer, add mobile layouts. Developer, implement responsive design."
#   Workers execute
#   Director: "Perfect, all requirements met" → Final output

Benefits of Hierarchical Swarm

Complex Project Management: Handles multi-faceted projects requiring coordination
Team Coordination: Ensures all agents work toward unified goals
Quality Control: Director provides oversight and validation
Adaptive Planning: Can adjust strategy based on initial results
Scalable Teams: Easy to add new specialists without restructuring
Clear Accountability: Director responsible for overall success

Best Practices

1. Define Clear Worker Specializations

# Good: Specific expertise
worker = Agent(
    agent_name="SEO-Specialist",
    system_prompt="You are an SEO expert specializing in technical SEO, keyword research, and organic growth.",
    model_name="gpt-5.4"
)

# Avoid: Too broad
worker = Agent(
    agent_name="Marketer",
    system_prompt="You do marketing.",
    model_name="gpt-5.4"
)

2. Use Appropriate Loop Counts

max_loops=1: Simple tasks, quick execution
max_loops=2: Standard quality control and refinement
max_loops=3+: Complex projects needing multiple iterations

3. Provide Comprehensive Context

result = swarm.run(
    """Launch a mobile app for fitness tracking.
    
    Requirements:
    - iOS and Android support
    - Integration with wearables
    - Social features for challenges
    - Freemium pricing model
    
    Constraints:
    - 3-month timeline
    - Budget: $200k
    - Team of 5 developers
    
    Deliverables:
    - Technical architecture
    - Development roadmap
    - Marketing strategy
    - Launch plan
    """
)

4. Balance Team Size

Too few workers (1-2): Underutilizes hierarchical pattern
Optimal (3-6): Good balance of specialization and coordination
Too many (8+): Director becomes overwhelmed coordinating

When to Use Hierarchical Swarm

Ideal for:

Complex Projects: Multi-faceted initiatives requiring coordination
Team Coordination: When specialized workers need unified direction
Quality-Critical Work: When oversight and validation are important
Iterative Refinement: When feedback loops improve results
Scalable Operations: When team may grow with new specialists

When NOT to Use Hierarchical Swarm

Simple Tasks: Overhead not justified for straightforward work
Independent Analyses: When diverse perspectives don’t need coordination (use MoA)
Speed Critical: Additional director layer adds latency
Linear Pipelines: When sequential processing suffices (use SequentialWorkflow)

MixtureOfAgents: Parallel experts with aggregation, no hierarchical control
SequentialWorkflow: Linear pipeline without director
GroupChat: Collaborative discussion without hierarchy

​How Hierarchical Swarm Works

​Key Characteristics

​Basic Example: Marketing Team

​How This Example Works

​The Director-Worker Pattern

​Centralized Vision

​Efficient Delegation

​Quality Assurance

​Adaptive Coordination

​Real-World Examples

​Software Development Team

​Research Team

​Event Planning Team

​Customer Service Team

​Feedback Loop Examples

​Single Loop (max_loops=1)

​Multiple Loops (max_loops=2+)

​Real Feedback Example

​Benefits of Hierarchical Swarm

​Best Practices

​1. Define Clear Worker Specializations

​2. Use Appropriate Loop Counts

​3. Provide Comprehensive Context

​4. Balance Team Size

​When to Use Hierarchical Swarm

​When NOT to Use Hierarchical Swarm

​Related Architectures

​Learn More