swarms

Swarms Website   •   Documentation   •   Swarms Marketplace   •   中文

Overview

Swarms, The Enterprise-Grade Production-Ready Multi-Agent Orchestration Framework

Build, deploy, and scale high-performance multi-agent systems with Swarms Python, a fast, flexible, and optimized agent framework. Featuring production-ready harnesses for sequential, concurrent, and hierarchical architectures, seamless framework compatibility, and integrations with MCP, x402, and skills.

Install

# pip
$ pip3 install -U swarms

# uv (recommended): https://github.com/astral-sh/uv
$ uv pip install swarms

# poetry
$ poetry add swarms

From source

# Clone the repository
$ git clone https://github.com/kyegomez/swarms.git
$ cd swarms
$ pip install -r requirements.txt

Faster model calls and graphs with swarms[fast]

swarms[fast] adds two optional speedups:

• RouteHub for faster model calls through a drop-in LLM gateway. No code changes needed. To switch back to litellm, set SWARMS_LLM_BACKEND=litellm.
• rustworkx, a graph library written in Rust, for faster GraphWorkflow graphs. Turn it on with GraphWorkflow(backend="rustworkx").

$ pip3 install -U "swarms[fast]"

Using Docker

The official image, swarmscorp/swarms on Docker Hub, has swarms and its CLI installed on Python 3.13, for linux/amd64 and linux/arm64.

# Pull the image
$ docker pull swarmscorp/swarms:latest

# Run a script from the current directory, passing your API key from the shell
$ docker run --rm -e OPENAI_API_KEY -v "$PWD:/app" swarmscorp/swarms python agent.py

# Open a Python shell with swarms installed
$ docker run -it --rm -e OPENAI_API_KEY swarmscorp/swarms

To build the image yourself, run docker build -t swarms . from the repository root.

Environment Configuration

Learn more about the environment configuration here

OPENAI_API_KEY=""
WORKSPACE_DIR="agent_workspace"
ANTHROPIC_API_KEY=""
GROQ_API_KEY=""
SWARMS_TELEMETRY_ON

Your First Agent

An Agent is the fundamental building block of a swarm: an autonomous entity powered by an LLM + Tools + Memory. Learn more Here

from swarms import Agent

# Initialize a new agent
agent = Agent(
    model_name="gpt-5.4", # Specify the LLM
    max_loops="auto",              # Set the number of interactions
    interactive=True,         # Enable interactive mode for real-time feedback
    temperature=None,
)

# Run the agent with a task
agent.run("What are the key benefits of using a multi-agent system?")

Autonomous Agent with max_loops="auto"

Setting max_loops="auto" lets the agent decide for itself when the task is complete. It keeps reasoning and acting until it reaches a stopping condition, rather than halting after a fixed number of iterations. This is the recommended mode for open-ended, multi-step tasks where the number of steps isn’t known in advance.

from swarms import Agent

agent = Agent(
    agent_name="Autonomous-Research-Agent",
    agent_description="An autonomous agent that conducts multi-step research independently.",
    system_prompt=(
        "You are an autonomous research agent. Break down complex tasks into steps, "
        "execute each step thoroughly, and signal completion only when the full task is done."
    ),
    model_name="gpt-5.4",
    max_loops="auto",       # Agent decides when it's done; no fixed iteration cap
    autosave=True,
    verbose=True,
)

# The agent will keep looping (planning, executing, and reflecting) until it
# determines the task is fully complete.
result = agent.run(
    "Research the current state of quantum computing, identify the top three "
    "hardware approaches, and summarize the key challenges each faces."
)
print(result)

Use max_loops="auto" for open-ended research, iterative refinement, or any task where the number of steps depends on intermediate results. Use a fixed max_loops value for latency- or cost-sensitive production pipelines and tasks with a well-defined number of steps.

MCP Integration

The Model Context Protocol (MCP) lets agents easily access external tools and data by pointing to an MCP server URL, which automatically provides tools to the agent as needed. Agents become MCP-enabled by setting mcp_url or mcp_urls, and can use tools from one or many servers with no manual configuration. Free and public MCP servers like DeepWiki work out of the box, offering immediate access to useful agent tools.

from swarms import Agent

