open-swarm 0.5.0

Open Swarm: Orchestrating AI Agent Swarms with Django

Open Swarm

Open Swarm is a Python framework for building, running, and deploying multi-agent AI workflows. Agent teams are defined as Blueprints — self-contained, discoverable Python modules — and can be used two ways:

1. As a CLI tool (swarm-cli): run blueprints locally, interactively or one-shot, and optionally compile them into standalone executables.
2. As an API service (swarm-api): serve blueprints over an OpenAI-compatible REST API (/v1/models, /v1/chat/completions, /v1/responses), so any OpenAI client — SDKs, chat UIs, integrations — can talk to your agents. The OpenAPI spec is served at /api/schema/ (with Swagger UI at /api/schema/swagger-ui/).

Built on the openai-agents SDK. Derivative of OpenAI's experimental Swarm (see Attribution).

Elevator pitch: define a team of AI agents once — as a blueprint — and run it anywhere: as a local CLI command, a compiled standalone executable, or behind an OpenAI-compatible API that any OpenAI client, SDK, or chat UI can talk to. Web dashboard, live websocket chat, MCP tool integration, and opt-in agent memory included.

The dashboard — take the full guided tour.

One blueprint — CLI and OpenAI-compatible API.

Status: beta. Core framework, CLI, OpenAI-compatible REST API, websocket chat, and both web UIs are working, covered by an 1100+ test suite and verified in Docker. Remaining gaps are listed honestly in Roadmap.

🧭 Start with the Vision — where Open Swarm is going (one OpenAI-compatible endpoint that adapts and orchestrates your agentic CLIs), with an honest built-vs-remaining table and live cross-CLI proofs. Pattern mechanics with sequence diagrams: Orchestration Patterns.

---

Quickstart (CLI)

# Install from source (PyPI package: open-swarm)
git clone https://github.com/matthewhand/open-swarm.git
cd open-swarm
uv sync --all-extras          # or: pip install -e .[dev]

# Configure an LLM key
export OPENAI_API_KEY="sk-..."

# List bundled blueprints
uv run swarm-cli list

# Run one
uv run swarm-cli launch codey --message "Explain this repo's structure"

# Compile a blueprint into a standalone executable (PyInstaller)
uv run swarm-cli install codey

swarm-cli commands available today: list, launch, install, install-executable, cli-agents (alias agents) — autodiscovers which of your installed agentic CLIs are configured, installed, and (with --check-auth) authenticated — and skills, which lists reusable capabilities (SKILL.md directories) you can apply to any CLI via the cli_agent skill= param.

Quickstart (API server)

cp .env.example .env          # set OPENAI_API_KEY, API_AUTH_TOKEN, DJANGO_SECRET_KEY
docker compose up -d

curl -sf http://localhost:8000/v1/models | jq .
curl -sf http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${API_AUTH_TOKEN}" \
  -d '{"model": "suggestion", "messages": [{"role":"user","content":"ping"}]}' | jq .

# OpenAI Responses API (input as a string or a message array):
curl -sf http://localhost:8000/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${API_AUTH_TOKEN}" \
  -d '{"model": "suggestion", "input": "ping"}' | jq .

The model field selects which blueprint handles the request. Streaming is supported. Wrapping your CLIs: install + authenticate your agentic CLIs, run swarm-cli cli-agents --init --write to generate the cli_agents config, then call with model: "cli_fusion" (one agent, consensus across your CLIs) or model: "cli_map" (many agents, each one CLI). See docs/CLI_FUSION.md. A Django web UI (teams, blueprint library, agent creator, settings, websocket chat) is served at / — built with server-rendered templates + HTMx; it is the supported UI.

---

Architecture

One OpenAI-compatible endpoint. Point any client at it; the model field selects a blueprint (a team/strategy), which runs the request over your CLI agents (gemini/claude/grok/opencode — each self-authenticated) and/or REST/LLM profiles (any OpenAI-compatible backend — local LiteLLM, Ollama, Groq, OpenAI).

