Platform for stateful agents: AI with advanced memory that can learn and self-improve over time.
feat: add backend support for agent relationship loads (#5693)
cthomasafdf0f80e370
diff --git a/letta/orm/agent.py b/letta/orm/agent.pyindex 2f2b10157..7f5e1c625 100644--- a/letta/orm/agent.py+++ b/letta/orm/agent.py@@ -282,7 +282,11 @@ class Agent(SqlalchemyBase, OrganizationMixin, ProjectMixin, TemplateEntityMixinreturn self.__pydantic_model__(**state)- async def to_pydantic_async(self, include_relationships: Optional[Set[str]] = None) -> PydanticAgentState:+ async def to_pydantic_async(+ self,+ include_relationships: Optional[Set[str]] = None,+ include: Optional[List[str]] = None,+ ) -> PydanticAgentState:"""Converts the SQLAlchemy Agent model into its Pydantic counterpart.@@ -351,6 +355,9 @@ class Agent(SqlalchemyBase, OrganizationMixin, ProjectMixin, TemplateEntityMixin# Initialize include_relationships to an empty set if it's Noneinclude_relationships = set(optional_fields.keys() if include_relationships is None else include_relationships)+ # Convert include list to set for efficient membership checks+ include_set = set(include) if include else set()+async def empty_list_async():return []@@ -358,18 +365,34 @@ class Agent(SqlalchemyBase, OrganizationMixin, ProjectMixin, TemplateEntityMixinreturn None# Only load requested relationships- tags = self.awaitable_attrs.tags if "tags" in include_relationships else empty_list_async()- tools = self.awaitable_attrs.tools if "tools" in include_relationships else empty_list_async()- sources = self.awaitable_attrs.sources if "sources" in include_relationships else empty_list_async()- memory = self.awaitable_attrs.core_memory if "memory" in include_relationships else empty_list_async()- identities = self.awaitable_attrs.identities if "identity_ids" in include_relationships else empty_list_async()- multi_agent_group = self.awaitable_attrs.multi_agent_group if "multi_agent_group" in include_relationships else none_async()+ tags = self.awaitable_attrs.tags if "tags" in include_relationships or "agent.tags" in include_set else empty_list_async()+ tools = self.awaitable_attrs.tools if "tools" in include_relationships or "agent.tools" in include_set else empty_list_async()+ sources = (+ self.awaitable_attrs.sources if "sources" in include_relationships or "agent.sources" in include_set else empty_list_async()+ )+ memory = (+ self.awaitable_attrs.core_memory if "memory" in include_relationships or "agent.blocks" in include_set else empty_list_async()+ )+ identities = (+ self.awaitable_attrs.identities+ if "identity_ids" in include_relationships or "agent.identities" in include_set+ else empty_list_async()+ )+ multi_agent_group = (+ self.awaitable_attrs.multi_agent_group+ if "multi_agent_group" in include_relationships or "agent.managed_group" in include_set+ else none_async()+ )tool_exec_environment_variables = (self.awaitable_attrs.tool_exec_environment_variables- if "tool_exec_environment_variables" in include_relationships or "secrets" in include_relationships+ if "tool_exec_environment_variables" in include_relationships+ or "secrets" in include_relationships+ or "agent.secrets" in include_setelse empty_list_async())- file_agents = self.awaitable_attrs.file_agents if "memory" in include_relationships else empty_list_async()+ file_agents = (+ self.awaitable_attrs.file_agents if "memory" in include_relationships or "agent.blocks" in include_set else empty_list_async()+ )(tags, tools, sources, memory, identities, multi_agent_group, tool_exec_environment_variables, file_agents) = await asyncio.gather(tags, tools, sources, memory, identities, multi_agent_group, tool_exec_environment_variables, file_agentsdiff --git a/letta/schemas/agent.py b/letta/schemas/agent.pyindex 8cfc0e4fd..844a282c3 100644--- a/letta/schemas/agent.py+++ b/letta/schemas/agent.py@@ -1,6 +1,6 @@from datetime import datetimefrom enum import Enum-from typing import Dict, List, Optional+from typing import Dict, List, Literal, Optionalfrom pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator@@ -43,6 +43,18 @@ class AgentType(str, Enum):voice_sleeptime_agent = "voice_sleeptime_agent"+# Relationship field literal type for AgentState include field to join related objects+AgentRelationships = Literal[+ "agent.blocks",+ "agent.identities",+ "agent.managed_group",+ "agent.secrets",+ "agent.sources",+ "agent.tags",+ "agent.tools",+]++class AgentState(OrmMetadataBase, validate_assignment=True):"""Representation of an agent's state. This is the state of the agent at a given time, and is persisted in the DB backend. The state has all the information needed to recreate a persisted agent.diff --git a/letta/services/agent_manager.py b/letta/services/agent_manager.pyindex dd94a74c2..655a9d2f4 100644--- a/letta/services/agent_manager.py+++ b/letta/services/agent_manager.py@@ -51,6 +51,7 @@ from letta.orm.sqlalchemy_base import AccessTypefrom letta.otel.tracing import trace_methodfrom letta.prompts.prompt_generator import PromptGeneratorfrom letta.schemas.agent import (+ AgentRelationships,AgentState as PydanticAgentState,CreateAgent,InternalTemplateAgentCreate,@@ -983,6 +984,7 @@ class AgentManager:agent_id: str,actor: PydanticUser,include_relationships: Optional[List[str]] = None,+ include: List[str] = [],) -> PydanticAgentState:"""Fetch an agent by its ID."""@@ -991,7 +993,7 @@ class AgentManager:query = select(AgentModel)query = AgentModel.apply_access_predicate(query, actor, ["read"], AccessType.ORGANIZATION)query = query.where(AgentModel.id == agent_id)- query = _apply_relationship_filters(query, include_relationships)+ query = _apply_relationship_filters(query, include_relationships, include)result = await session.execute(query)agent = result.scalar_one_or_none()@@ -999,7 +1001,7 @@ class AgentManager:if agent is None:raise NoResultFound(f"Agent with ID {agent_id} not found")- return await agent.to_pydantic_async(include_relationships=include_relationships)+ return await agent.to_pydantic_async(include_relationships=include_relationships, include=include)except NoResultFound:# Re-raise NoResultFound without logging to preserve 404 handlingraisediff --git a/letta/services/helpers/agent_manager_helper.py b/letta/services/helpers/agent_manager_helper.pyindex 3d49e38e8..fe5d7d05e 100644--- a/letta/services/helpers/agent_manager_helper.py+++ b/letta/services/helpers/agent_manager_helper.py@@ -775,24 +775,66 @@ def _apply_filters(return query-def _apply_relationship_filters(query, include_relationships: Optional[List[str]] = None):- if include_relationships is None:+def _apply_relationship_filters(+ query,+ include_relationships: Optional[List[str]] = None,+ include: Optional[List[str]] = None,+):+ # legacy include_relationships+ if include_relationships is None and not include:return query- if "memory" not in include_relationships:- query = query.options(noload(AgentModel.core_memory), noload(AgentModel.file_agents))- if "identity_ids" not in include_relationships:- query = query.options(noload(AgentModel.identities))+ column_names = get_column_names_from_includes_params(include_relationships, include)- relationships = ["tool_exec_environment_variables", "tools", "sources", "tags", "multi_agent_group"]+ relationships = [+ "core_memory",+ "file_agents",+ "identities",+ "tool_exec_environment_variables",+ "tools",+ "sources",+ "tags",+ "multi_agent_group",+ ]for rel in relationships:- if rel not in include_relationships:+ if rel not in column_names:query = query.options(noload(getattr(AgentModel, rel)))return query+def get_column_names_from_includes_params(+ include_relationships: Optional[List[str]] = None, includes: Optional[List[str]] = None+) -> Set[str]:+ include_mapping = {+ "agent.blocks": ["core_memory"],+ "agent.identities": ["identities"],+ "agent.managed_group": ["multi_agent_group"],+ "agent.secrets": ["tool_exec_environment_variables"],+ "agent.sources": ["sources"],+ "agent.tags": ["tags"],+ "agent.tools": ["tools"],+ # legacy+ "memory": ["core_memory", "file_agents"],+ "identity_ids": ["identities"],+ "multi_agent_group": ["multi_agent_group"],+ "tool_exec_environment_variables": ["tool_exec_environment_variables"],+ "secrets": ["tool_exec_environment_variables"],+ "sources": ["sources"],+ "tags": ["tags"],+ "tools": ["tools"],+ }+ column_names = set()+ if includes:+ for include in includes:+ column_names.update(include_mapping.get(include, []))+ else:+ for include_relationship in include_relationships:+ column_names.update(include_mapping.get(include_relationship, []))+ return column_names++async def build_passage_query(actor: User,agent_id: Optional[str] = None,diff --git a/tests/managers/test_agent_manager.py b/tests/managers/test_agent_manager.pyindex d3183cefe..08433bc13 100644--- a/tests/managers/test_agent_manager.py+++ b/tests/managers/test_agent_manager.py@@ -1373,3 +1373,70 @@ async def test_agent_state_schema_unchanged(server: SyncServer):f"Group schema changed. Expected fields: {expected_group_fields}, "f"Got: {actual_group_fields}. Schema changes must be intentional.")+++async def test_agent_state_relationship_loads(server: SyncServer, default_user, print_tool, default_block):+ memory_blocks = [CreateBlock(label="human", value="TestUser"), CreateBlock(label="persona", value="I am a test assistant")]++ create_agent_request = CreateAgent(+ name="test_default_source_agent",+ system="test system",+ memory_blocks=memory_blocks,+ llm_config=LLMConfig.default_config("gpt-4o-mini"),+ embedding_config=EmbeddingConfig.default_config(provider="openai"),+ block_ids=[default_block.id],+ tool_ids=[print_tool.id],+ include_default_source=True,+ include_base_tools=False,+ tags=["test_tag"],+ )++ # Create the agent+ created_agent = await server.agent_manager.create_agent_async(+ create_agent_request,+ actor=default_user,+ )++ # Test legacy default include_relationships+ agent_state = await server.agent_manager.get_agent_by_id_async(+ agent_id=created_agent.id,+ actor=default_user,+ )+ assert agent_state.blocks+ assert agent_state.sources+ assert agent_state.tags+ assert agent_state.tools++ # Test include_relationships override+ agent_state = await server.agent_manager.get_agent_by_id_async(+ agent_id=created_agent.id,+ actor=default_user,+ include_relationships=[],+ )+ assert not agent_state.blocks+ assert not agent_state.sources+ assert not agent_state.tags+ assert not agent_state.tools++ # Test include_relationships override with specific relationships+ agent_state = await server.agent_manager.get_agent_by_id_async(+ agent_id=created_agent.id,+ actor=default_user,+ include_relationships=["memory", "sources"],+ )+ assert agent_state.blocks+ assert agent_state.sources+ assert not agent_state.tags+ assert not agent_state.tools++ # Test include override with specific relationships+ agent_state = await server.agent_manager.get_agent_by_id_async(+ agent_id=created_agent.id,+ actor=default_user,+ include_relationships=[],+ include=["agent.blocks", "agent.sources"],+ )+ assert agent_state.blocks+ assert agent_state.sources+ assert not agent_state.tags+ assert not agent_state.tools