Session Storage

Session storage lets a ShoppingAgent resume across process restarts. The agent snapshots its state every loop iteration; if you reconstruct it with the same sessionId, it hydrates from the stored snapshot and continues.

The `SessionStorage` interface

interface SessionStorage {
  save(id: string, state: SessionState): Promise<void>;
  load(id: string): Promise<SessionState | null>;
  list(): Promise<string[]>;
  delete(id: string): Promise<void>;
}

Shipped storages

Two implementations ship in-tree:

MemorySessionStorage — a Map-backed store. Great for development and tests; state is lost when the process exits.
FileSessionStorage — persists each session to a JSON file using an atomic temp-write-then-rename, so a crash mid-write can’t corrupt state.

import { ShoppingAgent, FileSessionStorage } from '@agorio/sdk';
 
const agent = new ShoppingAgent({
  llm,
  sessionStorage: new FileSessionStorage({ dir: './.agorio-sessions' }),
  sessionId: 'order-acme-001',
});

Redis storage

For production, the separate @agorio/session-redis package provides RedisSessionStorage — Redis-backed with TTL support and a customer secondary index. It’s a separate package so the core SDK carries no Redis dependency:

npm install @agorio/session-redis ioredis

Plugins and resume

Plugins participate in resume too. An EnterprisePlugin can implement getState?() to contribute to the snapshot and hydrate?(state) to restore from it — the approval-workflow plugin does exactly this so a pending approval survives a restart.

AgentChain Overview