flowchart LR
    Client["OpenAI client — SDK, Open WebUI, curl, MCP"] -->|v1 chat or responses| API[Open Swarm API]
    API -->|model selects| BP{Blueprint = team or strategy}
    BP --> REG[CLI adapter registry]
    BP --> LLM["REST / LLM profiles"]
    REG --> g[gemini]
    REG --> c[claude]
    REG --> k[grok]
    REG --> o[opencode]
    LLM --> lite["local LiteLLM / Ollama"]
    LLM --> cloud["Groq / OpenAI / any OpenAI-compatible"]

The blueprints are examples of a composition system — you assemble your own personas, teams, and consensus rules. The architectural choice that matters most is how consensus is invoked: always, or only when an orchestration agent decides it's worth the spend.

flowchart TB
    Q[Request] --> MODE{Consensus strategy}
    MODE -->|single| S["one agent — cli_agent"]
    MODE -->|always| F["panel plus judge — cli_fusion"]
    MODE -->|gated| R["router decides, escalate only if high stakes — cli_orchestrator"]
    MODE -->|debate| D["group chat — cli_roundtable"]
    MODE -->|lenses| P["diverse expert lenses — persona_council"]
    MODE -->|mixed| H["REST coordinator plus CLI tools — hybrid_team"]

📖 All the recipes are in docs/EXAMPLES.md — two sections: Team examples (consensus blueprints + persona councils, with curl for each) and CLI + REST config (wiring cli_agents, llm profiles, and the mix). Diagrams + sequence flows for every pattern: docs/ORCHESTRATION_PATTERNS.md.

---

Core Concepts

• Agents — individual AI workers powered by LLMs, built on the openai-agents SDK (agents, tools, handoffs).

• Blueprints — BlueprintBase subclasses defining a team: its agents, coordination logic, tools, and required MCP servers/env vars. Discovered by directory scan; each blueprint is independently runnable, testable, and compilable. Blueprints can call other blueprints as tools (swarm.core.blueprint_utils.blueprint_tool).

• MCP servers — external tool providers (filesystem, search, databases, …) declared in config, not code; agents get their tools at runtime via the Model Context Protocol.

• CLI agents & fusion — wrap your installed agentic CLIs (grok/agent, claude, gemini, codex, opencode, …) as subagents behind the OpenAI API, and compose them four ways:

  • model: "cli_agent" — run a single CLI as one agent.
  • model: "cli_fusion" — fan a prompt to a panel in parallel, then judge and synthesize the answers (a bounded master plan can iterate the panel).
  • model: "cli_orchestrator" — a cheap router CLI answers directly and escalates only high-stakes questions to a consensus panel (fusion as a granular tool, not a whole-request mode).
  • model: "cli_map" — decompose a task, distribute the subtasks across worker CLIs in parallel, and reduce the results into one answer.

  Consensus can be framework-driven (self-consensus: the same persona N times; or a multi-persona panel) or delegated to a CLI's own built-in mode where one exists (e.g. grok's --best-of-n N) — and the two compose. grok is the preferred default for judge/router/planner roles. See docs/CLI_FUSION.md. Worked 3-CLI consensus transcripts — each showing every agent's individual contribution, the judge's analysis, and the synthesis (including where the panel disagrees) — live in docs/examples/.

• Skills — reusable capabilities packaged as SKILL.md directories (YAML frontmatter + instructions, optionally bundled scripts), following Anthropic's Agent Skills open standard so they're portable to Claude Code / the Skills API. List them with swarm-cli skills; apply one to any CLI with the cli_agent skill=<name> param — it prepends the skill's instructions and stages any bundled assets into the workdir for a write-mode CLI to run. Skills are CLI-agnostic: the same skill works on grok, claude, or gemini. Bundled examples: conventional-commit, reviewing-code, writing-changelog, counting-lines (ships an executable count.py).

