Platform for stateful agents: AI with advanced memory that can learn and self-improve over time.
feat: query param parity for conversation messages (#8730)
jnjpng037c20ae1b1d
diff --git a/letta/server/rest_api/routers/v1/conversations.py b/letta/server/rest_api/routers/v1/conversations.pyindex c489f3982..58aad8292 100644--- a/letta/server/rest_api/routers/v1/conversations.py+++ b/letta/server/rest_api/routers/v1/conversations.py@@ -1,5 +1,5 @@from datetime import timedelta-from typing import Annotated, List, Optional+from typing import Annotated, List, Literal, Optionalfrom fastapi import APIRouter, Body, Depends, HTTPException, Queryfrom pydantic import Field@@ -96,19 +96,26 @@ async def list_conversation_messages(server: SyncServer = Depends(get_letta_server),headers: HeaderParams = Depends(get_headers),before: Optional[str] = Query(- None, description="Message ID cursor for pagination. Returns messages that come before this message ID in the conversation"+ None, description="Message ID cursor for pagination. Returns messages that come before this message ID in the specified sort order"),after: Optional[str] = Query(- None, description="Message ID cursor for pagination. Returns messages that come after this message ID in the conversation"+ None, description="Message ID cursor for pagination. Returns messages that come after this message ID in the specified sort order"),limit: Optional[int] = Query(100, description="Maximum number of messages to return"),+ order: Literal["asc", "desc"] = Query(+ "desc", description="Sort order for messages by creation time. 'asc' for oldest first, 'desc' for newest first"+ ),+ order_by: Literal["created_at"] = Query("created_at", description="Field to sort by"),+ group_id: Optional[str] = Query(None, description="Group ID to filter messages by."),+ include_err: Optional[bool] = Query(+ None, description="Whether to include error messages and error statuses. For debugging purposes only."+ ),):"""List all messages in a conversation.Returns LettaMessage objects (UserMessage, AssistantMessage, etc.) for all- messages in the conversation, ordered by position (oldest first),- with support for cursor-based pagination.+ messages in the conversation, with support for cursor-based pagination."""actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)return await conversation_manager.list_conversation_messages(@@ -117,6 +124,9 @@ async def list_conversation_messages(limit=limit,before=before,after=after,+ reverse=(order == "desc"),+ group_id=group_id,+ include_err=include_err,)diff --git a/letta/services/conversation_manager.py b/letta/services/conversation_manager.pyindex 62239fb46..efe7c5f3f 100644--- a/letta/services/conversation_manager.py+++ b/letta/services/conversation_manager.py@@ -334,13 +334,15 @@ class ConversationManager:limit: Optional[int] = 100,before: Optional[str] = None,after: Optional[str] = None,+ reverse: bool = False,+ group_id: Optional[str] = None,+ include_err: Optional[bool] = None,) -> List[LettaMessage]:"""List all messages in a conversation with pagination support.Unlike get_messages_for_conversation, this returns ALL messages(not just in_context) and supports cursor-based pagination.- Messages are always ordered by position (oldest first).Args:conversation_id: The conversation to list messages for@@ -348,6 +350,9 @@ class ConversationManager:limit: Maximum number of messages to returnbefore: Return messages before this message IDafter: Return messages after this message ID+ reverse: If True, return messages in descending order (newest first)+ group_id: Optional group ID to filter messages by+ include_err: Optional boolean to include error messages and error statusesReturns:List of LettaMessage objects@@ -367,6 +372,10 @@ class ConversationManager:))+ # Filter by group_id if provided+ if group_id:+ query = query.where(MessageModel.group_id == group_id)+# Handle cursor-based paginationif before:# Get the position of the cursor message@@ -390,8 +399,11 @@ class ConversationManager:if cursor_position is not None:query = query.where(ConversationMessageModel.position > cursor_position)- # Order by position (oldest first)- query = query.order_by(ConversationMessageModel.position.asc())+ # Order by position+ if reverse:+ query = query.order_by(ConversationMessageModel.position.desc())+ else:+ query = query.order_by(ConversationMessageModel.position.asc())# Apply limitif limit is not None:@@ -401,7 +413,9 @@ class ConversationManager:messages = [msg.to_pydantic() for msg in result.scalars().all()]# Convert to LettaMessages- return PydanticMessage.to_letta_messages_from_list(messages, reverse=False, text_is_assistant_message=True)+ return PydanticMessage.to_letta_messages_from_list(+ messages, reverse=reverse, include_err=include_err, text_is_assistant_message=True+ )# ==================== Isolated Blocks Methods ====================diff --git a/tests/integration_test_conversations_sdk.py b/tests/integration_test_conversations_sdk.pyindex 6284b705d..c62a53c2d 100644--- a/tests/integration_test_conversations_sdk.py+++ b/tests/integration_test_conversations_sdk.py@@ -396,3 +396,172 @@ class TestConversationsSDK:))assert len(messages) > 0, "Should be able to send message after concurrent requests complete"++ def test_list_conversation_messages_order_asc(self, client: Letta, agent):+ """Test listing messages in ascending order (oldest first)."""+ conversation = client.conversations.create(agent_id=agent.id)++ # Send messages to create history+ list(+ client.conversations.messages.create(+ conversation_id=conversation.id,+ messages=[{"role": "user", "content": "First message"}],+ )+ )+ list(+ client.conversations.messages.create(+ conversation_id=conversation.id,+ messages=[{"role": "user", "content": "Second message"}],+ )+ )++ # List messages in ascending order (oldest first)+ messages_asc = client.conversations.messages.list(+ conversation_id=conversation.id,+ order="asc",+ )++ # First message should be system message (oldest)+ assert messages_asc[0].message_type == "system_message"++ # Get user messages and verify order+ user_messages = [m for m in messages_asc if m.message_type == "user_message"]+ assert len(user_messages) >= 2+ # First user message should contain "First message"+ assert "First" in user_messages[0].content++ def test_list_conversation_messages_order_desc(self, client: Letta, agent):+ """Test listing messages in descending order (newest first)."""+ conversation = client.conversations.create(agent_id=agent.id)++ # Send messages to create history+ list(+ client.conversations.messages.create(+ conversation_id=conversation.id,+ messages=[{"role": "user", "content": "First message"}],+ )+ )+ list(+ client.conversations.messages.create(+ conversation_id=conversation.id,+ messages=[{"role": "user", "content": "Second message"}],+ )+ )++ # List messages in descending order (newest first) - this is the default+ messages_desc = client.conversations.messages.list(+ conversation_id=conversation.id,+ order="desc",+ )++ # Get user messages and verify order+ user_messages = [m for m in messages_desc if m.message_type == "user_message"]+ assert len(user_messages) >= 2+ # First user message in desc order should contain "Second message" (newest)+ assert "Second" in user_messages[0].content++ def test_list_conversation_messages_order_affects_pagination(self, client: Letta, agent):+ """Test that order parameter affects pagination correctly."""+ conversation = client.conversations.create(agent_id=agent.id)++ # Send multiple messages+ for i in range(3):+ list(+ client.conversations.messages.create(+ conversation_id=conversation.id,+ messages=[{"role": "user", "content": f"Message {i}"}],+ )+ )++ # Get all messages in descending order with limit+ messages_desc = client.conversations.messages.list(+ conversation_id=conversation.id,+ order="desc",+ limit=5,+ )++ # Get all messages in ascending order with limit+ messages_asc = client.conversations.messages.list(+ conversation_id=conversation.id,+ order="asc",+ limit=5,+ )++ # The first messages should be different based on order+ assert messages_desc[0].id != messages_asc[0].id++ def test_list_conversation_messages_with_before_cursor(self, client: Letta, agent):+ """Test pagination with before cursor."""+ conversation = client.conversations.create(agent_id=agent.id)++ # Send messages to create history+ list(+ client.conversations.messages.create(+ conversation_id=conversation.id,+ messages=[{"role": "user", "content": "First message"}],+ )+ )+ list(+ client.conversations.messages.create(+ conversation_id=conversation.id,+ messages=[{"role": "user", "content": "Second message"}],+ )+ )++ # Get all messages first+ all_messages = client.conversations.messages.list(+ conversation_id=conversation.id,+ order="asc",+ )+ assert len(all_messages) >= 4 # system + user + assistant + user + assistant++ # Use the last message ID as cursor+ last_message_id = all_messages[-1].id+ messages_before = client.conversations.messages.list(+ conversation_id=conversation.id,+ order="asc",+ before=last_message_id,+ )++ # Should have fewer messages (all except the last one)+ assert len(messages_before) < len(all_messages)+ # Should not contain the cursor message+ assert last_message_id not in [m.id for m in messages_before]++ def test_list_conversation_messages_with_after_cursor(self, client: Letta, agent):+ """Test pagination with after cursor."""+ conversation = client.conversations.create(agent_id=agent.id)++ # Send messages to create history+ list(+ client.conversations.messages.create(+ conversation_id=conversation.id,+ messages=[{"role": "user", "content": "First message"}],+ )+ )+ list(+ client.conversations.messages.create(+ conversation_id=conversation.id,+ messages=[{"role": "user", "content": "Second message"}],+ )+ )++ # Get all messages first+ all_messages = client.conversations.messages.list(+ conversation_id=conversation.id,+ order="asc",+ )+ assert len(all_messages) >= 4++ # Use the first message ID as cursor+ first_message_id = all_messages[0].id+ messages_after = client.conversations.messages.list(+ conversation_id=conversation.id,+ order="asc",+ after=first_message_id,+ )++ # Should have fewer messages (all except the first one)+ assert len(messages_after) < len(all_messages)+ # Should not contain the cursor message+ assert first_message_id not in [m.id for m in messages_after]diff --git a/tests/managers/test_conversation_manager.py b/tests/managers/test_conversation_manager.pyindex 43999091a..03329a9ac 100644--- a/tests/managers/test_conversation_manager.py+++ b/tests/managers/test_conversation_manager.py@@ -749,3 +749,291 @@ async def test_delete_conversation_cleans_up_isolated_blocks(conversation_manage# Verify the isolated block was hard-deleteddeleted_block = await server.block_manager.get_block_by_id_async(isolated_block_id, default_user)assert deleted_block is None+++# ======================================================================================================================+# list_conversation_messages with order/reverse Tests+# ======================================================================================================================+++async def test_list_conversation_messages_ascending_order(conversation_manager, server: SyncServer, sarah_agent, default_user):+ """Test listing messages in ascending order (oldest first)."""+ from letta.schemas.letta_message_content import TextContent+ from letta.schemas.message import Message as PydanticMessage++ # Create a conversation+ conversation = await conversation_manager.create_conversation(+ agent_id=sarah_agent.id,+ conversation_create=CreateConversation(summary="Test"),+ actor=default_user,+ )++ # Create messages in a known order+ pydantic_messages = [+ PydanticMessage(+ agent_id=sarah_agent.id,+ role="user",+ content=[TextContent(text=f"Message {i}")],+ )+ for i in range(3)+ ]+ messages = await server.message_manager.create_many_messages_async(+ pydantic_messages,+ actor=default_user,+ )++ # Add messages to conversation+ await conversation_manager.add_messages_to_conversation(+ conversation_id=conversation.id,+ agent_id=sarah_agent.id,+ message_ids=[m.id for m in messages],+ actor=default_user,+ )++ # List messages in ascending order (reverse=False)+ letta_messages = await conversation_manager.list_conversation_messages(+ conversation_id=conversation.id,+ actor=default_user,+ reverse=False,+ )++ # First message should be "Message 0" (oldest)+ assert len(letta_messages) == 3+ assert "Message 0" in letta_messages[0].content+++async def test_list_conversation_messages_descending_order(conversation_manager, server: SyncServer, sarah_agent, default_user):+ """Test listing messages in descending order (newest first)."""+ from letta.schemas.letta_message_content import TextContent+ from letta.schemas.message import Message as PydanticMessage++ # Create a conversation+ conversation = await conversation_manager.create_conversation(+ agent_id=sarah_agent.id,+ conversation_create=CreateConversation(summary="Test"),+ actor=default_user,+ )++ # Create messages in a known order+ pydantic_messages = [+ PydanticMessage(+ agent_id=sarah_agent.id,+ role="user",+ content=[TextContent(text=f"Message {i}")],+ )+ for i in range(3)+ ]+ messages = await server.message_manager.create_many_messages_async(+ pydantic_messages,+ actor=default_user,+ )++ # Add messages to conversation+ await conversation_manager.add_messages_to_conversation(+ conversation_id=conversation.id,+ agent_id=sarah_agent.id,+ message_ids=[m.id for m in messages],+ actor=default_user,+ )++ # List messages in descending order (reverse=True)+ letta_messages = await conversation_manager.list_conversation_messages(+ conversation_id=conversation.id,+ actor=default_user,+ reverse=True,+ )++ # First message should be "Message 2" (newest)+ assert len(letta_messages) == 3+ assert "Message 2" in letta_messages[0].content+++async def test_list_conversation_messages_with_group_id_filter(conversation_manager, server: SyncServer, sarah_agent, default_user):+ """Test filtering messages by group_id."""+ from letta.schemas.letta_message_content import TextContent+ from letta.schemas.message import Message as PydanticMessage++ # Create a conversation+ conversation = await conversation_manager.create_conversation(+ agent_id=sarah_agent.id,+ conversation_create=CreateConversation(summary="Test"),+ actor=default_user,+ )++ # Create messages with different group_ids+ group_a_id = "group-aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"+ group_b_id = "group-bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb"++ messages_group_a = [+ PydanticMessage(+ agent_id=sarah_agent.id,+ role="user",+ content=[TextContent(text="Group A message 1")],+ group_id=group_a_id,+ ),+ PydanticMessage(+ agent_id=sarah_agent.id,+ role="user",+ content=[TextContent(text="Group A message 2")],+ group_id=group_a_id,+ ),+ ]+ messages_group_b = [+ PydanticMessage(+ agent_id=sarah_agent.id,+ role="user",+ content=[TextContent(text="Group B message 1")],+ group_id=group_b_id,+ ),+ ]++ created_a = await server.message_manager.create_many_messages_async(messages_group_a, actor=default_user)+ created_b = await server.message_manager.create_many_messages_async(messages_group_b, actor=default_user)++ # Add all messages to conversation+ all_message_ids = [m.id for m in created_a] + [m.id for m in created_b]+ await conversation_manager.add_messages_to_conversation(+ conversation_id=conversation.id,+ agent_id=sarah_agent.id,+ message_ids=all_message_ids,+ actor=default_user,+ )++ # List messages filtered by group A+ messages_a = await conversation_manager.list_conversation_messages(+ conversation_id=conversation.id,+ actor=default_user,+ group_id=group_a_id,+ )++ assert len(messages_a) == 2+ for msg in messages_a:+ assert "Group A" in msg.content++ # List messages filtered by group B+ messages_b = await conversation_manager.list_conversation_messages(+ conversation_id=conversation.id,+ actor=default_user,+ group_id=group_b_id,+ )++ assert len(messages_b) == 1+ assert "Group B" in messages_b[0].content+++async def test_list_conversation_messages_no_group_id_returns_all(conversation_manager, server: SyncServer, sarah_agent, default_user):+ """Test that not providing group_id returns all messages."""+ from letta.schemas.letta_message_content import TextContent+ from letta.schemas.message import Message as PydanticMessage++ # Create a conversation+ conversation = await conversation_manager.create_conversation(+ agent_id=sarah_agent.id,+ conversation_create=CreateConversation(summary="Test"),+ actor=default_user,+ )++ # Create messages with different group_ids+ group_a_id = "group-aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"+ group_b_id = "group-bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb"++ pydantic_messages = [+ PydanticMessage(+ agent_id=sarah_agent.id,+ role="user",+ content=[TextContent(text="Group A message")],+ group_id=group_a_id,+ ),+ PydanticMessage(+ agent_id=sarah_agent.id,+ role="user",+ content=[TextContent(text="Group B message")],+ group_id=group_b_id,+ ),+ PydanticMessage(+ agent_id=sarah_agent.id,+ role="user",+ content=[TextContent(text="No group message")],+ group_id=None,+ ),+ ]+ messages = await server.message_manager.create_many_messages_async(pydantic_messages, actor=default_user)++ # Add all messages to conversation+ await conversation_manager.add_messages_to_conversation(+ conversation_id=conversation.id,+ agent_id=sarah_agent.id,+ message_ids=[m.id for m in messages],+ actor=default_user,+ )++ # List all messages without group_id filter+ all_messages = await conversation_manager.list_conversation_messages(+ conversation_id=conversation.id,+ actor=default_user,+ )++ assert len(all_messages) == 3+++async def test_list_conversation_messages_order_with_pagination(conversation_manager, server: SyncServer, sarah_agent, default_user):+ """Test that order affects pagination correctly."""+ from letta.schemas.letta_message_content import TextContent+ from letta.schemas.message import Message as PydanticMessage++ # Create a conversation+ conversation = await conversation_manager.create_conversation(+ agent_id=sarah_agent.id,+ conversation_create=CreateConversation(summary="Test"),+ actor=default_user,+ )++ # Create messages+ pydantic_messages = [+ PydanticMessage(+ agent_id=sarah_agent.id,+ role="user",+ content=[TextContent(text=f"Message {i}")],+ )+ for i in range(5)+ ]+ messages = await server.message_manager.create_many_messages_async(+ pydantic_messages,+ actor=default_user,+ )++ # Add messages to conversation+ await conversation_manager.add_messages_to_conversation(+ conversation_id=conversation.id,+ agent_id=sarah_agent.id,+ message_ids=[m.id for m in messages],+ actor=default_user,+ )++ # Get first page in ascending order with limit+ page_asc = await conversation_manager.list_conversation_messages(+ conversation_id=conversation.id,+ actor=default_user,+ reverse=False,+ limit=2,+ )++ # Get first page in descending order with limit+ page_desc = await conversation_manager.list_conversation_messages(+ conversation_id=conversation.id,+ actor=default_user,+ reverse=True,+ limit=2,+ )++ # The first messages should be different+ assert page_asc[0].content != page_desc[0].content+ # In ascending, first should be "Message 0"+ assert "Message 0" in page_asc[0].content+ # In descending, first should be "Message 4"+ assert "Message 4" in page_desc[0].content