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: Make agent listing more performant (#1270)

Matthew Zhouab0a74ebc3f3
diff --git a/letta/orm/agent.py b/letta/orm/agent.py
index 579f22793..a4487963c 100644
--- a/letta/orm/agent.py
+++ b/letta/orm/agent.py
@@ -1,5 +1,5 @@
import uuid
-from typing import TYPE_CHECKING, List, Optional
+from typing import TYPE_CHECKING, List, Optional, Set
from sqlalchemy import JSON, Boolean, Index, String
from sqlalchemy.orm import Mapped, mapped_column, relationship
@@ -142,38 +142,72 @@ class Agent(SqlalchemyBase, OrganizationMixin):
back_populates="manager_agent",
)
- def to_pydantic(self) -> PydanticAgentState:
- """converts to the basic pydantic model counterpart"""
- # add default rule for having send_message be a terminal tool
- tool_rules = self.tool_rules
- multi_agent_group = self.multi_agent_group
+ def to_pydantic(self, include_relationships: Optional[Set[str]] = None) -> PydanticAgentState:
+ """
+ Converts the SQLAlchemy Agent model into its Pydantic counterpart.
+
+ The following base fields are always included:
+ - id, agent_type, name, description, system, message_ids, metadata_,
+ llm_config, embedding_config, project_id, template_id, base_template_id,
+ tool_rules, message_buffer_autoclear, tags
+
+ Everything else (e.g., tools, sources, memory, etc.) is optional and only
+ included if specified in `include_fields`.
+
+ Args:
+ include_relationships (Optional[Set[str]]):
+ A set of additional field names to include in the output. If None or empty,
+ no extra fields are loaded beyond the base fields.
+
+ Returns:
+ PydanticAgentState: The Pydantic representation of the agent.
+ """
+ # Base fields: always included
state = {
"id": self.id,
- "organization_id": self.organization_id,
+ "agent_type": self.agent_type,
"name": self.name,
"description": self.description,
- "message_ids": self.message_ids,
- "tools": self.tools,
- "sources": [source.to_pydantic() for source in self.sources],
- "tags": [t.tag for t in self.tags],
- "tool_rules": tool_rules,
"system": self.system,
- "agent_type": self.agent_type,
+ "message_ids": self.message_ids,
+ "metadata": self.metadata_, # Exposed as 'metadata' to Pydantic
"llm_config": self.llm_config,
"embedding_config": self.embedding_config,
- "metadata": self.metadata_,
- "memory": Memory(blocks=[b.to_pydantic() for b in self.core_memory]),
- "created_by_id": self.created_by_id,
- "last_updated_by_id": self.last_updated_by_id,
- "created_at": self.created_at,
- "updated_at": self.updated_at,
- "tool_exec_environment_variables": self.tool_exec_environment_variables,
"project_id": self.project_id,
"template_id": self.template_id,
"base_template_id": self.base_template_id,
- "identity_ids": [identity.id for identity in self.identities],
+ "tool_rules": self.tool_rules,
"message_buffer_autoclear": self.message_buffer_autoclear,
- "multi_agent_group": multi_agent_group,
+ "created_by_id": self.created_by_id,
+ "last_updated_by_id": self.last_updated_by_id,
+ "created_at": self.created_at,
+ "updated_at": self.updated_at,
+ # optional field defaults
+ "tags": [],
+ "tools": [],
+ "sources": [],
+ "memory": Memory(blocks=[]),
+ "identity_ids": [],
+ "multi_agent_group": None,
+ "tool_exec_environment_variables": [],
+ }
+
+ # Optional fields: only included if requested
+ optional_fields = {
+ "tags": lambda: [t.tag for t in self.tags],
+ "tools": lambda: self.tools,
+ "sources": lambda: [s.to_pydantic() for s in self.sources],
+ "memory": lambda: Memory(blocks=[b.to_pydantic() for b in self.core_memory]),
+ "identity_ids": lambda: [i.id for i in self.identities],
+ "multi_agent_group": lambda: self.multi_agent_group,
+ "tool_exec_environment_variables": lambda: self.tool_exec_environment_variables,
}
+ include_relationships = set(optional_fields.keys() if include_relationships is None else include_relationships)
+
+ for field_name in include_relationships:
+ resolver = optional_fields.get(field_name)
+ if resolver:
+ state[field_name] = resolver()
+
return self.__pydantic_model__(**state)
diff --git a/letta/server/rest_api/routers/v1/agents.py b/letta/server/rest_api/routers/v1/agents.py
index fc91b6faf..247dbe225 100644
--- a/letta/server/rest_api/routers/v1/agents.py
+++ b/letta/server/rest_api/routers/v1/agents.py
@@ -35,59 +35,61 @@ router = APIRouter(prefix="/agents", tags=["agents"])
logger = get_logger(__name__)
-# TODO: This should be paginated
@router.get("/", response_model=List[AgentState], operation_id="list_agents")
def list_agents(
name: Optional[str] = Query(None, description="Name of the agent"),
tags: Optional[List[str]] = Query(None, description="List of tags to filter agents by"),
match_all_tags: bool = Query(
False,
- description="If True, only returns agents that match ALL given tags. Otherwise, return agents that have ANY of the passed in tags.",
+ description="If True, only returns agents that match ALL given tags. Otherwise, return agents that have ANY of the passed-in tags.",
),
- server: "SyncServer" = Depends(get_letta_server),
+ server: SyncServer = Depends(get_letta_server),
actor_id: Optional[str] = Header(None, alias="user_id"),
before: Optional[str] = Query(None, description="Cursor for pagination"),
after: Optional[str] = Query(None, description="Cursor for pagination"),
- limit: Optional[int] = Query(None, description="Limit for pagination"),
+ limit: Optional[int] = Query(50, description="Limit for pagination"),
query_text: Optional[str] = Query(None, description="Search agents by name"),
- project_id: Optional[str] = Query(None, description="Search agents by project id"),
- template_id: Optional[str] = Query(None, description="Search agents by template id"),
- base_template_id: Optional[str] = Query(None, description="Search agents by base template id"),
- identity_id: Optional[str] = Query(None, description="Search agents by identifier id"),
+ project_id: Optional[str] = Query(None, description="Search agents by project ID"),
+ template_id: Optional[str] = Query(None, description="Search agents by template ID"),
+ base_template_id: Optional[str] = Query(None, description="Search agents by base template ID"),
+ identity_id: Optional[str] = Query(None, description="Search agents by identity ID"),
identifier_keys: Optional[List[str]] = Query(None, description="Search agents by identifier keys"),
+ include_relationships: Optional[List[str]] = Query(
+ None,
+ description=(
+ "Specify which relational fields (e.g., 'tools', 'sources', 'memory') to include in the response. "
+ "If not provided, all relationships are loaded by default. "
+ "Using this can optimize performance by reducing unnecessary joins."
+ ),
+ ),
):
"""
List all agents associated with a given user.
- This endpoint retrieves a list of all agents and their configurations associated with the specified user ID.
+
+ This endpoint retrieves a list of all agents and their configurations
+ associated with the specified user ID.
"""
+
+ # Retrieve the actor (user) details
actor = server.user_manager.get_user_or_default(user_id=actor_id)
- # Use dictionary comprehension to build kwargs dynamically
- kwargs = {
- key: value
- for key, value in {
- "name": name,
- "project_id": project_id,
- "template_id": template_id,
- "base_template_id": base_template_id,
- }.items()
- if value is not None
- }
-
- # Call list_agents with the dynamic kwargs
- agents = server.agent_manager.list_agents(
+ # Call list_agents directly without unnecessary dict handling
+ return server.agent_manager.list_agents(
actor=actor,
+ name=name,
before=before,
after=after,
limit=limit,
query_text=query_text,
tags=tags,
match_all_tags=match_all_tags,
- identifier_keys=identifier_keys,
+ project_id=project_id,
+ template_id=template_id,
+ base_template_id=base_template_id,
identity_id=identity_id,
- **kwargs,
+ identifier_keys=identifier_keys,
+ include_relationships=include_relationships,
)
- return agents
@router.get("/{agent_id}/download", operation_id="download_agent_serialized")
diff --git a/letta/services/agent_manager.py b/letta/services/agent_manager.py
index a3ba62ff2..8d2191797 100644
--- a/letta/services/agent_manager.py
+++ b/letta/services/agent_manager.py
@@ -18,6 +18,7 @@ from letta.orm import Tool as ToolModel
from letta.orm.enums import ToolType
from letta.orm.errors import NoResultFound
from letta.orm.sandbox_config import AgentEnvironmentVariable as AgentEnvironmentVariableModel
+from letta.orm.sqlalchemy_base import AccessType
from letta.orm.sqlite_functions import adapt_array
from letta.schemas.agent import AgentState as PydanticAgentState
from letta.schemas.agent import AgentType, CreateAgent, UpdateAgent
@@ -39,6 +40,10 @@ from letta.serialize_schemas import SerializedAgentSchema
from letta.serialize_schemas.tool import SerializedToolSchema
from letta.services.block_manager import BlockManager
from letta.services.helpers.agent_manager_helper import (
+ _apply_filters,
+ _apply_identity_filters,
+ _apply_pagination,
+ _apply_tag_filter,
_process_relationship,
_process_tags,
check_supports_structured_output,
@@ -326,39 +331,60 @@ class AgentManager:
# Convert to PydanticAgentState and return
return agent.to_pydantic()
- @enforce_types
+ # TODO: Make this general and think about how to roll this into sqlalchemybase
def list_agents(
self,
actor: PydanticUser,
+ name: Optional[str] = None,
+ tags: Optional[List[str]] = None,
+ match_all_tags: bool = False,
before: Optional[str] = None,
after: Optional[str] = None,
limit: Optional[int] = 50,
- tags: Optional[List[str]] = None,
- match_all_tags: bool = False,
query_text: Optional[str] = None,
- identifier_keys: Optional[List[str]] = None,
+ project_id: Optional[str] = None,
+ template_id: Optional[str] = None,
+ base_template_id: Optional[str] = None,
identity_id: Optional[str] = None,
- **kwargs,
+ identifier_keys: Optional[List[str]] = None,
+ include_relationships: Optional[List[str]] = None,
) -> List[PydanticAgentState]:
"""
- List agents that have the specified tags.
+ Retrieves agents with optimized filtering and optional field selection.
+
+ Args:
+ actor: The User requesting the list
+ name (Optional[str]): Filter by agent name.
+ tags (Optional[List[str]]): Filter agents by tags.
+ match_all_tags (bool): If True, only return agents that match ALL given tags.
+ before (Optional[str]): Cursor for pagination.
+ after (Optional[str]): Cursor for pagination.
+ limit (Optional[int]): Maximum number of agents to return.
+ query_text (Optional[str]): Search agents by name.
+ project_id (Optional[str]): Filter by project ID.
+ template_id (Optional[str]): Filter by template ID.
+ base_template_id (Optional[str]): Filter by base template ID.
+ 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.
+
+ Returns:
+ List[PydanticAgentState]: The filtered list of matching agents.
"""
with self.session_maker() as session:
- agents = AgentModel.list(
- db_session=session,
- before=before,
- after=after,
- limit=limit,
- tags=tags,
- match_all_tags=match_all_tags,
- organization_id=actor.organization_id if actor else None,
- query_text=query_text,
- identifier_keys=identifier_keys,
- identity_id=identity_id,
- **kwargs,
- )
+ query = select(AgentModel).distinct(AgentModel.created_at, AgentModel.id)
+ query = AgentModel.apply_access_predicate(query, actor, ["read"], AccessType.ORGANIZATION)
+
+ # Apply filters
+ 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 = query.limit(limit)
- return [agent.to_pydantic() for agent in agents]
+ agents = session.execute(query).scalars().all()
+ return [agent.to_pydantic(include_relationships=include_relationships) for agent in agents]
@enforce_types
def list_agents_matching_tags(
diff --git a/letta/services/helpers/agent_manager_helper.py b/letta/services/helpers/agent_manager_helper.py
index a87af65f7..a3571aa55 100644
--- a/letta/services/helpers/agent_manager_helper.py
+++ b/letta/services/helpers/agent_manager_helper.py
@@ -1,6 +1,8 @@
import datetime
from typing import List, Literal, Optional
+from sqlalchemy import and_, func, literal, or_, select
+
from letta import system
from letta.constants import IN_CONTEXT_MEMORY_KEYWORD, STRUCTURED_OUTPUT_MODELS
from letta.helpers import ToolRulesSolver
@@ -8,6 +10,7 @@ from letta.helpers.datetime_helpers import get_local_time
from letta.orm.agent import Agent as AgentModel
from letta.orm.agents_tags import AgentsTags
from letta.orm.errors import NoResultFound
+from letta.orm.identity import Identity
from letta.prompts import gpt_system
from letta.schemas.agent import AgentState, AgentType
from letta.schemas.enums import MessageRole
@@ -294,3 +297,149 @@ def check_supports_structured_output(model: str, tool_rules: List[ToolRule]) ->
return False
else:
return True
+
+
+def _apply_pagination(query, before: Optional[str], after: Optional[str], session) -> any:
+ """
+ Apply cursor-based pagination filters using the agent's created_at timestamp with id as a tie-breaker.
+
+ 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.
+
+ 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.
+ """
+ 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,
+ ),
+ )
+ )
+ 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())
+ return query
+
+
+def _apply_tag_filter(query, tags: Optional[List[str]], match_all_tags: bool):
+ """
+ Apply tag-based filtering to the agent query.
+
+ This helper function creates a subquery that groups agent IDs by their tags.
+ If `match_all_tags` is True, it filters agents that have all of the specified tags.
+ Otherwise, it filters agents that have any of the tags.
+
+ Args:
+ query: The SQLAlchemy query object to be modified.
+ tags (Optional[List[str]]): A list of tags to filter agents.
+ match_all_tags (bool): If True, only return agents that match all provided tags.
+
+ Returns:
+ The modified query with tag filters applied.
+ """
+ if tags:
+ # Build a subquery to select agent IDs that have the specified tags.
+ subquery = select(AgentsTags.agent_id).where(AgentsTags.tag.in_(tags)).group_by(AgentsTags.agent_id)
+ # If all tags must match, add a HAVING clause to ensure the count of tags equals the number provided.
+ if match_all_tags:
+ subquery = subquery.having(func.count(AgentsTags.tag) == literal(len(tags)))
+ # Filter the main query to include only agents present in the subquery.
+ query = query.where(AgentModel.id.in_(subquery))
+ return query
+
+
+def _apply_identity_filters(query, identity_id: Optional[str], identifier_keys: Optional[List[str]]):
+ """
+ Apply identity-related filters to the agent query.
+
+ This helper function joins the identities relationship and filters the agents based on
+ a specific identity ID and/or a list of identifier keys.
+
+ Args:
+ query: The SQLAlchemy query object to be modified.
+ identity_id (Optional[str]): The identity ID to filter by.
+ identifier_keys (Optional[List[str]]): A list of identifier keys to filter agents.
+
+ Returns:
+ The modified query with identity filters applied.
+ """
+ # Join the identities relationship and filter by a specific identity ID.
+ if identity_id:
+ query = query.join(AgentModel.identities).where(Identity.id == identity_id)
+ # Join the identities relationship and filter by a set of identifier keys.
+ if identifier_keys:
+ query = query.join(AgentModel.identities).where(Identity.identifier_key.in_(identifier_keys))
+ return query
+
+
+def _apply_filters(
+ query,
+ name: Optional[str],
+ query_text: Optional[str],
+ project_id: Optional[str],
+ template_id: Optional[str],
+ base_template_id: Optional[str],
+):
+ """
+ Apply basic filtering criteria to the agent query.
+
+ This helper function adds WHERE clauses based on provided parameters such as
+ exact name, partial name match (using ILIKE), project ID, template ID, and base template ID.
+
+ Args:
+ query: The SQLAlchemy query object to be modified.
+ name (Optional[str]): Exact name to filter by.
+ query_text (Optional[str]): Partial text to search in the agent's name (case-insensitive).
+ project_id (Optional[str]): Filter for agents belonging to a specific project.
+ template_id (Optional[str]): Filter for agents using a specific template.
+ base_template_id (Optional[str]): Filter for agents using a specific base template.
+
+ Returns:
+ The modified query with the applied filters.
+ """
+ # Filter by exact agent name if provided.
+ if name:
+ query = query.where(AgentModel.name == name)
+ # Apply a case-insensitive partial match for the agent's name.
+ if query_text:
+ query = query.where(AgentModel.name.ilike(f"%{query_text}%"))
+ # Filter agents by project ID.
+ if project_id:
+ query = query.where(AgentModel.project_id == project_id)
+ # Filter agents by template ID.
+ if template_id:
+ query = query.where(AgentModel.template_id == template_id)
+ # Filter agents by base template ID.
+ if base_template_id:
+ query = query.where(AgentModel.base_template_id == base_template_id)
+ return query
diff --git a/tests/test_managers.py b/tests/test_managers.py
index 0b43e9242..48416d16c 100644
--- a/tests/test_managers.py
+++ b/tests/test_managers.py
@@ -614,6 +614,104 @@ def test_update_agent(server: SyncServer, comprehensive_test_agent_fixture, othe
assert updated_agent.updated_at > last_updated_timestamp
+# ======================================================================================================================
+# AgentManager Tests - Listing
+# ======================================================================================================================
+
+
+def test_list_agents_select_fields_empty(server: SyncServer, comprehensive_test_agent_fixture, default_user):
+ # Create an agent using the comprehensive fixture.
+ created_agent, create_agent_request = comprehensive_test_agent_fixture
+
+ # List agents using an empty list for select_fields.
+ agents = server.agent_manager.list_agents(actor=default_user, include_relationships=[])
+ # Assert that the agent is returned and basic fields are present.
+ assert len(agents) >= 1
+ agent = agents[0]
+ assert agent.id is not None
+ assert agent.name is not None
+
+ # Assert no relationships were loaded
+ assert len(agent.tools) == 0
+ assert len(agent.tags) == 0
+
+
+def test_list_agents_select_fields_none(server: SyncServer, comprehensive_test_agent_fixture, default_user):
+ # Create an agent using the comprehensive fixture.
+ created_agent, create_agent_request = comprehensive_test_agent_fixture
+
+ # List agents using an empty list for select_fields.
+ agents = server.agent_manager.list_agents(actor=default_user, include_relationships=None)
+ # Assert that the agent is returned and basic fields are present.
+ assert len(agents) >= 1
+ agent = agents[0]
+ assert agent.id is not None
+ assert agent.name is not None
+
+ # Assert no relationships were loaded
+ assert len(agent.tools) > 0
+ assert len(agent.tags) > 0
+
+
+def test_list_agents_select_fields_specific(server: SyncServer, comprehensive_test_agent_fixture, default_user):
+ created_agent, create_agent_request = comprehensive_test_agent_fixture
+
+ # Choose a subset of valid relationship fields.
+ valid_fields = ["tools", "tags"]
+ agents = server.agent_manager.list_agents(actor=default_user, include_relationships=valid_fields)
+ assert len(agents) >= 1
+ agent = agents[0]
+ # Depending on your to_pydantic() implementation,
+ # verify that the fields exist in the returned pydantic model.
+ # (Note: These assertions may require that your CreateAgent fixture sets up these relationships.)
+ assert agent.tools
+ assert sorted(agent.tags) == ["a", "b"]
+ assert not agent.memory.blocks
+
+
+def test_list_agents_select_fields_invalid(server: SyncServer, comprehensive_test_agent_fixture, default_user):
+ created_agent, create_agent_request = comprehensive_test_agent_fixture
+
+ # Provide field names that are not recognized.
+ invalid_fields = ["foobar", "nonexistent_field"]
+ # The expectation is that these fields are simply ignored.
+ agents = server.agent_manager.list_agents(actor=default_user, include_relationships=invalid_fields)
+ assert len(agents) >= 1
+ agent = agents[0]
+ # Verify that standard fields are still present.c
+ assert agent.id is not None
+ assert agent.name is not None
+
+
+def test_list_agents_select_fields_duplicates(server: SyncServer, comprehensive_test_agent_fixture, default_user):
+ created_agent, create_agent_request = comprehensive_test_agent_fixture
+
+ # Provide duplicate valid field names.
+ duplicate_fields = ["tools", "tools", "tags", "tags"]
+ agents = server.agent_manager.list_agents(actor=default_user, include_relationships=duplicate_fields)
+ assert len(agents) >= 1
+ agent = agents[0]
+ # Verify that the agent pydantic representation includes the relationships.
+ # Even if duplicates were provided, the query should not break.
+ assert isinstance(agent.tools, list)
+ assert isinstance(agent.tags, list)
+
+
+def test_list_agents_select_fields_mixed(server: SyncServer, comprehensive_test_agent_fixture, default_user):
+ created_agent, create_agent_request = comprehensive_test_agent_fixture
+
+ # Mix valid fields with an invalid one.
+ mixed_fields = ["tools", "invalid_field"]
+ agents = server.agent_manager.list_agents(actor=default_user, include_relationships=mixed_fields)
+ assert len(agents) >= 1
+ agent = agents[0]
+ # Valid fields should be loaded and accessible.
+ assert agent.tools
+ # Since "invalid_field" is not recognized, it should have no adverse effect.
+ # You might optionally check that no extra attribute is created on the pydantic model.
+ assert not hasattr(agent, "invalid_field")
+
+
# ======================================================================================================================
# AgentManager Tests - Tools Relationship
# ======================================================================================================================