• Inference profiles — a blueprint can declare what kind of thinking it wants — intelligence, speed, cost as 0–1 priorities — instead of hard-coding a model. Each backend is tagged with capability traits (defaults you override per-agent), and the best match is chosen automatically. So a reasoning-heavy blueprint routes to whatever you labelled smart (e.g. claude opus 4.8 → intelligence 1.0); a high-volume one routes to your fast/cheap CLI. Keeps blueprints portable across hosts. See docs/CLI_FUSION.md.

• Configuration — one JSON file (~/.config/swarm/swarm_config.json) holding named LLM profiles and MCP server definitions, with ${ENV_VAR} placeholders so secrets stay in the environment / .env.

Example swarm_config.json

{
  "llm": {
    "default": {
      "provider": "openai",
      "model": "gpt-4o",
      "base_url": "https://api.openai.com/v1",
      "api_key": "${OPENAI_API_KEY}"
    },
    "local": {
      "provider": "ollama",
      "model": "llama3",
      "base_url": "http://localhost:11434"
    }
  },
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "${ALLOWED_PATH}"],
      "env": { "ALLOWED_PATH": "${ALLOWED_PATH}" }
    }
  }
}

Select a profile per run with DEFAULT_LLM=local swarm-cli launch codey .... Any OpenAI-compatible endpoint works (Ollama, LiteLLM, vLLM, …). See CONFIGURATION.md for the full guide.

---

Bundled Blueprints

Flagship blueprints (maintained, with the unified spinner/result-box CLI UX):

Blueprint	What it does
codey	Code generation, code/semantic search, file ops; approval-mode workflow
geese	Multi-agent coordination with memory; researcher/coordinator pattern
jeeves	Private web search (DuckDuckGo) + home automation via agent delegation
suggestion	Structured-output suggestions (Agent(output_type=...))
whinge_surf	Async subprocess management — launch, poll, review jobs
rue_code	Code execution / file-system interaction
zeus	General-purpose team launcher
poets	SQLite-backed creative-writing agents

CLI Agent Fusion blueprints (wrap your installed agentic CLIs — see docs/CLI_FUSION.md):

Blueprint	What it does
cli_agent	Run a single installed CLI (grok, claude, gemini, …) as one agent
cli_fusion	Fan a prompt to a panel of CLIs in parallel, then judge and synthesize
cli_orchestrator	Cheap router CLI answers directly; escalates hard questions to a consensus panel
cli_map	Decompose a task, distribute subtasks across worker CLIs, reduce to one answer

More live under src/swarm/blueprints/ (see its README); some are demos or Django-app experiments of varying maturity. Scaffold a new compliant blueprint with python3 scripts/scaffold_blueprint.py.

---

Environment Variables

Set in .env (copy .env.example). Security-critical ones first:

Variable	Description	Default
OPENAI_API_KEY	LLM API key (or key for your OpenAI-compatible endpoint)	required for real runs
API_AUTH_TOKEN	Bearer token for the REST API. If unset, API auth is disabled — required for any non-local deployment	unset ⚠️
DJANGO_SECRET_KEY	Django secret. Required when DJANGO_DEBUG is not true (server refuses to start without it)	dev-only fallback in debug
DJANGO_DEBUG	Django debug mode — never true in production	false
DJANGO_ALLOWED_HOSTS	Comma-separated allowed hosts	localhost,127.0.0.1
DEFAULT_LLM	Name of the LLM profile to use from config	default
SWARM_CONFIG_PATH	Path to swarm_config.json	XDG config dir
BLUEPRINT_DIRECTORY	Where blueprints are discovered	src/swarm/blueprints
SWARM_BLUEPRINTS	Comma-separated allow-list of blueprints to expose	all
SWARM_TEST_MODE	Deterministic canned output for tests/CI — never set in production	unset
ENABLE_ADMIN	Enable Django admin UI	false