agent = Agent(
    agent_name="MCP-Agent",
    model_name="claude-sonnet-5",
    mcp_url="https://mcp.deepwiki.com/mcp",
    max_loops=1,
    temperature=None,
    max_tokens=16_000,
    reasoning_effort=None,
)

print(
    agent.run(
        "Use your tools to explain what the kyegomez/swarms repository does."
    )
)

Serve an Agent as an MCP Server

The reverse direction works too. MCPDeployer turns any agent, or any swarm, into an MCP server that other agents and MCP hosts can call, with an auth layer in front of it. Each target becomes one tool; pass a list or a dict to serve several from one server. See the MCPDeployer examples

from swarms import Agent, MCPDeployer

researcher = Agent(
    agent_name="Researcher",
    agent_description="Answers research questions with a short summary.",
    model_name="gpt-5.4",
    max_loops=1,
)

# Serves http://127.0.0.1:8000/mcp as the tool "researcher".
MCPDeployer(researcher, api_keys=["sk-local-dev"], port=8000).run()

Any other agent can then use it by pointing at the URL with the key:

from swarms import Agent
from swarms.schemas.mcp_schemas import MCPConnection

client = Agent(
    agent_name="Client",
    model_name="gpt-5.4",
    mcp_url=MCPConnection(url="http://127.0.0.1:8000/mcp", api_key="sk-local-dev"),
    max_loops=2,
)
client.run("Use the researcher tool to summarise the state of solid-state batteries.")

Auth can be static API keys, your own auth callable that reads the request headers, or an mcp TokenVerifier with required scopes. A server with no auth configured refuses to start unless you pass allow_anonymous=True. Transports: streamable HTTP (default), SSE, or stdio for desktop MCP hosts.

Your First Swarm: Multi-Agent Collaboration

A Swarm is multiple agents working together. This example chains a researcher and a writer to produce a blog post. Learn More About SequentialWorkflow

from swarms import Agent, SequentialWorkflow

# Agent 1: The Researcher
researcher = Agent(
    agent_name="Researcher",
    system_prompt="Your job is to research the provided topic and provide a detailed summary.",
    model_name="gpt-5.4",
)

# Agent 2: The Writer
writer = Agent(
    agent_name="Writer",
    system_prompt="Your job is to take the research summary and write a beautiful, engaging blog post about it.",
    model_name="gpt-5.4",
)

# Create a sequential workflow where the researcher's output feeds into the writer's input
workflow = SequentialWorkflow(agents=[researcher, writer])

# Run the workflow on a task
final_post = workflow.run("The history and future of artificial intelligence")
print(final_post)

Available Multi-Agent Architectures

swarms provides a variety of powerful, pre-built multi-agent architectures enabling you to orchestrate agents in various ways. Choose the right structure for your specific problem to build efficient and reliable production systems.

Learn more about all of the 60+ Multi-Agent Structures we have available here

SequentialWorkflow

A SequentialWorkflow runs agents in a strict order, with each agent building on the previous one’s output. Use it for processes with clear, ordered steps that depend on each other.

from swarms import Agent, SequentialWorkflow

researcher = Agent(
    agent_name="Researcher",
    system_prompt="Your job is to research the provided topic and provide a detailed summary.",
    model_name="gpt-5.4",
)

writer = Agent(
    agent_name="Writer",
    system_prompt="Your job is to take the research summary and write a beautiful, engaging blog post about it.",
    model_name="gpt-5.4",
)

workflow = SequentialWorkflow(agents=[researcher, writer])

final_post = workflow.run("The history and future of artificial intelligence")
print(final_post)

ConcurrentWorkflow

A ConcurrentWorkflow runs multiple agents on the same task in parallel. It cuts execution time for high-throughput work where agents don’t depend on each other.

from swarms import Agent, ConcurrentWorkflow

market_analyst = Agent(
    agent_name="Market-Analyst",
    system_prompt="Analyze market trends and provide insights on the given topic.",
    model_name="gpt-5.4",
    max_loops=1,
)

financial_analyst = Agent(
    agent_name="Financial-Analyst", 
    system_prompt="Provide financial analysis and recommendations on the given topic.",
    model_name="gpt-5.4",
    max_loops=1,
)

risk_analyst = Agent(
    agent_name="Risk-Analyst",
    system_prompt="Assess risks and provide risk management strategies for the given topic.",
    model_name="gpt-5.4", 
    max_loops=1,
)

