Platform for stateful agents: AI with advanced memory that can learn and self-improve over time.
feat: Make agent listing more performant (#1270)
Matthew Zhou6555390eff16
diff --git a/letta/orm/agent.py b/letta/orm/agent.pyindex 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, Setfrom sqlalchemy import JSON, Boolean, Index, Stringfrom 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 includedstate = {"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.pyindex 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) detailsactor = 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.pyindex 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 ToolModelfrom letta.orm.enums import ToolTypefrom letta.orm.errors import NoResultFoundfrom letta.orm.sandbox_config import AgentEnvironmentVariable as AgentEnvironmentVariableModel+from letta.orm.sqlalchemy_base import AccessTypefrom letta.orm.sqlite_functions import adapt_arrayfrom letta.schemas.agent import AgentState as PydanticAgentStatefrom letta.schemas.agent import AgentType, CreateAgent, UpdateAgent@@ -39,6 +40,10 @@ from letta.serialize_schemas import SerializedAgentSchemafrom letta.serialize_schemas.tool import SerializedToolSchemafrom letta.services.block_manager import BlockManagerfrom 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 returnreturn agent.to_pydantic()- @enforce_types+ # TODO: Make this general and think about how to roll this into sqlalchemybasedef 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_typesdef list_agents_matching_tags(diff --git a/letta/services/helpers/agent_manager_helper.py b/letta/services/helpers/agent_manager_helper.pyindex a87af65f7..a3571aa55 100644--- a/letta/services/helpers/agent_manager_helper.py+++ b/letta/services/helpers/agent_manager_helper.py@@ -1,6 +1,8 @@import datetimefrom typing import List, Literal, Optional+from sqlalchemy import and_, func, literal, or_, select+from letta import systemfrom letta.constants import IN_CONTEXT_MEMORY_KEYWORD, STRUCTURED_OUTPUT_MODELSfrom letta.helpers import ToolRulesSolver@@ -8,6 +10,7 @@ from letta.helpers.datetime_helpers import get_local_timefrom letta.orm.agent import Agent as AgentModelfrom letta.orm.agents_tags import AgentsTagsfrom letta.orm.errors import NoResultFound+from letta.orm.identity import Identityfrom letta.prompts import gpt_systemfrom letta.schemas.agent import AgentState, AgentTypefrom letta.schemas.enums import MessageRole@@ -294,3 +297,149 @@ def check_supports_structured_output(model: str, tool_rules: List[ToolRule]) ->return Falseelse: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 querydiff --git a/tests/test_managers.py b/tests/test_managers.pyindex 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, otheassert 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# ======================================================================================================================