# Swarms: features, protocols, quickstart

## TL;DR

Swarms is a Python multi-agent framework maintained under the kyegomez GitHub account, whose team also sells a hosted Swarms API. It ships many prebuilt coordination structures, from sequential and concurrent workflows to DAGs, director-led hierarchies and group chat, plus MCP client and server support. It suits Python teams comparing several patterns behind one router.

## Key facts

| Field | Value |
| --- | --- |
| Type | Framework |
| Languages / SDKs | Python, Rust |
| License | Apache-2.0 |
| Pricing model | [Open core](https://docs.swarms.ai/docs/documentation/resources/pricing) |
| Orchestration pattern | Other |
| GitHub stars | 7,227 (as of 2026-10-01) |
| GitHub forks | 1,030 |
| Last push | 2026-10-01 |
| Latest release | 6.8.1 |
| Repository | [kyegomez/swarms](https://github.com/kyegomez/swarms) |
| Website | [swarms.ai](https://swarms.ai) |
| Documentation | [docs.swarms.world](https://docs.swarms.world) |
| Last verified | 2026-09-30 |

## Key features

- SequentialWorkflow and ConcurrentWorkflow for chained or parallel agent runs. ([source](https://docs.swarms.world/architectures/overview))
- GraphWorkflow runs agents as nodes of a DAG, with independent branches executed in parallel. ([source](https://docs.swarms.world/architectures/graph-workflow))
- HierarchicalSwarm: a director agent writes a plan, issues orders to workers and can loop with feedback or a judge. ([source](https://docs.swarms.world/architectures/hierarchical-swarm))
- AgentRearrange defines agent flows with a string syntax such as "a -> b, c". ([source](https://docs.swarms.world/architectures/agent-rearrange))
- SwarmRouter runs any supported swarm type through one interface, so the architecture can be switched by a parameter. ([source](https://docs.swarms.world/architectures/swarm-router))
- Agents use tools from one or more MCP servers by setting mcp_url or mcp_urls. ([source](https://docs.swarms.world/integrations/mcp))
- MCPDeployer serves an agent, swarm or function as an authenticated MCP server over Streamable HTTP, SSE or stdio. ([source](https://docs.swarms.world/api/mcp-deployer))
- Opt-in persistent memory in a per-agent MEMORY.md file, with context compression and transcript archives. ([source](https://docs.swarms.world/agents/agent-memory))

## Architecture and orchestration pattern

Pattern: Other.

The building block is `Agent`: a model plus tools, a system prompt and a loop count (`max_loops`, or `"auto"` to let the agent decide when it is done). Model calls go through a LiteLLM-based manager, so provider choice is a `model_name` string.

Multi-agent behaviour comes from a catalog of structure classes rather than one core model: pipelines (`SequentialWorkflow`), fan-out (`ConcurrentWorkflow`), DAGs (`GraphWorkflow`), director-worker hierarchies (`HierarchicalSwarm`), bidding group chat, mixture-of-agents, routers and more. `SwarmRouter` puts these behind one call, and `SocialAlgorithms` lets you write the communication order as a plain Python function.

State is a per-agent `Conversation` history held in process. Setting `persistent_memory=True` writes turns through to a `MEMORY.md` file keyed by `agent_name`, reloads it on the next run, and compresses older context when the window fills. No shared memory store across agents is documented beyond passing outputs along the chosen structure.

### Human in the loop

The documented hook is `interactive=True` (or `mode="interactive"`) on an `Agent`, which the FAQ describes as pausing for user input between loops; `HierarchicalSwarm(interactive=True)` only turns on a live terminal dashboard. No per-tool approval gate or checkpoint-and-resume flow is documented, and the v13 changelog says leftover human-in-the-loop code was removed. Searched docs for approve, interrupt, human and interactive.

## Protocols

| Protocol | Support | Evidence | Note |
| --- | --- | --- | --- |
| MCP | Yes (checked 2026-09-30) | [link](https://docs.swarms.world/integrations/mcp) | Client and server: agents load tools from MCP servers via mcp_url/mcp_urls (MCPManager), and MCPDeployer exposes agents or swarms as MCP servers. |
| A2A | Unknown (checked 2026-09-30) | — | Searched README, docs.swarms.world llms.txt and pages, GitHub code search and issues for a2a / agent2agent; only third-party integration pitches in issues, no official support. |
| AG-UI | Unknown (checked 2026-09-30) | — | Searched README, docs, GitHub code search for ag-ui / agui, and the AG-UI README integration list; Swarms is not listed. |

## Best for

- Trying several coordination patterns (pipeline, parallel, DAG, director-led) on the same set of agents.
- Multi-step research and analysis pipelines, such as the researcher-to-writer and HeavySwarm examples. ([shortlist](https://multiagentguide.top/best/research-agents.md))
- Publishing agents or whole swarms as MCP tools for other MCP hosts.
- Running agents on local models through Ollama model names. ([shortlist](https://multiagentguide.top/best/self-hosted-local.md))

## Not for

- Teams that need a TypeScript or Java framework (other languages only get Swarms Cloud API clients).
- Workflows that require documented tool-approval gates or resumable checkpoints.
- Projects that need a stable API across major versions without migration work.

## Quickstart

```sh
pip3 install -U swarms
```

Install not yet verified by this site.

```python
from swarms import Agent, HierarchicalSwarm, SequentialWorkflow

researcher = Agent(agent_name="Researcher", agent_description="Collects facts on a topic.",
                   system_prompt="List the key facts, each with a source.", model_name="gpt-5.4", max_loops=1)
writer = Agent(agent_name="Writer", agent_description="Turns notes into a short brief.",
               system_prompt="Write a 150-word brief from the notes.", model_name="gpt-5.4", max_loops=1)

# Fixed order: the researcher's output becomes the writer's input
pipeline = SequentialWorkflow(agents=[researcher, writer])
print(pipeline.run("Heat pumps in cold climates"))

# Same agents under a director that plans and assigns orders
team = HierarchicalSwarm(name="Brief-Team", description="Research then write",
                         agents=[researcher, writer], max_loops=1)
print(team.run("Compare heat pumps and gas boilers for a small office"))
```

### Common pitfalls

- Requires Python 3.10 or higher.
- Set a provider key such as `OPENAI_API_KEY` or `ANTHROPIC_API_KEY` in the environment; `WORKSPACE_DIR` controls where agents write files.
- OpenTelemetry tracing is on by default and records inputs and outputs; set `SWARMS_TELEMETRY_ON=false` before the process starts to disable it.
- `persistent_memory` defaults to `False`; reuse the same `agent_name` to resume a memory file.
- v13 removed the SwarmRouter speaker-function API and renamed `get_all_agent_names` to `return_all_agent_names`; check the changelog when upgrading.

Official quickstart: https://docs.swarms.world/installation

## Pros

- One router interface over many prebuilt structures, so patterns can be swapped without rewriting orchestration code. ([source](https://docs.swarms.world/architectures/swarm-router))
- MCP in both directions, including an auth layer (API keys, custom callable or TokenVerifier) when serving agents. ([source](https://docs.swarms.world/api/mcp-deployer))
- Opt-in file-based memory that survives restarts and is compressed when the context window fills. ([source](https://docs.swarms.world/agents/agent-memory))
- Many model providers, including local Ollama models, selected by a model_name string. ([source](https://docs.swarms.world/integrations/model-providers))
- Nested OpenTelemetry spans cover a swarm run and every agent run under it. ([source](https://docs.swarms.world/deployment/telemetry))

## Cons

- Telemetry is enabled by default and captures prompts and outputs (truncated) until SWARMS_TELEMETRY_ON is set to an off value. ([source](https://docs.swarms.world/deployment/telemetry))
- An open bug reports that eleven multi-agent structures never reset their Conversation between tasks and two share one Conversation across threads. ([source](https://github.com/kyegomez/swarms/issues/2054))
- Major versions include breaking API changes; v13 removed the speaker-function API and renamed agent lookup helpers. ([source](https://docs.swarms.world/changelog/swarms-v13))
- Human-in-the-loop support is thin: only an interactive pause mode is documented, and v13 removed leftover HITL code. ([source](https://docs.swarms.world/changelog/swarms-v13))
- GitHub Releases stop at 6.8.1 (December 2024) even though the docs describe a two-week release cadence, so version history must be read from the docs changelog. ([source](https://github.com/kyegomez/swarms/releases))

## Alternatives

- [CrewAI](https://multiagentguide.top/tools/crewai.md) ([Swarms vs CrewAI](https://multiagentguide.top/compare/swarms-vs-crewai.md))
- [AutoGen](https://multiagentguide.top/tools/autogen.md)
- [LangGraph](https://multiagentguide.top/tools/langgraph.md)
- [CAMEL](https://multiagentguide.top/tools/camel.md)
- [AgentScope](https://multiagentguide.top/tools/agentscope.md)

## FAQ

### Does Swarms support MCP?

Yes, both ways. Agents can call tools from MCP servers through mcp_url or mcp_urls, and MCPDeployer serves agents, swarms or functions as authenticated MCP servers. A2A and AG-UI support were not found in official sources.

### Is Swarms free?

The framework is Apache-2.0 and free to use; you pay your model provider. The same team runs a hosted Swarms API with free and paid subscription tiers plus usage-based billing.

### What language is Swarms written in?

The framework is Python (3.10+). The ecosystem page lists a separate Rust framework and API clients for Swarms Cloud in TypeScript, Go and Java.

### Which orchestration pattern does Swarms use?

It does not force one. It ships sequential, concurrent, DAG, director-worker, group chat, mixture-of-agents and router structures, and SwarmRouter selects among them.

### Does Swarms work with Claude Code?

Only as a coding aid: the repository ships a CLAUDE.md guide and the docs publish an llms.txt so assistants such as Claude Code or Cursor can write Swarms code. Swarms does not run or plug into Claude Code as a harness.

## Sources

- [kyegomez/swarms repository (README)](https://github.com/kyegomez/swarms)
- [GitHub releases](https://github.com/kyegomez/swarms/releases)
- [Swarms documentation home](https://docs.swarms.world)
- [Introduction](https://docs.swarms.world/introduction)
- [Installation](https://docs.swarms.world/installation)
- [Quickstart](https://docs.swarms.world/quickstart)
- [Multi-agent architectures overview](https://docs.swarms.world/architectures/overview)
- [GraphWorkflow](https://docs.swarms.world/architectures/graph-workflow)
- [HierarchicalSwarm](https://docs.swarms.world/architectures/hierarchical-swarm)
- [AgentRearrange](https://docs.swarms.world/architectures/agent-rearrange)
- [SwarmRouter](https://docs.swarms.world/architectures/swarm-router)
- [Model Context Protocol integration](https://docs.swarms.world/integrations/mcp)
- [MCPDeployer API](https://docs.swarms.world/api/mcp-deployer)
- [Agent memory](https://docs.swarms.world/agents/agent-memory)
- [Agent configuration](https://docs.swarms.world/agents/agent-configuration)
- [Telemetry](https://docs.swarms.world/deployment/telemetry)
- [Swarms v13 changelog](https://docs.swarms.world/changelog/swarms-v13)
- [Model providers](https://docs.swarms.world/integrations/model-providers)
- [FAQ](https://docs.swarms.world/community/faq)
- [Swarms ecosystem](https://docs.swarms.world/community/ecosystem)
- [Swarms API pricing](https://docs.swarms.ai/docs/documentation/resources/pricing)
- [Issue #2054: structures never reset Conversation per task](https://github.com/kyegomez/swarms/issues/2054)

## Unknown fields

protocols.a2a and protocols.agui are unknown: README, docs.swarms.world llms.txt and pages, GitHub code search and issue search for a2a/agent2agent/ag-ui/agui found no official support, and the AG-UI integration list does not include Swarms.

Corrections or removal requests: support@multiagentguide.top

---

Data as of 2026-10-01. Not affiliated with listed projects. HTML version: https://multiagentguide.top/tools/swarms