concurrent_workflow = ConcurrentWorkflow(
    agents=[market_analyst, financial_analyst, risk_analyst],
    max_loops=1,
)

results = concurrent_workflow.run(
    "Analyze the potential impact of AI technology on the healthcare industry"
)

print(results)

AgentRearrange

Inspired by einsum, AgentRearrange defines relationships between agents with a simple string syntax, where -> runs agents in sequence and , runs them in parallel. Use it to mix sequential and parallel steps in any combination. Learn more

from swarms import Agent, AgentRearrange

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")

flow = "researcher -> writer, editor"

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

outputs = rearrange_system.run("Analyze the impact of AI on modern cinema.")
print(outputs)

GraphWorkflow

GraphWorkflow runs agents as nodes in a Directed Acyclic Graph (DAG), where each edge is a dependency and independent branches run in parallel. Use it for fan-out / fan-in, diamond patterns, or any structure that isn’t a simple line or parallel batch. Learn more about GraphWorkflow

from swarms import Agent, GraphWorkflow

researcher = Agent(agent_name="Researcher", system_prompt="Research the topic and list the key findings.", model_name="gpt-5.4")
writer = Agent(agent_name="Writer", system_prompt="Write a clear article from the research.", model_name="gpt-5.4")
reviewer = Agent(agent_name="Reviewer", system_prompt="Review the article for accuracy and clarity.", model_name="gpt-5.4")

workflow = GraphWorkflow()
workflow.add_nodes([researcher, writer, reviewer])
workflow.add_edge(researcher, writer)
workflow.add_edge(writer, reviewer)

print(workflow.run("Write a short article on the rise of small language models."))

SwarmRouter: The Universal Swarm Orchestrator

SwarmRouter gives you a single interface to run any type of swarm. Change swarm_type (for example to "ConcurrentWorkflow" or "HierarchicalSwarm") to run the same agents with a different strategy. Read the full documentation

from swarms import Agent, SwarmRouter

writer = Agent(agent_name="Writer", system_prompt="You are a creative writer.", model_name="gpt-5.4")
editor = Agent(agent_name="Editor", system_prompt="You are an expert editor for stories.", model_name="gpt-5.4")

router = SwarmRouter(
    agents=[writer, editor],
    swarm_type="SequentialWorkflow",
)

print(router.run("Write a short story about a robot who discovers music."))

AutoSwarmBuilder: Autonomous Agent Generation

AutoSwarmBuilder generates specialized agents, their prompts, and their workflow from a description of your task. Use it for rapid prototyping or to build a team without configuring each agent by hand. Learn more about AutoSwarmBuilder

from swarms import AutoSwarmBuilder
import json

swarm = AutoSwarmBuilder(
    name="My Swarm",
    description="A swarm of agents",
    verbose=True,
    max_loops=1,
    return_agents=True,
    model_name="gpt-5.4",
)

result = swarm.run(
    task="Create an accounting team to analyze crypto transactions, "
         "there must be 5 agents in the team with extremely extensive prompts. "
         "Make the prompts extremely detailed and specific and long and comprehensive. "
         "Make sure to include all the details of the task in the prompts."
)

print(json.dumps(result, indent=4))

MixtureOfAgents (MoA)

MixtureOfAgents sends a task to multiple expert agents in parallel. An aggregator agent then synthesizes their outputs into one final answer. Learn more here

from swarms import Agent, MixtureOfAgents

financial_analyst = Agent(agent_name="FinancialAnalyst", system_prompt="Analyze financial data.", model_name="gpt-5.4")
market_analyst = Agent(agent_name="MarketAnalyst", system_prompt="Analyze market trends.", model_name="gpt-5.4")
risk_analyst = Agent(agent_name="RiskAnalyst", system_prompt="Analyze investment risks.", model_name="gpt-5.4")

aggregator = Agent(
    agent_name="InvestmentAdvisor",
    system_prompt="Synthesize the financial, market, and risk analyses to provide a final investment recommendation.",
    model_name="gpt-5.4"
)

moa_swarm = MixtureOfAgents(
    agents=[financial_analyst, market_analyst, risk_analyst],
    aggregator_agent=aggregator,
)

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

GroupChat

In GroupChat, every agent bids each turn with a score for how much it wants to speak, and the highest bidder above threshold posts its reply. The chat ends when no agent clears threshold or max_loops messages have been posted, and every agent must carry RESPOND_TOOL so it can bid.

