Overview

Recommended: use DistributedStore for one-line setup — it covers AgentStateStore, BaseStore, SandboxSnapshotSpec, and SandboxExecutionGuard together. Read on if you only need to configure AgentStateStore individually.

io.agentscope.core.state.AgentStateStore is the interface AgentScope uses to persist agent state — Memory, Workspace, Plan, and other components are serialized as State objects and stored via AgentStateStore, enabling restart recovery and cross-node sharing. State is addressed by (userId, sessionId):

sessionId — required, non-blank, identifies a session.
userId — optional. null means anonymous / single-tenant (CLI, tests, etc.).

AgentStateStore and the Thread journal

This page covers AgentStateStore. With journaling enabled, HarnessAgent recovers from its ThreadJournalStore; changing only stateStore does not move or share journal history. The main Thread also reads state written by AgentScope 2.0 and mirrors each committed checkpoint back to the 2.0 agent_state slot for rollback compatibility. Named Threads use independent state entries. A file-capable BaseStore does not necessarily provide the journal CAS and fencing contract. See Thread journals and recovery.

Available Implementations

Implementation	Module	When to use
`InMemoryAgentStateStore`	`agentscope-core`	Unit tests
`JsonFileAgentStateStore`	`agentscope-core`	Single-node dev (HarnessAgent default)
`RedisAgentStateStore`	`agentscope-extensions-redis`	Multi-replica production default
`JdbcAgentStateStore`	`agentscope-extensions-jdbc`	Existing database infrastructure
`OssAgentStateStore`	`agentscope-extensions-oss`	Alibaba Cloud ecosystem

Standalone Configuration

ReActAgent agent = ReActAgent.builder()
    .name("assistant")
    .model(model)
    .stateStore(stateStore)   // any AgentStateStore implementation
    .build();

For detailed usage and code examples, see each store’s documentation:

Integration

Channels

Distributed storage

AgentStateStore and the Thread journal

Available Implementations

Standalone Configuration