Swarm Type: HierarchicalSwarm

​
Overview

The HierarchicalSwarm implements a multi-level organizational structure where supervisor agents coordinate and manage specialized worker agents. This architecture mirrors real-world organizational hierarchies, allowing for complex task decomposition, quality control, and efficient resource allocation across multiple levels of responsibility. Key features:
  • Multi-Level Structure: Supervisor and worker agent hierarchy
  • Task Decomposition: Complex tasks broken down into manageable subtasks
  • Quality Control: Supervisors oversee and validate worker outputs
  • Resource Coordination: Efficient allocation and management of agent resources

​
Use Cases

  • Complex project management and coordination
  • Multi-stage research and analysis workflows
  • Content creation with editorial oversight
  • Quality assurance and validation processes

​
API Usage

​
Basic HierarchicalSwarm Example

curl -X POST "https://api.swarms.world/v1/swarm/completions" \
  -H "x-api-key: $SWARMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Research Project Coordinator",
    "description": "Hierarchical research coordination with supervisor oversight",
    "swarm_type": "HierarchicalSwarm",
    "task": "Conduct comprehensive research on the impact of AI on healthcare, including technological advances, economic implications, ethical considerations, and future trends",
    "agents": [
      {
        "agent_name": "Research Coordinator",
        "description": "Supervisor agent coordinating research efforts and synthesizing results",
        "system_prompt": "You are a research coordinator supervising a team of specialized researchers. Delegate tasks, coordinate efforts, and synthesize final results into a comprehensive report.",
        "model_name": "gpt-4o",
        "max_loops": 1,
        "temperature": 0.3
      },
      {
        "agent_name": "Technology Researcher",
        "description": "Worker agent researching AI technological advances in healthcare",
        "system_prompt": "You are a technology researcher specializing in AI healthcare applications. Research and analyze current technological advances, breakthroughs, and implementation challenges.",
        "model_name": "gpt-4o",
        "max_loops": 1,
        "temperature": 0.3
      },
      {
        "agent_name": "Economic Analyst",
        "description": "Worker agent analyzing economic implications of AI in healthcare",
        "system_prompt": "You are an economic analyst specializing in healthcare economics. Research and analyze the economic implications, cost-benefit analysis, and market impact of AI in healthcare.",
        "model_name": "gpt-4o",
        "max_loops": 1,
        "temperature": 0.3
      },
      {
        "agent_name": "Ethics Specialist",
        "description": "Worker agent examining ethical considerations of AI in healthcare",
        "system_prompt": "You are an ethics specialist focusing on AI and healthcare ethics. Research and analyze ethical considerations, privacy concerns, bias issues, and regulatory implications.",
        "model_name": "gpt-4o",
        "max_loops": 1,
        "temperature": 0.3
      },
      {
        "agent_name": "Future Trends Analyst",
        "description": "Worker agent predicting future trends in AI healthcare",
        "system_prompt": "You are a future trends analyst specializing in healthcare technology. Research and analyze future trends, predictions, and long-term implications of AI in healthcare.",
        "model_name": "gpt-4o",
        "max_loops": 1,
        "temperature": 0.3
      }
    ],
    "max_loops": 1
  }'
Example Response: 
{
    "job_id": "swarms-H17nZFDesmLHxCRoeyF3NVYvPaXk",
    "status": "success",
    "swarm_name": "Research Project Coordinator",
    "description": "Hierarchical research coordination with supervisor oversight",
    "swarm_type": "HierarchicalSwarm",
    "output": [
        {
            "role": "Research Coordinator",
            "content": "As the Research Coordinator, I have synthesized the findings from our specialized research team into a comprehensive report on AI's impact on healthcare..."
        },
        {
            "role": "Technology Researcher",
            "content": "My research on AI technological advances in healthcare reveals significant breakthroughs in diagnostic imaging, drug discovery, and personalized medicine..."
        },
        {
            "role": "Economic Analyst",
            "content": "The economic analysis shows that AI in healthcare could reduce costs by 15-20% while improving outcomes, though initial implementation costs are substantial..."
        },
        {
            "role": "Ethics Specialist",
            "content": "Ethical considerations include data privacy, algorithmic bias, transparency in decision-making, and ensuring human oversight in critical healthcare decisions..."
        },
        {
            "role": "Future Trends Analyst",
            "content": "Future trends indicate rapid adoption of AI in preventive care, remote monitoring, and personalized treatment plans, with full integration expected within 5-10 years..."
        }
    ],
    "number_of_agents": 5,
    "service_tier": "standard",
    "execution_time": 45.8,
    "usage": {
        "input_tokens": 55,
        "output_tokens": 3200,
        "total_tokens": 3255,
        "billing_info": {
            "cost_breakdown": {
                "agent_cost": 0.05,
                "input_token_cost": 0.000165,
                "output_token_cost": 0.048,
                "token_counts": {
                    "total_input_tokens": 55,
                    "total_output_tokens": 3200,
                    "total_tokens": 3255
                },
                "num_agents": 5,
                "service_tier": "standard",
                "night_time_discount_applied": true
            },
            "total_cost": 0.098165,
            "discount_active": true,
            "discount_type": "night_time",
            "discount_percentage": 75
        }
    }
}

​
Best Practices

  • Design clear supervisor-worker relationships
  • Ensure supervisors can effectively coordinate and synthesize results
  • Use for complex projects requiring oversight and coordination
  • Ideal for research, content creation, and project management