from swarms import Agent, GroupChat, RESPOND_TOOL

tech_optimist = Agent(
    agent_name="TechOptimist",
    system_prompt="Argue for the benefits of AI in society.",
    model_name="gpt-5.4",
    max_loops=1,
    persistent_memory=False,
    tools_list_dictionary=[RESPOND_TOOL],
)
tech_critic = Agent(
    agent_name="TechCritic",
    system_prompt="Argue against the unchecked advancement of AI.",
    model_name="gpt-5.4",
    max_loops=1,
    persistent_memory=False,
    tools_list_dictionary=[RESPOND_TOOL],
)

chat = GroupChat(
    agents=[tech_optimist, tech_critic],
    max_loops=10,
    threshold=0.5,
)

result = chat.run("Let's discuss the societal impact of artificial intelligence.")
print(result)

HierarchicalSwarm

In a HierarchicalSwarm, a director agent creates a plan and assigns tasks to specialized worker agents. The director then reviews their results and can issue new orders over several loops.

from swarms import Agent, HierarchicalSwarm

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"
)

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,
    verbose=True
)

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)

HeavySwarm

Inspired by Grok Heavy, HeavySwarm generates questions about a task, runs specialized research, analysis, alternatives, and verification agents in parallel, and synthesizes their findings. The example below uses exa_search from swarms-tools (pip install swarms-tools). Learn more about HeavySwarm

from swarms import HeavySwarm

from swarms_tools import exa_search

swarm = HeavySwarm(
    name="Gold ETF Research Team",
    description="A team of agents that research the best gold ETFs",
    worker_model_name="claude-sonnet-4-20250514",
    show_dashboard=True,
    question_agent_model_name="gpt-5.4",
    loops_per_agent=1,
    agent_prints_on=False,
    worker_tools=[exa_search],
    random_loops_per_agent=True,
)

prompt = (
    "Find the best 3 gold ETFs. For each ETF, provide the ticker symbol, "
    "full name, current price, expense ratio, assets under management, and "
    "a brief explanation of why it is considered among the best. Present the information "
    "in a clear, structured format suitable for investors. Scrape the data from the web. "
)

out = swarm.run(prompt)
print(out)

Social Algorithms

Social Algorithms let you define custom communication patterns between agents. You pass a callable that decides which agent talks to which, and in what order. Learn more about Social Algorithms

from swarms import Agent, SocialAlgorithms

def research_analysis_synthesis_algorithm(agents, task, **kwargs):
    research_result = agents[0].run(f"Research: {task}")
    analysis = agents[1].run(f"Analyze this research: {research_result}")
    synthesis = agents[2].run(f"Synthesize: {research_result} + {analysis}")
    return {
        "research": research_result,
        "analysis": analysis,
        "synthesis": synthesis
    }

researcher = Agent(
  agent_name="Researcher",
  agent_description="Expert in comprehensive research and information gathering.",
  model_name="gpt-5.4"
)
analyst = Agent(
  agent_name="Analyst",
  agent_description="Specialist in analyzing and interpreting data.",
  model_name="gpt-5.4"
)
synthesizer = Agent(
  agent_name="Synthesizer",
  agent_description="Focused on synthesizing and integrating research insights.",
  model_name="gpt-5.4"
)

social_alg = SocialAlgorithms(
    name="Research-Analysis-Synthesis",
    agents=[researcher, analyst, synthesizer],
    social_algorithm=research_analysis_synthesis_algorithm,
    verbose=True
)

result = social_alg.run("The impact of AI on healthcare")
print(result.final_outputs)

Documentation

The full documentation lives at docs.swarms.world. Below are the resources most useful when building with Swarms, both for humans and for AI coding assistants.

Tip for AI coding assistants: point your tool (Claude Code, Cursor, Windsurf, Continue, etc.) at https://docs.swarms.world/llms.txt. It will pull the entire docs index in one shot and write idiomatic Swarms code without per-question lookups.

Using Swarms with AI Coding Assistants

The repo ships with AGENTS.md and CLAUDE.md, guides that teach AI coding assistants (Claude Code, Cursor, Codex, Copilot and others) how to build with Swarms: the Agent primitive, every multi-agent architecture, tools, streaming, memory and MCP.

