Getting Started

This guide explains how to install SwarmForge, configure a provider, and run the smallest useful swarm. It does not explain multi-agent routing, FastAPI integration details, or evaluation workflows in depth.

This guide is for Python developers who want a quick package-first path to a working runtime example. It assumes that you can install packages, set environment variables, and run a short Python script.

After reading this guide, you should be able to:

• install swarmforge
• configure a provider-backed model
• run a single-node swarm with process_swarm_stream(...)
• identify the core package modules

SwarmForge installs as a Python package and exposes four primary entry points:

• swarmforge.authoring for graph generation and validation
• swarmforge.swarm for runtime execution and session state
• swarmforge.evaluation for graph inspection and artifact scoring
• swarmforge.api for FastAPI transport

Install

Python 3.11+ is required.

Install the base package:

pip install swarmforge

These docs track the repository main branch. If your installed PyPI package lags behind the examples here and an import is missing, install from a matching Git tag or upgrade to a newer release before continuing.

If you need the HTTP API too:

pip install "swarmforge[api]"

If you are modifying the package from source instead of consuming it, use the contributor workflow in the repository rather than the package install path.

Provider-backed usage and the repository example scripts load a nearby .env automatically. For runnable examples, set these env vars explicitly:

• MODEL_PROVIDER
• LLM_MODEL
• the matching API key for that provider: OPENROUTER_API_KEY, GEMINI_API_KEY, GOOGLE_API_KEY, or OPENAI_API_KEY

If you use OpenRouter, you can also set:

• OPENROUTER_SITE_URL
• OPENROUTER_APP_NAME

The full service-by-service env reference is in Providers.

Minimal Runtime Example

This is the smallest useful swarm: one agent, one session, and one 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 now contains a real hosted model response, so the exact text depends on the provider and model you selected in .env.

Package Modules

swarmforge/
  authoring/     Prompt templates + graph validators/builders
  evaluation/    Graph snapshots + scenario generation + scoring
  swarm/         Runtime models, tools, stores, and orchestrator
  api/           FastAPI application factory

Core Runtime Objects

SwarmDefinition

The graph model: nodes, edges, variables, and a graph version.

SwarmSession

Mutable runtime state for one conversation, including the current node, global variables, scoped state, histories, and agent context.

SessionStore

Persistence interface for sessions and checkpoints. InMemorySessionStore is the default implementation.

process_swarm_stream(...)

The async orchestration entry point. It consumes a session, a user input, and a model-driving callback, then emits runtime events.

Minimal Import Surface

from swarmforge.authoring import build_swarm_definition
from swarmforge.swarm import InMemorySessionStore, SwarmSession, process_swarm_stream
from swarmforge.evaluation import build_graph_snapshot

Next Documentation Targets

• Read Create Your First Agent if you want the shortest path to a working single-agent runtime with tools.
• Read Create Your First Multi-Agent Swarm if you want to add handoffs and required-variable routing.
• Read Authoring if your graph is generated or JSON-authored.
• Read Orchestration if you need to run multi-agent turns.
• Read Providers if you need hosted model access.
• Read API if you want HTTP transport.
• Read Evaluation if you need graph inspection or scoring.