/swarms

name: swarms
description: Build agents and multi-agent systems with the Swarms framework — the Agent class, tools, autonomous loops, memory, and the 15+ multi-agent architectures (SequentialWorkflow, ConcurrentWorkflow, GraphWorkflow, HierarchicalSwarm, SwarmRouter, and more). Use whenever writing, reviewing, or debugging code that imports `swarms`.

Swarms

Swarms is a multi-agent orchestration framework. Everything is built from one primitive — `Agent` — which multi-agent structures compose. This document is verified against **swarms v14.0.0**.

Golden rules

1. **Import from the top level**: `from swarms import Agent`, never `from swarms.structs.agent import Agent`. The one common exception is `PlannerWorkerSwarm` (see below). 2. **Every agent needs a unique `agent_name`** — memory files and swarm routing key on it. 3. **Default to `max_loops=1`.** Use a specific integer for production. Use `"auto"` only for genuinely open-ended work. 4. **Pass `tools=None`, not `tools=[]`.** An empty list breaks schema generation. 5. **Check `examples/`** — 586 runnable examples live there. One is probably close to what you need. 6. **Never set `streaming_on=True` and `streaming_callback` together.** Pick one.

Setup

pip install -U swarms

Set the key for whichever provider you use — any [LiteLLM](https://docs.litellm.ai/docs/providers) model string works:

export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
export GROQ_API_KEY="..."
export WORKSPACE_DIR="agent_workspace"   # where agent state and memory land

---

Part 1 — The Agent

from swarms import Agent

agent = Agent(
    agent_name="Analyst",
    agent_description="Analyzes market data and produces summaries.",
    system_prompt="You are a precise financial analyst.",
    model_name="gpt-5.4",
    max_loops=1,
)

result = agent.run("Summarize the state of the semiconductor market.")

`Agent.__init__` accepts 90+ parameters. These are the ones that matter:

| Parameter | Type | Default | Purpose | |---|---|---|---| | `agent_name` | `str` | `"swarm-worker-01"` | Unique identity; keys memory + routing | | `agent_description` | `str` | generic | How orchestrators decide to route to it | | `system_prompt` | `str` | built-in | Persona and instructions | | `model_name` | `str` | `"gpt-5.4"` | Any LiteLLM model string | | `max_loops` | `int \| "auto"` | `1` | Iterations, or autonomous mode | | `tools` | `list[Callable]` | `None` | Python functions the agent may call | | `temperature` | `float` | `0.5` | Sampling temperature | | `max_tokens` | `int` | model max | Output cap per call | | `top_p` | `float` | `None` | Nucleus sampling | | `context_length` | `int` | `None` | Token budget; triggers compression at 90% | | `output_type` | `str` | `"str-all-except-first"` | Return shape — see below | | `streaming_on` | `bool` | `False` | Stream tokens to stdout | | `streaming_callback` | `Callable` | `None` | Stream tokens to your function | | `interactive` | `bool` | `False` | REPL — prompts the user each loop | | `verbose` | `bool` | `False` | Debug logging | | `print_on` | `bool` | `True` | Print the final output | | `autosave` | `bool` | `False` | Persist agent state after each run | | `retry_attempts` | `int` | `3` | LLM call retries | | `reasoning_effort` | `str` | `None` | `minimal`/`low`/`medium`/`high`/`xhigh`/`ultra`/`max`/`none` | | `thinking_tokens` | `int` | `1024` | Extended thinking budget (Claude) | | `mcp_url` / `mcp_urls` | `str` / `list[str]` | `None` | MCP servers to load tools from | | `handoffs` | `list[Agent]` | `None` | Agents this one may delegate to | | `persistent_memory` | `bool` | `False` | Read/write `MEMORY.md` across restarts | | `context_compression` | `bool` | `True` | Auto-summarize near the context limit | | `plan_enabled` | `bool` | `False` | Plan before executing | | `mode` | `str` | `"standard"` | `"standard"`, `"fast"`, `"interactive"` | | `fallback_models` | `list[str]` | `None` | Models to try if the primary fails |

**`output_type` options**: `"str"`, `"list"`, `"dict"`, `"json"`, `"yaml"`, `"final"`, `"last"`, `"all"`, `"basemodel"`, `"str-all-except-first"`, `"dict-all-except-first"`, `"dict-final"`, `"list-final"`.

Running

agent.run(task="...")                          # standard
agent.run(task="...", img="chart.png")         # one image
agent.run(task="...", imgs=["a.png", "b.png"]) # several images
agent.run(task="...", n=3)                     # 3 independent samples
await agent.arun("...")                        # async

`Agent.run` signature: `run(task=None, img=None, imgs=None, correct_answer=None, streaming_callback=None, n=1)`.

Streaming

# To stdout
agent = Agent(agent_name="Writer", model_name="gpt-5.4", streaming_on=True)
agent.run("Write a haiku about distributed systems.")

# To a callback (do NOT combine with streaming_on)
def on_token(token: str) -> None:
    print(token, end="", flush=True)

agent = Agent(agent_name="Writer", model_name="gpt-5.4", streaming_callback=on_token)
agent.run("Write a haiku.")

# Async streaming
async for token in agent.arun_stream("Explain async/await."):
    print(token, end="", flush=True)

---

Part 2 — Tools

Any Python function with type hints and a docstring becomes a tool. The framework generates the OpenAI function schema automatically — **the docstring is the tool description the model reads, so write it for the model.**

from swarms import Agent

def get_stock_price(ticker: str) -> str:
    """Fetch the current stock price for a ticker symbol.

    Args:
        ticker: Stock ticker symbol, e.g. 'AAPL'.

    Returns:
        The current price as a formatted string.
    """
    import yfinance as yf
    return f"{ticker}: ${yf.Ticker(ticker).fast_info['last_price']:.2f}"

agent = Agent(
    agent_name="StockAnalyst",
    model_name="gpt-5.4",
    tools=[get_stock_price],
    max_loops=3,          # needs > 1 so it can act on the tool resul