{"slug": "how-flisk-routes-agent-traffic-a-sequence-diagram-of-one-turn", "title": "How Flisk Routes Agent Traffic: A Sequence Diagram of One Turn", "summary": "A developer documented how Flisk routes a single agent turn: a client POSTs to a Traefik gateway with an x-session-id header, the gateway routes to the agent service, which loads a per-session checkpoint from a named Docker volume, calls the user-supplied runTurn model code, and commits updated state atomically before replying. Because the volume outlives `flisk down`, restarted agents resume the same conversation, and a SIGTERM drain lets in-flight turns finish and checkpoint first, though a hard crash loses the turn in progress and requires a client retry with the same session ID.", "body_md": "The earlier articles covered the agent, the MCP resource, and the control plane. This one follows a single turn: one request from a client to an agent, through the gateway, the checkpoint store, and back.\n\nThe sequence follows the Flisk agent docs. The model call is a placeholder, since your `runTurn` decides what it looks like.\n\n```\nsequenceDiagram\n    autonumber\n    actor User as Client\n    participant GW as Traefik gateway\n    participant Agent as Agent service\n    participant Store as Checkpoint volume\n    participant Model as Model provider (your code)\n\n    User->>GW: POST /api/bot/turn with x-session-id\n    GW->>Agent: route by session header\n    Agent->>Store: load checkpoint for the session\n    alt no checkpoint yet\n        Store-->>Agent: empty state\n    else checkpoint exists\n        Store-->>Agent: prior messages\n    end\n    Agent->>Agent: append the user's input\n    Agent->>Model: runTurn(checkpoint, input)\n    Model-->>Agent: reply and updated state\n    Agent->>Store: commit the checkpoint atomically\n    Store-->>Agent: committed\n    Agent-->>GW: reply\n    GW-->>User: reply\n\n    Note over Agent,Store: On SIGTERM an in-flight turn finishes and checkpoints first\n    Note over Store: The named volume survives flisk down\n```\n\nThe session state sits in a checkpoint store, a file per session on a named Docker volume. The turn reads it first and writes it last. The write is atomic, so a crash partway through does not leave a half-saved conversation.\n\nBecause the volume outlives `flisk down`, a restarted agent loads the same state the next turn needs. The docs also say an explicit volume removal is the only way to lose it, which is a deliberate safeguard.\n\nThe gateway uses the `x-session-id` header to choose the session. Two conversations never share a checkpoint, even when they hit the same agent service. The header is also the one thing a client must get right: a missing or changed session ID starts a new conversation.\n\nIf the agent restarts between turns, the next turn loads the checkpoint and carries on. If it restarts during a turn, the drain on SIGTERM lets the in-flight turn finish and checkpoint first. The docs say live-update reloads use the same path.\n\nA crash rather than a clean stop skips the drain. The atomic commit then protects the last saved state, and the turn in progress is lost. Plan for that in your client: retry the request with the same session ID, and check whether the turn was saved.\n\nSend two turns with one session ID, restart the stack, and send a third turn. The third reply should reflect the first two. Then send a turn with a new session ID and confirm it starts fresh. Those two checks cover the parts that break quietly.\n\nOne turn goes through the gateway, which routes by session. The agent loads the checkpoint, calls your model code, commits the new state atomically, and replies. The state survives a restart because it lives on a volume, and a clean stop drains the turn in progress. Test the two-turn, restart, third-turn path before you depend on it.", "url": "https://wpnews.pro/news/how-flisk-routes-agent-traffic-a-sequence-diagram-of-one-turn", "canonical_source": "https://dev.to/flisk/how-flisk-routes-agent-traffic-a-sequence-diagram-of-one-turn-5a4g", "published_at": "2026-10-24 11:07:34+00:00", "updated_at": "2026-10-24 11:13:41.408688+00:00", "lang": "en", "topics": ["ai-agents", "agent-protocols", "ai-infrastructure", "developer-tools"], "entities": ["Flisk", "Traefik", "Docker"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/how-flisk-routes-agent-traffic-a-sequence-diagram-of-one-turn", "markdown": "https://wpnews.pro/news/how-flisk-routes-agent-traffic-a-sequence-diagram-of-one-turn.md", "text": "https://wpnews.pro/news/how-flisk-routes-agent-traffic-a-sequence-diagram-of-one-turn.txt", "jsonld": "https://wpnews.pro/news/how-flisk-routes-agent-traffic-a-sequence-diagram-of-one-turn.jsonld"}}