SwarmForge

Appearance

SwarmForgePython SDK for Multi-Agent Systems

Author, build, run, and evaluate multi-agent systems with one Python SDK for graph authoring, runtime orchestration, FastAPI transport, and evaluation.

Get Started
First Agent
GitHub

Runtime SDK

Define swarms, run turns, manage sessions, execute tools, and inspect runtime events with `swarmforge.swarm`.

Authoring + Build

Validate generated JSON, normalize graph payloads, and compile them into runnable `SwarmDefinition` objects.

Provider Layer

Use OpenRouter by default, switch to Gemini, or point the same wrapper at another OpenAI-compatible backend.

Evaluation Package

Build graph snapshots, generate scenario seeds, classify feasibility, and score recorded artifacts.

FastAPI Transport

Expose the same orchestration runtime over HTTP with stateless and session-backed endpoints.

Source Examples

The repository includes companion scripts and a demo UI when you want end-to-end reference implementations.

SwarmForge v5 breaking changes

SwarmForge v5 removes implicit handoff routes. Specialists must declare return and cross-specialist edges explicitly. See Migrating to v5 before upgrading from v4.

SDK-First Docs ​

These docs explain how to install, configure, and use swarmforge as a package. They do not describe the maintainer workflow for developing SwarmForge itself; use CONTRIBUTING.md for repository development and release steps.

These docs are for application developers who want to build agents, swarms, FastAPI endpoints, or evaluation flows with SwarmForge. They assume that you are comfortable with Python and can set environment variables for a hosted model provider.

Before you run provider-backed examples, set MODEL_PROVIDER, LLM_MODEL, and the matching API key described in Providers.

After reading this docs set, you should be able to:

  • build a single-agent or multi-agent swarm
  • run the swarm directly in Python or through FastAPI
  • configure a provider-backed turn runner
  • evaluate runtime artifacts such as events and checkpoints

Current package version: 5.0.0.

Documentation Map ​

  • Getting Started Install from PyPI, configure a provider and model, and run the smallest possible swarm.
  • Create Your First Agent Build a single-node agent, attach Python tools, and run a complete provider-backed example.
  • Create Your First Multi-Agent Swarm Add handoffs, required variables, and inspect a provider-backed routing flow.
  • Authoring Editor skills, linked repo folders, skill wrappers, payload schema, validators, and graph compilation helpers.
  • Agent Builder Chat-style onboarding, serialized builder sessions, authoring transport routes, and streaming prompt generation.
  • OrchestrationSwarmSession, process_swarm_stream(...), event flow, tool execution, and persistence hooks.
  • ProvidersModelConfig, environment variables, wrapper behavior, and request customization.
  • APIcreate_fastapi_app(...), endpoints, SSE behavior, and storage injection.
  • Evaluation Snapshots, scenario seeds, linked repo sources, feasibility checks, and scoring helpers.
  • Examples Package usage paths plus companion source scripts in the repository.

Suggested Reading Order ​

  1. Start with Getting Started.
  2. Build a minimal runtime path with Create Your First Agent.
  3. Add routing with Create Your First Multi-Agent Swarm.
  4. Read Authoring and Agent Builder if your app needs generated prompts or builder UX.
  5. Read Orchestration.
  6. Add Providers or API based on your integration path.
  7. Use Evaluation and Examples when you want to validate or expand behavior.

Released as open source.

Copyright © SwarmForge contributors