# 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](https://docs.platformatic.dev/).

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.

```plaintext
---
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`:

```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`:

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

Example agent definition (`agents/assistant.md`):

```plaintext
---
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](http://regina.storage) so you can restore on another pod.

**Filesystem (**`fs`**)**

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

**Object storage (**`s3`**)**

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

**Redis (**`redis`**)**

```json
{
 "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](https://github.com/platformatic/regina)
    
*   [Regina package docs](https://github.com/platformatic/regina/tree/main/packages/regina)
    
*   [Agent runtime docs](https://github.com/platformatic/regina/tree/main/packages/regina-agent)
    
*   [Storage adapters docs](https://github.com/platformatic/regina/tree/main/packages/regina-storage)
    

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.