Feature-flag variables for experimental subsystems (ENABLE_MCP_SERVER, ENABLE_GITHUB_MARKETPLACE) exist but gate unfinished features — see Roadmap.

---

Development

uv sync --all-extras                  # install with all extras
uv run pytest -q --timeout=120       # full suite (1100+ tests, no API keys needed)
uv run python manage.py check         # Django sanity
ruff check .                          # lint

• Tests run keyless via SWARM_TEST_MODE — blueprints emit deterministic spinner/result-box output that the suite asserts against.

• Blueprint UX standards (spinner sequences, ANSI/emoji result boxes) are codified in docs/blueprint_standards.md and checked by scripts/check_ux_compliance.py plus CI compliance workflows.

• The optional React frontend lives in webui/frontend/ (Node >= 22, npm install && npm run build); Django serves the built dist/ automatically when present and falls back to the template UI otherwise. The React UI is experimental — see Roadmap. Documentation map:

• USERGUIDE.md — task-oriented swarm-cli reference.

• docs/DEPLOYMENT.md — runbook for deploying a CLI-wrapping OpenAI-compatible server (pull → configure → prove).

• docs/USER_JOURNEY.md — screenshot-illustrated end-to-end story (install → CLI → web UI → API) with real transcripts.

• docs/GUIDED_TOUR.md — visual page-by-page tour of the web UI (React SPA + Django templates).

• docs/SKILLS_AND_CONSENSUS_WALKTHROUGH.md — illustrated end-to-end walkthrough of skills + 3-CLI consensus, with real terminal captures.

• docs/SCREENSHOTS.md — screenshot capture registry; regenerate with scripts/capture_user_journey.py.

• DEVELOPMENT.md — tech stack and internal architecture; ROADMAP.md — honest feature status.

---

Roadmap / Unfinished Features

Detailed nested progress lives in ROADMAP.md; per-feature evidence in FEATURE_STATUS.md. The honest short list of what is not done:

• React SPA full parity with the Django UI — dashboard, chat, teams, blueprints, agent-creator, and settings pages are live on real APIs, but the Django templates UI remains the supported surface until per-page parity is complete
• MCP server mode (ENABLE_MCP_SERVER) — aspirational; the flag warns loudly and docs/mcp_server_mode.md documents real adoption options
• Memory — mem0 is wired into the agent loop (opt-in) and documented in CONFIGURATION.md, but not yet validated against a live mem0 end-to-end; letta/langmem are placeholders
• Deprecation-shim sunset — 7 import shims from the consolidation get removed in the release after v0.3.x
• CLI fusion follow-ups — the cli_agent/cli_fusion blueprints work end-to-end (docs/CLI_FUSION.md); next: extract the panel→judge→synthesize loop into a reusable swarm.core.cli_fusion service for the websocket/CLI front-ends, and add opt-in git-worktree isolation for write-mode panels

Acknowledgements & Attribution

Open Swarm is a derivative of OpenAI's experimental Swarm framework — it began as an extension of the original Swarm concept (lightweight multi-agent orchestration via agents and handoffs) and has since migrated to the openai-agents SDK, Swarm's production-ready successor, which provides the core agent, tool, and handoff functionality.

Further acknowledgements live in DEVELOPMENT.md and individual source files.

License

MIT — see LICENSE. Attribution and vendored-asset notices live in NOTICE (the project uses a single NOTICE file rather than per-file license headers).

Contributing

Issues and PRs welcome. Before submitting: run the test suite, lint, and the blueprint compliance scripts (scripts/check_ux_compliance.py, scripts/audit_blueprint_compliance.py); CI enforces blueprint metadata and UX standards. See DEVELOPMENT.md and ROADMAP.md for where help is most useful.

Dev setup, test commands, and PR guidelines: CONTRIBUTING.md.