Skip to content

armgit / letta

Public Imported from GitHub
0

Platform for stateful agents: AI with advanced memory that can learn and self-improve over time.

feat: Add asc/desc to agent listing (#1359)

Matthew Zhou6dc8cb3e50bd
diff --git a/letta/server/rest_api/routers/v1/agents.py b/letta/server/rest_api/routers/v1/agents.py
index 7233024b5..189985da9 100644
--- a/letta/server/rest_api/routers/v1/agents.py
+++ b/letta/server/rest_api/routers/v1/agents.py
@@ -63,6 +63,10 @@ def list_agents(
"Using this can optimize performance by reducing unnecessary joins."
),
),
+ ascending: bool = Query(
+ False,
+ description="Whether to sort agents oldest to newest (True) or newest to oldest (False, default)",
+ ),
):
"""
List all agents associated with a given user.
@@ -90,6 +94,7 @@ def list_agents(
identity_id=identity_id,
identifier_keys=identifier_keys,
include_relationships=include_relationships,
+ ascending=ascending,
)
diff --git a/letta/services/agent_manager.py b/letta/services/agent_manager.py
index cf9853de0..9e12531b4 100644
--- a/letta/services/agent_manager.py
+++ b/letta/services/agent_manager.py
@@ -349,6 +349,7 @@ class AgentManager:
identity_id: Optional[str] = None,
identifier_keys: Optional[List[str]] = None,
include_relationships: Optional[List[str]] = None,
+ ascending: bool = True,
) -> List[PydanticAgentState]:
"""
Retrieves agents with optimized filtering and optional field selection.
@@ -368,6 +369,7 @@ class AgentManager:
identity_id (Optional[str]): Filter by identifier ID.
identifier_keys (Optional[List[str]]): Search agents by identifier keys.
include_relationships (Optional[List[str]]): List of fields to load for performance optimization.
+ ascending
Returns:
List[PydanticAgentState]: The filtered list of matching agents.
@@ -380,7 +382,7 @@ class AgentManager:
query = _apply_filters(query, name, query_text, project_id, template_id, base_template_id)
query = _apply_identity_filters(query, identity_id, identifier_keys)
query = _apply_tag_filter(query, tags, match_all_tags)
- query = _apply_pagination(query, before, after, session)
+ query = _apply_pagination(query, before, after, session, ascending=ascending)
query = query.limit(limit)
diff --git a/letta/services/helpers/agent_manager_helper.py b/letta/services/helpers/agent_manager_helper.py
index a3571aa55..d620a225f 100644
--- a/letta/services/helpers/agent_manager_helper.py
+++ b/letta/services/helpers/agent_manager_helper.py
@@ -1,7 +1,7 @@
import datetime
from typing import List, Literal, Optional
-from sqlalchemy import and_, func, literal, or_, select
+from sqlalchemy import and_, asc, desc, func, literal, or_, select
from letta import system
from letta.constants import IN_CONTEXT_MEMORY_KEYWORD, STRUCTURED_OUTPUT_MODELS
@@ -299,55 +299,41 @@ def check_supports_structured_output(model: str, tool_rules: List[ToolRule]) ->
return True
-def _apply_pagination(query, before: Optional[str], after: Optional[str], session) -> any:
+def _cursor_filter(created_at_col, id_col, ref_created_at, ref_id, forward: bool):
"""
- Apply cursor-based pagination filters using the agent's created_at timestamp with id as a tie-breaker.
+ Returns a SQLAlchemy filter expression for cursor-based pagination.
- Instead of relying on the UUID ordering, this function uses the agent's creation time
- (and id for tie-breaking) to paginate the results. It performs a minimal lookup to fetch
- only the created_at and id for the agent corresponding to the provided cursor.
+ If `forward` is True, returns records after the reference.
+ If `forward` is False, returns records before the reference.
+ """
+ if forward:
+ return or_(
+ created_at_col > ref_created_at,
+ and_(created_at_col == ref_created_at, id_col > ref_id),
+ )
+ else:
+ return or_(
+ created_at_col < ref_created_at,
+ and_(created_at_col == ref_created_at, id_col < ref_id),
+ )
- Args:
- query: The SQLAlchemy query object to modify.
- before (Optional[str]): Cursor (agent id) to return agents created before this agent.
- after (Optional[str]): Cursor (agent id) to return agents created after this agent.
- session: The active database session used to execute the minimal lookup.
- Returns:
- The modified query with pagination filters applied and ordered by created_at and id.
- """
+def _apply_pagination(query, before: Optional[str], after: Optional[str], session, ascending: bool = True) -> any:
if after:
- # Retrieve only the created_at and id for the agent corresponding to the 'after' cursor.
result = session.execute(select(AgentModel.created_at, AgentModel.id).where(AgentModel.id == after)).first()
if result:
after_created_at, after_id = result
- # Filter: include agents created after the reference, or at the same time but with a greater id.
- query = query.where(
- or_(
- AgentModel.created_at > after_created_at,
- and_(
- AgentModel.created_at == after_created_at,
- AgentModel.id > after_id,
- ),
- )
- )
+ query = query.where(_cursor_filter(AgentModel.created_at, AgentModel.id, after_created_at, after_id, forward=ascending))
+
if before:
- # Retrieve only the created_at and id for the agent corresponding to the 'before' cursor.
result = session.execute(select(AgentModel.created_at, AgentModel.id).where(AgentModel.id == before)).first()
if result:
before_created_at, before_id = result
- # Filter: include agents created before the reference, or at the same time but with a smaller id.
- query = query.where(
- or_(
- AgentModel.created_at < before_created_at,
- and_(
- AgentModel.created_at == before_created_at,
- AgentModel.id < before_id,
- ),
- )
- )
- # Enforce a deterministic ordering: first by created_at, then by id.
- query = query.order_by(AgentModel.created_at.asc(), AgentModel.id.asc())
+ query = query.where(_cursor_filter(AgentModel.created_at, AgentModel.id, before_created_at, before_id, forward=not ascending))
+
+ # Apply ordering
+ order_fn = asc if ascending else desc
+ query = query.order_by(order_fn(AgentModel.created_at), order_fn(AgentModel.id))
return query
diff --git a/tests/test_managers.py b/tests/test_managers.py
index 6bd11b18a..ac1c8693a 100644
--- a/tests/test_managers.py
+++ b/tests/test_managers.py
@@ -739,6 +739,124 @@ def test_list_agents_select_fields_mixed(server: SyncServer, comprehensive_test_
assert not hasattr(agent, "invalid_field")
+def test_list_agents_ascending(server: SyncServer, default_user):
+ # Create two agents with known names
+ agent1 = server.agent_manager.create_agent(
+ agent_create=CreateAgent(
+ name="agent_oldest",
+ llm_config=LLMConfig.default_config("gpt-4"),
+ embedding_config=EmbeddingConfig.default_config(provider="openai"),
+ memory_blocks=[],
+ ),
+ actor=default_user,
+ )
+
+ if USING_SQLITE:
+ time.sleep(CREATE_DELAY_SQLITE)
+
+ agent2 = server.agent_manager.create_agent(
+ agent_create=CreateAgent(
+ name="agent_newest",
+ llm_config=LLMConfig.default_config("gpt-4"),
+ embedding_config=EmbeddingConfig.default_config(provider="openai"),
+ memory_blocks=[],
+ ),
+ actor=default_user,
+ )
+
+ agents = server.agent_manager.list_agents(actor=default_user, ascending=True)
+ names = [agent.name for agent in agents]
+ assert names.index("agent_oldest") < names.index("agent_newest")
+
+
+def test_list_agents_descending(server: SyncServer, default_user):
+ # Create two agents with known names
+ agent1 = server.agent_manager.create_agent(
+ agent_create=CreateAgent(
+ name="agent_oldest",
+ llm_config=LLMConfig.default_config("gpt-4"),
+ embedding_config=EmbeddingConfig.default_config(provider="openai"),
+ memory_blocks=[],
+ ),
+ actor=default_user,
+ )
+
+ if USING_SQLITE:
+ time.sleep(CREATE_DELAY_SQLITE)
+
+ agent2 = server.agent_manager.create_agent(
+ agent_create=CreateAgent(
+ name="agent_newest",
+ llm_config=LLMConfig.default_config("gpt-4"),
+ embedding_config=EmbeddingConfig.default_config(provider="openai"),
+ memory_blocks=[],
+ ),
+ actor=default_user,
+ )
+
+ agents = server.agent_manager.list_agents(actor=default_user, ascending=False)
+ names = [agent.name for agent in agents]
+ assert names.index("agent_newest") < names.index("agent_oldest")
+
+
+def test_list_agents_ordering_and_pagination(server: SyncServer, default_user):
+ names = ["alpha_agent", "beta_agent", "gamma_agent"]
+ created_agents = []
+
+ # Create agents in known order
+ for name in names:
+ agent = server.agent_manager.create_agent(
+ agent_create=CreateAgent(
+ name=name,
+ memory_blocks=[],
+ llm_config=LLMConfig.default_config("gpt-4"),
+ embedding_config=EmbeddingConfig.default_config(provider="openai"),
+ ),
+ actor=default_user,
+ )
+ created_agents.append(agent)
+ if USING_SQLITE:
+ time.sleep(CREATE_DELAY_SQLITE)
+
+ agent_ids = {agent.name: agent.id for agent in created_agents}
+
+ # Ascending (oldest to newest)
+ agents_asc = server.agent_manager.list_agents(actor=default_user, ascending=True)
+ asc_names = [agent.name for agent in agents_asc]
+ assert asc_names.index("alpha_agent") < asc_names.index("beta_agent") < asc_names.index("gamma_agent")
+
+ # Descending (newest to oldest)
+ agents_desc = server.agent_manager.list_agents(actor=default_user, ascending=False)
+ desc_names = [agent.name for agent in agents_desc]
+ assert desc_names.index("gamma_agent") < desc_names.index("beta_agent") < desc_names.index("alpha_agent")
+
+ # After: Get agents after alpha_agent in ascending order (should exclude alpha)
+ after_alpha = server.agent_manager.list_agents(actor=default_user, after=agent_ids["alpha_agent"], ascending=True)
+ after_names = [a.name for a in after_alpha]
+ assert "alpha_agent" not in after_names
+ assert "beta_agent" in after_names
+ assert "gamma_agent" in after_names
+ assert after_names == ["beta_agent", "gamma_agent"]
+
+ # Before: Get agents before gamma_agent in ascending order (should exclude gamma)
+ before_gamma = server.agent_manager.list_agents(actor=default_user, before=agent_ids["gamma_agent"], ascending=True)
+ before_names = [a.name for a in before_gamma]
+ assert "gamma_agent" not in before_names
+ assert "alpha_agent" in before_names
+ assert "beta_agent" in before_names
+ assert before_names == ["alpha_agent", "beta_agent"]
+
+ # After: Get agents after gamma_agent in descending order (should exclude gamma, return beta then alpha)
+ after_gamma_desc = server.agent_manager.list_agents(actor=default_user, after=agent_ids["gamma_agent"], ascending=False)
+ after_names_desc = [a.name for a in after_gamma_desc]
+ assert after_names_desc == ["beta_agent", "alpha_agent"]
+
+ # Before: Get agents before alpha_agent in descending order (should exclude alpha)
+ before_alpha_desc = server.agent_manager.list_agents(actor=default_user, before=agent_ids["alpha_agent"], ascending=False)
+ before_names_desc = [a.name for a in before_alpha_desc]
+ assert before_names_desc == ["gamma_agent", "beta_agent"]
+
+
# ======================================================================================================================
# AgentManager Tests - Tools Relationship
# ======================================================================================================================