Redis

​

Dependency

<dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope-extensions-redis</artifactId>
    <version>${agentscope.version}</version>
</dependency>

​

One-Line Setup

import io.agentscope.extensions.redis.RedisDistributedStore;

JedisPooled jedis = new JedisPooled("redis://localhost:6379");
DistributedStore store = RedisDistributedStore.fromJedis(jedis);

HarnessAgent agent = HarnessAgent.builder()
    .distributedStore(store)
    .filesystem(new RemoteFilesystemSpec()
            .isolationScope(IsolationScope.USER))
    .build();

DistributedStore store = RedisDistributedStore.fromJedis(jedis, "prod:");

import io.agentscope.extensions.redis.state.RedisAgentStateStore;

DistributedStore store = RedisDistributedStore.fromJedis(
    jedisCluster,
    "prod:",
    RedisAgentStateStore.KeyLayoutVersion.V1);

​

Components Provided

​

1. RedisAgentStateStore

import io.agentscope.extensions.redis.state.RedisAgentStateStore;

// Jedis
AgentStateStore store = RedisAgentStateStore.builder()
    .jedisClient(new JedisPooled("redis://localhost:6379"))
    .keyPrefix("myapp:session:")
    .build();

// Lettuce Cluster
AgentStateStore store = RedisAgentStateStore.builder()
    .lettuceClusterClient(RedisClusterClient.create(RedisURI.create("localhost", 7000)))
    .keyLayoutVersion(RedisAgentStateStore.KeyLayoutVersion.V1)
    .build();

// Redisson
Config config = new Config();
config.useSingleServer().setAddress("redis://localhost:6379");
AgentStateStore store = RedisAgentStateStore.builder()
    .redissonClient(Redisson.create(config))
    .build();

​

V0 and V1 key layouts

keyPrefix = agentscope:session:
userId = alice
sessionId = s1

• keyPrefix must not contain { or }.
• userId and sessionId must not contain {, }, or /.
• sessionId must not be null or blank.

​

Migrating from V0 to V1

1. Inventory and validate. Identify every application instance using the prefix and inventory the (userId, sessionId) pairs that must be retained. Resolve identifiers that violate the V1 restrictions before migration. Do not infer ambiguous identifiers containing / only by splitting V0 key names; use the application’s authoritative IDs.
2. Choose whether to retain old state. If agent state is disposable or already governed by a short TTL, stop writers, remove or expire the V0 keys, and start with V1. Otherwise continue with the copy procedure below.
3. Stop writes and back up Redis. Drain in-flight requests and prevent all instances from writing to the prefix. Take a backup or snapshot before changing keys. Copying live V0 keys without a write barrier can produce mismatched values, versions, and session indexes.
4. Copy every session one key at a time. For each V0 session, change only the session segment from userId/sessionId to {userId/sessionId}. Copy all existing keys: single-state values, version keys, lists, list hashes, and the _keys session index. Copy the session index last so a partially copied session is not reported as present.
5. Preserve type and TTL. A migration tool can use DUMP, PTTL, and RESTORE ... REPLACE for each individual key. Treat PTTL = -1 as a non-expiring destination (RESTORE TTL 0) and skip a key if PTTL = -2. Use a cluster-aware client so each source and destination command is routed to the correct node. Do not use RENAME or a multi-key copy/delete command across slots.
6. Verify before cutover. Compare the V0 and V1 values, Redis types, TTLs, version numbers, list contents, and _keys members for a representative sample and for total session counts. Run CLUSTER KEYSLOT for the V1 state, version, and index keys and confirm that the slot numbers are identical. Perform application smoke tests for load, save, compare-and-set, list, and delete on test sessions.
7. Switch all instances together. Configure every store using the prefix with KeyLayoutVersion.V1, deploy the instances as one coordinated cutover, and then resume traffic. Running V0 and V1 writers concurrently creates two independently changing copies of a session.
8. Keep V0 data during an observation window. Do not modify the retained V0 copy after the V1 cutover. If rollback is required before any V1 write, all instances can return to V0. After V1 writes begin, stop writes again and reverse-migrate the changed data before switching back; otherwise the V1 updates will be invisible. V0 also reintroduces the original Cluster CROSSSLOT limitation.
9. Remove V0 data selectively. After the observation window, delete only the old V0 keys, one key per command. Do not use prefix-wide cleanup because it also deletes V1 keys under the same prefix.

​

2. RedisStore (BaseStore)

import io.agentscope.extensions.redis.store.RedisStore;

BaseStore store = new RedisStore(jedis);
BaseStore store = new RedisStore(jedis, "myapp:store:");

​

3. RedisSnapshotSpec

import io.agentscope.extensions.redis.snapshot.RedisSnapshotSpec;

SandboxSnapshotSpec spec = new RedisSnapshotSpec(jedis, "myapp:snapshot:", 3600);

​

4. RedisSandboxExecutionGuard

import io.agentscope.extensions.redis.sandbox.RedisSandboxExecutionGuard;

SandboxExecutionGuard guard = RedisSandboxExecutionGuard.builder(jedis)
    .keyPrefix("myapp:guard:")
    .leaseTtl(Duration.ofMinutes(30))
    .retryInterval(Duration.ofMillis(500))
    .build();

​

When to Use