Fast Mode Response Templates Example

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

"""Example: fast mode with mode:fast response template parameters."""

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, order_success: str = None, order_not_success: str = None):
    """Fetch order status for a customer order.

    In normal mode the LLM fills order_success / order_not_success with
    context-aware messages (mode:fast params are auto-added to required).
    In fast mode those params are resolved from
    fast_default_args / fast_tool_params or left as None; the handler
    supplies fallback text and returns the chosen message as a string.
    """
    order_success = order_success or "Your order has been processed successfully!"
    order_not_success = order_not_success or "We encountered an issue processing your order."

    # Simulate an API call
    import random
    success = random.choice([True, False])

    return order_success if success else order_not_success


FAST_MODE_RESPONSE_TEMPLATES_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",
                                    "description": "The order ID",
                                },
                                "order_not_success": {
                                    "type": "string",
                                    "mode": "fast",
                                    "description": "A message to say to the user if the order was not accomplished successfully.",
                                },
                                "order_success": {
                                    "type": "string",
                                    "mode": "fast",
                                    "description": "A message to say to the user if the order was accomplished successfully.",
                                },
                            },
                            "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_RESPONSE_TEMPLATES_SWARM,
    title="Fast Mode Response Templates 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),
    )

How it works

Parameters with "mode": "fast" serve dual purpose:

• Normal mode: the LLM sees them in the tool definition and fills in context-appropriate message text based on the description field. These fields are automatically appended to the schema required list, so the model is forced to generate them. The tool handler receives those values and returns the one that matches the operation outcome.

• Fast mode: those params are excluded from state-inference (they won't be auto-matched from visible state keys), but can still be provided via fast_default_args or fast_tool_params. The tool handler uses its own fallback logic and returns a string. That string becomes the assistant message directly — no generic "Fast mode completed N tool(s)" wrapper.

Run:

python examples/fast_mode_response_templates.py

Create a session:

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

Send a message that triggers fast mode:

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

Expected event sequence (the success/failure message varies depending on the simulated API result):

[
    { "event": "open", "data": { "currentAgent": "Ops" } },
    { "event": "fast_tool_use", "data": { "agentName": "Ops", "results": [...] } },
    { "event": "done", "data": { "fullText": "Your order has been processed successfully!", "agentName": "Ops" } }
]

Override the response templates via fast_tool_params:

curl -X POST http://127.0.0.1:8000/sessions/fast-templates-1/messages \
    -H 'Content-Type: application/json' \
    -d '{
        "user_input": "Track my order",
        "state": {
            "fast_tool_params": {
                "lookup_order": {
                    "order_id": "B-42",
                    "order_success": "Custom: order B-42 is all set!",
                    "order_not_success": "Custom: sorry, order B-42 could not be found."
                }
            }
        }
    }'

This also works with the generic transport (POST /v1/swarm/run) and streaming endpoints (…/stream).

Tip: prefer mode: "fast" params in +/- pairs (for example, order_success and order_not_success) so the handler can select the right response branch based on tool outcome.