kyegomez/swarms: a Python multi-agent orchestration framework for sequential, concurrent and hierarchical swarms

What kyegomez/swarms is actually for

A single LLM call is a function. A workflow that researches, drafts, critiques and revises is a graph, and most teams end up hand-rolling that graph with dictionaries and retry loops. Swarms exists to make those graphs first-class Python objects. The README describes the project as an "Enterprise-Grade Production-Ready Multi-Agent Orchestration Framework" and lists prebuilt sequential, concurrent and hierarchical architectures alongside backward compatibility with other agent frameworks and interoperability with MCP and x402.

The intended reader is a Python developer who already has API keys and wants to stop writing orchestration glue. The pyproject classifiers say Development Status :: 4 - Beta and Python :: 3.10, so the project positions itself as beta software for Python 3.10 and above. That combination matters: the marketing language says enterprise, the packaging metadata says beta. Believe the metadata when you plan your release schedule.

How the Agent and Swarm classes fit together

The core abstraction is the Agent: an LLM plus tools plus memory, per the README. An Agent is configured with model_name, max_loops, temperature and optionally system_prompt, autosave and verbose. The model layer is not written from scratch; pyproject.toml pins litellm to 1.76.1, so provider routing (OpenAI, Anthropic, Google, Groq and others named in .env.example) goes through litellm rather than a bespoke client per vendor.

A Swarm is several Agents composed into a topology. The README's first swarm example is a two-agent research-and-write workflow, and the repository ships examples/multi_agent/, examples/single_agent/, examples/reasoning_agents/, examples/tools/ and examples/mcp/ as separate directories, which tells you the intended learning path is by example rather than by a single canonical tutorial.

The most consequential design choice is max_loops. A fixed integer caps iterations. The string "auto" hands the stopping decision to the model: the README says the agent "keeps reasoning and acting until it reaches a stopping condition". That is a control-flow decision delegated to a language model, and the README itself lists the trade-off, recommending auto for open-ended multi-step work and a fixed value for "latency-sensitive or cost-sensitive production pipelines". Treat that recommendation as the project's own admission that auto mode is unbounded in the worst case.

Observability is wired in at the dependency level: opentelemetry-sdk and opentelemetry-exporter-otlp-proto-http are both listed in requirements.txt, so traces can be exported over OTLP HTTP. The README does not show a configuration example for the exporter, so expect to read the source or the docs site to find the endpoint setting.

Installing swarms and running a first agent

The README gives four install paths. The plain pip route is the shortest:

pip3 install -U swarms

The README marks uv as recommended and describes it as a fast Python package installer and resolver written in Rust:

uv pip install swarms

Poetry and a from-source clone are also documented. Docker is not: there is a commented-out Docker section in the README and a scripts/ directory in the repository, but the README does not present a working image reference, so do not assume an official container exists.

Configuration is environment-based. The README shows a minimal set of keys, and .env.example in the repository root carries a longer list including provider keys and workspace settings:

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

With a key set, the smallest useful program is the README's first agent. Note that the README uses model_name="gpt-5.4"; whether that identifier resolves depends on your litellm version and provider account, so substitute a model your key can actually reach if the call fails:

from swarms import Agent

agent = Agent(
    model_name="gpt-5.4",
    max_loops="auto",
    interactive=True,
    temperature=None,
)

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

The expected result is a printed string containing the model's answer. If you get an authentication error, the key is missing or the provider is not the one litellm routed to. If you get a model-not-found error, the model identifier is the problem, not the framework.

For tool access without writing tool schemas, the README shows MCP wiring through a URL. The DeepWiki server is given as a free public example:

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

Setting mcp_url is the whole configuration step; the README states tools from one or many servers are provided automatically. mcp_urls (plural) is the multi-server form. The caveat is that the tool list is fetched at runtime from a remote endpoint, so a network failure or a changed server surface changes what your agent can do without any change on your side.

Telemetry is on until you turn it off

.env.example is unusually direct about this. The comment above the setting reads "Telemetry is ON by default. Set to false/0/no/off to opt out", and the key ships as:

