kyegomez/swarms

Swarms Website   •   Documentation   •   Swarms Marketplace   •   中文

Overview

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

Swarms is the most reliable, scalable, and adaptive multi-agent orchestration framework available today. We provide a comprehensive suite of production-ready, prebuilt multi-agent architectures, including sequential, concurrent, and hierarchical systems. Additionally, Swarms offers backward compatibility with leading agent frameworks and interoperability with protocols such as MCP, x402, skills, and much more.

Install

Using pip

$ pip3 install -U swarms

Using uv (Recommended)

uv is a fast Python package installer and resolver, written in Rust.

$ uv pip install swarms

Using poetry

$ poetry add swarms

From source

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

---

Environment Configuration

Learn more about the environment configuration here

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

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)

When to use max_loops="auto":

• Open-ended research or analysis tasks
• Tasks that require iterative refinement (e.g., write → review → revise)
• Any workflow where the number of steps depends on intermediate results

When to use a fixed max_loops value:

• Latency-sensitive or cost-sensitive production pipelines
• Tasks with a well-defined, bounded 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.

| Example | What it shows | |---|---| | single_agent_api_key.py | One agent behind a static key | | multiple_agents_one_server.py | Two agents, a SequentialWorkflow and two functions as separate tools | | custom_auth_per_tenant.py | Your own async auth callable reading an x-tenant header | | token_verifier_with_scopes.py | TokenVerifier with required scopes | | background_server_and_client_agent.py | Serve, call from a second agent, and stop, all in one process | | All MCPDeployer examples | Every target kind, auth mode and transport |

Your First Swarm: Multi-Agent Collaboration

A Swarm consists of multiple agents working together. This simple example creates a two-agent workflow for researching and writing 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.

| Architecture | Description | Best For | |---|---|---| | SequentialWorkflow | Agents execute tasks in a linear chain; the output of one agent becomes the input for the next. | Step-by-step processes such as data transformation pipelines and report generation. | | ConcurrentWorkflow | Agents run tasks simultaneously for maximum efficiency. | High-throughput tasks such as batch processing and parallel data analysis. | | AgentRearrange | Dynamically maps complex relationships (e.g., a -> b, c) between agents. | Flexible and adaptive workflows, task distribution, and dynamic routing. | | GraphWorkflow | Orchestrates agents as nodes in a Directed Acyclic Graph (DAG). | Complex projects with intricate dependencies, such as software builds. | | MixtureOfAgents (MoA) | Utilizes multiple expert agents in parallel and synthesizes their outputs. | Complex problem-solving and achieving state-of-the-art performance through collaboration. | | GroupChat | Agents collaborate and make decisions through a conversational interface. | Real-time collaborative decision-making, negotiations, and brainstorming. | | ForestSwarm | Dynamically selects the most suitable agent or tree of agents for a given task. | Task routing, optimizing for expertise, and complex decision-making trees. | | HierarchicalSwarm | Orchestrates agents with a director who creates plans and distributes tasks to specialized worker agents. | Complex project management, team coordination, and hierarchical decision-making with feedback loops. | | HeavySwarm | Implements a five-phase workflow with specialized agents (Research, Analysis, Alternatives, Verification) for comprehensive task analysis. | Complex research and analysis tasks, financial analysis, strategic planning, and comprehensive reporting. | | SwarmRouter | A universal orchestrator that provides a single interface to run any type of swarm with dynamic selection. | Simplifying complex workflows, switching between swarm strategies, and unified multi-agent management. |

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

-----

SequentialWorkflow

A SequentialWorkflow executes tasks in a strict order, forming a pipeline where each agent builds upon the work of the previous one. SequentialWorkflow is Ideal for processes that have clear, ordered steps. This ensures that tasks with dependencies are handled correctly.

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)

-----

ConcurrentWorkflow

A ConcurrentWorkflow runs multiple agents simultaneously, allowing for parallel execution of tasks. This architecture drastically reduces execution time for tasks that can be performed in parallel, making it ideal for high-throughput scenarios where agents work on similar tasks concurrently.

from swarms import Agent, ConcurrentWorkflow
Create agents for different analysis tasks
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,
)
Create concurrent workflow
concurrent_workflow = ConcurrentWorkflow(
    agents=[market_analyst, financial_analyst, risk_analyst],
    max_loops=1,
)
Run all agents concurrently on the same task
results = concurrent_workflow.run(
    "Analyze the potential impact of AI technology on the healthcare industry"
)
print(results)

---

AgentRearrange

Inspired by einsum, AgentRearrange lets you define complex, non-linear relationships between agents using a simple string-based syntax. Learn more. This architecture is perfect for orchestrating dynamic workflows where agents might work in parallel, in sequence, or in any combination you choose.

from swarms import Agent, AgentRearrange
Define agents
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")
Define a flow: researcher sends work to both writer and editor simultaneously
This is a one-to-many relationship
flow = "researcher -> writer, editor"
Create the rearrangement system
rearrange_system = AgentRearrange(
    agents=[researcher, writer, editor],
    flow=flow,
)
Run the swarm
outputs = rearrange_system.run("Analyze the impact of AI on modern cinema.")
print(outputs)

GraphWorkflow

GraphWorkflow orchestrates agents as nodes in a Directed Acyclic Graph (DAG). Each node is an agent and each edge declares a dependency, so a node only runs after every upstream node has finished. A topological sort guarantees correct execution order, while independent branches run in parallel automatically.

This makes GraphWorkflow the right choice when your workflow has fan-out / fan-in patterns, conditional dependencies, or any structure that doesn't fit a strict line or a flat parallel batch. Learn more about GraphWorkflow

