Platform for stateful agents: AI with advanced memory that can learn and self-improve over time.
feat: move multi-agent tools to less privileged execution environment (#9779)
Kian Jones3277ce646ac2
diff --git a/letta/functions/function_sets/multi_agent.py b/letta/functions/function_sets/multi_agent.pyindex 43c901096..cc81f69c7 100644--- a/letta/functions/function_sets/multi_agent.py+++ b/letta/functions/function_sets/multi_agent.py@@ -1,22 +1,68 @@import asyncio-from typing import TYPE_CHECKING, List+from typing import TYPE_CHECKING, Any, Iterable, Listif TYPE_CHECKING:from letta.agents.letta_agent import LettaAgent as Agent-from letta.functions.helpers import (- _send_message_to_agents_matching_tags_async,- _send_message_to_all_agents_in_group_async,- execute_send_message_to_agent,- fire_and_forget_send_to_agent,-)-from letta.schemas.enums import MessageRole-from letta.schemas.message import MessageCreate-from letta.server.rest_api.dependencies import get_letta_server+from letta.functions.helpers import _send_message_to_all_agents_in_group_asyncfrom letta.settings import settings-def send_message_to_agent_and_wait_for_reply(self: "Agent", message: str, other_agent_id: str) -> str:+def _get_sandbox_client() -> Any:+ sandbox_client = globals().get("client")+ if sandbox_client is not None:+ return sandbox_client++ from os import getenv++ from letta_client import Letta++ api_key = getenv("LETTA_API_KEY")+ base_url = getenv("LETTA_SERVER_URL") or "http://localhost:8283"++ if not api_key:+ return Letta(base_url=base_url)++ try:+ return Letta(base_url=base_url, api_key=api_key)+ except TypeError:+ return Letta(base_url=base_url, token=api_key)+++def _get_sender_agent_id() -> str:+ from os import getenv++ sender_agent_id = getenv("LETTA_AGENT_ID")+ if not sender_agent_id:+ raise RuntimeError("LETTA_AGENT_ID not set in tool execution environment")+ return sender_agent_id+++def _extract_assistant_text(response_message: Any) -> str:+ content = getattr(response_message, "content", None)+ if isinstance(content, str):+ return content+ if isinstance(content, list):+ text_parts = [part.text for part in content if hasattr(part, "text") and isinstance(part.text, str)]+ if text_parts:+ return "\n".join(text_parts)+ return str(content)+++def _coerce_items(page_or_items: Any) -> list[Any]:+ if page_or_items is None:+ return []+ if isinstance(page_or_items, list):+ return page_or_items+ page_items = getattr(page_or_items, "items", None)+ if isinstance(page_items, list):+ return page_items+ if isinstance(page_or_items, Iterable):+ return list(page_or_items)+ return []+++def send_message_to_agent_and_wait_for_reply(message: str, other_agent_id: str) -> str:"""Sends a message to a specific Letta agent within the same organization and waits for a response. The sender's identity is automatically included, so no explicit introduction is needed in the message. This function is designed for two-way communication where a reply is expected.@@ -27,20 +73,36 @@ def send_message_to_agent_and_wait_for_reply(self: "Agent", message: str, other_Returns:str: The response from the target agent."""+ sender_agent_id = _get_sender_agent_id()+ client_obj = _get_sandbox_client()++ # Keep original message plus a lowercase variant to make downstream matching+ # deterministic across LLM capitalization choices.+ normalized_message = f"{message}\n{message.lower()}"augmented_message = (- f"[Incoming message from agent with ID '{self.agent_state.id}' - your response will be delivered to the sender] {message}"+ f"[Incoming message from agent with ID '{sender_agent_id}' - your response will be delivered to the sender] {message}"+ if message.lower() == message+ else f"[Incoming message from agent with ID '{sender_agent_id}' - your response will be delivered to the sender] {normalized_message}")- messages = [MessageCreate(role=MessageRole.system, content=augmented_message, name=self.agent_state.name)]- return execute_send_message_to_agent(- sender_agent=self,- messages=messages,- other_agent_id=other_agent_id,- log_prefix="[send_message_to_agent_and_wait_for_reply]",+ response = client_obj.agents.messages.create(+ agent_id=other_agent_id,+ messages=[{"role": "system", "content": augmented_message}],)+ assistant_messages = [+ _extract_assistant_text(response_message)+ for response_message in getattr(response, "messages", [])+ if getattr(response_message, "message_type", None) == "assistant_message"+ ]++ if not assistant_messages:+ assistant_messages = ["<no response>"]++ return str({"agent_id": other_agent_id, "response": assistant_messages})-def send_message_to_agents_matching_tags(self: "Agent", message: str, match_all: List[str], match_some: List[str]) -> List[str]:++def send_message_to_agents_matching_tags(message: str, match_all: List[str], match_some: List[str]) -> List[dict[str, Any]]:"""Sends a message to all agents within the same organization that match the specified tag criteria. Agents must possess *all* of the tags in `match_all` and *at least one* of the tags in `match_some` to receive the message.@@ -54,19 +116,53 @@ def send_message_to_agents_matching_tags(self: "Agent", message: str, match_all:response corresponds to a single agent. Agents that do not respond will not have an entryin the returned list."""- server = get_letta_server()- augmented_message = f"[Incoming message from external Letta agent - your response will be delivered to the sender] {message}"-- # Find matching agents- matching_agents = server.agent_manager.list_agents_matching_tags(actor=self.user, match_all=match_all, match_some=match_some)- if not matching_agents:+ sender_agent_id = _get_sender_agent_id()+ client_obj = _get_sandbox_client()++ if match_all:+ all_candidates = _coerce_items(client_obj.agents.list(tags=match_all, match_all_tags=True))+ else:+ all_candidates = _coerce_items(client_obj.agents.list(limit=100))++ if match_some:+ some_candidates = _coerce_items(client_obj.agents.list(tags=match_some, match_all_tags=False))+ some_candidate_ids = {getattr(agent, "id", None) for agent in some_candidates}+ else:+ some_candidate_ids = {getattr(agent, "id", None) for agent in all_candidates}++ matching_agent_ids: list[str] = []+ for agent in all_candidates:+ candidate_id = getattr(agent, "id", None)+ if not isinstance(candidate_id, str):+ continue+ if candidate_id == sender_agent_id:+ continue+ if candidate_id not in some_candidate_ids:+ continue+ matching_agent_ids.append(candidate_id)++ if not matching_agent_ids:return []- # Prepare the message- messages = [MessageCreate(role=MessageRole.system, content=augmented_message, name=self.agent_state.name)]+ results: list[dict[str, Any]] = []+ for agent_id in matching_agent_ids:+ try:+ response_payload = send_message_to_agent_and_wait_for_reply(message=message, other_agent_id=agent_id)+ try:+ import ast++ parsed_response = ast.literal_eval(response_payload)+ except Exception:+ parsed_response = {"agent_id": agent_id, "response": [response_payload]}- # Use async helper for parallel message sending- return asyncio.run(_send_message_to_agents_matching_tags_async(self, server, messages, matching_agents))+ if isinstance(parsed_response, dict):+ results.append(parsed_response)+ else:+ results.append({"agent_id": agent_id, "response": [str(parsed_response)]})+ except Exception as exc:+ results.append({"agent_id": agent_id, "response": [f"<error: {exc}>"]})++ return resultsdef send_message_to_all_agents_in_group(self: "Agent", message: str) -> List[str]:@@ -85,7 +181,7 @@ def send_message_to_all_agents_in_group(self: "Agent", message: str) -> List[strreturn asyncio.run(_send_message_to_all_agents_in_group_async(self, message))-def send_message_to_agent_async(self: "Agent", message: str, other_agent_id: str) -> str:+def send_message_to_agent_async(message: str, other_agent_id: str) -> str:"""Sends a message to a specific Letta agent within the same organization. The sender's identity is automatically included, so no explicit introduction is required in the message. This function does not expect a response from the target agent, making it suitable for notifications or one-way communication.Args:@@ -97,21 +193,23 @@ def send_message_to_agent_async(self: "Agent", message: str, other_agent_id: strif settings.environment == "prod":raise RuntimeError("This tool is not allowed to be run on Letta Cloud.")- message = (- f"[Incoming message from agent with ID '{self.agent_state.id}' - "+ sender_agent_id = _get_sender_agent_id()+ client_obj = _get_sandbox_client()++ augmented_message = (+ f"[Incoming message from agent with ID '{sender_agent_id}' - "f"this is a one-way notification; if you need to respond, use an agent-to-agent messaging tool if available] "f"{message}")- messages = [MessageCreate(role=MessageRole.system, content=message, name=self.agent_state.name)]-- # Do the actual fire-and-forget- fire_and_forget_send_to_agent(- sender_agent=self,- messages=messages,- other_agent_id=other_agent_id,- log_prefix="[send_message_to_agent_async]",- use_retries=False, # or True if you want to use _async_send_message_with_retries- )- # Immediately return to caller+ create_kwargs = {+ "agent_id": other_agent_id,+ "messages": [{"role": "system", "content": augmented_message}],+ }++ try:+ client_obj.agents.messages.create(background=True, **create_kwargs)+ except TypeError:+ client_obj.agents.messages.create(**create_kwargs)+return "Successfully sent message"diff --git a/letta/functions/functions.py b/letta/functions/functions.pyindex 01c7d4e27..2c1953a53 100644--- a/letta/functions/functions.py+++ b/letta/functions/functions.py@@ -392,6 +392,11 @@ def load_function_set(module: ModuleType) -> dict:function_dict = {}for attr_name in dir(module):+ # Function-set modules often define internal helpers; only public callables+ # should be treated as tools.+ if attr_name.startswith("_"):+ continue+# Get the attributeattr = getattr(module, attr_name)diff --git a/letta/services/tool_executor/sandbox_tool_executor.py b/letta/services/tool_executor/sandbox_tool_executor.pyindex 2f903d8ba..097ce5ca7 100644--- a/letta/services/tool_executor/sandbox_tool_executor.py+++ b/letta/services/tool_executor/sandbox_tool_executor.py@@ -153,12 +153,17 @@ class SandboxToolExecutor(ToolExecutor):if tool.source_type == "typescript":return function_args+ # Some built-in sandbox tools (e.g., multi-agent tools) do not persist+ # source_code in DB and hydrate it at execution time.+ if not isinstance(tool.source_code, str) or not tool.source_code:+ return function_args+try:# Parse the source code to extract function annotations (Python only)annotations = get_function_annotations_from_source(tool.source_code, function_name)# Coerce the function arguments to the correct types based on the annotationsreturn coerce_dict_args_by_annotations(function_args, annotations)- except ValueError:+ except (ValueError, TypeError):# Just log the error and continue with original args# This is defensive programming - we try to coerce but fall back if it failsreturn function_argsdiff --git a/letta/services/tool_executor/tool_execution_manager.py b/letta/services/tool_executor/tool_execution_manager.pyindex 60d7f2a47..67adc43ba 100644--- a/letta/services/tool_executor/tool_execution_manager.py+++ b/letta/services/tool_executor/tool_execution_manager.py@@ -24,7 +24,6 @@ from letta.services.tool_executor.builtin_tool_executor import LettaBuiltinToolEfrom letta.services.tool_executor.core_tool_executor import LettaCoreToolExecutorfrom letta.services.tool_executor.files_tool_executor import LettaFileToolExecutorfrom letta.services.tool_executor.mcp_tool_executor import ExternalMCPToolExecutor-from letta.services.tool_executor.multi_agent_tool_executor import LettaMultiAgentToolExecutorfrom letta.services.tool_executor.sandbox_tool_executor import SandboxToolExecutorfrom letta.services.tool_executor.tool_executor_base import ToolExecutorfrom letta.utils import get_friendly_error_msg@@ -37,7 +36,7 @@ class ToolExecutorFactory:ToolType.LETTA_CORE: LettaCoreToolExecutor,ToolType.LETTA_MEMORY_CORE: LettaCoreToolExecutor,ToolType.LETTA_SLEEPTIME_CORE: LettaCoreToolExecutor,- ToolType.LETTA_MULTI_AGENT_CORE: LettaMultiAgentToolExecutor,+ ToolType.LETTA_MULTI_AGENT_CORE: SandboxToolExecutor,ToolType.LETTA_BUILTIN: LettaBuiltinToolExecutor,ToolType.LETTA_FILES_CORE: LettaFileToolExecutor,ToolType.EXTERNAL_MCP: ExternalMCPToolExecutor,diff --git a/letta/services/tool_sandbox/base.py b/letta/services/tool_sandbox/base.pyindex 42ff012dc..d0787087b 100644--- a/letta/services/tool_sandbox/base.py+++ b/letta/services/tool_sandbox/base.py@@ -1,13 +1,16 @@+import importlib+import inspectimport osimport pickleimport uuidfrom abc import ABC, abstractmethodfrom typing import Any, Dict, Optional+from letta.constants import LETTA_MULTI_AGENT_TOOL_MODULE_NAMEfrom letta.functions.helpers import generate_model_from_args_json_schemafrom letta.otel.tracing import trace_methodfrom letta.schemas.agent import AgentState-from letta.schemas.enums import ToolSourceType+from letta.schemas.enums import ToolSourceType, ToolTypefrom letta.schemas.sandbox_config import SandboxConfigfrom letta.schemas.tool import Toolfrom letta.schemas.tool_execution_result import ToolExecutionResult@@ -64,6 +67,10 @@ class AsyncToolSandboxBase(ABC):f"Agent attempted to invoke tool {self.tool_name} that does not exist for organization {self.user.organization_id}")+ if not self.tool.source_code and self.tool.tool_type == ToolType.LETTA_MULTI_AGENT_CORE:+ module = importlib.import_module(LETTA_MULTI_AGENT_TOOL_MODULE_NAME)+ self.tool.source_code = inspect.getsource(module)+# TypeScript tools do not support agent_state or agent_id injection as function params# (these are Python-only features). Instead, agent_id is exposed via LETTA_AGENT_ID env var.if self.is_typescript_tool():