Skip to content

Build and run agents you can see, understand and trust.

feat(session): add redis based session in agentscope (#1140)

Weirui Kuangd9b51965f018
diff --git a/src/agentscope/memory/_working_memory/_redis_memory.py b/src/agentscope/memory/_working_memory/_redis_memory.py
index 9ec0b2a43..512ea4faf 100644
--- a/src/agentscope/memory/_working_memory/_redis_memory.py
+++ b/src/agentscope/memory/_working_memory/_redis_memory.py
@@ -23,17 +23,27 @@ class RedisMemory(MemoryBase):
`remove_messages` method will only remove messages that belong to the
specified `session_id` and `user_id`.
+ .. note:: All Redis keys used by this class will be prefixed by `prefix`
+ (if provided) to support multi-tenant / multi-app isolation.
+
"""
SESSION_KEY = "user_id:{user_id}:session:{session_id}:messages"
- """The Redis key pattern to store messages for a specific session."""
+ """Redis key pattern (without prefix) for storing message IDs (ordered) for
+ a specific session.
+ """
+
+ SESSION_PATTERN = "user_id:{user_id}:session:{session_id}:*"
+ """Redis key pattern (without prefix) for scanning all keys belong to
+ a specific user and session."""
MARK_KEY = "user_id:{user_id}:session:{session_id}:mark:{mark}"
- """The Redis key pattern to store message ids that belong to a specific
- mark."""
+ """Redis key pattern (without prefix) for storing message IDs that belong
+ to a specific mark.
+ """
MESSAGE_KEY = "user_id:{user_id}:session:{session_id}:msg:{msg_id}"
- """The Redis key pattern for storing message data."""
+ """Redis key pattern (without prefix) for storing message payload data."""
def __init__(
self,
@@ -44,6 +54,8 @@ class RedisMemory(MemoryBase):
db: int = 0,
password: str | None = None,
connection_pool: ConnectionPool | None = None,
+ key_prefix: str = "",
+ key_ttl: int | None = None,
**kwargs: Any,
) -> None:
"""Initialize the Redis based storage by connecting to the Redis
@@ -66,6 +78,16 @@ class RedisMemory(MemoryBase):
connection_pool (`ConnectionPool | None`, optional):
An optional Redis connection pool. If provided, it will be used
instead of creating a new connection.
+ key_prefix (`str`, default to `""`):
+ Optional Redis key prefix prepended to every key generated by
+ this storage. Useful for isolating keys across
+ apps/environments (e.g. `"prod"`, `"staging"`, `"myapp"`).
+ key_ttl (`int | None`, default to `None`):
+ The expired time in seconds for each key. If provided, the
+ expiration will be refreshed on every access (sliding TTL). If
+ `None`, the keys will not expire. **Note** the ttl will update
+ all session related keys, so it's not recommended to set for
+ large sessions.
**kwargs (`Any`):
Additional keyword arguments to pass to the Redis client.
"""
@@ -81,6 +103,8 @@ class RedisMemory(MemoryBase):
self.session_id = session_id
self.user_id = user_id
+ self.key_prefix = key_prefix or ""
+ self.key_ttl = key_ttl
self._client = redis.Redis(
host=host,
@@ -108,7 +132,19 @@ class RedisMemory(MemoryBase):
`str`:
The Redis key for storing messages in the current session.
"""
- return self.SESSION_KEY.format(
+ return self.key_prefix + self.SESSION_KEY.format(
+ user_id=self.user_id,
+ session_id=self.session_id,
+ )
+
+ def _get_session_pattern(self) -> str:
+ """Get the Redis key pattern for all keys in the current session.
+
+ Returns:
+ `str`:
+ The Redis key pattern for all keys in the current session.
+ """
+ return self.key_prefix + self.SESSION_PATTERN.format(
user_id=self.user_id,
session_id=self.session_id,
)
@@ -124,7 +160,7 @@ class RedisMemory(MemoryBase):
`str`:
The Redis key for storing message IDs with the given mark.
"""
- return self.MARK_KEY.format(
+ return self.key_prefix + self.MARK_KEY.format(
user_id=self.user_id,
session_id=self.session_id,
mark=mark,
@@ -137,7 +173,7 @@ class RedisMemory(MemoryBase):
`str`:
The Redis key pattern for all mark keys.
"""
- return self.MARK_KEY.format(
+ return self.key_prefix + self.MARK_KEY.format(
user_id=self.user_id,
session_id=self.session_id,
mark="*",
@@ -154,12 +190,48 @@ class RedisMemory(MemoryBase):
`str`:
The Redis key for storing the message data.
"""
- return self.MESSAGE_KEY.format(
+ return self.key_prefix + self.MESSAGE_KEY.format(
user_id=self.user_id,
session_id=self.session_id,
msg_id=msg_id,
)
+ async def _refresh_session_ttl(
+ self,
+ pipe: Any | None = None,
+ ) -> None:
+ """Refresh the TTL for the session keys (if `key_ttl` is set).
+
+ Args:
+ pipe (`Any | None`, optional):
+ An optional Redis pipeline to use. If `None`, a new pipeline
+ will be created and executed immediately. If provided, the
+ expired commands will be added to the pipeline without
+ executing it.
+ """
+ if self.key_ttl is None:
+ return
+
+ # Create a new pipeline if not provided
+ should_execute = pipe is None
+ if pipe is None:
+ pipe = self._client.pipeline()
+
+ cursor = 0
+ while True:
+ cursor, keys = await self._client.scan(
+ cursor,
+ match=self._get_session_pattern(),
+ count=100,
+ )
+ for key in keys:
+ await pipe.expire(key, self.key_ttl)
+ if cursor == 0:
+ break
+
+ if should_execute:
+ await pipe.execute()
+
async def get_memory(
self,
mark: str | None = None,
@@ -234,6 +306,9 @@ class RedisMemory(MemoryBase):
msg_dict = json.loads(msg_data)
messages.append(Msg.from_dict(msg_dict))
+ # Refresh TTLs
+ await self._refresh_session_ttl()
+
if prepend_summary and self._compressed_summary:
return [
Msg(
@@ -323,6 +398,9 @@ class RedisMemory(MemoryBase):
for mark in mark_list:
await pipe.rpush(self._get_mark_key(mark), m.id)
+ # Refresh TTLs
+ await self._refresh_session_ttl(pipe=pipe)
+
await pipe.execute()
async def delete(
@@ -368,6 +446,9 @@ class RedisMemory(MemoryBase):
for mark_key in mark_keys:
await pipe.lrem(mark_key, 0, msg_id)
+ # Refresh TTLs
+ await self._refresh_session_ttl(pipe=pipe)
+
results = await pipe.execute()
# Count actual deletions from lrem results (every 3rd result
@@ -420,6 +501,9 @@ class RedisMemory(MemoryBase):
# Delete the mark list
await self._client.delete(mark_key)
+ # Refresh TTLs
+ await self._refresh_session_ttl()
+
return total_removed
async def clear(self) -> None:
@@ -462,6 +546,7 @@ class RedisMemory(MemoryBase):
The number of messages in the storage.
"""
size = await self._client.llen(self._get_session_key())
+ await self._refresh_session_ttl()
return size
async def update_messages_mark(
@@ -557,6 +642,8 @@ class RedisMemory(MemoryBase):
updated_count += 1
+ await self._refresh_session_ttl(pipe=pipe)
+
await pipe.execute()
return updated_count
diff --git a/src/agentscope/session/__init__.py b/src/agentscope/session/__init__.py
index 3937b9e9f..c0ac730c1 100644
--- a/src/agentscope/session/__init__.py
+++ b/src/agentscope/session/__init__.py
@@ -3,8 +3,10 @@
from ._session_base import SessionBase
from ._json_session import JSONSession
+from ._redis_session import RedisSession
__all__ = [
"SessionBase",
"JSONSession",
+ "RedisSession",
]
diff --git a/src/agentscope/session/_json_session.py b/src/agentscope/session/_json_session.py
index 6d7f4e191..04dc0f628 100644
--- a/src/agentscope/session/_json_session.py
+++ b/src/agentscope/session/_json_session.py
@@ -13,46 +13,40 @@ class JSONSession(SessionBase):
def __init__(
self,
- session_id: str | None = None,
save_dir: str = "./",
) -> None:
"""Initialize the JSON session class.
Args:
- session_id (`str`):
- The session id, deprecated and move to the `save_session_state`
- and `load_session_state` methods to support different session
- ids.
save_dir (`str`, defaults to `"./"):
The directory to save the session state.
"""
self.save_dir = save_dir
- if session_id is not None:
- logger.warning(
- "The `session_id` argument in the JSONSession constructor is "
- "deprecated and will be removed in future versions. Please "
- "pass the `session_id` to the `save_session_state` and "
- "`load_session_state` methods instead.",
- )
-
- def _get_save_path(self, session_id: str) -> str:
+ def _get_save_path(self, session_id: str, user_id: str) -> str:
"""The path to save the session state.
Args:
session_id (`str`):
The session id.
+ user_id (`str`):
+ The user ID for the storage.
Returns:
`str`:
The path to save the session state.
"""
os.makedirs(self.save_dir, exist_ok=True)
- return os.path.join(self.save_dir, f"{session_id}.json")
+ if user_id:
+ file_path = f"{user_id}_{session_id}.json"
+ else:
+ file_path = f"{session_id}.json"
+ return os.path.join(self.save_dir, file_path)
async def save_session_state(
self,
session_id: str,
+ user_id: str = "",
**state_modules_mapping: StateModule,
) -> None:
"""Load the state dictionary from a JSON file.
@@ -60,6 +54,8 @@ class JSONSession(SessionBase):
Args:
session_id (`str`):
The session id.
+ user_id (`str`, default to `""`):
+ The user ID for the storage.
**state_modules_mapping (`dict[str, StateModule]`):
A dictionary mapping of state module names to their instances.
"""
@@ -68,7 +64,7 @@ class JSONSession(SessionBase):
for name, state_module in state_modules_mapping.items()
}
with open(
- self._get_save_path(session_id),
+ self._get_save_path(session_id, user_id=user_id),
"w",
encoding="utf-8",
errors="surrogatepass",
@@ -78,6 +74,7 @@ class JSONSession(SessionBase):
async def load_session_state(
self,
session_id: str,
+ user_id: str = "",
allow_not_exist: bool = True,
**state_modules_mapping: StateModule,
) -> None:
@@ -86,13 +83,15 @@ class JSONSession(SessionBase):
Args:
session_id (`str`):
The session id.
+ user_id (`str`, default to `""`):
+ The user ID for the storage.
allow_not_exist (`bool`, defaults to `True`):
Whether to allow the session to not exist. If `False`, raises
an error if the session does not exist.
state_modules_mapping (`list[StateModule]`):
The list of state modules to be loaded.
"""
- session_save_path = self._get_save_path(session_id)
+ session_save_path = self._get_save_path(session_id, user_id=user_id)
if os.path.exists(session_save_path):
with open(
session_save_path,
diff --git a/src/agentscope/session/_redis_session.py b/src/agentscope/session/_redis_session.py
new file mode 100644
index 000000000..5e61ab641
--- /dev/null
+++ b/src/agentscope/session/_redis_session.py
@@ -0,0 +1,209 @@
+# -*- coding: utf-8 -*-
+"""The Redis session class."""
+import json
+from typing import Any, TYPE_CHECKING
+
+from ._session_base import SessionBase
+from .._logging import logger
+from ..module import StateModule
+
+if TYPE_CHECKING:
+ from redis.asyncio import ConnectionPool, Redis
+else:
+ ConnectionPool = Any
+ Redis = Any
+
+
+class RedisSession(SessionBase):
+ """The Redis session class."""
+
+ SESSION_KEY = "user_id:{user_id}:session:{session_id}:state"
+ """Redis key pattern (without prefix) for storing sessions state for
+ a specific session.
+ """
+
+ def __init__(
+ self,
+ host: str = "localhost",
+ port: int = 6379,
+ db: int = 0,
+ password: str | None = None,
+ connection_pool: ConnectionPool | None = None,
+ key_ttl: int | None = None,
+ key_prefix: str = "",
+ **kwargs: Any,
+ ) -> None:
+ """Initialize the Redis session class by connecting to Redis.
+
+ Args:
+ host (`str`, defaults to `"localhost"`):
+ Redis server host.
+ port (`int`, defaults to `6379`):
+ Redis server port.
+ db (`int`, defaults to `0`):
+ Redis database index.
+ password (`str | None`, optional):
+ Redis password if required.
+ connection_pool (`ConnectionPool | None`, optional):
+ Optional Redis connection pool.
+ key_ttl (`int | None`, optional):
+ Expire time in seconds for each session state key. If provided,
+ the expiration will be refreshed on every save/load
+ (sliding TTL). If `None`, the session state will not expire.
+ key_prefix (`str`, default to `""`):
+ Optional Redis key prefix prepended to every key generated by
+ this storage. Useful for isolating keys across
+ apps/environments (e.g. `"prod:"`, `"staging:"`, `"myapp:"`).
+ **kwargs (`Any`):
+ Additional keyword arguments passed to redis client.
+ """
+ try:
+ import redis.asyncio as redis
+ except ImportError as e:
+ raise ImportError(
+ "The 'redis' package is required for RedisSession. "
+ "Please install it via 'pip install redis[async]'.",
+ ) from e
+
+ self.key_ttl = key_ttl
+ self.key_prefix = key_prefix or ""
+
+ self._client = redis.Redis(
+ host=host,
+ port=port,
+ db=db,
+ password=password,
+ connection_pool=connection_pool,
+ decode_responses=True,
+ **kwargs,
+ )
+
+ def get_client(self) -> Redis:
+ """Get the underlying Redis client.
+
+ Returns:
+ `Redis`:
+ The Redis client instance.
+ """
+ return self._client
+
+ def _get_session_key(
+ self,
+ session_id: str,
+ user_id: str,
+ ) -> str:
+ """Get the Redis key to store a given session state."""
+ return self.key_prefix + self.SESSION_KEY.format(
+ user_id=user_id,
+ session_id=session_id,
+ )
+
+ async def save_session_state(
+ self,
+ session_id: str,
+ user_id: str = "default_user",
+ **state_modules_mapping: StateModule,
+ ) -> None:
+ """Save the state dictionary to Redis.
+
+ Args:
+ session_id (`str`):
+ The session id.
+ user_id (`str`, default to `"default_user"`):
+ The user ID for the storage.
+ **state_modules_mapping (`dict[str, StateModule]`):
+ A dictionary mapping of state module names to their instances.
+ """
+ state_dicts = {
+ name: state_module.state_dict()
+ for name, state_module in state_modules_mapping.items()
+ }
+
+ key = self._get_session_key(session_id, user_id=user_id)
+ value = json.dumps(state_dicts, ensure_ascii=False)
+
+ await self._client.set(key, value, ex=self.key_ttl)
+
+ logger.info("Save session state to redis key %s successfully.", key)
+
+ async def load_session_state(
+ self,
+ session_id: str,
+ user_id: str = "default_user",
+ allow_not_exist: bool = True,
+ **state_modules_mapping: StateModule,
+ ) -> None:
+ """Load the state dictionary from Redis.
+
+ Args:
+ session_id (`str`):
+ The session id.
+ user_id (`str`, default to `"default_user"`):
+ The user ID for the storage.
+ allow_not_exist (`bool`, defaults to `True`):
+ Whether to allow the session to not exist.
+ **state_modules_mapping (`dict[str, StateModule]`):
+ The mapping of state modules to be loaded.
+ """
+ key = self._get_session_key(session_id, user_id=user_id)
+
+ # Use GETEX to get and refresh TTL in a single atomic operation
+ if self.key_ttl is not None:
+ data = await self._client.getex(key, ex=self.key_ttl)
+ else:
+ data = await self._client.get(key)
+
+ if data is None:
+ if allow_not_exist:
+ logger.info(
+ "Session key %s does not exist in Redis. Skip loading "
+ "session state.",
+ key,
+ )
+ return
+ raise ValueError(
+ f"Failed to load session state because redis key {key} "
+ "does not exist.",
+ )
+
+ if isinstance(data, (bytes, bytearray)):
+ data = data.decode("utf-8")
+
+ states = json.loads(data)
+
+ for name, state_module in state_modules_mapping.items():
+ if name in states:
+ state_module.load_state_dict(states[name])
+
+ logger.info("Load session state from redis key %s successfully.", key)
+
+ async def close(self) -> None:
+ """Close the Redis client connection."""
+ await self._client.close()
+
+ async def __aenter__(self) -> "RedisSession":
+ """Enter the async context manager.
+
+ Returns:
+ `RedisSession`:
+ The current `RedisSession` instance.
+ """
+ return self
+
+ async def __aexit__(
+ self,
+ exc_type: type[BaseException] | None,
+ exc_value: BaseException | None,
+ traceback: Any,
+ ) -> None:
+ """Exit the async context manager and close the connection.
+
+ Args:
+ exc_type (`type[BaseException] | None`):
+ The type of the exception.
+ exc_value (`BaseException | None`):
+ The exception instance.
+ traceback (`Any`):
+ The traceback.
+ """
+ await self.close()
diff --git a/src/agentscope/session/_session_base.py b/src/agentscope/session/_session_base.py
index f7834d5a3..703bab606 100644
--- a/src/agentscope/session/_session_base.py
+++ b/src/agentscope/session/_session_base.py
@@ -12,6 +12,7 @@ class SessionBase:
async def save_session_state(
self,
session_id: str,
+ user_id: str = "",
**state_modules_mapping: StateModule,
) -> None:
"""Save the session state
@@ -19,6 +20,8 @@ class SessionBase:
Args:
session_id (`str`):
The session id.
+ user_id (`str`, default to `""`):
+ The user ID for the storage.
**state_modules_mapping (`dict[str, StateModule]`):
A dictionary mapping of state module names to their instances.
"""
@@ -27,7 +30,19 @@ class SessionBase:
async def load_session_state(
self,
session_id: str,
+ user_id: str = "",
allow_not_exist: bool = True,
**state_modules_mapping: StateModule,
) -> None:
- """Load the session state"""
+ """Load the session state
+
+ Args:
+ session_id (`str`):
+ The session id.
+ user_id (`str`, default to `""`):
+ The user ID for the storage.
+ allow_not_exist (`bool`, defaults to `True`):
+ Whether to allow the session to not exist.
+ **state_modules_mapping (`dict[str, StateModule]`):
+ The mapping of state modules to be loaded.
+ """
diff --git a/tests/memory_test.py b/tests/memory_test.py
index a28d22e8d..473156982 100644
--- a/tests/memory_test.py
+++ b/tests/memory_test.py
@@ -1,5 +1,6 @@
# -*- coding: utf-8 -*-
"""The short-term memory tests."""
+import asyncio
from unittest.async_case import IsolatedAsyncioTestCase
from sqlalchemy.ext.asyncio import create_async_engine
@@ -568,3 +569,25 @@ class RedisMemoryTest(ShortTermMemoryTest):
await self._test_delete_nonexistent_msg()
await self._multi_tenant_tests()
await self._multi_session_tests()
+
+ async def test_ttl(self) -> None:
+ """Test the TTL functionality of the Redis memory."""
+ # Set a short TTL for testing
+ self.memory.key_ttl = 2 # 2 seconds
+
+ # Add messages and verify they exist
+ await self.memory.add(self.msgs[:5])
+ msgs = await self.memory.get_memory()
+ self.assertEqual(
+ len(msgs),
+ 5,
+ )
+
+ # Wait for TTL to expire
+ await asyncio.sleep(3)
+
+ msgs = await self.memory.get_memory()
+ self.assertEqual(
+ len(msgs),
+ 0,
+ )
diff --git a/tests/session_test.py b/tests/session_test.py
index 2f58104d1..0730c5cb5 100644
--- a/tests/session_test.py
+++ b/tests/session_test.py
@@ -9,7 +9,7 @@ from agentscope.formatter import DashScopeChatFormatter
from agentscope.memory import InMemoryMemory
from agentscope.message import Msg
from agentscope.model import DashScopeChatModel
-from agentscope.session import JSONSession
+from agentscope.session import JSONSession, RedisSession
from agentscope.tool import Toolkit
@@ -85,3 +85,62 @@ class SessionTest(IsolatedAsyncioTestCase):
session_file = "./user_1.json"
if os.path.exists(session_file):
os.remove(session_file)
+
+
+class RedisSessionTest(IsolatedAsyncioTestCase):
+ """Test cases for the redis session module (with fake redis)."""
+
+ async def asyncSetUp(self) -> None:
+ # Use fakeredis (async)
+ try:
+ import fakeredis.aioredis # type: ignore
+ except ImportError as e:
+ raise ImportError(
+ "fakeredis is required for this test. "
+ "Please install it via `pip install fakeredis`.",
+ ) from e
+
+ self._redis = fakeredis.aioredis.FakeRedis()
+ self.session = RedisSession(
+ connection_pool=self._redis.connection_pool,
+ )
+
+ async def test_redis_session_save_and_load(self) -> None:
+ """Test the RedisSession class."""
+ agent1 = ReActAgent(
+ name="Friday",
+ sys_prompt="A helpful assistant.",
+ model=DashScopeChatModel(api_key="xxx", model_name="qwen_max"),
+ formatter=DashScopeChatFormatter(),
+ toolkit=Toolkit(),
+ memory=InMemoryMemory(),
+ )
+ agent2 = MyAgent()
+
+ await agent2.memory.add(Msg("Alice", "Hi!", "user"))
+
+ # Save
+ await self.session.save_session_state(
+ session_id="user_1",
+ agent1=agent1,
+ agent2=agent2,
+ )
+
+ # Mutate local state to verify load really works
+ agent1.name = "Changed"
+ agent2.sys_prompt = "Changed prompt"
+
+ # Load back
+ await self.session.load_session_state(
+ session_id="user_1",
+ agent1=agent1,
+ agent2=agent2,
+ )
+
+ self.assertEqual(agent1.name, "Friday")
+ self.assertEqual(agent2.sys_prompt, "A helpful assistant.")
+
+ async def asyncTearDown(self) -> None:
+ # close clients
+ await self.session.close()
+ await self._redis.close()