letta-nightly 0.8.8.dev20250703104323__py3-none-any.whl → 0.8.8.dev20250703174903__py3-none-any.whl

letta/agent.py

@@ -990,6 +990,7 @@ class Agent(BaseAgent):
                 ),
                 job_id=job_id,
                 step_id=step_id,
+                project_id=self.agent_state.project_id,
             )
             for message in all_new_messages:
                 message.step_id = step.id

letta/agents/base_agent.py

@@ -67,7 +67,8 @@ class BaseAgent(ABC):
         """
         raise NotImplementedError
 
-    def pre_process_input_message(self, input_messages: List[MessageCreate]) -> Any:
+    @staticmethod
+    def pre_process_input_message(input_messages: List[MessageCreate]) -> Any:
         """
         Pre-process function to run on the input_message.
         """
@@ -97,9 +98,13 @@ class BaseAgent(ABC):
             # [DB Call] loading blocks (modifies: agent_state.memory.blocks)
             await self.agent_manager.refresh_memory_async(agent_state=agent_state, actor=self.actor)
 
+            tool_constraint_block = None
+            if tool_rules_solver is not None:
+                tool_constraint_block = tool_rules_solver.compile_tool_rule_prompts()
+
             # TODO: This is a pretty brittle pattern established all over our code, need to get rid of this
             curr_system_message = in_context_messages[0]
-            curr_memory_str = agent_state.memory.compile()
+            curr_memory_str = agent_state.memory.compile(tool_usage_rules=tool_constraint_block, sources=agent_state.sources)
             curr_system_message_text = curr_system_message.content[0].text
             if curr_memory_str in curr_system_message_text:
                 logger.debug(
@@ -124,6 +129,7 @@ class BaseAgent(ABC):
                 previous_message_count=num_messages - len(in_context_messages),
                 archival_memory_size=num_archival_memories,
                 tool_rules_solver=tool_rules_solver,
+                sources=agent_state.sources,
             )
 
             diff = united_diff(curr_system_message_text, new_system_message_str)

letta/agents/ephemeral_summary_agent.py

@@ -1,27 +1,28 @@
-from pathlib import Path
-from typing import AsyncGenerator, Dict, List
-
-from openai import AsyncOpenAI
+from typing import AsyncGenerator, List
 
 from letta.agents.base_agent import BaseAgent
 from letta.constants import DEFAULT_MAX_STEPS
+from letta.helpers.message_helper import convert_message_creates_to_messages
+from letta.llm_api.llm_client import LLMClient
+from letta.log import get_logger
 from letta.orm.errors import NoResultFound
+from letta.prompts.gpt_system import get_system_text
 from letta.schemas.block import Block, BlockUpdate
 from letta.schemas.enums import MessageRole
 from letta.schemas.letta_message_content import TextContent
 from letta.schemas.message import Message, MessageCreate
-from letta.schemas.openai.chat_completion_request import ChatCompletionRequest
 from letta.schemas.user import User
 from letta.services.agent_manager import AgentManager
 from letta.services.block_manager import BlockManager
 from letta.services.message_manager import MessageManager
 
+logger = get_logger(__name__)
+
 
 class EphemeralSummaryAgent(BaseAgent):
     """
