vrsen/openswarm

This repo is a Python-first multi-agent system built on Agency Swarm, with a thin Node.js wrapper for distribution and a few JavaScript helpers for slide conversion. The main architecture is centered on a single orchestrator that receives a user request and delegates work to specialist agents.

The primary entrypoints are swarm.py for local development, server.py for an HTTP API runtime, and bin/openswarm as the packaged CLI entry. The README also shows an npm-installed launcher, so the repo supports both developer-run and end-user CLI distribution.

The orchestration boundary is explicit: orchestrator/orchestrator.py is the coordination layer and orchestrator/instructions.md defines its behavior. Its job is to route tasks, not solve them directly. This is the control plane that fans out requests to one or more specialist agents.

The specialist agents are separated into top-level modules, each with its own instructions and toolset: virtual_assistant, deep_research, data_analyst_agent, slides_agent, docs_agent, image_generation_agent, and video_generation_agent. Each agent is a distinct capability boundary, which makes the architecture strongly modular and easy to diagram as independent workers under one orchestrator.

A shared tool layer lives in shared_tools/ and provides cross-cutting operations such as file copying, searching tools, finding tools, executing tools, and managing connections. This is also where model availability and OpenAI client utilities are centralized, so model/provider logic is not duplicated in every agent.

Several agents have their own internal pipelines rather than being just prompt wrappers. The slides agent is the most complex: it includes PPTX/OOXML schema assets, HTML-to-PPTX scripts, rendering utilities, slide screenshots, template registry, and slide file utilities. That indicates a two-stage flow: generate or edit slide content in HTML/PPTX-oriented intermediate forms, then export and validate to final presentation artifacts.

The docs agent follows a similar document-processing pattern. It contains tools for creating, viewing, modifying, restoring, listing, and converting documents, plus a substantial tools/utils/ layer for HTML-to-DOCX transformation and validation. That suggests document generation is not purely textual; it includes structured document assembly and fidelity checks.

The media agents each encapsulate a specialized artifact pipeline. image_generation_agent includes create/edit/combine/background-removal tools plus image I/O helpers. video_generation_agent includes generation, trimming, audio/image/video edits, subtitles, and combine operations. These agents likely produce local media files as intermediate and final outputs rather than returning only text.

data_analyst_agent is built around structured-data analysis and an isolated IPython execution environment, as stated in the README. The presence of test CSV data and a separate tools package suggests a sandboxed compute boundary for analysis, plotting, and statistical work.

virtual_assistant is the most integration-heavy agent. Its tools cover email, calendar, Slack, filesystem operations, product search, scholar search, and skill listing. The README calls out Composio support, so this agent acts as the connector to external SaaS systems like Gmail, Slack, GitHub, and HubSpot when credentials are available.

The repo also has a clear artifact/workspace model: agents operate on files, documents, decks, images, and videos, with utilities for reading, writing, restoring, and converting those artifacts. That means the main data flow is usually prompt → orchestration → agent/tool execution → file-based deliverable, with some agents also calling external APIs for enrichment or generation.

patches/ is an important compatibility layer. It contains targeted fixes for upstream dependencies and runtime behavior, including PPTX-related patches and file/encoding fixes. In an architecture diagram, this sits beneath the application layer as a maintenance layer that adapts third-party libraries to OpenSwarm’s workflows.

Deployment is supported in multiple ways: local Python execution, Docker via Dockerfile and docker-compose.yml, and GitHub Actions for build/test automation. The repo is therefore not just an agent library; it is a distributed delivery system for running agent workflows in terminal, container, or API form.