code-review

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 with RouteHub

swarms[fast] uses 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.

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

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_k