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, use the source example docs below. Each page includes the full script so you can copy, run, and adapt it without leaving the docs.

Core Runtime Flow

• Single agent swarm example Smallest local runtime example.
• Build support swarm example Build a swarm from generated JSON and inspect the resulting artifacts.
• Run support swarm example Run a multi-agent support flow with routing and variable resolution.
• Evaluate support swarm example Generate evaluation scenarios and score recorded artifacts.

Provider and Transport

• examples/agent_builder_flow.py Direct SDK example for AgentBuilderFlow onboarding plus generation.
• FastAPI authoring server example Minimal create_authoring_app(...) bootstrap for the conversational agent-builder transport and stream endpoint.
• FastAPI swarm example Define a swarm in Python code and expose it through your own typed FastAPI routes.
• FastAPI tools swarm example Bind a code-defined swarm to FastAPI with shared runtime tools and external state.
• Fast mode swarm example Run tools immediately without a model turn by using fast mode and per-turn fast_tool_params.
• Fast mode response templates example Pre-author response messages via mode:fast parameters that become the assistant text directly in fast mode.
• OpenRouter conversation example Real provider-backed conversation example with fallback model configuration.
• FastAPI server example Generic JSON transport using create_fastapi_app(...).
• Runtime tool registry example 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/agent_builder_flow.py
python examples/fastapi_authoring_server.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. Single agent swarm example
2. Build support swarm example
3. Run support swarm example
4. Evaluate support swarm example
5. FastAPI authoring server example
6. FastAPI swarm example
7. FastAPI server example

Demo UI

The demo UI is documented at Demo UI example and sits on top of FastAPI swarm example.

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.