Examples

This guide explains where to find package-first examples and repository source examples. It does not replace the step-by-step guides for agents, swarms, API integration, or evaluation.

This guide is for developers deciding which example path to follow next. It assumes that you already installed SwarmForge or cloned the repository.

After reading this guide, you should be able to:

• choose between package docs and source examples
• find the right example for runtime, API, provider, or evaluation work
• run the repository examples from source

This page has two clean paths:

• package examples for teams integrating swarmforge into their own application
• repository examples for teams working from source, building demos, or wiring a custom UI such as React Flow

Package Examples

If you installed swarmforge from PyPI, start with these docs pages:

1. Create Your First Agent Smallest single-agent runtime with optional Python tools.
2. Create Your First Multi-Agent Swarm Two-agent routing, handoffs, and required variables.
3. Authoring Generated or UI-authored JSON into validated SwarmDefinition objects.
4. Orchestration Event flow, sessions, tool execution, and persistence hooks.
5. API FastAPI transport for stateless and session-backed endpoints.
6. Evaluation Snapshots, scenario seeds, feasibility checks, and artifact scoring.

Before running provider-backed examples, set MODEL_PROVIDER, LLM_MODEL, and the matching provider credentials described in Providers.

Repository Examples

If you are working from the repository, the main source examples live under examples/.

Core Runtime Flow

• examples/single_agent_swarm.py Smallest local runtime example.
• examples/build_support_swarm.py Build a swarm from generated JSON and inspect the resulting artifacts.
• examples/run_support_swarm.py Run a multi-agent support flow with routing and variable resolution.
• examples/evaluate_support_swarm.py Generate evaluation scenarios and score recorded artifacts.

Provider and Transport

• examples/fastapi_swarm.py Define a swarm in Python code and expose it through your own typed FastAPI routes.
• examples/fastapi_tools_swarm.py Bind a code-defined swarm to FastAPI with shared runtime tools and external state.
• examples/openrouter_conversation.py Real provider-backed conversation example.
• examples/fastapi_server.py Generic JSON transport using create_fastapi_app(...).
• examples/runtime_tool_registry.py Shared runtime tool registry example.

Run From Source

These scripts are source examples. They are not installed as console commands when you pip install swarmforge.

Clone the repository and use an editable install:

git clone https://github.com/Rvey/swarm-forge.git
cd swarm-forge
pip install -e '.[dev,api]'
cp .env.example .env

Then choose the path you want:

python examples/single_agent_swarm.py
python examples/fastapi_swarm.py
python examples/openrouter_conversation.py
python examples/fastapi_server.py

Provider-backed examples read the root .env automatically. Pure local examples do not require provider credentials.

Suggested Source Walkthrough

If you want one clean source walkthrough, use this order:

1. examples/single_agent_swarm.py
2. examples/build_support_swarm.py
3. examples/run_support_swarm.py
4. examples/evaluate_support_swarm.py
5. examples/fastapi_swarm.py
6. examples/fastapi_server.py

Demo UI

The demo-ui/ folder is the React presentation layer for examples/fastapi_swarm.py.

Use it when you want to:

• present a code-defined multi-agent swarm from a browser
• inspect runtime events and checkpoints
• create sessions and send messages against the typed FastAPI routes
• show how a React app can sit on top of a Python-defined swarm backend

The Python example owns the multi-agent setup. The React app reads that setup from /swarm and communicates through /sessions and /sessions/{session_id}/messages.

The inspector now reads /sessions/{session_id}/runtime for per-node history and scratchpad state instead of relying on the session payload alone.

Run the pair together:

python examples/fastapi_swarm.py
npm -C demo-ui run dev

It reads the root .env for defaults such as:

• MODEL_PROVIDER optional, defaults the selected provider in the UI
• LLM_MODEL optional, defaults the selected model in the UI
• SWARMFORGE_HOST optional, defaults the API host to 127.0.0.1
• SWARMFORGE_PORT optional, defaults the API port to 8000

The demo UI does not use provider API keys directly.