SwarmForge

SwarmForge is a Python SDK for authoring, running, exposing, and evaluating single-agent and multi-agent systems. You define the swarm graph in Python, keep runtime state explicit, and reuse the same orchestration model in direct SDK flows, FastAPI services, and evaluation pipelines.

Why SwarmForge

Build graph-based agent systems with explicit nodes, handoffs, tools, and shared state.
Run swarms directly in Python with streamed runtime events and persisted checkpoints.
Expose the same runtime through FastAPI for stateless or session-backed HTTP flows.
Use OpenAI-compatible providers such as OpenRouter, Gemini, and OpenAI.
Score routing, tool usage, checkpoints, and final state with transport-agnostic evaluation helpers.

Choose an integration surface

Surface	Main entrypoints	Use when
SDK runtime	`SwarmDefinition`, `SwarmSession`, `process_swarm_stream(...)`	You want direct Python control over orchestration, state, and tool execution.
FastAPI transport	`create_fastapi_app(...)`, `create_swarm_app(...)`	You want HTTP endpoints on top of the same runtime model.
Evaluation	`build_graph_snapshot(...)`, `evaluate_scenario_artifacts(...)`	You want to score runtime behavior in SDK or FastAPI tests.

Installation

SwarmForge requires Python 3.11+.

Install the SDK:

pip install swarmforge

Install the FastAPI transport too:

pip install "swarmforge[api]"

The documentation in this repository tracks the current main branch. If you are using a released package from PyPI, prefer the docs that match that version or tag.

Upgrading from v4? SwarmForge v5 removes implicit handoff routes. See docs/migration-v5.md for breaking changes and migration steps.

Configure a model provider

Provider-backed examples and local API runs load a nearby .env automatically. Start from the repository example file:

cp .env.example .env

Set:

MODEL_PROVIDER
LLM_MODEL
the matching provider API key such as OPENROUTER_API_KEY, GEMINI_API_KEY, GOOGLE_API_KEY, or OPENAI_API_KEY
optional for OpenRouter: OPENROUTER_FALLBACK_MODELS (comma-separated model slugs)

Example .env values:

MODEL_PROVIDER=openrouter
LLM_MODEL=openrouter/auto
OPENROUTER_API_KEY=sk-or-...
OPENROUTER_FALLBACK_MODELS=openai/gpt-4o-mini,anthropic/claude-3.5-sonnet

MODEL_PROVIDER=gemini
LLM_MODEL=gemini-3-flash-preview
GEMINI_API_KEY=...

Quick start: run a swarm in Python

This example defines a single-node swarm and runs it with the default provider-backed turn runner.

import asyncio
import json

from swarmforge.env import require_env_vars
from swarmforge.evaluation.provider import ModelConfig
from swarmforge.swarm import (
    InMemorySessionStore,
    SwarmDefinition,
    SwarmNode,
    SwarmSession,
    build_turn_runner,
    process_swarm_stream,
)


swarm = SwarmDefinition(
    id="assistant",
    name="Assistant Swarm",
    nodes=[
        SwarmNode(
            id="assistant",
            node_key="assistant",
            name="Assistant",
            system_prompt="You are a concise assistant.",
            is_entry_node=True,
        )
    ],
)


async def main():
    require_env_vars("MODEL_PROVIDER", "LLM_MODEL")
    session = SwarmSession(id="session-1", swarm=swarm)
    store = InMemorySessionStore()
    turn_runner = build_turn_runner(ModelConfig())

    async for event in process_swarm_stream(
        session,
        "Give me a concise summary of SwarmForge.",
        store=store,
        turn_runner=turn_runner,
    ):
        print(json.dumps(event, indent=2))


if __name__ == "__main__":
    asyncio.run(main())

Use session state when you want to inject application facts into the runtime:

session = SwarmSession(
    id="session-1",
    swarm=swarm,
    global_variables={"account_id": "ACME-991", "priority": "high"},
)

Quick start: expose the runtime with FastAPI

SwarmForge supports two FastAPI shapes:

create_fastapi_app(...) when the client sends swarm JSON at request time
create_swarm_app(...) when your backend defines the swarm in Python once and exposes a fixed route surface

Installed-package server:

uvicorn swarmforge.api.fastapi:create_fastapi_app --factory --reload

Code-defined swarm server:

from swarmforge.api import create_swarm_app
from swarmforge.evaluation.provider import ModelConfig

app = create_swarm_app(swarm, default_model_config=ModelConfig())

Both FastAPI factories use the same runtime model as process_swarm_stream(...), including sessions, handoffs, tools, checkpoints, and state updates.

Quick start: score runtime behavior

SwarmForge evaluation helpers work on runtime artifacts, so the same scoring flow applies to SDK runs and FastAPI runs.

from swarmforge.evaluation import build_graph_snapshot, evaluate_scenario_artifacts