Copy CLAUDE.md (or symlink it as AGENTS.md / .cursorrules) into any project that uses swarms, and your assistant will write idiomatic Swarms code from the start.

Two hosted MCP servers give an assistant live Swarms context instead of training data that may predate a rename:

The whole documentation is also available as plain text at docs.swarms.world/llms.txt (an index) and docs.swarms.world/llms-full.txt (every page).

Claude Code:

claude mcp add --transport http swarms-docs https://docs.swarms.world/mcp
claude mcp add --transport http swarms-marketplace https://swarms.world/mcp \
  --header "Authorization: Bearer $SWARMS_API_KEY"

Cursor, in .cursor/mcp.json:

{
  "mcpServers": {
    "swarms-docs": { "url": "https://docs.swarms.world/mcp" },
    "swarms-marketplace": {
      "url": "https://swarms.world/mcp",
      "headers": { "Authorization": "Bearer ${env:SWARMS_API_KEY}" }
    }
  }
}

Features

Swarms delivers a comprehensive, enterprise-grade multi-agent infrastructure platform designed for production-scale deployments and seamless integration with existing systems. Learn more about the swarms feature set here

Supported Protocols & Integrations

Swarms seamlessly integrates with industry-standard protocols and open specifications, unlocking powerful capabilities for tool integration, payment processing, distributed agent orchestration, and model interoperability.

Examples

Explore comprehensive examples and tutorials to learn how to use Swarms effectively HERE

Contribute to Swarms

Swarms is an open-source, community-driven framework aiming to accelerate a fully autonomous world by providing robust infrastructure for deploying and orchestrating millions of agents. By contributing, you can help advance multi-agent AI, collaborate with passionate peers, shape the agent economy, and enhance your expertise.

Learn more about how you can make a meaningful impact in our Contributor’s Guide.

How to Contribute

We’ve made it easy to start contributing. Here’s how you can help:

1. Find an Issue to Tackle: The best way to begin is by visiting our contributing project board. Look for issues tagged with good first issue; these are specifically selected for new contributors.

2. Report a Bug or Request a Feature: Have a new idea or found something that isn’t working right? We’d love to hear from you. Please file a Bug Report or Feature Request on our GitHub Issues page.

3. Understand Our Workflow and Standards: Before submitting your work, please review our complete Contribution Guidelines. To help maintain code quality, we also encourage you to read our guide on Code Cleanliness.

4. Join the Discussion: To participate in roadmap discussions and connect with other developers, join our community on Discord.

5. Use WARP for Every Commit, PR and Issue: All contributors, people and AI agents alike, must write commit messages, PR titles and issue titles in the WARP (Warp Speed Protocol) shorthand: [TYPE][Function/FileName][Short Description], for example [FIX][Agent._run][Raise AgentLLMError after retry exhaustion]. The full spec is the WARP Git Message Skill. Issues and PRs that skip WARP are triaged after the ones that use it, so expect a delay without it.

Thank You to Our Contributors

Thank you for contributing to swarms. Your work is extremely appreciated and recognized.

Join Swarms

Our mission is to advance humanity by building the infrastructure that powers the agent economy. We’re actively recruiting talented individuals across multiple roles to accelerate this vision. Join our team to help build, maintain, and scale the Swarms Python package, Swarms Marketplace, and our growing suite of products.

• Check Open roles: swarms.ai/hiring

• Get in touch: email [email protected] to learn more

Join the Discord

Join thousands of agent builders and AI engineers in the Swarms Discord for technical support, project showcases, collaboration, and the latest swarms ecosystem updates.

Join the Swarms Discord →

Join the Swarms Community!

Join our community of agent engineers and researchers for technical support, cutting-edge updates, and exclusive access to world-class agent engineering insights!

Citation

If you use swarms in your research, please cite the project by referencing the metadata in CITATION.cff.

@misc{SWARMS_2022,
  author  = {Kye Gomez and Pliny and Zack Bradshaw and Ilumn and Harshal and the Swarms Community},
  title   = {{Swarms: Production-Grade Multi-Agent Infrastructure Platform}},
  year    = {2022},
  howpublished = {\url{https://github.com/kyegomez/swarms}},
  note    = {Documentation available at \url{https://docs.swarms.world}},
  version = {latest}

License

Swarms is licensed under the Apache License 2.0. Learn more here