Skip to content

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

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.ts
index 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.py
index 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.py
index 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.py
index 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.py
index 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 warnings
from datetime import datetime, timedelta
from typing import Any, TYPE_CHECKING, Self
@@ -988,17 +989,95 @@ class RedisStorage(StorageBase):
return msg
return 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 persistence
diff --git a/tests/storage_redis_test.py b/tests/storage_redis_test.py
index 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 no
messages."""
- 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."""