-    A stateless summarization agent (thin wrapper around OpenAI)
-
-    # TODO: Extend to more clients
+    A stateless summarization agent that utilizes the caller's LLM client to summarize the conversation.
+    TODO (cliandy): allow the summarizer to use another llm_config from the main agent maybe?
     """
 
     def __init__(
@@ -35,7 +36,7 @@ class EphemeralSummaryAgent(BaseAgent):
     ):
         super().__init__(
             agent_id=agent_id,
-            openai_client=AsyncOpenAI(),
+            openai_client=None,
             message_manager=message_manager,
             agent_manager=agent_manager,
             actor=actor,
@@ -65,17 +66,33 @@ class EphemeralSummaryAgent(BaseAgent):
             input_message = input_messages[0]
             input_message.content[0].text += f"\n\n--- Previous Summary ---\n{block.value}\n"
 
-        openai_messages = self.pre_process_input_message(input_messages=input_messages)
-        request = self._build_openai_request(openai_messages)
+        # Gets the LLMCLient based on the calling agent's LLM Config
+        agent_state = await self.agent_manager.get_agent_by_id_async(agent_id=self.agent_id, actor=self.actor)
+        llm_client = LLMClient.create(
+            provider_type=agent_state.llm_config.model_endpoint_type,
+            put_inner_thoughts_first=True,
+            actor=self.actor,
+        )
 
-        # TODO: Extend to generic client
-        chat_completion = await self.openai_client.chat.completions.create(**request.model_dump(exclude_unset=True))
-        summary = chat_completion.choices[0].message.content.strip()
+        system_message_create = MessageCreate(
+            role=MessageRole.system,
+            content=[TextContent(text=get_system_text("summary_system_prompt"))],
+        )
+        messages = convert_message_creates_to_messages(
+            message_creates=[system_message_create] + input_messages,
+            agent_id=self.agent_id,
+            timezone=agent_state.timezone,
+        )
+
+        request_data = llm_client.build_request_data(messages, agent_state.llm_config, tools=[])
+        response_data = await llm_client.request_async(request_data, agent_state.llm_config)
+        response = llm_client.convert_response_to_chat_completion(response_data, messages, agent_state.llm_config)
+        summary = response.choices[0].message.content.strip()
 
         await self.block_manager.update_block_async(block_id=block.id, block_update=BlockUpdate(value=summary), actor=self.actor)
 
-        print(block)
-        print(summary)
+        logger.debug("block:", block)
+        logger.debug("summary:", summary)
 
         return [
             Message(
@@ -84,22 +101,5 @@ class EphemeralSummaryAgent(BaseAgent):
             )
         ]
 
-    def _build_openai_request(self, openai_messages: List[Dict]) -> ChatCompletionRequest:
-        current_dir = Path(__file__).parent
-        file_path = current_dir / "prompts" / "summary_system_prompt.txt"
-        with open(file_path, "r") as file:
-            system = file.read()
-
-        system_message = [{"role": "system", "content": system}]
-
-        openai_request = ChatCompletionRequest(
-            model="gpt-4o",
-            messages=system_message + openai_messages,
-            user=self.actor.id,
-            max_completion_tokens=4096,
-            temperature=0.7,
-        )
-        return openai_request
-
     async def step_stream(self, input_messages: List[MessageCreate], max_steps: int = DEFAULT_MAX_STEPS) -> AsyncGenerator[str, None]:
         raise NotImplementedError("EphemeralAgent does not support async step.")

letta/agents/letta_agent.py

@@ -1,8 +1,9 @@
 import asyncio
 import json
 import uuid
+from collections.abc import AsyncGenerator
 from datetime import datetime
-from typing import AsyncGenerator, Dict, List, Optional, Tuple, Union
+from typing import Optional
 
 from openai import AsyncStream
 from openai.types.chat import ChatCompletionChunk
@@ -34,7 +35,7 @@ from letta.otel.context import get_ctx_attributes
 from letta.otel.metric_registry import MetricRegistry
 from letta.otel.tracing import log_event, trace_method, tracer
 from letta.schemas.agent import AgentState, UpdateAgent
-from letta.schemas.enums import MessageRole, ProviderType
+from letta.schemas.enums import JobStatus, MessageRole, ProviderType
 from letta.schemas.letta_message import MessageType
 from letta.schemas.letta_message_content import OmittedReasoningContent, ReasoningContent, RedactedReasoningContent, TextContent
 from letta.schemas.letta_response import LettaResponse
@@ -58,14 +59,17 @@ from letta.services.summarizer.enums import SummarizationMode
 from letta.services.summarizer.summarizer import Summarizer
 from letta.services.telemetry_manager import NoopTelemetryManager, TelemetryManager
 from letta.services.tool_executor.tool_execution_manager import ToolExecutionManager
-from letta.settings import model_settings
+from letta.settings import model_settings, settings, summarizer_settings
 from letta.system import package_function_response
 from letta.types import JsonDict
 from letta.utils import log_telemetry, validate_function_response
 
+logger = get_logger(__name__)
+
+DEFAULT_SUMMARY_BLOCK_LABEL = "conversation_summary"
 
-class LettaAgent(BaseAgent):
 
+class LettaAgent(BaseAgent):
     def __init__(
         self,
         agent_id: str,
@@ -77,11 +81,12 @@ class LettaAgent(BaseAgent):
         actor: User,
         step_manager: StepManager = NoopStepManager(),
         telemetry_manager: TelemetryManager = NoopTelemetryManager(),
-        summary_block_label: str = "conversation_summary",
-        message_buffer_limit: int = 60,  # TODO: Make this configurable
-        message_buffer_min: int = 15,  # TODO: Make this configurable
-        enable_summarization: bool = True,  # TODO: Make this configurable
-        max_summarization_retries: int = 3,  # TODO: Make this configurable
+        current_run_id: str | None = None,
+        summary_block_label: str = DEFAULT_SUMMARY_BLOCK_LABEL,
+        message_buffer_limit: int = summarizer_settings.message_buffer_limit,
+        message_buffer_min: int = summarizer_settings.message_buffer_min,
+        enable_summarization: bool = summarizer_settings.enable_summarization,
+        max_summarization_retries: int = summarizer_settings.max_summarization_retries,
     ):
         super().__init__(agent_id=agent_id, openai_client=None, message_manager=message_manager, agent_manager=agent_manager, actor=actor)
 
@@ -92,7 +97,9 @@ class LettaAgent(BaseAgent):
         self.passage_manager = passage_manager
         self.step_manager = step_manager
         self.telemetry_manager = telemetry_manager
-        self.response_messages: List[Message] = []
+        self.job_manager = job_manager
+        self.current_run_id = current_run_id
+        self.response_messages: list[Message] = []
 
         self.last_function_response = None
 
@@ -117,23 +124,42 @@ class LettaAgent(BaseAgent):
             )
 
         self.summarizer = Summarizer(
-            mode=SummarizationMode.STATIC_MESSAGE_BUFFER,
+            mode=SummarizationMode(summarizer_settings.mode),
             summarizer_agent=self.summarization_agent,
             # TODO: Make this configurable
             message_buffer_limit=message_buffer_limit,
             message_buffer_min=message_buffer_min,
         )
 
+    async def _check_run_cancellation(self) -> bool:
+        """
+        Check if the current run associated with this agent execution has been cancelled.
+
+        Returns:
+            True if the run is cancelled, False otherwise (or if no run is associated)
+        """
+        if not self.job_manager or not self.current_run_id:
+            return False
+
+        try:
+            job = await self.job_manager.get_job_by_id_async(job_id=self.current_run_id, actor=self.actor)
+            return job.status == JobStatus.cancelled
+        except Exception as e:
+            # Log the error but don't fail the execution
+            logger.warning(f"Failed to check job cancellation status for job {self.current_run_id}: {e}")
+            return False
+
     @trace_method
     async def step(
         self,
-        input_messages: List[MessageCreate],
+        input_messages: list[MessageCreate],
         max_steps: int = DEFAULT_MAX_STEPS,
-        run_id: Optional[str] = None,
+        run_id: str | None = None,
         use_assistant_message: bool = True,
-        request_start_timestamp_ns: Optional[int] = None,
-        include_return_message_types: Optional[List[MessageType]] = None,
+        request_start_timestamp_ns: int | None = None,
+        include_return_message_types: list[MessageType] | None = None,
     ) -> LettaResponse:
+        # TODO (cliandy): pass in run_id and use at send_message endpoints for all step functions
         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
         )
@@ -155,11 +181,11 @@ class LettaAgent(BaseAgent):
     @trace_method
     async def step_stream_no_tokens(
         self,
-        input_messages: List[MessageCreate],
+        input_messages: list[MessageCreate],
         max_steps: int = DEFAULT_MAX_STEPS,
         use_assistant_message: bool = True,
-        request_start_timestamp_ns: Optional[int] = None,
-        include_return_message_types: Optional[List[MessageType]] = None,
+        request_start_timestamp_ns: int | None = None,
+        include_return_message_types: list[MessageType] | None = 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
@@ -182,6 +208,13 @@ class LettaAgent(BaseAgent):
         request_span.set_attributes({f"llm_config.{k}": v for k, v in agent_state.llm_config.model_dump().items() if v is not None})
 
         for i in range(max_steps):
+            # Check for job cancellation at the start of each step
+            if await self._check_run_cancellation():
+                stop_reason = LettaStopReason(stop_reason=StopReasonType.cancelled.value)
+                logger.info(f"Agent execution cancelled for run {self.current_run_id}")
+                yield f"data: {stop_reason.model_dump_json()}\n\n"
+                break
+
             step_id = generate_step_id()
             step_start = get_utc_timestamp_ns()
             agent_step_span = tracer.start_span("agent_step", start_time=step_start)
@@ -313,11 +346,11 @@ class LettaAgent(BaseAgent):
     async def _step(
         self,
         agent_state: AgentState,
-        input_messages: List[MessageCreate],
+        input_messages: list[MessageCreate],
         max_steps: int = DEFAULT_MAX_STEPS,
-        run_id: Optional[str] = None,
-        request_start_timestamp_ns: Optional[int] = None,
-    ) -> Tuple[List[Message], List[Message], Optional[LettaStopReason], LettaUsageStatistics]:
+        run_id: str | None = None,
+        request_start_timestamp_ns: int | None = None,
+    ) -> tuple[list[Message], list[Message], LettaStopReason | None, LettaUsageStatistics]:
         """
         Carries out an invocation of the agent loop. In each step, the agent
             1. Rebuilds its memory
