Build and run agents you can see, understand and trust.
Python agentchatbotlarge-language-modelsllmllm-agentmcpmulti-agentmulti-modalreact-agentrealtime-agentvoice-agentvoice-assistant
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.pyindex 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 thespecified `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 usedinstead 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_idself.user_id = user_id+ self.key_prefix = key_prefix or ""+ self.key_ttl = key_ttlself._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 listawait self._client.delete(mark_key)+ # Refresh TTLs+ await self._refresh_session_ttl()+return total_removedasync 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 sizeasync 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_countdiff --git a/src/agentscope/session/__init__.py b/src/agentscope/session/__init__.pyindex 3937b9e9f..c0ac730c1 100644--- a/src/agentscope/session/__init__.py+++ b/src/agentscope/session/__init__.py@@ -3,8 +3,10 @@from ._session_base import SessionBasefrom ._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.pyindex 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`, raisesan 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.pynew file mode 100644index 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.pyindex 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.pyindex 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 asynciofrom unittest.async_case import IsolatedAsyncioTestCasefrom 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.pyindex 2f58104d1..0730c5cb5 100644--- a/tests/session_test.py+++ b/tests/session_test.py@@ -9,7 +9,7 @@ from agentscope.formatter import DashScopeChatFormatterfrom agentscope.memory import InMemoryMemoryfrom agentscope.message import Msgfrom agentscope.model import DashScopeChatModel-from agentscope.session import JSONSession+from agentscope.session import JSONSession, RedisSessionfrom 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()