from swarms import Agent, GraphWorkflow, Node, Edge, NodeType
Define agents
researcher = Agent(agent_name="Researcher", system_prompt="Research the given topic and produce key findings.", model_name="gpt-5.4")
writer     = Agent(agent_name="Writer",     system_prompt="Write a clear article from the research provided.", model_name="gpt-5.4")
reviewer   = Agent(agent_name="Reviewer",   system_prompt="Review the article for accuracy and clarity.",      model_name="gpt-5.4")
publisher  = Agent(agent_name="Publisher",  system_prompt="Format the final reviewed article for publication.", model_name="gpt-5.4")
Build the graph: Researcher -> Writer -> Reviewer -> Publisher
workflow = GraphWorkflow()
workflow.add_node(Node(id="researcher", type=NodeType.AGENT, agent=researcher))
workflow.add_node(Node(id="writer",     type=NodeType.AGENT, agent=writer))
workflow.add_node(Node(id="reviewer",   type=NodeType.AGENT, agent=reviewer))
workflow.add_node(Node(id="publisher",  type=NodeType.AGENT, agent=publisher))
workflow.add_edge(Edge(source="researcher", target="writer"))
workflow.add_edge(Edge(source="writer",     target="reviewer"))
workflow.add_edge(Edge(source="reviewer",   target="publisher"))
workflow.set_entry_points(["researcher"])
workflow.set_end_points(["publisher"])
Run the graph
results = workflow.run("Produce a short article on the rise of small language models.")
print(results)

GraphWorkflow excels at:

• Complex Dependencies: Express any DAG, including fan-out, fan-in, and diamond patterns
• Automatic Parallelism: Independent branches execute concurrently without extra configuration
• Per-node Observability: Hook into node completion via callbacks for streaming and progress tracking

----

SwarmRouter: The Universal Swarm Orchestrator

The SwarmRouter simplifies building complex workflows by providing a single interface to run any type of swarm. Instead of importing and managing different swarm classes, you can dynamically select the one you need just by changing the swarm_type parameter. Read the full documentation

This makes your code cleaner and more flexible, allowing you to switch between different multi-agent strategies with ease. Here's a complete example that shows how to define agents and then use SwarmRouter to execute the same task using different collaborative strategies.

from swarms import Agent, SwarmRouter, SwarmType
Define a few generic agents
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")
reviewer = Agent(agent_name="Reviewer", system_prompt="You are a final reviewer who gives a score.", model_name="gpt-5.4")
The agents and task will be the same for all examples
agents = [writer, editor, reviewer]
task = "Write a short story about a robot who discovers music."
--- Example 1: SequentialWorkflow ---
Agents run one after another in a chain: Writer -> Editor -> Reviewer.
print("Running a Sequential Workflow...")
sequential_router = SwarmRouter(swarm_type=SwarmType.SequentialWorkflow, agents=agents)
sequential_output = sequential_router.run(task)
print(f"Final Sequential Output:\n{sequential_output}\n")
--- Example 2: ConcurrentWorkflow ---
All agents receive the same initial task and run at the same time.
print("Running a Concurrent Workflow...")
concurrent_router = SwarmRouter(swarm_type=SwarmType.ConcurrentWorkflow, agents=agents)
concurrent_outputs = concurrent_router.run(task)
This returns a dictionary of each agent's output
for agent_name, output in concurrent_outputs.items():
    print(f"Output from {agent_name}:\n{output}\n")
--- Example 3: MixtureOfAgents ---
All agents run in parallel, and a special 'aggregator' agent synthesizes their outputs.
print("Running a Mixture of Agents Workflow...")
aggregator = Agent(
    agent_name="Aggregator",
    system_prompt="Combine the story, edits, and review into a final document.",
    model_name="gpt-5.4"
)
moa_router = SwarmRouter(
    swarm_type=SwarmType.MixtureOfAgents,
    agents=agents,
    aggregator_agent=aggregator, # MoA requires an aggregator
)
aggregated_output = moa_router.run(task)
print(f"Final Aggregated Output:\n{aggregated_output}\n")

The SwarmRouter is a powerful tool for simplifying multi-agent orchestration. It provides a consistent and flexible way to deploy different collaborative strategies, allowing you to build more sophisticated applications with less code.

-------

AutoSwarmBuilder: Autonomous Agent Generation

The AutoSwarmBuilder automatically generates specialized agents and their workflows based on your task description. Simply describe what you need, and it will create a complete multi-agent system with detailed prompts and optimal agent configurations. Learn more about AutoSwarmBuilder

from swarms import AutoSwarmBuilder
import json
Initialize the AutoSwarmBuilder
swarm = AutoSwarmBuilder(
    name="My Swarm",
    description="A swarm of agents",
    verbose=True,
    max_loops=1,
    return_agents=True,
    model_name="gpt-5.4",
)
Let the builder automatically create agents and workflows
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."
)
The result contains the generated agents and their configurations
print(json.dumps(result, indent=4))

The AutoSwarmBuilder provides:

• Automatic Agent Generation: Creates specialized agents based on task requirements
• Intelligent Prompt Engineering: Generates comprehensive, detailed prompts for each agent
• Optimal Workflow Design: Determines the best agent interactions and workflow structure
• Production-Ready Configurations: Returns fully configured agents ready for deployment
• Flexible Architecture: Supports various swarm types and agent specializations

This feature is perfect for rapid prototyping, complex task decomposition, and creating specialized agent teams without manual configuration.

-------

MixtureOfAgents (MoA)

The MixtureOfAgents architecture processes tasks by feeding them to multiple "expert" agents in parallel. Their diverse outputs are then synthesized by an aggregator agent to produce a final, high-quality result. Learn more here

```python from swarms import Agent, MixtureOfAgents

Define expert ag