Platform for stateful agents: AI with advanced memory that can learn and self-improve over time.
feat: add `include_return_message_types` to `LettaRequest` to filter down requests (#2666)
Sarah Wooders3e6729214b9d
diff --git a/letta/agents/helpers.py b/letta/agents/helpers.pyindex 0d653813f..5e96996ac 100644--- a/letta/agents/helpers.py+++ b/letta/agents/helpers.py@@ -1,8 +1,9 @@import uuidimport xml.etree.ElementTree as ET-from typing import List, Tuple+from typing import List, Optional, Tuplefrom letta.schemas.agent import AgentState+from letta.schemas.letta_message import MessageTypefrom letta.schemas.letta_response import LettaResponsefrom letta.schemas.message import Message, MessageCreatefrom letta.schemas.usage import LettaUsageStatistics@@ -12,16 +13,26 @@ from letta.services.message_manager import MessageManagerdef _create_letta_response(- new_in_context_messages: list[Message], use_assistant_message: bool, usage: LettaUsageStatistics+ new_in_context_messages: list[Message],+ use_assistant_message: bool,+ usage: LettaUsageStatistics,+ include_return_message_types: Optional[List[MessageType]] = None,) -> LettaResponse:"""Converts the newly created/persisted messages into a LettaResponse."""# NOTE: hacky solution to avoid returning heartbeat messages and the original user messagefilter_user_messages = [m for m in new_in_context_messages if m.role != "user"]++ # Convert to Letta messages firstresponse_messages = Message.to_letta_messages_from_list(messages=filter_user_messages, use_assistant_message=use_assistant_message, reverse=False)++ # Apply message type filtering if specified+ if include_return_message_types is not None:+ response_messages = [msg for msg in response_messages if msg.message_type in include_return_message_types]+return LettaResponse(messages=response_messages, usage=usage)diff --git a/letta/agents/letta_agent.py b/letta/agents/letta_agent.pyindex 93a575c1a..79e644077 100644--- a/letta/agents/letta_agent.py+++ b/letta/agents/letta_agent.py@@ -30,6 +30,7 @@ from letta.otel.metric_registry import MetricRegistryfrom letta.otel.tracing import log_event, trace_method, tracerfrom letta.schemas.agent import AgentStatefrom letta.schemas.enums import MessageRole, MessageStreamStatus+from letta.schemas.letta_message import MessageTypefrom letta.schemas.letta_message_content import OmittedReasoningContent, ReasoningContent, RedactedReasoningContent, TextContentfrom letta.schemas.letta_response import LettaResponsefrom letta.schemas.llm_config import LLMConfig@@ -121,6 +122,7 @@ class LettaAgent(BaseAgent):max_steps: int = 10,use_assistant_message: bool = True,request_start_timestamp_ns: Optional[int] = None,+ include_return_message_types: Optional[List[MessageType]] = None,) -> LettaResponse:agent_state = await self.agent_manager.get_agent_by_id_async(agent_id=self.agent_id, include_relationships=["tools", "memory", "tool_exec_environment_variables"], actor=self.actor@@ -132,7 +134,10 @@ class LettaAgent(BaseAgent):request_start_timestamp_ns=request_start_timestamp_ns,)return _create_letta_response(- new_in_context_messages=new_in_context_messages, use_assistant_message=use_assistant_message, usage=usage+ new_in_context_messages=new_in_context_messages,+ use_assistant_message=use_assistant_message,+ usage=usage,+ include_return_message_types=include_return_message_types,)@trace_method@@ -142,6 +147,7 @@ class LettaAgent(BaseAgent):max_steps: int = 10,use_assistant_message: bool = True,request_start_timestamp_ns: Optional[int] = None,+ include_return_message_types: Optional[List[MessageType]] = None,):agent_state = await self.agent_manager.get_agent_by_id_async(agent_id=self.agent_id, include_relationships=["tools", "memory", "tool_exec_environment_variables"], actor=self.actor@@ -250,8 +256,12 @@ class LettaAgent(BaseAgent):letta_messages = Message.to_letta_messages_from_list(filter_user_messages, use_assistant_message=use_assistant_message, reverse=False)+for message in letta_messages:- yield f"data: {message.model_dump_json()}\n\n"+ if not include_return_message_types:+ yield f"data: {message.model_dump_json()}\n\n"+ elif include_return_message_types and message.message_type in include_return_message_types:+ yield f"data: {message.model_dump_json()}\n\n"if not should_continue:break@@ -409,6 +419,7 @@ class LettaAgent(BaseAgent):max_steps: int = 10,use_assistant_message: bool = True,request_start_timestamp_ns: Optional[int] = None,+ include_return_message_types: Optional[List[MessageType]] = None,) -> AsyncGenerator[str, None]:"""Carries out an invocation of the agent loop in a streaming fashion that yields partial tokens.@@ -486,7 +497,12 @@ class LettaAgent(BaseAgent):request_span.add_event(name="time_to_first_token_ms", attributes={"ttft_ms": ns_to_ms(ttft_ns)})first_chunk = False- yield f"data: {chunk.model_dump_json()}\n\n"+ if include_return_message_types is None:+ # return all data+ yield f"data: {chunk.model_dump_json()}\n\n"+ elif include_return_message_types and chunk.message_type in include_return_message_types:+ # filter down returned data+ yield f"data: {chunk.model_dump_json()}\n\n"# update usageusage.step_count += 1@@ -563,7 +579,9 @@ class LettaAgent(BaseAgent):tool_return = [msg for msg in persisted_messages if msg.role == "tool"][-1].to_letta_messages()[0]if not (use_assistant_message and tool_return.name == "send_message"):- yield f"data: {tool_return.model_dump_json()}\n\n"+ # Apply message type filtering if specified+ if include_return_message_types is None or tool_return.message_type in include_return_message_types:+ yield f"data: {tool_return.model_dump_json()}\n\n"if not should_continue:breakdiff --git a/letta/agents/voice_sleeptime_agent.py b/letta/agents/voice_sleeptime_agent.pyindex c8ebeb989..1d5abfde2 100644--- a/letta/agents/voice_sleeptime_agent.py+++ b/letta/agents/voice_sleeptime_agent.py@@ -7,7 +7,7 @@ from letta.otel.tracing import trace_methodfrom letta.schemas.agent import AgentStatefrom letta.schemas.block import BlockUpdatefrom letta.schemas.enums import MessageStreamStatus-from letta.schemas.letta_message import LegacyLettaMessage, LettaMessage+from letta.schemas.letta_message import LegacyLettaMessage, LettaMessage, MessageTypefrom letta.schemas.letta_response import LettaResponsefrom letta.schemas.message import MessageCreatefrom letta.schemas.tool_rule import ChildToolRule, ContinueToolRule, InitToolRule, TerminalToolRule@@ -59,7 +59,13 @@ class VoiceSleeptimeAgent(LettaAgent):def update_message_transcript(self, message_transcripts: List[str]):self.message_transcripts = message_transcripts- async def step(self, input_messages: List[MessageCreate], max_steps: int = 20, use_assistant_message: bool = True) -> LettaResponse:+ async def step(+ self,+ input_messages: List[MessageCreate],+ max_steps: int = 20,+ use_assistant_message: bool = True,+ include_return_message_types: Optional[List[MessageType]] = None,+ ) -> LettaResponse:"""Process the user's input message, allowing the model to call memory-related toolsuntil it decides to stop and provide a final response.@@ -86,7 +92,10 @@ class VoiceSleeptimeAgent(LettaAgent):)return _create_letta_response(- new_in_context_messages=new_in_context_messages, use_assistant_message=use_assistant_message, usage=usage+ new_in_context_messages=new_in_context_messages,+ use_assistant_message=use_assistant_message,+ usage=usage,+ include_return_message_types=include_return_message_types,)@trace_methoddiff --git a/letta/groups/sleeptime_multi_agent_v2.py b/letta/groups/sleeptime_multi_agent_v2.pyindex 587a8ef89..c88a99773 100644--- a/letta/groups/sleeptime_multi_agent_v2.py+++ b/letta/groups/sleeptime_multi_agent_v2.py@@ -9,6 +9,7 @@ from letta.otel.tracing import trace_methodfrom letta.schemas.enums import JobStatusfrom letta.schemas.group import Group, ManagerTypefrom letta.schemas.job import JobUpdate+from letta.schemas.letta_message import MessageTypefrom letta.schemas.letta_message_content import TextContentfrom letta.schemas.letta_response import LettaResponsefrom letta.schemas.message import Message, MessageCreate@@ -63,6 +64,7 @@ class SleeptimeMultiAgentV2(BaseAgent):max_steps: int = 10,use_assistant_message: bool = True,request_start_timestamp_ns: Optional[int] = None,+ include_return_message_types: Optional[List[MessageType]] = None,) -> LettaResponse:run_ids = []@@ -87,7 +89,10 @@ class SleeptimeMultiAgentV2(BaseAgent):)# Perform foreground agent stepresponse = await foreground_agent.step(- input_messages=new_messages, max_steps=max_steps, use_assistant_message=use_assistant_message+ input_messages=new_messages,+ max_steps=max_steps,+ use_assistant_message=use_assistant_message,+ include_return_message_types=include_return_message_types,)# Get last response messages@@ -129,8 +134,11 @@ class SleeptimeMultiAgentV2(BaseAgent):max_steps: int = 10,use_assistant_message: bool = True,request_start_timestamp_ns: Optional[int] = None,+ include_return_message_types: Optional[List[MessageType]] = None,):- response = await self.step(input_messages, max_steps, use_assistant_message)+ response = await self.step(+ input_messages, max_steps, use_assistant_message, request_start_timestamp_ns, include_return_message_types+ )for message in response.messages:yield f"data: {message.model_dump_json()}\n\n"@@ -144,6 +152,7 @@ class SleeptimeMultiAgentV2(BaseAgent):max_steps: int = 10,use_assistant_message: bool = True,request_start_timestamp_ns: Optional[int] = None,+ include_return_message_types: Optional[List[MessageType]] = None,) -> AsyncGenerator[str, None]:# Prepare new messagesnew_messages = []@@ -170,6 +179,7 @@ class SleeptimeMultiAgentV2(BaseAgent):max_steps=max_steps,use_assistant_message=use_assistant_message,request_start_timestamp_ns=request_start_timestamp_ns,+ include_return_message_types=include_return_message_types,):yield chunkdiff --git a/letta/schemas/letta_request.py b/letta/schemas/letta_request.pyindex 6774b3599..b7c4117fc 100644--- a/letta/schemas/letta_request.py+++ b/letta/schemas/letta_request.py@@ -3,6 +3,7 @@ from typing import List, Optionalfrom pydantic import BaseModel, Field, HttpUrlfrom letta.constants import DEFAULT_MESSAGE_TOOL, DEFAULT_MESSAGE_TOOL_KWARG+from letta.schemas.letta_message import MessageTypefrom letta.schemas.message import MessageCreate@@ -21,6 +22,11 @@ class LettaRequest(BaseModel):description="The name of the message argument in the designated message tool.",)+ # filter to only return specific message types+ include_return_message_types: Optional[List[MessageType]] = Field(+ default=None, description="Only return specified message types in the response. If `None` (default) returns all messages."+ )+class LettaStreamingRequest(LettaRequest):stream_tokens: bool = Field(diff --git a/letta/server/rest_api/routers/v1/agents.py b/letta/server/rest_api/routers/v1/agents.pyindex 4fc29bad1..b7dfeb9a3 100644--- a/letta/server/rest_api/routers/v1/agents.py+++ b/letta/server/rest_api/routers/v1/agents.py@@ -23,7 +23,7 @@ from letta.schemas.agent import AgentState, AgentType, CreateAgent, UpdateAgentfrom letta.schemas.block import Block, BlockUpdatefrom letta.schemas.group import Groupfrom letta.schemas.job import JobStatus, JobUpdate, LettaRequestConfig-from letta.schemas.letta_message import LettaMessageUnion, LettaMessageUpdateUnion+from letta.schemas.letta_message import LettaMessageUnion, LettaMessageUpdateUnion, MessageTypefrom letta.schemas.letta_request import LettaRequest, LettaStreamingRequestfrom letta.schemas.letta_response import LettaResponsefrom letta.schemas.memory import ContextWindowOverview, CreateArchivalMemory, Memory@@ -704,6 +704,7 @@ async def send_message(max_steps=10,use_assistant_message=request.use_assistant_message,request_start_timestamp_ns=request_start_timestamp_ns,+ include_return_message_types=request.include_return_message_types,)else:result = await server.send_message_to_agent(@@ -716,6 +717,7 @@ async def send_message(use_assistant_message=request.use_assistant_message,assistant_message_tool_name=request.assistant_message_tool_name,assistant_message_tool_kwarg=request.assistant_message_tool_kwarg,+ include_return_message_types=request.include_return_message_types,)return result@@ -791,6 +793,7 @@ async def send_message_streaming(max_steps=10,use_assistant_message=request.use_assistant_message,request_start_timestamp_ns=request_start_timestamp_ns,+ include_return_message_types=request.include_return_message_types,),media_type="text/event-stream",)@@ -801,6 +804,7 @@ async def send_message_streaming(max_steps=10,use_assistant_message=request.use_assistant_message,request_start_timestamp_ns=request_start_timestamp_ns,+ include_return_message_types=request.include_return_message_types,),media_type="text/event-stream",)@@ -816,6 +820,7 @@ async def send_message_streaming(assistant_message_tool_name=request.assistant_message_tool_name,assistant_message_tool_kwarg=request.assistant_message_tool_kwarg,request_start_timestamp_ns=request_start_timestamp_ns,+ include_return_message_types=request.include_return_message_types,)return result@@ -830,6 +835,7 @@ async def process_message_background(use_assistant_message: bool,assistant_message_tool_name: str,assistant_message_tool_kwarg: str,+ include_return_message_types: Optional[List[MessageType]] = None,) -> None:"""Background task to process the message and update job status."""try:@@ -845,6 +851,7 @@ async def process_message_background(assistant_message_tool_kwarg=assistant_message_tool_kwarg,metadata={"job_id": job_id}, # Pass job_id through metadatarequest_start_timestamp_ns=request_start_timestamp_ns,+ include_return_message_types=include_return_message_types,)# Update job status to completed@@ -912,6 +919,7 @@ async def send_message_async(use_assistant_message=request.use_assistant_message,assistant_message_tool_name=request.assistant_message_tool_name,assistant_message_tool_kwarg=request.assistant_message_tool_kwarg,+ include_return_message_types=request.include_return_message_types,)return rundiff --git a/letta/server/server.py b/letta/server/server.pyindex 3b417542b..1ee944d3c 100644--- a/letta/server/server.py+++ b/letta/server/server.py@@ -45,7 +45,7 @@ from letta.schemas.enums import JobStatus, MessageStreamStatus, ProviderCategoryfrom letta.schemas.environment_variables import SandboxEnvironmentVariableCreatefrom letta.schemas.group import GroupCreate, ManagerType, SleeptimeManager, VoiceSleeptimeManagerfrom letta.schemas.job import Job, JobUpdate-from letta.schemas.letta_message import LegacyLettaMessage, LettaMessage, ToolReturnMessage+from letta.schemas.letta_message import LegacyLettaMessage, LettaMessage, MessageType, ToolReturnMessagefrom letta.schemas.letta_message_content import TextContentfrom letta.schemas.letta_response import LettaResponsefrom letta.schemas.llm_config import LLMConfig@@ -2237,6 +2237,7 @@ class SyncServer(Server):assistant_message_tool_kwarg: str = constants.DEFAULT_MESSAGE_TOOL_KWARG,metadata: Optional[dict] = None,request_start_timestamp_ns: Optional[int] = None,+ include_return_message_types: Optional[List[MessageType]] = None,) -> Union[StreamingResponse, LettaResponse]:"""Split off into a separate function so that it can be imported in the /chat/completion proxy."""# TODO: @charles is this the correct way to handle?@@ -2342,6 +2343,11 @@ class SyncServer(Server):# Get rid of the stream status messagesfiltered_stream = [d for d in generated_stream if not isinstance(d, MessageStreamStatus)]++ # Apply message type filtering if specified+ if include_return_message_types is not None:+ filtered_stream = [msg for msg in filtered_stream if msg.message_type in include_return_message_types]+usage = await task# By default the stream will be messages of type LettaMessage or LettaLegacyMessagediff --git a/tests/test_sdk_client.py b/tests/test_sdk_client.pyindex befab5df4..943e779b5 100644--- a/tests/test_sdk_client.py+++ b/tests/test_sdk_client.py@@ -679,3 +679,86 @@ def test_many_blocks(client: LettaSDKClient):client.agents.delete(agent1.id)client.agents.delete(agent2.id)+++# cases: steam, async, token stream, sync[email protected]("message_create", ["stream_step", "token_stream", "sync"])+def test_include_return_message_types(client: LettaSDKClient, agent: AgentState, message_create: str):+ """Test that the include_return_message_types parameter works"""++ def verify_message_types(messages, message_types):+ for message in messages:+ assert message.message_type in message_types++ message = "My name is actually Sarah"+ message_types = ["reasoning_message", "tool_call_message"]+ agent = client.agents.create(+ memory_blocks=[+ CreateBlock(label="user", value="Name: Charles"),+ ],+ model="letta/letta-free",+ embedding="letta/letta-free",+ )++ if message_create == "stream_step":+ response = client.agents.messages.create_stream(+ agent_id=agent.id,+ messages=[+ MessageCreate(+ role="user",+ content=message,+ ),+ ],+ include_return_message_types=message_types,+ )+ messages = [message for message in list(response) if message.message_type != "usage_statistics"]+ verify_message_types(messages, message_types)++ elif message_create == "async":+ response = client.agents.messages.create_async(+ agent_id=agent.id,+ messages=[+ MessageCreate(+ role="user",+ content=message,+ )+ ],+ include_return_message_types=message_types,+ )+ # wait to finish+ while response.status != "completed":+ time.sleep(1)+ response = client.runs.retrieve(run_id=response.id)+ messages = client.runs.messages.list(run_id=response.id)+ verify_message_types(messages, message_types)++ elif message_create == "token_stream":+ response = client.agents.messages.create_stream(+ agent_id=agent.id,+ messages=[+ MessageCreate(+ role="user",+ content=message,+ ),+ ],+ include_return_message_types=message_types,+ )+ messages = [message for message in list(response) if message.message_type != "usage_statistics"]+ verify_message_types(messages, message_types)++ elif message_create == "sync":+ response = client.agents.messages.create(+ agent_id=agent.id,+ messages=[+ MessageCreate(+ role="user",+ content=message,+ ),+ ],+ include_return_message_types=message_types,+ )+ messages = response.messages+ verify_message_types(messages, message_types)++ # cleanup+ client.agents.delete(agent.id)