SWARMS_TELEMETRY_ON="true"

Opt-out telemetry is a legitimate design choice, but it is a choice that has to survive a security review. If your deployment pipeline copies .env.example as a starting template, you are shipping telemetry enabled. Set the value explicitly in every environment rather than relying on the default, and check it again after any upgrade, since a default can change between versions. The README does not document what the telemetry payload contains, which is the part a reviewer will ask about first.

Version drift between tags and pyproject.toml

The release history given for this repository lists 6.8.1 (2024-12-27), 5.3.7 (2024-07-15) and 2.5.0 (2023-12-01). The pyproject.toml in the repository declares version = "15.0.2". Those two facts do not line up, and the gap is large enough to be a planning problem rather than a rounding error.

What that means in practice is that a tag is not a reliable reference point. If you pin swarms==6.8.1 you are pinning something roughly nine major versions behind what the source tree describes. If you install from PyPI without pinning, you get whatever is published, which may or may not correspond to a tag you can read release notes for. The README does not document rollback, and no changelog is present at the repository root, though examples/changelogs/ exists as a directory.

The last push to the repository was on 2026-09-09, so the code is moving. The release tags are not moving at the same rate. Plan for that: pin an exact version in your own lockfile, read the source you actually installed, and treat the README as a description of the current tree rather than of your installed package.

When swarms is the wrong choice, and what to use instead

The wrong choice is any pipeline where cost per run must be predictable to the cent. max_loops="auto" delegates the stopping condition to the model, and the README lists cost-sensitive production pipelines as the case for a fixed loop count instead. If your workload is a bounded extraction or classification job, an orchestration framework adds a dependency tree (litellm, pydantic, networkx, opentelemetry, mcp) for control flow you could write in fifty lines.

LangChain is the obvious alternative and the difference is structural, not cosmetic. LangChain is built around composable runnable chains and a large integration surface; swarms is built around named agent topologies (sequential, concurrent, hierarchical) as prebuilt architectures. If your mental model is "a chain of transformations", LangChain matches it. If your mental model is "a team of agents with roles", swarms matches it. The repository lists langchain and langchain-python as topics and the README claims backward compatibility with leading agent frameworks, so the two are not mutually exclusive, but mixing them means two abstractions competing for the same control flow.

A second alternative worth naming is writing the loop yourself against litellm directly. You lose the prebuilt topologies and the MCP wiring, and you keep full control over stopping conditions, retries and spend. For a single-agent tool-calling loop, that is usually the better trade.

Licence and the cost of keeping up

The licence is Apache-2.0, declared in pyproject.toml and present as a LICENSE file at the repository root. Apache-2.0 permits commercial use and modification and includes an explicit patent grant, which is friendlier than a bare MIT for a project that may touch patented model-serving techniques. It also requires that you preserve notices. This is not legal advice; have counsel review if you redistribute the framework inside a product.

Upgrade cost is the real ongoing expense. The dependency set is broad and some pins are exact: litellm==1.76.1 and pydantic==2.12.5 in requirements.txt. Exact pins reduce breakage but they also mean a security fix in either library cannot be adopted without either waiting for a swarms release or overriding the pin yourself, which puts you off the tested path. The mcp dependency is ranged (mcp>=1.28.1,<3.0.0), so that one floats within a major window.

Budget for reading the source at each upgrade. There is no root changelog to diff against, the release tags lag the declared version, and the README does not document rollback. A dependency you cannot cleanly roll back is a dependency you should upgrade deliberately, in a branch, with your own smoke test.

Editorial conclusion

Adopt swarms if you are building Python services where agent topology is a design decision you want to express as code, and you are comfortable tracking the master branch because the published release tags run well behind the pyproject version. Do not adopt it if you need a documented rollback path, a pinned dependency set you can audit without reading requirements.txt, or telemetry that is off unless you ask. Before committing, check whether the version you install matches the docs you are reading, and set SWARMS_TELEMETRY_ON="false" in .env if outbound telemetry is not acceptable in your environment.

Frequently asked questions

Official sources

1. kyegomez/swarms on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases