open-swarm

by matthewhand

About

Open Swarm

Open Swarm is a versatile, modular framework for building intelligent, multi-agent systems. It's a fork and actively maintained extension of the OpenAI Swarm framework. It includes modifications to support stateless RESTful operations and a plugin system for custom extensions that enhance agentic workflows.

https://github.com/user-attachments/assets/1335f7fb-ff61-4e96-881c-7d3154eb9f14

(generated by www.gitpodcast.com)

Key Features
Quickstart
Blueprints
Further Documentation
License
Acknowledgements

Key Features

Multi-Agent Orchestration
- Define multiple agents, each with unique instructions and roles.
- Agents coordinate tasks, share context, or hand off queries between one another.
Blueprint-Driven Architecture
- Each Blueprint encapsulates logic, tool connections, and environment/config settings.
- Encourages reusable, modular patterns for different use cases.
Optional MCP Integration
- Integrate with external tools (e.g., databases, web search, filesystems) through MCP servers.
- Note npx MCP servers work great but uvx MCP servers currently have issues.
CLI & REST Interface
- Run from the command line or expose a Django-powered REST API for broader integration.
- Interactive web pages per blueprint at /<blueprint_name>/.
OpenAI API Compatibility
- Exposes an endpoint at /v1/chat/completions that is functionally similar to the OpenAI Chat Completions API.
- Includes a mandatory sender field in agent responses.
  - This field identifies which Swarm agent provided the response and must be preserved in the conversation history for proper handoffs between agents.
  - While the framework is compatible with OpenAI-like API clients, it assumes the client application maintains the sender field and, ideally, displays it in the user interface.
  - Note: Most OpenAI API-compatible applications will ignore the sender field by default and not display the agent name. Custom UI or logic is required to utilise and present this information.
Configurable LLMs
- Supports multiple OpenAI-compatible providers in a single environment (e.g., openai, grok, ollama).
- Allows specifying different models/providers for different agents—even within the same blueprint.
- Use environment variable DEFAULT_LLM to specify default LLM model used by blueprints, e.g., DEFAULT_LLM=deepseek-r1-distill-llama-70b

Quickstart

Follow these simple steps to get Open Swarm up and running:

Install the Package
Run:
```
pip install open-swarm
```
Configure an LLM Provider
When you run a blueprint for the first time, Open Swarm checks for a configuration file at ~/.swarm/swarm_config.json. If the file is missing, it will automatically create a default configuration as shown below:
```
{
    "llm": {
        "default": {
            "provider": "openai",
            "model": "gpt-4o",
            "base_url": "https://api.openai.com/v1",
            "api_key": "${OPENAI_API_KEY}"
        }
    },
    "mcpServers": {}
}
```
Make sure to set the OPENAI_API_KEY environment variable with your valid OpenAI API key.

An example of using an alternative provider:

swarm-cli config add --section llm --name deepseek-r1-distill-llama-70b --json '{"provider": "openai", "model": "deepseek-r1-distill-llama-70b", "base_url": "https://api.groq.com/openai/v1", "api_key": "${GROQ_API_KEY}"}'

(Optional) Configure a Simple MCP Server
To add an MCP server for additional utilities (e.g., file fetching), use the swarm-cli config add --json '<multiline_json_block>'. For example:

   "filesystem": {
      "command": "npx",
      "args": [
            "-y",
            "@modelcontextprotocol/server-filesystem ${ALLOWED_PATH}"
      ],
      "env": {
            "ALLOWED_PATH": "${ALLOWED_PATH}"
      }
   }

Add an Example Blueprint
Add an example blueprint by running:
```
swarm-cli add /path/to/your/blueprint.py --name example
```
This copies your blueprint into the managed blueprints directory.

Example blueprints are provided here: https://github.com/matthewhand/open-swarm/tree/main/blueprints
Run the Blueprint from CLI
Execute the blueprint with:
```
swarm-cli run example
```

Overview

Open Swarm provides the following core components:

Swarm CLI:
A command-line tool for managing blueprints and configuration settings. It allows you to add, list, delete, run, and install blueprints, as well as update configuration entries for LLM providers and MCP servers.
Swarm API:
An HTTP REST service that exposes endpoints such as /v1/models and /v1/chat/completion(s). These endpoints let external applications interact with Open Swarm in an OpenAI API-compatible manner, publishing blueprints as models and processing chat completions. Additional endpoints can be exposed via blueprints.
Swarm SDK:
Open Swarm can be used as a Python module. It is backwards compatible with the original OpenAI Swarm educational framework. It also adds many extensions including configuration loading, MCP server integration, Python Django DB and REST features, etc etc.

For detailed usage instructions, please refer to the USERGUIDE.md. For developer-specific guidance, see DEVELOPMENT.md.

Blueprints

A Blueprint is a Python module that wraps:

Agent Logic: Defines how each agent in the Swarm processes user messages, whether it calls tools, and how it decides to hand off to other agents.
Tools: Specifies which agents have which tools (e.g., MCP-discovered tools, Python function calls).
Environment & Configuration: Ensures required environment variables and JSON configs are validated prior to agent execution.

Once registered, a blueprint is discoverable at runtime, allowing the system to list and load agents on demand.

Personal Assistant Example

The Personal Assistant Blueprint demonstrates a hybrid approach, integrating local Python function tools with MCP-discovered tools. It consists of:

Personal Assistant Agent
- Determines user intent and delegates queries accordingly.
- Routes weather-related queries to the WeatherAgent.
- Routes knowledge-based queries to the DocumentationAgent.
Weather Agent (Uses Python Function Tools)
- Fetches current weather and forecasts via OpenWeatherMap.
- Uses a locally defined Python function rather than an MCP server.
- Requires WEATHER_API_KEY as an environment variable.
Documentation Agent (Uses MCP-Discovered Tools)
- Retrieves relevant documentation via rag-docs.
- Uses the MCP function search_documentation to dynamically retrieve information.
- Requires the following environment variables:
  - OPENAI_API_KEY
  - QDRANT_URL
  - QDRANT_API_KEY

This blueprint highlights seamless multi-agent coordination and the flexibility of combining Python functions with MCP-discovered tools.

Other Examples

Open Swarm includes a growing library of Blueprint examples:

Blueprint Name	Description	Status
Echo Blueprint	A straightforward agent that simply echoes user inputs—ideal for testing or as a starter template.	Stable
Suggestion Blueprint	Blueprint providing suggestions and recommendations.	Stable
Database and Web Blueprint	Demonstrates MCP-based integration with an SQLite database and Brave Search, illustrating how to combine data retrieval with real-time web queries.	Stable
University Blueprint	Multi-agent system for university-related tasks.	Stable
Divine Ops Blueprint	Multi-agent system for handling system administration tasks using MCP tools (filesystem, SQLite, search, etc.).	Stable
Nebucha Shellzzar Blueprint	Example system administration blueprint.	Stable
Personal Assistant Blueprint	Combines real-time weather updates (Python function) with documentation search (`rag-docs`, MCP). Demonstrates mixed tooling.	Broken (uvx-based)
Flowise Blueprint	Integrates with Flowise for visual flow orchestration.	Broken (uvx-based, requires Flowise setup)

Further Documentation

For advanced usage, sequence diagrams, or in-depth tooling examples, see DEVELOPMENT.md. Additional expansions and best practices for agent orchestration, LLM provider swapping, and more can be found in that document.

License

Open Swarm is provided under the MIT License. Refer to the LICENSE file for full details.

Acknowledgements

This project is based on the OpenAI Swarm framework. We would like to acknowledge the original authors and contributors of this project for their work.
We also wish to credit django_chatbot for the Django chatbot view.

Third-Party Libraries

Marked.js (MIT License)
A fast, lightweight library for parsing Markdown into HTML.
Tabler Icons (MIT License)
A set of free, high-quality SVG icons for web projects, designed by Paweł Kuna.