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

letta/services/files_agents_manager.py

@@ -4,15 +4,19 @@ from typing import List, Optional
 from sqlalchemy import and_, func, select, update
 
 from letta.constants import MAX_FILES_OPEN
+from letta.log import get_logger
 from letta.orm.errors import NoResultFound
 from letta.orm.files_agents import FileAgent as FileAgentModel
 from letta.otel.tracing import trace_method
 from letta.schemas.block import Block as PydanticBlock
 from letta.schemas.file import FileAgent as PydanticFileAgent
+from letta.schemas.file import FileMetadata
 from letta.schemas.user import User as PydanticUser
 from letta.server.db import db_registry
 from letta.utils import enforce_types
 
+logger = get_logger(__name__)
+
 
 class FileAgentManager:
     """High-level helpers for CRUD / listing on the `files_agents` join table."""
@@ -165,17 +169,19 @@ class FileAgentManager:
         self,
         *,
         file_names: List[str],
+        agent_id: str,
         actor: PydanticUser,
     ) -> List[PydanticBlock]:
         """
-        Retrieve multiple FileAgent associations by their IDs in a single query.
+        Retrieve multiple FileAgent associations by their file names for a specific agent.
 
         Args:
             file_names: List of file names to retrieve
+            agent_id: ID of the agent to retrieve file blocks for
             actor: The user making the request
 
         Returns:
-            List of PydanticFileAgent objects found (may be fewer than requested if some IDs don't exist)
+            List of PydanticBlock objects found (may be fewer than requested if some file names don't exist)
         """
         if not file_names:
             return []
@@ -185,6 +191,7 @@ class FileAgentManager:
             query = select(FileAgentModel).where(
                 and_(
                     FileAgentModel.file_name.in_(file_names),
+                    FileAgentModel.agent_id == agent_id,
                     FileAgentModel.organization_id == actor.organization_id,
                 )
             )
@@ -420,6 +427,117 @@ class FileAgentManager:
 
             return closed_file_names, file_was_already_open
 
