Flisk's Agent Resource: Durable Agents With Sessions You Can Restart

#ai #agents #flisk #devtools

An agent is a process that holds a conversation. Restart the process and the conversation can disappear, unless something saves it. Flisk's agent resource type is built for that case. It scaffolds an agent service with durable checkpoints, routes each conversation by session, and drains in-flight turns before shutdown.

This article covers the resource type. The series continues with tools, control, and workers.

Scaffold one

flisk resource bot --type agent --stack shop --yes
flisk up shop

The command creates a Bun HTTP service in services/shop/bot. Its service.json declares the app type and the agent settings:

{
  "appType": "agent",
  "stack": "shop",
  "port": 4001,
  "healthCheckPath": "/health",
  "agent": {
    "runtime": "custom",
    "durability": "files"
  }
}

The runtime: custom setting means the agent code is plain Bun or Node. It is vendor-neutral, so you can call a model provider or an agent framework from inside it.

What you get

Durable checkpoints. Session state is stored in a named Docker volume. Flisk's docs say it survives flisk down, container restarts, and hot reloads. Removing the volume is an explicit step, so an accidental down does not erase conversations.

Session routing. Requests carry an x-session-id header. Traefik routes by that header, which keeps concurrent conversations apart. Two users talking to the same agent do not share a checkpoint.

Graceful drain. On SIGTERM, an in-flight turn finishes and checkpoints before the process stops. Live-update reloads follow the same path, so a code change does not cut a reply in half.

Two health routes. /health confirms the process is alive, and it is the route the generated health check uses. /ready checks that the checkpoint store is accessible and writable. A caller that must not send a turn before the store is ready should check /ready first.

Where the logic goes

You write the turn logic in runTurn(checkpoint, input). Flisk loads the session checkpoint, appends the user's message, calls your function, commits the updated checkpoint atomically, and returns the reply. Your code decides what the model call looks like. Flisk decides how the state survives.

Try it

After flisk up shop, send a turn with a session header:

curl -s -X POST http://api.shop.localhost/api/bot/turn \
  -H 'content-type: application/json' -H 'x-session-id: session-123' \
  -d '{"input":"hello"}'

Send another turn with the same session ID, then restart the stack. The second turn should still see the first. The exact request body shape is in the agent docs, so check it before you rely on the input field name.

What it does not do

It does not pick a model for you, and it does not manage prompts or evaluation. Those belong to your agent code and to whichever framework you use.

It also does not make a state store free of cost. A checkpoint file grows with the conversation, so long sessions need a plan for trimming or archiving.

Summary

The agent resource gives a local agent durable state, session isolation, and clean shutdown, with a health route and a readiness route. You supply the turn logic. Flisk supplies the parts that break when an agent restarts.

DEV Community