graph_snapshot = build_graph_snapshot(swarm)

result = evaluate_scenario_artifacts(
    graph_snapshot,
    scenario_seed,
    event_log=events,
    checkpoints=checkpoints,
)

print(result["overall_score"])

Use this flow when you want to score routing, state updates, tool usage, minimum turns, and agent coverage.

Documentation

Goal	Guide
Install and orient yourself	Getting Started
Build a first single-agent swarm	Create Your First Agent
Build a routed multi-agent swarm	Create Your First Multi-Agent Swarm
Compile and validate swarm definitions	Authoring
Build a conversational prompt-builder flow	Agent Builder
Understand orchestration, sessions, tools, and state	Orchestration
Configure hosted model providers	Providers
Add an HTTP layer with FastAPI	FastAPI
Evaluate SDK and FastAPI runs	Evaluation
Browse runnable examples	Examples

Examples

The repository includes runnable reference flows under examples/, including:

Project status

SwarmForge 3.0.0 is available on PyPI. The package is still classified as Alpha, so expect the API to keep improving as the runtime and transport layers evolve.

Contributing

See CONTRIBUTING.md for local development, docs work, demo UI, and release instructions.

License

Released under the MIT License.

Metadata

Release files for swarmforge 5.0.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for swarmforge 5.0.4
File	Size	Uploaded	Provenance
swarmforge-5.0.4.tar.gz	148.0 kB	Oct 25, 2026	With provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for swarmforge 5.0.4
File	Interpreter	ABI	Platform	Reset
swarmforge-5.0.4-py3-none-any.whl 125.9 kB Oct 25, 2026 With provenance	Python 3	none	any	Details

Total release size: 273.9 kB

Release files / swarmforge-5.0.4.tar.gz

Download URL	swarmforge-5.0.4.tar.gz
Size	148.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`f8e08f4efdc35e6734b5aa4adb643b2631beeb90e8efc6c7c17f70ad2f009a9a`
BLAKE2b-256 checksum How to use checksums	`aa417e836ae6e3645a0d77197adf66c8a775e30ead625546812eba829bfb91da`
Upload date	Oct 25, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.16`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/blitzgoai/swarm-forge
Publishing commit: github.com/blitzgoai/swarm-forge/tree/87bca334d77707dbe34eaf46114826332448e467

Workflow

Publishing configuration: github.com/blitzgoai/swarm-forge/blob/87bca334d77707dbe34eaf46114826332448e467/.github/workflows/release.yml
Publishing logs: github.com/blitzgoai/swarm-forge/actions/runs/40204211914/attempts/1

Artifact

Subject: swarmforge-5.0.4.tar.gz
SHA-256 checksum: f8e08f4efdc35e6734b5aa4adb643b2631beeb90e8efc6c7c17f70ad2f009a9a Verifying attestations

Release files / swarmforge-5.0.4-py3-none-any.whl

Download URL	swarmforge-5.0.4-py3-none-any.whl
Size	125.9 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`e0eff4e60deb5ccd2a916c5d3a8be905e908b3aefb94a5eaa644c9e18bf97678`
BLAKE2b-256 checksum How to use checksums	`db5be72d49ae63aac848ba9bde1ba7ad6657ee881a7c40f361a63c0dadec85bf`
Upload date	Oct 25, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.16`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/blitzgoai/swarm-forge
Publishing commit: github.com/blitzgoai/swarm-forge/tree/87bca334d77707dbe34eaf46114826332448e467

Workflow

Publishing configuration: github.com/blitzgoai/swarm-forge/blob/87bca334d77707dbe34eaf46114826332448e467/.github/workflows/release.yml
Publishing logs: github.com/blitzgoai/swarm-forge/actions/runs/40204211914/attempts/1

Artifact

Subject: swarmforge-5.0.4-py3-none-any.whl
SHA-256 checksum: e0eff4e60deb5ccd2a916c5d3a8be905e908b3aefb94a5eaa644c9e18bf97678 Verifying attestations

Security for swarmforge 5.0.4

Report project as malware

Provenance

Full provenance

All 2 files in this release have been uploaded with provenance metadata.

Attestation for swarmforge-5.0.4.tar.gz

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/blitzgoai/swarm-forge
Publishing commit: github.com/blitzgoai/swarm-forge/tree/87bca334d77707dbe34eaf46114826332448e467

Workflow

Publishing configuration: github.com/blitzgoai/swarm-forge/blob/87bca334d77707dbe34eaf46114826332448e467/.github/workflows/release.yml
Publishing logs: github.com/blitzgoai/swarm-forge/actions/runs/40204211914/attempts/1

Artifact

Subject: swarmforge-5.0.4.tar.gz
SHA-256 checksum: f8e08f4efdc35e6734b5aa4adb643b2631beeb90e8efc6c7c17f70ad2f009a9a Verifying attestations

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.