swarmforge 3.0.0

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

SwarmForge

SwarmForge is a Python SDK for authoring, building, running, and evaluating multi-agent systems. You define the swarm graph, provide the model-turn callback, and keep sessions, handoffs, tools, checkpoints, and evaluation artifacts under your control.

• SDK primitives for authoring and building graph-based multi-agent systems
• Explicit runtime orchestration with sessions, handoffs, and tool execution
• OpenRouter, Gemini, and other OpenAI-compatible provider support
• FastAPI transport for stateless and session-backed HTTP flows
• Evaluation helpers for graph snapshots, scenario seeds, and artifact scoring

Install

Python 3.11+ is required.

pip install swarmforge

The docs in this repository track the current main branch. If your installed PyPI package is older than the docs and a symbol is missing, install from a matching Git tag or upgrade to a newer release before using the examples below.

If you want the FastAPI transport too:

pip install "swarmforge[api]"

Provider-backed examples, the demo UI, and local API runs load a nearby .env automatically. Copy .env.example to .env, then set MODEL_PROVIDER, LLM_MODEL, and the matching API key before using any runnable example:

cp .env.example .env

Quick Start

The shortest path is a single-node swarm with a real 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.",
        store=store,
        turn_runner=turn_runner,
    ):
        print(json.dumps(event, indent=2))


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

The final done event contains the real model output, so the wording varies by provider and model. When you are ready to add routing, continue with the multi-agent flow in the docs.

Passing External Variables

When you want to pass facts from your application into the swarm, the default path is direct variable injection.

Code-defined runtime:

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

API runtime:

{
  "user_input": "Help with this charge.",
  "variables": {
    "account_id": "ACME-991",
    "priority": "high"
  }
}

Those values are available inside tool handlers and dynamic prompts through visible_global_variables.

Package Surfaces

• swarmforge.swarm Runtime models, session state, orchestration, tool execution, and stores.
• swarmforge.authoring Prompt templates, payload validation, and graph compilation helpers.
• swarmforge.evaluation Graph snapshots, scenario generation, feasibility checks, and artifact scoring.
• swarmforge.api FastAPI application factory built on the same runtime primitives.

Providers

SwarmForge ships with an OpenAI-compatible provider wrapper. OpenRouter is the default path, and Gemini is built in as an alternative mode.

Start from the repository .env.example and explicitly set both the provider and the model you want to use.

OpenRouter .env:

MODEL_PROVIDER=openrouter
LLM_MODEL=openrouter/auto
OPENROUTER_API_KEY=sk-or-...
OPENROUTER_SITE_URL=https://your-app.example
OPENROUTER_APP_NAME="Your App Name"

Gemini .env:

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

Minimal client setup:

from swarmforge.evaluation.provider import ModelConfig, OpenAIClientWrapper

client = OpenAIClientWrapper(ModelConfig())

ModelConfig() reads MODEL_PROVIDER, LLM_MODEL, and the matching API key from .env or the shell environment.

FastAPI Transport

You can expose the runtime over HTTP without changing your swarm definitions:

pip install "swarmforge[api]"
uvicorn swarmforge.api.fastapi:create_fastapi_app --factory --reload

That app exposes both stateless run endpoints and session-backed endpoints with SSE streaming.

Documentation

• Getting Started
• Create Your First Agent
• Create Your First Multi-Agent Swarm
• Authoring
• Orchestration
• Providers
• API
• Evaluation
• Examples

Source Examples

The repository includes end-to-end example scripts under examples/. Those scripts are useful when you want runnable reference flows for authoring, orchestration, evaluation, provider integration, or FastAPI transport. Provider-backed examples and the local FastAPI example read from .env.example-style settings.

The demo UI under demo-ui/ reads the same root .env for its default API base, provider, and model. Its Vite scripts create .env from .env.example automatically when the file is missing.

Contributing

Core modification, docs development, demo UI work, and PyPI release steps are documented in CONTRIBUTING.md.