Fast Mode Swarm Example

This page embeds the full source for examples/fast_mode_swarm.py.

"""Example: expose a code-defined swarm with fast mode and per-turn fast_tool_params."""

from __future__ import annotations

import uvicorn

from swarmforge.api import create_swarm_app
from swarmforge.env import get_env, get_env_int
from swarmforge.swarm import SwarmDefinition, SwarmNode, function_tool


async def lookup_order(order_id: str):
    """Fetch order status for a customer order."""
    return {"summary": f"Order {order_id} has shipped."}


FAST_MODE_SWARM = SwarmDefinition(
    id="ops",
    name="Ops Swarm",
    nodes=[
        SwarmNode(
            id="ops",
            node_key="ops",
            name="Ops",
            system_prompt="You are an operations specialist.",
            enabled_tools=[
                {
                    **function_tool(
                        name="lookup_order",
                        description="Fetch order status",
                        parameters={
                            "type": "object",
                            "properties": {"order_id": {"type": "string"}},
                            "required": ["order_id"],
                        },
                        handler=lookup_order,
                    ),
                    "fast_enabled": True,
                    "fast_default_args": {"order_id": "A-77"},
                }
            ],
            behavior_config={"fast_mode_enabled": True},
            is_entry_node=True,
        )
    ],
)


app = create_swarm_app(
    FAST_MODE_SWARM,
    title="Fast Mode API",
)


if __name__ == "__main__":
    uvicorn.run(
        app,
        host=get_env("SWARMFORGE_HOST", default="127.0.0.1") or "127.0.0.1",
        port=get_env_int("SWARMFORGE_PORT", default=8000),
    )

Run:

python examples/fast_mode_swarm.py

Create a session:

curl -X POST http://127.0.0.1:8000/sessions \
    -H 'Content-Type: application/json' \
    -d '{
        "session_id": "fast-1"
    }'

Send a message that triggers fast mode with default args:

curl -X POST http://127.0.0.1:8000/sessions/fast-1/messages \
    -H 'Content-Type: application/json' \
    -d '{
        "user_input": "Track my order"
    }'

Expected event sequence:

[
    { "event": "open", "data": { "currentAgent": "Ops" } },
    { "event": "fast_tool_use", "data": { "agentName": "Ops", "results": [{ "name": "lookup_order", "status": "ok" }] } },
    { "event": "done", "data": { "fullText": "Fast mode completed 1 tool(s) for Ops.\nResults:\n- lookup_order: Order A-77 has shipped.", "agentName": "Ops" } }
]

Override fast-tool arguments for the current turn by sending fast_tool_params in the state payload:

curl -X POST http://127.0.0.1:8000/sessions/fast-1/messages \
    -H 'Content-Type: application/json' \
    -d '{
        "user_input": "Track my order",
        "state": {
            "fast_tool_params": {
                "lookup_order": {"order_id": "A-99"}
            }
        }
    }'

The response now uses order_id: A-99 instead of the default A-77.

Fast mode also works with the generic transport (POST /v1/swarm/run) and the streaming endpoints (…/stream). On streams, the fast_tool_use event is emitted as a single SSE event before the final done.