Swarms AI — Multi-Agent Orchestration

Build production-grade multi-agent systems using the Swarms API platform. Supports single agents, reasoning agents, and swarms of 3–10,000+ agents with 20+ architecture patterns.

Quick Reference

Base URL: https://api.swarms.world
Auth: x-api-key header with API key from swarms.world/platform/api-keys
Docs index: https://docs.swarms.ai/llms.txt
Python SDK: pip install swarms-client
Marketplace: swarms.world

Architecture Tiers

Tier	Name	Agents	Endpoint
1	Individual Agent	1	`/v1/agent/completions`
2	Reasoning Agent	1-2 internal	`/v1/reasoning-agent/completions`
3	Multi-Agent Swarm	3–10,000+	`/v1/swarm/completions`

Workflow

1. Single Agent

import requests

payload = {
    "agent_config": {
        "agent_name": "MyAgent",
        "description": "Purpose of the agent",
        "system_prompt": "You are...",
        "model_name": "gpt-4o",  # or claude-sonnet-4-20250514, etc.
        "role": "worker",
        "max_loops": 1,
        "max_tokens": 8192,
        "temperature": 0.5,
        "auto_generate_prompt": False,
        "tools_list_dictionary": None
    },
    "task": "Your task here"
}

response = requests.post(
    "https://api.swarms.world/v1/agent/completions",
    headers={"x-api-key": API_KEY, "Content-Type": "application/json"},
    json=payload
)

2. Multi-Agent Swarm

payload = {
    "name": "My Swarm",
    "description": "What this swarm does",
    "agents": [
        {
            "agent_name": "Agent1",
            "description": "Role 1",
            "system_prompt": "You are...",
            "model_name": "gpt-4o",
            "role": "worker",
            "max_loops": 1,
            "max_tokens": 8192,
            "temperature": 0.5
        },
        {
            "agent_name": "Agent2",
            "description": "Role 2",
            "system_prompt": "You are...",
            "model_name": "claude-sonnet-4-20250514",
            "role": "worker",
            "max_loops": 1,
            "max_tokens": 8192,
            "temperature": 0.5
        }
    ],
    "max_loops": 1,
    "swarm_type": "SequentialWorkflow",  # See architecture table
    "task": "Your task here"
}

response = requests.post(
    "https://api.swarms.world/v1/swarm/completions",
    headers={"x-api-key": API_KEY, "Content-Type": "application/json"},
    json=payload
)

3. Token Launch (Solana)

payload = {
    "name": "My Agent Token",
    "description": "Agent description",
    "ticker": "MAG",
    "private_key": "[1,2,3,...]"  # Solana wallet private key
}

response = requests.post(
    "https://swarms.world/api/token/launch",
    headers={"Authorization": "Bearer API_KEY", "Content-Type": "application/json"},
    json=payload
)
# Returns: token_address, pool_address, listing_url
# Cost: ~0.04 SOL

Available Swarm Architectures

Use the swarm_type parameter:

Type	Description	Best For
`SequentialWorkflow`	Linear pipeline, each agent builds on previous	Step-by-step processing
`ConcurrentWorkflow`	Parallel execution	Independent tasks, speed
`AgentRearrange`	Dynamic agent reordering	Adaptive workflows
`MixtureOfAgents`	Specialist agent selection	Multi-domain tasks
`MultiAgentRouter`	Intelligent task routing	Large-scale distribution
`HierarchicalSwarm`	Nested hierarchies with delegation	Complex org structures
`MajorityVoting`	Consensus across agents	Decision making
`BatchedGridWorkflow`	Grid pattern execution	Multi-task × multi-agent
`GraphWorkflow`	Directed graph of agent nodes	Complex dependencies
`GroupChat`	Agent discussion	Collaborative brainstorming
`InteractiveGroupChat`	Real-time agent interaction	Dynamic collaboration
`AutoSwarmBuilder`	Auto-generate optimal swarm	When unsure of architecture
`HeavySwarm`	High-capacity processing	Large workloads
`DebateWithJudge`	Structured debate	Adversarial evaluation
`RoundRobin`	Round-robin distribution	Even load distribution
`MALT`	Multi-agent learning	Training systems
`CouncilAsAJudge`	Expert panel evaluation	Quality assessment
`LLMCouncil`	LM council for decisions	Group decision making
`AdvancedResearch`	Research workflows	Deep research
`auto`	Auto-select best type	Default/unknown

Agent Config Parameters

Param	Type	Default	Description
`agent_name`	string	—	Unique agent identifier
`description`	string	—	Agent purpose
`system_prompt`	string	—	Behavior instructions
`model_name`	string	`gpt-4.1`	AI model (gpt-4o, claude-sonnet-4-20250514, etc.)
`role`	string	`worker`	Agent role in swarm
`max_loops`	int/string	`1`	Iterations (`"auto"` for autonomous)
`max_tokens`	int	`8192`	Max response length
`temperature`	float	`0.5`	Creativity (0.0–2.0)
`auto_generate_prompt`	bool	`false`	Auto-enhance system prompt
`tools_list_dictionary`	list	—	OpenAPI-style tool definitions
`streaming_on`	bool	`false`	Enable SSE streaming
`mcp_url`	string	—	MCP server URL
`selected_tools`	list	all safe	Restrict available tools

Rules

Always use environment variables for API keys — never hardcode.
Set appropriate max_loops — use "auto" only when sub-agent delegation is needed.
Match swarm_type to use case (see architecture table).
For streaming, set streaming_on: true and parse SSE events (metadata → chunks → usage → done).
Token launches cost ~0.04 SOL from the provided wallet.
Batch endpoint (/v1/swarm/batch/completions) requires Pro/Ultra/Premium tier.
Reasoning agents (/v1/reasoning-agent/completions) require Pro+ tier.

Resource Map

Topic	Reference
Full API architecture & tiers	`references/architecture.md`
Sub-agent delegation patterns	`references/sub-agents.md`
ATP payment protocol (Solana)	`references/atp-protocol.md`
Marketplace publishing	`references/marketplace.md`
Streaming implementation	`references/streaming.md`
Tools integration	`references/tools.md`
All docs pages	https://docs.swarms.ai/llms.txt

Read references only when the task requires that specific depth.

swarms-ai

Installation