@@ -343,6 +376,12 @@ class LettaAgent(BaseAgent):
         stop_reason = None
         usage = LettaUsageStatistics()
         for i in range(max_steps):
+            # Check for job cancellation at the start of each step
+            if await self._check_run_cancellation():
+                stop_reason = LettaStopReason(stop_reason=StopReasonType.cancelled.value)
+                logger.info(f"Agent execution cancelled for run {self.current_run_id}")
+                break
+
             step_id = generate_step_id()
             step_start = get_utc_timestamp_ns()
             agent_step_span = tracer.start_span("agent_step", start_time=step_start)
@@ -425,7 +464,7 @@ class LettaAgent(BaseAgent):
                 ),
             )
 
-            MetricRegistry().step_execution_time_ms_histogram.record(step_start - get_utc_timestamp_ns(), get_ctx_attributes())
+            MetricRegistry().step_execution_time_ms_histogram.record(get_utc_timestamp_ns() - step_start, get_ctx_attributes())
 
             if not should_continue:
                 break
@@ -455,6 +494,8 @@ class LettaAgent(BaseAgent):
         return current_in_context_messages, new_in_context_messages, stop_reason, usage
 
     async def _update_agent_last_run_metrics(self, completion_time: datetime, duration_ms: float) -> None:
+        if not settings.track_last_agent_run:
+            return
         try:
             await self.agent_manager.update_agent_async(
                 agent_id=self.agent_id,
@@ -467,11 +508,11 @@ class LettaAgent(BaseAgent):
     @trace_method
     async def step_stream(
         self,
-        input_messages: List[MessageCreate],
+        input_messages: list[MessageCreate],
         max_steps: int = DEFAULT_MAX_STEPS,
         use_assistant_message: bool = True,
-        request_start_timestamp_ns: Optional[int] = None,
-        include_return_message_types: Optional[List[MessageType]] = None,
+        request_start_timestamp_ns: int | None = None,
+        include_return_message_types: list[MessageType] | None = None,
     ) -> AsyncGenerator[str, None]:
         """
         Carries out an invocation of the agent loop in a streaming fashion that yields partial tokens.
@@ -503,6 +544,13 @@ class LettaAgent(BaseAgent):
             request_span.set_attributes({f"llm_config.{k}": v for k, v in agent_state.llm_config.model_dump().items() if v is not None})
 
         for i in range(max_steps):
+            # Check for job cancellation at the start of each step
+            if await self._check_run_cancellation():
+                stop_reason = LettaStopReason(stop_reason=StopReasonType.cancelled.value)
+                logger.info(f"Agent execution cancelled for run {self.current_run_id}")
+                yield f"data: {stop_reason.model_dump_json()}\n\n"
+                break
+
             step_id = generate_step_id()
             step_start = get_utc_timestamp_ns()
             agent_step_span = tracer.start_span("agent_step", start_time=step_start)
@@ -543,7 +591,9 @@ class LettaAgent(BaseAgent):
                 raise ValueError(f"Streaming not supported for {agent_state.llm_config}")
 
             async for chunk in interface.process(
-                stream, ttft_span=request_span, provider_request_start_timestamp_ns=provider_request_start_timestamp_ns
+                stream,
+                ttft_span=request_span,
+                provider_request_start_timestamp_ns=provider_request_start_timestamp_ns,
             ):
                 # Measure time to first token
                 if first_chunk and request_span is not None:
@@ -653,7 +703,7 @@ class LettaAgent(BaseAgent):
                     yield f"data: {tool_return.model_dump_json()}\n\n"
 
             # TODO (cliandy): consolidate and expand with trace
-            MetricRegistry().step_execution_time_ms_histogram.record(step_start - get_utc_timestamp_ns(), get_ctx_attributes())
+            MetricRegistry().step_execution_time_ms_histogram.record(get_utc_timestamp_ns() - step_start, get_ctx_attributes())
 
             if not should_continue:
                 break
@@ -686,13 +736,13 @@ class LettaAgent(BaseAgent):
     # noinspection PyInconsistentReturns
     async def _build_and_request_from_llm(
         self,
-        current_in_context_messages: List[Message],
-        new_in_context_messages: List[Message],
+        current_in_context_messages: list[Message],
+        new_in_context_messages: list[Message],
         agent_state: AgentState,
         llm_client: LLMClientBase,
         tool_rules_solver: ToolRulesSolver,
         agent_step_span: "Span",
-    ) -> Tuple[Dict, Dict, List[Message], List[Message], List[str]] | None:
+    ) -> tuple[dict, dict, list[Message], list[Message], list[str]] | None:
         for attempt in range(self.max_summarization_retries + 1):
             try:
                 log_event("agent.stream_no_tokens.messages.refreshed")
@@ -738,12 +788,12 @@ class LettaAgent(BaseAgent):
         first_chunk: bool,
         ttft_span: "Span",
         request_start_timestamp_ns: int,
-        current_in_context_messages: List[Message],
-        new_in_context_messages: List[Message],
+        current_in_context_messages: list[Message],
+        new_in_context_messages: list[Message],
         agent_state: AgentState,
         llm_client: LLMClientBase,
         tool_rules_solver: ToolRulesSolver,
-    ) -> Tuple[Dict, AsyncStream[ChatCompletionChunk], List[Message], List[Message], List[str], int] | None:
+    ) -> tuple[dict, AsyncStream[ChatCompletionChunk], list[Message], list[Message], list[str], int] | None:
         for attempt in range(self.max_summarization_retries + 1):
             try:
                 log_event("agent.stream_no_tokens.messages.refreshed")
@@ -795,11 +845,11 @@ class LettaAgent(BaseAgent):
         self,
         e: Exception,
         llm_client: LLMClientBase,
-        in_context_messages: List[Message],
-        new_letta_messages: List[Message],
+        in_context_messages: list[Message],
+        new_letta_messages: list[Message],
         llm_config: LLMConfig,
         force: bool,
-    ) -> List[Message]:
+    ) -> list[Message]:
         if isinstance(e, ContextWindowExceededError):
             return await self._rebuild_context_window(
                 in_context_messages=in_context_messages, new_letta_messages=new_letta_messages, llm_config=llm_config, force=force
@@ -810,12 +860,12 @@ class LettaAgent(BaseAgent):
     @trace_method
     async def _rebuild_context_window(
         self,
-        in_context_messages: List[Message],
-        new_letta_messages: List[Message],
+        in_context_messages: list[Message],
+        new_letta_messages: list[Message],
         llm_config: LLMConfig,
-        total_tokens: Optional[int] = None,
+        total_tokens: int | None = None,
         force: bool = False,
-    ) -> List[Message]:
+    ) -> list[Message]:
         # If total tokens is reached, we truncate down
         # TODO: This can be broken by bad configs, e.g. lower bound too high, initial messages too fat, etc.
         if force or (total_tokens and total_tokens > llm_config.context_window):
@@ -851,10 +901,10 @@ class LettaAgent(BaseAgent):
     async def _create_llm_request_data_async(
         self,
         llm_client: LLMClientBase,
-        in_context_messages: List[Message],
+        in_context_messages: list[Message],
         agent_state: AgentState,
         tool_rules_solver: ToolRulesSolver,
-    ) -> Tuple[dict, List[str]]:
+    ) -> tuple[dict, list[str]]:
         self.num_messages, self.num_archival_memories = await asyncio.gather(
             (
                 self.message_manager.size_async(actor=self.actor, agent_id=agent_state.id)
@@ -925,18 +975,18 @@ class LettaAgent(BaseAgent):
     async def _handle_ai_response(
         self,
         tool_call: ToolCall,
-        valid_tool_names: List[str],
+        valid_tool_names: list[str],
         agent_state: AgentState,
         tool_rules_solver: ToolRulesSolver,
         usage: UsageStatistics,
-        reasoning_content: Optional[List[Union[TextContent, ReasoningContent, RedactedReasoningContent, OmittedReasoningContent]]] = None,
-        pre_computed_assistant_message_id: Optional[str] = None,
+        reasoning_content: list[TextContent | ReasoningContent | RedactedReasoningContent | OmittedReasoningContent] | None = None,
+        pre_computed_assistant_message_id: str | None = None,
         step_id: str | None = None,
-        initial_messages: Optional[List[Message]] = None,
+        initial_messages: list[Message] | None = None,
         agent_step_span: Optional["Span"] = None,
-        is_final_step: Optional[bool] = None,
-        run_id: Optional[str] = None,
-    ) -> Tuple[List[Message], bool, Optional[LettaStopReason]]:
+        is_final_step: bool | None = None,
+        run_id: str | None = None,
+    ) -> tuple[list[Message], bool, LettaStopReason | None]:
         """
         Handle the final AI response once streaming completes, execute / validate the
         tool call, decide whether we should keep stepping, and persist state.
@@ -1012,8 +1062,9 @@ class LettaAgent(BaseAgent):
             context_window_limit=agent_state.llm_config.context_window,
             usage=usage,
             provider_id=None,
-            job_id=run_id,
+            job_id=run_id if run_id else self.current_run_id,
             step_id=step_id,
+            project_id=agent_state.project_id,
         )
 
         tool_call_messages = create_letta_messages_from_llm_response(
@@ -1150,7 +1201,7 @@ class LettaAgent(BaseAgent):
                 name="tool_execution_completed",
                 attributes={
                     "tool_name": target_tool.name,
-                    "duration_ms": ns_to_ms((end_time - start_time)),
+                    "duration_ms": ns_to_ms(end_time - start_time),
                     "success": tool_execution_result.success_flag,
                     "tool_type": target_tool.tool_type,
                     "tool_id": target_tool.id,
@@ -1160,7 +1211,7 @@ class LettaAgent(BaseAgent):
         return tool_execution_result
 
     @trace_method
-    def _load_last_function_response(self, in_context_messages: List[Message]):
+    def _load_last_function_response(self, in_context_messages: list[Message]):
         """Load the last function response from message history"""
         for msg in reversed(in_context_messages):
             if msg.role == MessageRole.tool and msg.content and len(msg.content) == 1 and isinstance(msg.content[0], TextContent):

letta/agents/voice_agent.py

@@ -153,6 +153,7 @@ class VoiceAgent(BaseAgent):
             timezone=agent_state.timezone,
             previous_message_count=self.num_messages,
             archival_memory_size=self.num_archival_memories,
+            sources=agent_state.sources,
         )
         letta_message_db_queue = create_input_messages(
             input_messages=input_messages, agent_id=agent_state.id, timezone=agent_state.timezone, actor=self.actor
@@ -366,7 +367,7 @@ class VoiceAgent(BaseAgent):
                         "description": (
                             "Look in long-term or earlier-conversation memory **only when** the "
                             "user asks about something missing from the visible context. "
-                            "The user’s latest utterance is sent automatically as the main query.\n\n"
+                            "The user's latest utterance is sent automatically as the main query.\n\n"
                             "Optional refinements (set unused fields to *null*):\n"
                             "• `convo_keyword_queries`   – extra names/IDs if the request is vague.\n"
                             "• `start_minutes_ago` / `end_minutes_ago` – limit results to a recent time window."

letta/constants.py

@@ -83,7 +83,7 @@ SEND_MESSAGE_TOOL_NAME = "send_message"
 # Base tools that cannot be edited, as they access agent state directly
 # Note that we don't include "conversation_search_date" for now
 BASE_TOOLS = [SEND_MESSAGE_TOOL_NAME, "conversation_search", "archival_memory_insert", "archival_memory_search"]
-DEPRECATED_BASE_TOOLS = ["archival_memory_insert", "archival_memory_search"]
+DEPRECATED_LETTA_TOOLS = ["archival_memory_insert", "archival_memory_search"]
 # Base memory tools CAN be edited, and are added by default by the server
 BASE_MEMORY_TOOLS = ["core_memory_append", "core_memory_replace"]
 # New v2 collection of the base memory tools (effecitvely same as sleeptime set), to pair with memgpt_v2 prompt
@@ -115,7 +115,8 @@ BASE_VOICE_SLEEPTIME_TOOLS = [
     "finish_rethinking_memory",
 ]
 # Multi agent tools
-MULTI_AGENT_TOOLS = ["send_message_to_agent_and_wait_for_reply", "send_message_to_agents_matching_tags"]
+MULTI_AGENT_TOOLS = ["send_message_to_agent_and_wait_for_reply", "send_message_to_agents_matching_tags", "send_message_to_agent_async"]
+LOCAL_ONLY_MULTI_AGENT_TOOLS = ["send_message_to_agent_async"]
 
 # Used to catch if line numbers are pushed in
 # MEMORY_TOOLS_LINE_NUMBER_PREFIX_REGEX = re.compile(r"^Line \d+: ", re.MULTILINE)
@@ -130,7 +131,7 @@ MEMORY_TOOLS_LINE_NUMBER_PREFIX_REGEX = re.compile(
 BUILTIN_TOOLS = ["run_code", "web_search"]
 
 # Built in tools
-FILES_TOOLS = ["open_files", "grep_files", "search_files"]
+FILES_TOOLS = ["open_files", "grep_files", "semantic_search_files"]
 
 FILE_MEMORY_EXISTS_MESSAGE = "The following files are currently accessible in memory:"
 FILE_MEMORY_EMPTY_MESSAGE = (
@@ -325,7 +326,7 @@ MAX_ERROR_MESSAGE_CHAR_LIMIT = 500
 CORE_MEMORY_PERSONA_CHAR_LIMIT: int = 5000
 CORE_MEMORY_HUMAN_CHAR_LIMIT: int = 5000
 CORE_MEMORY_BLOCK_CHAR_LIMIT: int = 5000
-CORE_MEMORY_SOURCE_CHAR_LIMIT: int = 5000
+CORE_MEMORY_SOURCE_CHAR_LIMIT: int = 50000
 # Function return limits
 FUNCTION_RETURN_CHAR_LIMIT = 6000  # ~300 words
 BASE_FUNCTION_RETURN_CHAR_LIMIT = 1000000  # very high (we rely on implementation)
@@ -357,6 +358,9 @@ REDIS_INCLUDE = "include"
 REDIS_EXCLUDE = "exclude"
 REDIS_SET_DEFAULT_VAL = "None"
 REDIS_DEFAULT_CACHE_PREFIX = "letta_cache"
+REDIS_RUN_ID_PREFIX = "agent:send_message:run_id"
 
 # TODO: This is temporary, eventually use token-based eviction
 MAX_FILES_OPEN = 5
+
+GET_PROVIDERS_TIMEOUT_SECONDS = 10

letta/functions/function_sets/files.py

@@ -10,15 +10,20 @@ if TYPE_CHECKING:
 async def open_files(agent_state: "AgentState", file_requests: List[FileOpenRequest], close_all_others: bool = False) -> str:
     """Open one or more files and load their contents into files section in core memory. Maximum of 5 files can be opened simultaneously.
 
+    Use this when you want to:
+    - Inspect or reference file contents during reasoning
+    - View specific portions of large files (e.g. functions or definitions)
+    - Replace currently open files with a new set for focused context (via `close_all_others=True`)
+
     Examples:
-        Open single file (entire content):
-            file_requests = [FileOpenRequest(file_name="config.py")]
+        Open single file belonging to a directory named `project_utils` (entire content):
+            file_requests = [FileOpenRequest(file_name="project_utils/config.py")]
 
         Open multiple files with different view ranges:
             file_requests = [
-                FileOpenRequest(file_name="config.py", offset=1, length=50),     # Lines 1-50
-                FileOpenRequest(file_name="main.py", offset=100, length=100),    # Lines 100-199
-                FileOpenRequest(file_name="utils.py")                            # Entire file
+                FileOpenRequest(file_name="project_utils/config.py", offset=1, length=50),     # Lines 1-50
+                FileOpenRequest(file_name="project_utils/main.py", offset=100, length=100),    # Lines 100-199
+                FileOpenRequest(file_name="project_utils/utils.py")                            # Entire file
             ]
 
         Close all other files and open new ones:
@@ -43,6 +48,11 @@ async def grep_files(
     """
     Grep tool to search files across data sources using a keyword or regex pattern.
 
+    Use this when you want to:
+    - Quickly find occurrences of a variable, function, or keyword
+    - Locate log messages, error codes, or TODOs across files
+    - Understand surrounding code by including `context_lines`
+
     Args:
         pattern (str): Keyword or regex pattern to search within file contents.
         include (Optional[str]): Optional keyword or regex pattern to filter filenames to include in the search.
@@ -55,9 +65,14 @@ async def grep_files(
     raise NotImplementedError("Tool not implemented. Please contact the Letta team.")
 
 
-async def search_files(agent_state: "AgentState", query: str) -> List["FileMetadata"]:
+async def semantic_search_files(agent_state: "AgentState", query: str) -> List["FileMetadata"]:
     """
-    Get list of most relevant files across all data sources using embedding search.
+    Get list of most relevant chunks from any file using vector/embedding search.
+
+    Use this when you want to:
+    - Find related content that without using exact keywords (e.g., conceptually similar sections)
+    - Look up high-level descriptions, documentation, or config patterns
+    - Perform fuzzy search when grep isn't sufficient
 
     Args:
         query (str): The search query.