State Overview
State management in AgentForge — state stores, checkpointing, and crash recovery.
Why State Matters
AgentForge checkpoints run state after every step. This enables:
- Crash recovery — resume runs from the last checkpoint
- Long-running tasks — runs that span process restarts
- Approval flows — pause a run, get human approval, resume
- Debugging — inspect state at any point in a run
StateStore Interface
interface StateStore {
save(state: RunState): Promise<void>;
load(runId: string): Promise<RunState | null>;
list(): Promise<RunSummary[]>;
delete(runId: string): Promise<void>;
}Available Stores
| Store | Persistence | Use Case |
|---|---|---|
InMemoryStateStore | Process lifetime | Development, testing |
RedisStateStore | Durable | Production |
Quick Start
import { defineAgent, InMemoryStateStore, RedisStateStore } from '@ahzan-agentforge/core';
// Development
const devAgent = defineAgent({
// ...
stateStore: new InMemoryStateStore(),
});
// Production
const prodAgent = defineAgent({
// ...
stateStore: new RedisStateStore({ url: 'redis://localhost:6379' }),
});RunState
The full state saved at each checkpoint:
interface RunState {
runId: string;
agentName: string;
status: RunStatus;
task: string;
context?: string;
messages: Message[];
stepCount: number;
steps: StepRecord[];
createdAt: number;
updatedAt: number;
completedAt?: number;
output?: string;
error?: RunError;
pendingApproval?: PendingApproval;
metadata?: Record<string, unknown>;
}Next Steps
- In-Memory Store — ephemeral state
- Redis Store — persistent state
- Checkpoint & Resume — recovery mechanics