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 backend support for agent relationship loads (#5693)

cthomasafdf0f80e370
diff --git a/letta/orm/agent.py b/letta/orm/agent.py
index 2f2b10157..7f5e1c625 100644
--- a/letta/orm/agent.py
+++ b/letta/orm/agent.py
@@ -282,7 +282,11 @@ class Agent(SqlalchemyBase, OrganizationMixin, ProjectMixin, TemplateEntityMixin
return 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 None
include_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, TemplateEntityMixin
return 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_set
else 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_agents
diff --git a/letta/schemas/agent.py b/letta/schemas/agent.py
index 8cfc0e4fd..844a282c3 100644
--- a/letta/schemas/agent.py
+++ b/letta/schemas/agent.py
@@ -1,6 +1,6 @@
from datetime import datetime
from enum import Enum
-from typing import Dict, List, Optional
+from typing import Dict, List, Literal, Optional
from 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.py
index 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 AccessType
from letta.otel.tracing import trace_method
from letta.prompts.prompt_generator import PromptGenerator
from 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 handling
raise
diff --git a/letta/services/helpers/agent_manager_helper.py b/letta/services/helpers/agent_manager_helper.py
index 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.py
index 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