Build and run agents you can see, understand and trust.
Python agentchatbotlarge-language-modelsllmllm-agentmcpmulti-agentmulti-modalreact-agentrealtime-agentvoice-agentvoice-assistant
fix(app): use cursor-based pagination for list_messages (#2081)
DavdGao0745ea5a1ae0
diff --git a/examples/web_ui/frontend/src/api/session.ts b/examples/web_ui/frontend/src/api/session.tsindex 15dc5feec..4fdc16728 100644--- a/examples/web_ui/frontend/src/api/session.ts+++ b/examples/web_ui/frontend/src/api/session.ts@@ -13,6 +13,7 @@ import type {export interface MessagesResponse {messages: Msg[];is_running: boolean;+ has_more: boolean;}export const sessionApi = {@@ -41,11 +42,11 @@ export const sessionApi = {agent_id: agentId,}),- messages: (sessionId: string, agentId: string, offset = 0, limit = 50) =>+ messages: (sessionId: string, agentId: string, params?: { before?: string; limit?: number }) =>client.get<MessagesResponse>(`/sessions/${sessionId}/messages`, {agent_id: agentId,- offset: String(offset),- limit: String(limit),+ ...(params?.before != null && { before: params.before }),+ ...(params?.limit != null && { limit: String(params.limit) }),}),/**diff --git a/src/agentscope/app/_router/_schema/_session.py b/src/agentscope/app/_router/_schema/_session.pyindex 52a407856..caaa9baa4 100644--- a/src/agentscope/app/_router/_schema/_session.py+++ b/src/agentscope/app/_router/_schema/_session.py@@ -193,6 +193,13 @@ class ListMessagesResponse(BaseModel):is_running: bool = Field(description="Whether the session is currently running.",)+ has_more: bool = Field(+ description=(+ "Whether there are older messages before this page. "+ "When ``True``, pass a message ID from this response as "+ "the ``before`` parameter to load the previous page."+ ),+ )class SessionStatusResponse(BaseModel):diff --git a/src/agentscope/app/_router/_session.py b/src/agentscope/app/_router/_session.pyindex 35a29e50c..4524fb549 100644--- a/src/agentscope/app/_router/_session.py+++ b/src/agentscope/app/_router/_session.py@@ -513,25 +513,47 @@ async def update_session(async def list_messages(session_id: str,agent_id: str = Query(description="Agent the session belongs to."),- offset: int = Query(0, ge=0, description="Pagination offset."),+ before: str+ | None = Query(+ None,+ description=(+ "A message ID used as the pagination cursor. Omit to get "+ "the latest page. Provide a message ID from a previous "+ "response to load older messages."+ ),+ ),+ offset: int+ | None = Query(+ None,+ deprecated=True,+ description=(+ "**Deprecated.** Use ``before`` for cursor-based pagination. "+ "This parameter is always ignored."+ ),+ ),limit: int = Query(50, ge=1, le=200, description="Max messages."),user_id: str = Depends(get_current_user_id),storage: StorageBase = Depends(get_storage),message_bus: MessageBus = Depends(get_message_bus),) -> ListMessagesResponse:- """Return persisted messages for a session.+ """Return persisted messages for a session with cursor-based+ pagination.Args:session_id: The session to query.agent_id: Agent the session belongs to.- offset: Pagination offset.+ before: A message ID used as the pagination cursor. Omit for+ the latest page; provide a message ID from a previous+ response to load older messages.+ offset: **Deprecated.** Numeric offset, always ignored. Still+ accepted for backward compatibility.limit: Maximum number of messages to return.user_id: Injected authenticated user ID.storage: Injected storage backend.message_bus: Injected message bus.Returns:- Messages and running status.+ Messages, running status, and whether more pages exist."""existing = await storage.get_session(user_id, agent_id, session_id)if existing is None:@@ -540,17 +562,24 @@ async def list_messages(detail=f"Session '{session_id}' not found.",)- messages = await storage.list_messages(+ # Forward deprecated offset via kwargs so storage can warn.+ extra: dict = {}+ if offset is not None:+ extra["offset"] = offset++ messages, has_more = await storage.list_messages(user_id,session_id,- offset=offset,limit=limit,+ before=before,+ **extra,)return ListMessagesResponse(messages=messages,is_running=await message_bus.is_locked(MessageBusKeys.session_lock(session_id),),+ has_more=has_more,)diff --git a/src/agentscope/app/storage/_base.py b/src/agentscope/app/storage/_base.pyindex 6c5b944aa..63e7fa433 100644--- a/src/agentscope/app/storage/_base.py+++ b/src/agentscope/app/storage/_base.py@@ -439,19 +439,29 @@ class StorageBase(ABC):self,user_id: str,session_id: str,- offset: int = 0,limit: int = 50,- ) -> list[Msg]:- """Return messages for a session with pagination.+ before: str | None = None,+ **kwargs: Any,+ ) -> tuple[list[Msg], bool]:+ """Return the most recent messages for a session with+ cursor-based pagination.Args:user_id (`str`): The owner user id.session_id (`str`): The session id.- offset (`int`): Starting index (0-based). Defaults to 0.- limit (`int`): Maximum number of messages to return.-- Returns:- `list[Msg]`: Messages in chronological order.+ limit (`int`, optional): Maximum number of messages to+ return. Defaults to 50.+ before (`str | None`, optional): A message ID used as the+ cursor. When provided, returns messages created before+ this message. Omit to get the latest page.+ **kwargs: Reserved for backward compatibility. Passing+ ``offset`` will emit a ``DeprecationWarning`` and be+ ignored.++ Returns:+ `tuple[list[Msg], bool]`: A tuple of (messages in+ chronological order, has_more). ``has_more`` is ``True``+ when older messages exist before the returned page."""# ------------------------------------------------------------------diff --git a/src/agentscope/app/storage/_redis_storage.py b/src/agentscope/app/storage/_redis_storage.pyindex 57e43bde3..a9cc45591 100644--- a/src/agentscope/app/storage/_redis_storage.py+++ b/src/agentscope/app/storage/_redis_storage.py@@ -2,6 +2,7 @@# pylint: disable=too-many-public-methods"""The Redis storage implementation."""+import warningsfrom datetime import datetime, timedeltafrom typing import Any, TYPE_CHECKING, Self@@ -988,17 +989,95 @@ class RedisStorage(StorageBase):return msgreturn None+ async def _find_message_index(+ self,+ key: str,+ message_id: str,+ chunk_size: int = 100,+ ) -> int | None:+ """Return the index of a message in the Redis list, or ``None``.++ Scans backwards from the tail (most recent) in chunks, since+ ``before`` cursors are typically near the end.++ Args:+ key (`str`): The Redis list key.+ message_id (`str`): The message ID to locate.+ chunk_size (`int`, optional): Number of entries fetched per+ round trip. Defaults to 100.++ Returns:+ `int | None`: Zero-based index, or ``None`` if not found.+ """+ end = await self._client.llen(key) - 1+ while end >= 0:+ start = max(end - chunk_size + 1, 0)+ raw_list = await self._client.lrange(key, start, end)+ for offset, raw in enumerate(reversed(raw_list)):+ if Msg.model_validate_json(raw).id == message_id:+ return end - offset+ end = start - 1+ return None+async def list_messages(self,user_id: str,session_id: str,- offset: int = 0,limit: int = 50,- ) -> list[Msg]:- """Return messages for a session with pagination."""+ before: str | None = None,+ **kwargs: Any,+ ) -> tuple[list[Msg], bool]:+ """Return the most recent messages with cursor-based pagination.++ Messages are returned in chronological order.++ Args:+ user_id (`str`): The owner user id.+ session_id (`str`): The session id.+ limit (`int`, optional): Maximum number of messages to+ return. Defaults to 50.+ before (`str | None`, optional): A message ID used as the+ cursor. When provided, returns messages created before+ this message. Omit to get the latest page.+ **kwargs: Reserved for backward compatibility. Passing+ ``offset`` will emit a ``DeprecationWarning`` and be+ ignored.++ Returns:+ `tuple[list[Msg], bool]`: A tuple of (messages in+ chronological order, has_more). ``has_more`` is ``True``+ when older messages exist before the returned page.+ """+ if "offset" in kwargs:+ warnings.warn(+ "The 'offset' parameter is deprecated and will be "+ "removed in a future version. Use 'before' for "+ "cursor-based pagination instead.",+ DeprecationWarning,+ stacklevel=2,+ )+key = self._message_key(user_id, session_id)- raw_list = await self._client.lrange(key, offset, offset + limit - 1)- return [Msg.model_validate_json(raw) for raw in raw_list]+ total = await self._client.llen(key)++ if total == 0:+ return [], False++ if before is None:+ end = total - 1+ else:+ idx = await self._find_message_index(key, before)+ if idx is None:+ return [], False+ end = idx - 1++ start = max(end - limit + 1, 0)+ if end < 0:+ return [], False++ raw_list = await self._client.lrange(key, start, end)+ has_more = start > 0+ return [Msg.model_validate_json(raw) for raw in raw_list], has_more# ------------------------------------------------------------------# Team persistencediff --git a/tests/storage_redis_test.py b/tests/storage_redis_test.pyindex fc748c312..f4fec20b5 100644--- a/tests/storage_redis_test.py+++ b/tests/storage_redis_test.py@@ -336,10 +336,11 @@ class TestMessage(IsolatedAsyncioTestCase):"""Upserting a new message appends it to the session list."""msg = UserMsg(name="alice", content="hello")await self.storage.upsert_message(self.user_id, self.session_id, msg)- messages = await self.storage.list_messages(+ messages, has_more = await self.storage.list_messages(self.user_id,self.session_id,)+ self.assertFalse(has_more)self.assertListEqual([m.model_dump() for m in messages],[msg.model_dump()],@@ -373,10 +374,11 @@ class TestMessage(IsolatedAsyncioTestCase):updated,)- messages = await self.storage.list_messages(+ messages, has_more = await self.storage.list_messages(self.user_id,self.session_id,)+ self.assertFalse(has_more)self.assertListEqual([m.model_dump() for m in messages],[updated.model_dump()],@@ -413,10 +415,11 @@ class TestMessage(IsolatedAsyncioTestCase):msg2 = UserMsg(name="alice", content="second")await self.storage.upsert_message(self.user_id, self.session_id, msg1)await self.storage.upsert_message(self.user_id, self.session_id, msg2)- messages = await self.storage.list_messages(+ messages, has_more = await self.storage.list_messages(self.user_id,self.session_id,)+ self.assertFalse(has_more)self.assertListEqual([m.model_dump() for m in messages],[msg1.model_dump(), msg2.model_dump()],@@ -449,14 +452,15 @@ class TestMessage(IsolatedAsyncioTestCase):async def test_list_messages_empty_session(self) -> None:"""list_messages returns an empty list for a session with nomessages."""- messages = await self.storage.list_messages(+ messages, has_more = await self.storage.list_messages(self.user_id,self.session_id,)+ self.assertFalse(has_more)self.assertListEqual(messages, [])- async def test_list_messages_pagination(self) -> None:- """list_messages respects offset and limit parameters."""+ async def test_list_messages_latest_page(self) -> None:+ """list_messages without cursor returns the most recent messages."""msgs = [UserMsg(name="alice", content=f"msg-{i}") for i in range(5)]for m in msgs:await self.storage.upsert_message(@@ -465,18 +469,100 @@ class TestMessage(IsolatedAsyncioTestCase):m,)- # Fetch the middle slice: offset=1, limit=3 → msgs[1], msgs[2], msgs[3]- page = await self.storage.list_messages(+ # Default: latest page with limit=3 → last 3 messages+ page, has_more = await self.storage.list_messages(self.user_id,self.session_id,- offset=1,limit=3,)+ self.assertTrue(has_more)self.assertListEqual([m.model_dump() for m in page],- [m.model_dump() for m in msgs[1:4]],+ [m.model_dump() for m in msgs[2:5]],)+ async def test_list_messages_cursor_pagination(self) -> None:+ """list_messages with before cursor returns older messages."""+ msgs = [UserMsg(name="alice", content=f"msg-{i}") for i in range(5)]+ for m in msgs:+ await self.storage.upsert_message(+ self.user_id,+ self.session_id,+ m,+ )++ # Use msgs[3].id as cursor → should get msgs[0], msgs[1], msgs[2]+ page, has_more = await self.storage.list_messages(+ self.user_id,+ self.session_id,+ limit=3,+ before=msgs[3].id,+ )+ self.assertFalse(has_more)+ self.assertListEqual(+ [m.model_dump() for m in page],+ [m.model_dump() for m in msgs[0:3]],+ )++ async def test_list_messages_has_more_flag(self) -> None:+ """has_more is True when older messages exist beyond the page."""+ msgs = [UserMsg(name="alice", content=f"msg-{i}") for i in range(10)]+ for m in msgs:+ await self.storage.upsert_message(+ self.user_id,+ self.session_id,+ m,+ )++ # Latest 5 of 10 → has_more should be True+ _, has_more = await self.storage.list_messages(+ self.user_id,+ self.session_id,+ limit=5,+ )+ self.assertTrue(has_more)++ # Cursor at msgs[5], limit=5 → msgs[0..4], has_more should be False+ _, has_more = await self.storage.list_messages(+ self.user_id,+ self.session_id,+ limit=5,+ before=msgs[5].id,+ )+ self.assertFalse(has_more)++ async def test_list_messages_invalid_cursor(self) -> None:+ """list_messages with nonexistent cursor returns empty result."""+ msg = UserMsg(name="alice", content="hello")+ await self.storage.upsert_message(self.user_id, self.session_id, msg)++ page, has_more = await self.storage.list_messages(+ self.user_id,+ self.session_id,+ before="nonexistent-id",+ )+ self.assertFalse(has_more)+ self.assertListEqual(page, [])++ async def test_find_message_index_across_chunks(self) -> None:+ """_find_message_index locates messages beyond the first chunk."""+ msgs = [UserMsg(name="alice", content=f"msg-{i}") for i in range(7)]+ for m in msgs:+ await self.storage.upsert_message(+ self.user_id,+ self.session_id,+ m,+ )+ key = self.storage._message_key(self.user_id, self.session_id)++ # chunk_size=2 forces the scan to walk several chunks.+ for i, m in enumerate(msgs):+ idx = await self.storage._find_message_index(key, m.id, 2)+ self.assertEqual(idx, i)++ idx = await self.storage._find_message_index(key, "nonexistent", 2)+ self.assertIsNone(idx)+async def test_list_messages_order_preserved(self) -> None:"""Messages are returned in the insertion order (chronological)."""msgs = [@@ -489,10 +575,11 @@ class TestMessage(IsolatedAsyncioTestCase):self.session_id,m,)- messages = await self.storage.list_messages(+ messages, has_more = await self.storage.list_messages(self.user_id,self.session_id,)+ self.assertFalse(has_more)self.assertListEqual([m.model_dump() for m in messages],[m.model_dump() for m in msgs],@@ -505,12 +592,28 @@ class TestMessage(IsolatedAsyncioTestCase):"session-A",UserMsg(name="alice", content="in A"),)- messages = await self.storage.list_messages(+ messages, has_more = await self.storage.list_messages(self.user_id,"session-B",)+ self.assertFalse(has_more)self.assertListEqual(messages, [])+ async def test_list_messages_offset_kwarg_warns(self) -> None:+ """Passing deprecated offset via kwargs emits DeprecationWarning."""+ msg = UserMsg(name="alice", content="hello")+ await self.storage.upsert_message(self.user_id, self.session_id, msg)++ with self.assertWarns(DeprecationWarning):+ messages, has_more = await self.storage.list_messages(+ self.user_id,+ self.session_id,+ offset=0,+ )+ # Should still return results (offset is ignored, latest page).+ self.assertFalse(has_more)+ self.assertEqual(len(messages), 1)+def make_schedule_record(user_id: str, agent_id: str) -> ScheduleRecord:"""Create a test ScheduleRecord."""