+    @enforce_types
+    @trace_method
+    async def attach_files_bulk(
+        self,
+        *,
+        agent_id: str,
+        files_metadata: list[FileMetadata],
+        visible_content_map: Optional[dict[str, str]] = None,
+        actor: PydanticUser,
+    ) -> list[str]:
+        """Atomically attach many files, applying an LRU cap with one commit."""
+        if not files_metadata:
+            return []
+
+        # TODO: This is not strictly necessary, as the file_metadata should never be duped
+        # TODO: But we have this as a protection, check logs for details
+        # dedupe while preserving caller order
+        seen: set[str] = set()
+        ordered_unique: list[FileMetadata] = []
+        for m in files_metadata:
+            if m.file_name not in seen:
+                ordered_unique.append(m)
+                seen.add(m.file_name)
+        if (dup_cnt := len(files_metadata) - len(ordered_unique)) > 0:
+            logger.warning(
+                "attach_files_bulk: removed %d duplicate file(s) for agent %s",
+                dup_cnt,
+                agent_id,
+            )
+
+        now = datetime.now(timezone.utc)
+        vc_for = visible_content_map or {}
+
+        async with db_registry.async_session() as session:
+            # fetch existing assoc rows for requested names
+            existing_q = select(FileAgentModel).where(
+                FileAgentModel.agent_id == agent_id,
+                FileAgentModel.organization_id == actor.organization_id,
+                FileAgentModel.file_name.in_(seen),
+            )
+            existing_rows = (await session.execute(existing_q)).scalars().all()
+            existing_by_name = {r.file_name: r for r in existing_rows}
+
+            # snapshot current OPEN rows (oldest first)
+            open_q = (
+                select(FileAgentModel)
+                .where(
+                    FileAgentModel.agent_id == agent_id,
+                    FileAgentModel.organization_id == actor.organization_id,
+                    FileAgentModel.is_open.is_(True),
+                )
+                .order_by(FileAgentModel.last_accessed_at.asc())
+            )
+            currently_open = (await session.execute(open_q)).scalars().all()
+
+            new_names = [m.file_name for m in ordered_unique]
+            new_names_set = set(new_names)
+            still_open_names = [r.file_name for r in currently_open if r.file_name not in new_names_set]
+
+            # decide final open set
+            if len(new_names) >= MAX_FILES_OPEN:
+                final_open = new_names[:MAX_FILES_OPEN]
+            else:
+                room_for_old = MAX_FILES_OPEN - len(new_names)
+                final_open = new_names + still_open_names[-room_for_old:]
+            final_open_set = set(final_open)
+
+            closed_file_names = [r.file_name for r in currently_open if r.file_name not in final_open_set]
+            # Add new files that won't be opened due to MAX_FILES_OPEN limit
+            if len(new_names) >= MAX_FILES_OPEN:
+                closed_file_names.extend(new_names[MAX_FILES_OPEN:])
+            evicted_ids = [r.file_id for r in currently_open if r.file_name in closed_file_names]
+
+            # upsert requested files
+            for meta in ordered_unique:
+                is_now_open = meta.file_name in final_open_set
+                vc = vc_for.get(meta.file_name, "") if is_now_open else None
+
+                if row := existing_by_name.get(meta.file_name):
+                    row.is_open = is_now_open
+                    row.visible_content = vc
+                    row.last_accessed_at = now
+                    session.add(row)  # already present, but safe
+                else:
+                    session.add(
+                        FileAgentModel(
+                            agent_id=agent_id,
+                            file_id=meta.id,
+                            file_name=meta.file_name,
+                            organization_id=actor.organization_id,
+                            is_open=is_now_open,
+                            visible_content=vc,
+                            last_accessed_at=now,
+                        )
+                    )
+
+            # bulk-close evicted rows
+            if evicted_ids:
+                await session.execute(
+                    update(FileAgentModel)
+                    .where(
+                        FileAgentModel.agent_id == agent_id,
+                        FileAgentModel.organization_id == actor.organization_id,
+                        FileAgentModel.file_id.in_(evicted_ids),
+                    )
+                    .values(is_open=False, visible_content=None)
+                )
+
+            await session.commit()
+            return closed_file_names
+
     async def _get_association_by_file_id(self, session, agent_id: str, file_id: str, actor: PydanticUser) -> FileAgentModel:
         q = select(FileAgentModel).where(
             and_(

letta/services/helpers/agent_manager_helper.py

@@ -1,3 +1,4 @@
+import os
 from datetime import datetime
 from typing import List, Literal, Optional, Set
 
@@ -10,9 +11,11 @@ from letta.constants import (
     BASE_MEMORY_TOOLS,
     BASE_MEMORY_TOOLS_V2,
     BASE_TOOLS,
-    DEPRECATED_BASE_TOOLS,
+    DEPRECATED_LETTA_TOOLS,
     IN_CONTEXT_MEMORY_KEYWORD,
+    LOCAL_ONLY_MULTI_AGENT_TOOLS,
     MAX_EMBEDDING_DIM,
+    MULTI_AGENT_TOOLS,
     STRUCTURED_OUTPUT_MODELS,
 )
 from letta.embeddings import embedding_model
@@ -248,6 +251,7 @@ def compile_system_message(
     previous_message_count: int = 0,
     archival_memory_size: int = 0,
     tool_rules_solver: Optional[ToolRulesSolver] = None,
+    sources: Optional[List] = None,
 ) -> str:
     """Prepare the final/full system message that will be fed into the LLM API
 
@@ -256,6 +260,7 @@ def compile_system_message(
     The following are reserved variables:
       - CORE_MEMORY: the in-context memory of the LLM
     """
+
     # Add tool rule constraints if available
     tool_constraint_block = None
     if tool_rules_solver is not None:
@@ -278,13 +283,16 @@ def compile_system_message(
             archival_memory_size=archival_memory_size,
             timezone=timezone,
         )
-        full_memory_string = in_context_memory.compile(tool_usage_rules=tool_constraint_block) + "\n\n" + memory_metadata_string
+
+        memory_with_sources = in_context_memory.compile(tool_usage_rules=tool_constraint_block, sources=sources)
+        full_memory_string = memory_with_sources + "\n\n" + memory_metadata_string
 
         # Add to the variables list to inject
         variables[IN_CONTEXT_MEMORY_KEYWORD] = full_memory_string
 
     if template_format == "f-string":
         memory_variable_string = "{" + IN_CONTEXT_MEMORY_KEYWORD + "}"
+
         # Catch the special case where the system prompt is unformatted
         if append_icm_if_missing:
             if memory_variable_string not in system_prompt:
@@ -327,6 +335,7 @@ def initialize_message_sequence(
         append_icm_if_missing=True,
         previous_message_count=previous_message_count,
         archival_memory_size=archival_memory_size,
+        sources=agent_state.sources,
     )
     first_user_message = get_login_event(agent_state.timezone)  # event letting Letta know the user just logged in
 
@@ -1050,6 +1059,14 @@ def build_agent_passage_query(
 
 def calculate_base_tools(is_v2: bool) -> Set[str]:
     if is_v2:
-        return (set(BASE_TOOLS) - set(DEPRECATED_BASE_TOOLS)) | set(BASE_MEMORY_TOOLS_V2)
+        return (set(BASE_TOOLS) - set(DEPRECATED_LETTA_TOOLS)) | set(BASE_MEMORY_TOOLS_V2)
+    else:
+        return (set(BASE_TOOLS) - set(DEPRECATED_LETTA_TOOLS)) | set(BASE_MEMORY_TOOLS)
+
+
+def calculate_multi_agent_tools() -> Set[str]:
+    """Calculate multi-agent tools, excluding local-only tools in production environment."""
+    if os.getenv("LETTA_ENVIRONMENT") == "PRODUCTION":
+        return set(MULTI_AGENT_TOOLS) - set(LOCAL_ONLY_MULTI_AGENT_TOOLS)
     else:
-        return (set(BASE_TOOLS) - set(DEPRECATED_BASE_TOOLS)) | set(BASE_MEMORY_TOOLS)
+        return set(MULTI_AGENT_TOOLS)

letta/services/job_manager.py

@@ -1,4 +1,4 @@
-from functools import reduce
+from functools import partial, reduce
 from operator import add
 from typing import List, Literal, Optional, Union
 
@@ -14,7 +14,7 @@ from letta.orm.message import Message as MessageModel
 from letta.orm.sqlalchemy_base import AccessType
 from letta.orm.step import Step
 from letta.orm.step import Step as StepModel
-from letta.otel.tracing import trace_method
+from letta.otel.tracing import log_event, trace_method
 from letta.schemas.enums import JobStatus, JobType, MessageRole
 from letta.schemas.job import BatchJob as PydanticBatchJob
 from letta.schemas.job import Job as PydanticJob
@@ -98,7 +98,6 @@ class JobManager:
         async with db_registry.async_session() as session:
             # Fetch the job by ID
             job = await self._verify_job_access_async(session=session, job_id=job_id, actor=actor, access=["write"])
-            not_completed_before = not bool(job.completed_at)
 
             # Update job attributes with only the fields that were explicitly set
             update_data = job_update.model_dump(to_orm=True, exclude_unset=True, exclude_none=True)
@@ -110,16 +109,62 @@ class JobManager:
                     value = value.replace(tzinfo=None)
                 setattr(job, key, value)
 
-            if job_update.status in {JobStatus.completed, JobStatus.failed} and not_completed_before:
+            # If we are updating the job to a terminal state
+            if job_update.status in {JobStatus.completed, JobStatus.failed}:
+                logger.info(f"Current job completed at: {job.completed_at}")
                 job.completed_at = get_utc_time().replace(tzinfo=None)
                 if job.callback_url:
                     await self._dispatch_callback_async(job)
+                else:
+                    logger.info(f"Job does not contain callback url: {job}")
+            else:
+                logger.info(f"Job update is not terminal {job_update}")
 
             # Save the updated job to the database
             await job.update_async(db_session=session, actor=actor)
 
             return job.to_pydantic()
 
+    @enforce_types
+    @trace_method
+    async def safe_update_job_status_async(
+        self, job_id: str, new_status: JobStatus, actor: PydanticUser, metadata: Optional[dict] = None
+    ) -> bool:
+        """
+        Safely update job status with state transition guards.
+        Created -> Pending -> Running --> <Terminal>
+
+        Returns:
+            True if update was successful, False if update was skipped due to invalid transition
+        """
+        try:
+            # Get current job state
+            current_job = await self.get_job_by_id_async(job_id=job_id, actor=actor)
+
+            current_status = current_job.status
+            if not any(
+                (
+                    new_status.is_terminal and not current_status.is_terminal,
+                    current_status == JobStatus.created and new_status != JobStatus.created,
+                    current_status == JobStatus.pending and new_status == JobStatus.running,
+                )
+            ):
+                logger.warning(f"Invalid job status transition from {current_job.status} to {new_status} for job {job_id}")
+                return False
+
+            job_update_builder = partial(JobUpdate, status=new_status)
+            if metadata:
+                job_update_builder = partial(job_update_builder, metadata=metadata)
+            if new_status.is_terminal:
+                job_update_builder = partial(job_update_builder, completed_at=get_utc_time())
+
+            await self.update_job_by_id_async(job_id=job_id, job_update=job_update_builder(), actor=actor)
+            return True
+
+        except Exception as e:
+            logger.error(f"Failed to safely update job status for job {job_id}: {e}")
+            return False
+
     @enforce_types
     @trace_method
     def get_job_by_id(self, job_id: str, actor: PydanticUser) -> PydanticJob:
@@ -628,6 +673,7 @@ class JobManager:
             request_config = job.request_config or LettaRequestConfig()
         return request_config
 
+    @trace_method
     def _dispatch_callback(self, job: JobModel) -> None:
         """
         POST a standard JSON payload to job.callback_url
@@ -643,18 +689,21 @@ class JobManager:
         try:
             import httpx
 
+            log_event("POST callback dispatched", payload)
             resp = httpx.post(job.callback_url, json=payload, timeout=5.0)
+            log_event("POST callback finished")
             job.callback_sent_at = get_utc_time().replace(tzinfo=None)
             job.callback_status_code = resp.status_code
 
         except Exception as e:
-            error_message = f"Failed to dispatch callback for job {job.id} to {job.callback_url}: {str(e)}"
+            error_message = f"Failed to dispatch callback for job {job.id} to {job.callback_url}: {e!s}"
             logger.error(error_message)
             # Record the failed attempt
             job.callback_sent_at = get_utc_time().replace(tzinfo=None)
             job.callback_error = error_message
             # Continue silently - callback failures should not affect job completion
 
+    @trace_method
     async def _dispatch_callback_async(self, job: JobModel) -> None:
         """
         POST a standard JSON payload to job.callback_url and record timestamp + HTTP status asynchronously.
@@ -670,12 +719,14 @@ class JobManager:
             import httpx
 
             async with httpx.AsyncClient() as client:
+                log_event("POST callback dispatched", payload)
                 resp = await client.post(job.callback_url, json=payload, timeout=5.0)
+                log_event("POST callback finished")
                 # Ensure timestamp is timezone-naive for DB compatibility
                 job.callback_sent_at = get_utc_time().replace(tzinfo=None)
                 job.callback_status_code = resp.status_code
         except Exception as e:
-            error_message = f"Failed to dispatch callback for job {job.id} to {job.callback_url}: {str(e)}"
+            error_message = f"Failed to dispatch callback for job {job.id} to {job.callback_url}: {e!s}"
             logger.error(error_message)
             # Record the failed attempt
             job.callback_sent_at = get_utc_time().replace(tzinfo=None)

letta/services/mcp/base_client.py

@@ -77,6 +77,7 @@ class AsyncBaseMCPClient:
             logger.error("MCPClient has not been initialized")
             raise RuntimeError("MCPClient has not been initialized")
 
+    # TODO: still hitting some async errors for voice agents, need to fix
     async def cleanup(self):
         """Clean up resources - ensure this runs in the same task"""
         if hasattr(self, "_cleanup_task"):

letta/services/mcp_manager.py

@@ -2,6 +2,8 @@ import json
 import os
 from typing import Any, Dict, List, Optional, Tuple, Union
 
+from sqlalchemy import null
+
 import letta.constants as constants
 from letta.functions.mcp_client.types import MCPServerType, MCPTool, SSEServerConfig, StdioServerConfig, StreamableHTTPServerConfig
 from letta.log import get_logger
@@ -156,6 +158,10 @@ class MCPManager:
             pydantic_mcp_server.organization_id = actor.organization_id
             mcp_server_data = pydantic_mcp_server.model_dump(to_orm=True)
 
+            # Ensure custom_headers None is stored as SQL NULL, not JSON null
+            if mcp_server_data.get("custom_headers") is None:
+                mcp_server_data.pop("custom_headers", None)
+
             mcp_server = MCPServerModel(**mcp_server_data)
             mcp_server = await mcp_server.create_async(session, actor=actor)
             return mcp_server.to_pydantic()
@@ -168,7 +174,13 @@ class MCPManager:
             mcp_server = await MCPServerModel.read_async(db_session=session, identifier=mcp_server_id, actor=actor)
 
             # Update tool attributes with only the fields that were explicitly set
-            update_data = mcp_server_update.model_dump(to_orm=True, exclude_none=True)
+            update_data = mcp_server_update.model_dump(to_orm=True, exclude_unset=True)
+
+            # Ensure custom_headers None is stored as SQL NULL, not JSON null
+            if update_data.get("custom_headers") is None:
+                update_data.pop("custom_headers", None)
+                setattr(mcp_server, "custom_headers", null())
+
             for key, value in update_data.items():
                 setattr(mcp_server, key, value)
 

letta/services/step_manager.py

@@ -42,6 +42,7 @@ class StepManager:
         trace_ids: Optional[list[str]] = None,
         feedback: Optional[Literal["positive", "negative"]] = None,
         has_feedback: Optional[bool] = None,
+        project_id: Optional[str] = None,
     ) -> List[PydanticStep]:
         """List all jobs with optional pagination and status filter."""
         async with db_registry.async_session() as session:
@@ -54,6 +55,8 @@ class StepManager:
                 filter_kwargs["trace_id"] = trace_ids
             if feedback:
                 filter_kwargs["feedback"] = feedback
+            if project_id:
+                filter_kwargs["project_id"] = project_id
             steps = await StepModel.list_async(
                 db_session=session,
                 before=before,
@@ -82,6 +85,7 @@ class StepManager:
         provider_id: Optional[str] = None,
         job_id: Optional[str] = None,
         step_id: Optional[str] = None,
+        project_id: Optional[str] = None,
     ) -> PydanticStep:
         step_data = {
             "origin": None,
@@ -100,6 +104,7 @@ class StepManager:
             "tags": [],
             "tid": None,
             "trace_id": get_trace_id(),  # Get the current trace ID
+            "project_id": project_id,
         }
         if step_id:
             step_data["id"] = step_id
@@ -125,6 +130,7 @@ class StepManager:
         provider_id: Optional[str] = None,
         job_id: Optional[str] = None,
         step_id: Optional[str] = None,
+        project_id: Optional[str] = None,
     ) -> PydanticStep:
         step_data = {
             "origin": None,
@@ -143,6 +149,7 @@ class StepManager:
             "tags": [],
             "tid": None,
             "trace_id": get_trace_id(),  # Get the current trace ID
+            "project_id": project_id,
         }
         if step_id:
             step_data["id"] = step_id
@@ -173,7 +180,7 @@ class StepManager:
 
     @enforce_types
     @trace_method
-    def update_step_transaction_id(self, actor: PydanticUser, step_id: str, transaction_id: str) -> PydanticStep:
+    async def update_step_transaction_id(self, actor: PydanticUser, step_id: str, transaction_id: str) -> PydanticStep:
         """Update the transaction ID for a step.
 
         Args:
@@ -187,15 +194,15 @@ class StepManager:
         Raises:
             NoResultFound: If the step does not exist
         """
-        with db_registry.session() as session:
-            step = session.get(StepModel, step_id)
+        async with db_registry.async_session() as session:
+            step = await session.get(StepModel, step_id)
             if not step:
                 raise NoResultFound(f"Step with id {step_id} does not exist")
             if step.organization_id != actor.organization_id:
                 raise Exception("Unauthorized")
 
             step.tid = transaction_id
-            session.commit()
+            await session.commit()
             return step.to_pydantic()
 
     def _verify_job_access(
@@ -226,8 +233,8 @@ class StepManager:
             raise NoResultFound(f"Job with id {job_id} does not exist or user does not have access")
         return job
 
+    @staticmethod
     async def _verify_job_access_async(
-        self,
         session: AsyncSession,
         job_id: str,
         actor: PydanticUser,
@@ -280,6 +287,7 @@ class NoopStepManager(StepManager):
         provider_id: Optional[str] = None,
         job_id: Optional[str] = None,
         step_id: Optional[str] = None,
+        project_id: Optional[str] = None,
     ) -> PydanticStep:
         return
 
@@ -298,5 +306,6 @@ class NoopStepManager(StepManager):
         provider_id: Optional[str] = None,
         job_id: Optional[str] = None,
         step_id: Optional[str] = None,
+        project_id: Optional[str] = None,
     ) -> PydanticStep:
         return

letta/services/summarizer/summarizer.py

@@ -11,6 +11,7 @@ from letta.schemas.enums import MessageRole
 from letta.schemas.letta_message_content import TextContent
 from letta.schemas.message import Message, MessageCreate
 from letta.services.summarizer.enums import SummarizationMode
+from letta.templates.template_helper import render_template
 
 logger = get_logger(__name__)
 
@@ -123,30 +124,13 @@ class Summarizer:
             formatted_evicted_messages = [f"{i}. {msg}" for (i, msg) in enumerate(formatted_evicted_messages)]
             formatted_in_context_messages = [f"{i + offset}. {msg}" for (i, msg) in enumerate(formatted_in_context_messages)]
 
-            evicted_messages_str = "\n".join(formatted_evicted_messages)
-            in_context_messages_str = "\n".join(formatted_in_context_messages)
-            # Base prompt
-            prompt_header = (
-                f"You’re a memory-recall helper for an AI that can only keep the last {retain_count} messages. "
-                "Scan the conversation history, focusing on messages about to drop out of that window, "
-                "and write crisp notes that capture any important facts or insights about the conversation history so they aren’t lost."
+            summary_request_text = render_template(
+                "summary_request_text.j2",
+                retain_count=retain_count,
+                evicted_messages=formatted_evicted_messages,
+                in_context_messages=formatted_in_context_messages,
             )
 
-            # Sections
-            evicted_section = f"\n\n(Older) Evicted Messages:\n{evicted_messages_str}" if evicted_messages_str.strip() else ""
-            in_context_section = ""
-
-            if retain_count > 0 and in_context_messages_str.strip():
-                in_context_section = f"\n\n(Newer) In-Context Messages:\n{in_context_messages_str}"
-            elif retain_count == 0:
-                prompt_header = (
-                    "You’re a memory-recall helper for an AI that is about to forget all prior messages. "
-                    "Scan the conversation history and write crisp notes that capture any important facts or insights about the conversation history."
-                )
-
-            # Compose final prompt
-            summary_request_text = prompt_header + evicted_section + in_context_section
-
             # Fire-and-forget the summarization task
             self.fire_and_forget(
                 self.summarizer_agent.step([MessageCreate(role=MessageRole.user, content=[TextContent(text=summary_request_text)])])

letta/services/tool_executor/builtin_tool_executor.py

@@ -327,7 +327,6 @@ class LettaBuiltinToolExecutor(ToolExecutor):
             messages=[{"role": "system", "content": FIRECRAWL_SEARCH_SYSTEM_PROMPT}, {"role": "user", "content": user_prompt}],
             response_format=DocumentAnalysis,
             temperature=0.1,
-            max_tokens=300,  # Limit output tokens - only need line numbers
         )
 
         end_time = time.time()

letta/services/tool_executor/files_tool_executor.py

@@ -76,7 +76,7 @@ class LettaFileToolExecutor(ToolExecutor):
         function_map = {
             "open_files": self.open_files,
             "grep_files": self.grep_files,
-            "search_files": self.search_files,
+            "semantic_search_files": self.semantic_search_files,
         }
 
         if function_name not in function_map:
@@ -463,7 +463,7 @@ class LettaFileToolExecutor(ToolExecutor):
         return "\n".join(formatted_results)
 
     @trace_method
-    async def search_files(self, agent_state: AgentState, query: str, limit: int = 10) -> str:
+    async def semantic_search_files(self, agent_state: AgentState, query: str, limit: int = 10) -> str:
         """
         Search for text within attached files using semantic search and return passages with their source filenames.
 

letta/services/tool_executor/multi_agent_tool_executor.py

@@ -1,6 +1,8 @@
 import asyncio
+import os
 from typing import Any, Dict, List, Optional
 
+from letta.log import get_logger
 from letta.schemas.agent import AgentState
 from letta.schemas.enums import MessageRole
 from letta.schemas.letta_message import AssistantMessage
@@ -12,6 +14,8 @@ from letta.schemas.tool_execution_result import ToolExecutionResult
 from letta.schemas.user import User
 from letta.services.tool_executor.tool_executor_base import ToolExecutor
 
+logger = get_logger(__name__)
+
 
 class LettaMultiAgentToolExecutor(ToolExecutor):
     """Executor for LETTA multi-agent core tools."""
@@ -29,6 +33,7 @@ class LettaMultiAgentToolExecutor(ToolExecutor):
         assert agent_state is not None, "Agent state is required for multi-agent tools"
         function_map = {
             "send_message_to_agent_and_wait_for_reply": self.send_message_to_agent_and_wait_for_reply,
+            "send_message_to_agent_async": self.send_message_to_agent_async,
             "send_message_to_agents_matching_tags": self.send_message_to_agents_matching_tags_async,
         }
 
@@ -105,3 +110,21 @@ class LettaMultiAgentToolExecutor(ToolExecutor):
                 "error": str(e),
                 "type": type(e).__name__,
             }
+
+    async def send_message_to_agent_async(self, agent_state: AgentState, message: str, other_agent_id: str) -> str:
+        if os.getenv("LETTA_ENVIRONMENT") == "PRODUCTION":
+            raise RuntimeError("This tool is not allowed to be run on Letta Cloud.")
+
+        # 1) Build the prefixed system‐message
+        prefixed = (
+            f"[Incoming message from agent with ID '{agent_state.id}' - "
+            f"to reply to this message, make sure to use the "
+            f"'send_message_to_agent_async' tool, or the agent will not receive your message] "
+            f"{message}"
+        )
+
+        task = asyncio.create_task(self._process_agent(agent_id=other_agent_id, message=prefixed))
+
+        task.add_done_callback(lambda t: (logger.error(f"Async send_message task failed: {t.exception()}") if t.exception() else None))
+
+        return "Successfully sent message"