swarmforge 3.0.3

Python SDK for authoring, building, running, and evaluating multi-agent systems.

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.

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
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:

• build_support_swarm.py
• run_support_swarm.py
• evaluate_support_swarm.py
• fastapi_server.py
• fastapi_swarm.py

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.