Introducing Regina: Stateful AI Agent Orchestration for Platformatic Watt

We’re excited to share Regina, a production-ready agent orchestration layer built on Platformatic Watt.

Regina lets you go from single-agent demos to real systems you can run and scale confidently. You define agents in Markdown, start instances over HTTP, and get built-in lifecycle management, persistence, and recovery, all by running and managing agents in Watt as isolated worker threads.

Why Regina, why now

Most AI projects hit the same wall after the first demo:

• Prompts are not versioned in a clean, operational way.

• Sessions disappear on restart.

• Scaling introduces routing and state headaches.

• Tool-heavy workflows are hard to observe and control.

Regina solves these problems directly, so your team can focus on building your product and not re-inventing the wheel when it comes to complex orchestration and state management.

What you get on day one

Regina comes as three packages:

• @platformatic/regina: per-pod agent manager

• @platformatic/regina-agent: per-agent runtime

• @platformatic/regina-storage: pluggable backup adapters (fs, s3, redis)

With this stack, you’ll have:

• stateful agent instances with per-instance SQLite VFS (“Virtual File System”)

• suspend/resume lifecycle management with idle timeout control

• NDJSON streaming events for full run visibility

• steerable agentic loops via POST /instances/:id/steer

• storage-backed restore for resilient multi-pod operation

Markdown-native agent definitions

Regina uses Markdown with YAML frontmatter as the main source for each agent.

---
name: support-agent
description: Customer support assistant
model: anthropic/claude-sonnet-4-5
provider: vercel-gateway
tools:
 - ./tools/search-docs.ts
temperature: 0.3
maxSteps: 10
---
You are a helpful support agent.

This setup keeps prompt and runtime configuration together, so it’s easy to review in pull requests and update across teams.

Built for real runtime behaviour

Regina keeps management and execution separate:

• @platformatic/regina discovers definitions, spawns instances, and proxies instance APIs

• @platformatic/regina-agent runs each instance in isolation

• message history is persisted at /.session/messages.jsonl in each instance VFS

This design gives you reliable performance, even under heavy load:

• Idle suspension to free resources automatically

• Auto-resume on next request

• State continuity across restarts

• Rich streaming (text-delta, tool-call, tool-result, step-finish)

In practice, running your agents with Regina and Watt gives you agents that act like durable workflows backed by persistent state instead of ephemeral, one-off chat sessions.

Start simple and scale smoothly

Regina works great in single-pod mode with no Redis, no external storage, and minimal setup.

As your traffic grows, you can add Redis or Valkey for member and instance mapping, and add shared storage for state restore if needed. The API stays the same, so clients don’t need to change as your setup evolves.

Getting started

The Regina demo app is small on purpose, but it shows the full production pattern in a single repo:

• watt.json at the root defines a single entrypoint service for Regina

• services/regina/watt.json enables @platformatic/regina and points to the shared agents/ directory

• Each file in agents/ is a full agent definition (prompt + model + provider + tools)

• Custom tools sit alongside agents in agents/tools/*

Here’s how the demo app is set up.

Root watt.json:

{
 "$schema": "https://schemas.platformatic.dev/wattpm/3.50.0.json",
 "server": {
   "port": 3042
 },
 "management": true,
 "entrypoint": "regina",
 "services": [
   {
     "id": "regina",
     "path": "./services/regina",
     "management": {
       "operations": ["addApplications", "removeApplications", "getApplications", "getApplicationDetails", "inject"]
     }
   }
 ]
}

Service services/regina/watt.json:

{
 "$schema": "https://schemas.platformatic.dev/@platformatic/regina/0.1.0.json",
 "regina": {
   "agentsDir": "../../agents"
 }
}

Example agent definition (agents/assistant.md):

---
name: assistant
description: A general-purpose assistant with file and shell access
model: anthropic/claude-sonnet-4-5
provider: vercel-gateway
greeting: "Hi! I'm a general-purpose assistant. I can read and write files, run commands, and help with any task."
temperature: 0.3
maxSteps: 15
---
You are a helpful assistant. You can read, write, and edit files, run bash commands, and help with any task.

Here’s a typical flow in the demo:

1. Start Watt (wattpm start).

2. Create an instance from an agent definition (POST /agents/:defId/instances).

3. Chat with that instance (POST /instances/:instanceId/chat or /chat/stream).

4. Resume the same instance later with history already available.

This is important because it shows Regina’s core value from start to finish: agents are defined as code, run as managed instances, and keep their state across requests without extra orchestration work.

Storage options for state backup

For multi-pod setups, configure regina.storage so you can restore on another pod.

Filesystem (fs)

{
 "module": "@platformatic/regina",
 "regina": {
   "storage": {
     "type": "fs",
     "basePath": "/mnt/shared/regina-state"
   }
 }
}

Object storage (s3)

{
 "module": "@platformatic/regina",
 "regina": {
   "storage": {
     "type": "s3",
     "bucket": "regina-state",
     "prefix": "backups/",
     "endpoint": "https://s3.amazonaws.com"
   }
 }
}

Redis (redis)

{
 "module": "@platformatic/regina",
 "regina": {
   "redis": "redis://valkey:6379",
   "storage": {
     "type": "redis"
   }
 }
}

All adapters use the same interface (put, get, delete, list, close), so you can switch backends without changing how your clients work.

Get started

• Regina repository

• Regina package docs

• Agent runtime docs

• Storage adapters docs

Regina is built for teams shipping serious AI systems on Node.js. If you need agents that are reliable, observable, and stateful in production, Regina is ready for you.