Swarms API Documentation - Build AI Agents & Multi-Agent Systems

What This Example Shows

A HierarchicalSwarm applied to a real-world business analysis problem
A director coordinating three domain specialists (logistics, inventory, procurement)
How to write director and worker system prompts that compose cleanly

This is the same hierarchical pattern as the Hierarchical Workflow Example, applied to supply chain analysis instead of software development. Swap the worker roles and prompts to apply it to any domain — legal review, M&A due diligence, clinical case conferences, marketing campaign planning.

Step 1: Setup

import json
import os

import requests
from dotenv import load_dotenv

load_dotenv()

API_KEY = os.getenv("SWARMS_API_KEY")
BASE_URL = os.getenv("SWARMS_BASE_URL", "https://api.swarms.world")

headers = {"x-api-key": API_KEY, "Content-Type": "application/json"}

Step 2: Define the Team

The director sets strategy and synthesizes. Each specialist owns one functional area.

payload = {
    "name": "Supply Chain Hierarchical Swarm",
    "description": "Director coordinates logistics, inventory, and procurement specialists.",
    "swarm_type": "HierarchicalSwarm",
    "max_loops": 1,
    "task": (
        "Analyze the current supply chain challenges facing the semiconductor "
        "industry and provide optimization recommendations for a mid-sized "
        "electronics manufacturer. Consider:\n"
        "1. Current supply chain bottlenecks and disruptions\n"
        "2. Inventory management strategies during shortages\n"
        "3. Supplier diversification opportunities\n"
        "4. Long-term resilience improvements"
    ),
    "agents": [
        {
            "agent_name": "Supply Chain Director",
            "description": "Oversees strategy and synthesizes specialist outputs.",
            "system_prompt": (
                "You are a Supply Chain Director with extensive global experience. "
                "Coordinate analysis across logistics, inventory, and procurement. "
                "Identify bottlenecks, develop optimization strategies, and ensure "
                "resilience and risk mitigation. Synthesize your team's input into "
                "actionable strategic recommendations."
            ),
            "model_name": "gpt-4.1",
            "role": "coordinator",
            "max_loops": 1,
            "max_tokens": 8192,
            "temperature": 0.3,
        },
        {
            "agent_name": "Logistics Specialist",
            "description": "Transportation and distribution optimization.",
            "system_prompt": (
                "You are a Logistics Specialist. Focus on transportation modes, "
                "route planning, distribution network design, last-mile delivery, "
                "and freight cost optimization. Provide detailed analysis with "
                "improvement recommendations."
            ),
            "model_name": "gpt-4.1",
            "role": "worker",
            "max_loops": 1,
            "max_tokens": 4096,
            "temperature": 0.4,
        },
        {
            "agent_name": "Inventory Manager",
            "description": "Stock optimization and demand forecasting.",
            "system_prompt": (
                "You are an Inventory Management expert. Focus on demand "
                "forecasting, inventory optimization, safety stock, warehouse "
                "utilization, and carrying-cost reduction. Provide data-driven "
                "recommendations."
            ),
            "model_name": "gpt-4.1",
            "role": "worker",
            "max_loops": 1,
            "max_tokens": 4096,
            "temperature": 0.4,
        },
        {
            "agent_name": "Procurement Analyst",
            "description": "Supplier management and strategic sourcing.",
            "system_prompt": (
                "You are a Procurement Analyst. Focus on supplier evaluation, "
                "sourcing strategy, vendor diversification, contract negotiation, "
                "and supplier risk assessment. Balance cost efficiency with "
                "supply reliability."
            ),
            "model_name": "gpt-4.1",
            "role": "worker",
            "max_loops": 1,
            "max_tokens": 4096,
            "temperature": 0.4,
        },
    ],
}

Step 3: Run the Swarm

response = requests.post(
    f"{BASE_URL}/v1/swarm/completions",
    headers=headers,
    json=payload,
    timeout=300,
)

result = response.json()

for output in result.get("output", []):
    print("=" * 60)
    print(output["role"])
    print("=" * 60)
    content = output["content"]
    if isinstance(content, list):
        content = " ".join(str(c) for c in content)
    print(str(content)[:400] + "...")

print(f"\nTotal cost: ${result['usage']['billing_info']['total_cost']:.4f}")
print(f"Execution time: {result['execution_time']:.1f}s")

HierarchicalSwarm always builds its own director from director_model_name (default gpt-5.4) that decomposes the task and dispatches it to every agent in agents — the Supply Chain Director above runs as one of the director’s workers, not as a privileged synthesizer, and with the default max_loops: 1 and parallel worker execution, no agent sees another specialist’s output before writing its own. For a guaranteed synthesis pass, either set "max_loops": 2 on the swarm (the framework’s director gets every first-round output on its second pass and can route the synthesis to the Supply Chain Director by name/description), or collect the specialist outputs client-side and issue one more /v1/agent/completions call using the Supply Chain Director’s system prompt. Design that prompt around “review, decide, recommend” — not “write a long report.”

Adapting the Pattern

Replace the three specialists to retarget the swarm:

Domain	Director	Workers
M&A due diligence	Deal Lead	Financial Analyst, Legal Counsel, Technical Auditor
Clinical case conference	Attending Physician	Radiologist, Pathologist, Cardiologist
Marketing campaign	Brand Director	Copywriter, Designer, Performance Marketer
Software architecture review	Principal Engineer	Backend Engineer, Database Engineer, Security Engineer

Everything else — the request shape, the response shape, the billing — stays identical.

Getting Started

MCP Server Tutorials

Agent Capabilities

Multi-Agent Architectures

Finance & Investing

Healthcare & Life Sciences

Legal, M&A & Diligence

Customer Operations

Defense, Gov & Supply Chain

Marketing, Content & Founder Tools

API Utilities

Migration Guides

Resources

Production

Compatibility & Benchmarks

Tutorials & Integrations

Supply Chain Hierarchical Swarm

What This Example Shows

Step 1: Setup

Step 2: Define the Team

Step 3: Run the Swarm

Adapting the Pattern

​What This Example Shows

​Step 1: Setup

​Step 2: Define the Team

​Step 3: Run the Swarm

​Adapting the Pattern

What This Example Shows

Step 1: Setup

Step 2: Define the Team

Step 3: Run the Swarm

Adapting the Pattern