Skip to content

armgit / letta

Public Imported from GitHub
0

Platform for stateful agents: AI with advanced memory that can learn and self-improve over time.

feat: Add back multi agent tools and protections for cloud (#3100)

Matthew Zhoub802b2251309
diff --git a/letta/constants.py b/letta/constants.py
index 58fc1fff4..132aae1a0 100644
--- a/letta/constants.py
+++ b/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)
diff --git a/letta/functions/function_sets/multi_agent.py b/letta/functions/function_sets/multi_agent.py
index 458798e4a..373512d28 100644
--- a/letta/functions/function_sets/multi_agent.py
+++ b/letta/functions/function_sets/multi_agent.py
@@ -1,5 +1,6 @@
import asyncio
import json
+import os
from concurrent.futures import ThreadPoolExecutor, as_completed
from typing import TYPE_CHECKING, List
@@ -7,6 +8,7 @@ from letta.functions.helpers import (
_send_message_to_all_agents_in_group_async,
execute_send_message_to_agent,
extract_send_message_from_steps_messages,
+ fire_and_forget_send_to_agent,
)
from letta.schemas.enums import MessageRole
from letta.schemas.message import MessageCreate
@@ -125,3 +127,35 @@ def send_message_to_all_agents_in_group(self: "Agent", message: str) -> List[str
"""
return 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:
+ """
+ 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:
+ message (str): The content of the message to be sent to the target agent.
+ other_agent_id (str): The unique identifier of the target Letta agent.
+ Returns:
+ str: A confirmation message indicating the message was successfully sent.
+ """
+ if os.getenv("LETTA_ENVIRONMENT") == "PRODUCTION":
+ 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}' - to reply to this message, "
+ f"make sure to use the 'send_message_to_agent_async' tool, or the agent will not receive your message] "
+ 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
+ return "Successfully sent message"
diff --git a/letta/services/agent_manager.py b/letta/services/agent_manager.py
index 8b9b403d5..0e2256f1c 100644
--- a/letta/services/agent_manager.py
+++ b/letta/services/agent_manager.py
@@ -16,9 +16,8 @@ from letta.constants import (
BASE_VOICE_SLEEPTIME_CHAT_TOOLS,
BASE_VOICE_SLEEPTIME_TOOLS,
DEFAULT_TIMEZONE,
- DEPRECATED_BASE_TOOLS,
+ DEPRECATED_LETTA_TOOLS,
FILES_TOOLS,
- MULTI_AGENT_TOOLS,
)
from letta.helpers import ToolRulesSolver
from letta.helpers.datetime_helpers import get_utc_time
@@ -79,6 +78,7 @@ from letta.services.helpers.agent_manager_helper import (
build_passage_query,
build_source_passage_query,
calculate_base_tools,
+ calculate_multi_agent_tools,
check_supports_structured_output,
compile_system_message,
derive_system_message,
@@ -271,7 +271,7 @@ class AgentManager:
else:
tool_names |= calculate_base_tools(is_v2=False)
if agent_create.include_multi_agent_tools:
- tool_names |= set(MULTI_AGENT_TOOLS)
+ tool_names |= calculate_multi_agent_tools()
supplied_ids = set(agent_create.tool_ids or [])
@@ -294,7 +294,7 @@ class AgentManager:
tool_rules = list(agent_create.tool_rules or [])
if agent_create.include_base_tool_rules:
for tn in tool_names:
- if tn in {"send_message", "memory_finish_edits"}:
+ if tn in {"send_message", "send_message_to_agent_async", "memory_finish_edits"}:
tool_rules.append(TerminalToolRule(tool_name=tn))
elif tn in (BASE_TOOLS + BASE_MEMORY_TOOLS + BASE_SLEEPTIME_TOOLS):
tool_rules.append(ContinueToolRule(tool_name=tn))
@@ -438,10 +438,10 @@ class AgentManager:
else:
tool_names |= calculate_base_tools(is_v2=False)
if agent_create.include_multi_agent_tools:
- tool_names |= set(MULTI_AGENT_TOOLS)
+ tool_names |= calculate_multi_agent_tools()
# take out the deprecated tool names
- tool_names.difference_update(set(DEPRECATED_BASE_TOOLS))
+ tool_names.difference_update(set(DEPRECATED_LETTA_TOOLS))
supplied_ids = set(agent_create.tool_ids or [])
@@ -479,7 +479,7 @@ class AgentManager:
tool_rules = list(agent_create.tool_rules or [])
if agent_create.include_base_tool_rules:
for tn in tool_names:
- if tn in {"send_message", "memory_finish_edits"}:
+ if tn in {"send_message", "send_message_to_agent_async", "memory_finish_edits"}:
tool_rules.append(TerminalToolRule(tool_name=tn))
elif tn in (BASE_TOOLS + BASE_MEMORY_TOOLS + BASE_MEMORY_TOOLS_V2 + BASE_SLEEPTIME_TOOLS):
tool_rules.append(ContinueToolRule(tool_name=tn))
diff --git a/letta/services/helpers/agent_manager_helper.py b/letta/services/helpers/agent_manager_helper.py
index 3842ad3c9..d22c9cb02 100644
--- a/letta/services/helpers/agent_manager_helper.py
+++ b/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
@@ -1050,6 +1053,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_BASE_TOOLS)) | set(BASE_MEMORY_TOOLS)
+ 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(MULTI_AGENT_TOOLS)
diff --git a/letta/services/tool_executor/multi_agent_tool_executor.py b/letta/services/tool_executor/multi_agent_tool_executor.py
index b91308e03..6e7e2d7bf 100644
--- a/letta/services/tool_executor/multi_agent_tool_executor.py
+++ b/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"
diff --git a/letta/services/tool_manager.py b/letta/services/tool_manager.py
index f73c70755..6bd231724 100644
--- a/letta/services/tool_manager.py
+++ b/letta/services/tool_manager.py
@@ -15,7 +15,6 @@ from letta.constants import (
LETTA_TOOL_MODULE_NAMES,
LETTA_TOOL_SET,
MCP_TOOL_TAG_NAME_PREFIX,
- MULTI_AGENT_TOOLS,
)
from letta.functions.functions import derive_openai_json_schema, load_function_set
from letta.log import get_logger
@@ -29,6 +28,7 @@ from letta.schemas.tool import Tool as PydanticTool
from letta.schemas.tool import ToolCreate, ToolUpdate
from letta.schemas.user import User as PydanticUser
from letta.server.db import db_registry
+from letta.services.helpers.agent_manager_helper import calculate_multi_agent_tools
from letta.services.mcp.types import SSEServerConfig, StdioServerConfig
from letta.utils import enforce_types, printd
@@ -419,7 +419,7 @@ class ToolManager:
elif name in BASE_MEMORY_TOOLS:
tool_type = ToolType.LETTA_MEMORY_CORE
tags = [tool_type.value]
- elif name in MULTI_AGENT_TOOLS:
+ elif name in calculate_multi_agent_tools():
tool_type = ToolType.LETTA_MULTI_AGENT_CORE
tags = [tool_type.value]
elif name in BASE_SLEEPTIME_TOOLS:
@@ -435,9 +435,8 @@ class ToolManager:
tool_type = ToolType.LETTA_FILES_CORE
tags = [tool_type.value]
else:
- raise ValueError(
- f"Tool name {name} is not in the list of base tool names: {BASE_TOOLS + BASE_MEMORY_TOOLS + MULTI_AGENT_TOOLS + BASE_SLEEPTIME_TOOLS + BASE_VOICE_SLEEPTIME_TOOLS + BASE_VOICE_SLEEPTIME_CHAT_TOOLS}"
- )
+ logger.warning(f"Tool name {name} is not in any known base tool set, skipping")
+ continue
# create to tool
tools.append(
@@ -486,7 +485,7 @@ class ToolManager:
tool_type = ToolType.LETTA_MEMORY_CORE
elif name in BASE_SLEEPTIME_TOOLS:
tool_type = ToolType.LETTA_SLEEPTIME_CORE
- elif name in MULTI_AGENT_TOOLS:
+ elif name in calculate_multi_agent_tools():
tool_type = ToolType.LETTA_MULTI_AGENT_CORE
elif name in BASE_VOICE_SLEEPTIME_TOOLS or name in BASE_VOICE_SLEEPTIME_CHAT_TOOLS:
tool_type = ToolType.LETTA_VOICE_SLEEPTIME_CORE
@@ -495,7 +494,8 @@ class ToolManager:
elif name in FILES_TOOLS:
tool_type = ToolType.LETTA_FILES_CORE
else:
- raise ValueError(f"Tool name {name} is not recognized in any known base tool set.")
+ logger.warning(f"Tool name {name} is not in any known base tool set, skipping")
+ continue
if allowed_types is not None and tool_type not in allowed_types:
continue
diff --git a/tests/test_managers.py b/tests/test_managers.py
index b809d1698..751d514f8 100644
--- a/tests/test_managers.py
+++ b/tests/test_managers.py
@@ -34,6 +34,7 @@ from letta.constants import (
FILES_TOOLS,
LETTA_TOOL_EXECUTION_DIR,
LETTA_TOOL_SET,
+ LOCAL_ONLY_MULTI_AGENT_TOOLS,
MCP_TOOL_TAG_NAME_PREFIX,
MULTI_AGENT_TOOLS,
)
@@ -86,7 +87,7 @@ from letta.schemas.user import UserUpdate
from letta.server.db import db_registry
from letta.server.server import SyncServer
from letta.services.block_manager import BlockManager
-from letta.services.helpers.agent_manager_helper import calculate_base_tools
+from letta.services.helpers.agent_manager_helper import calculate_base_tools, calculate_multi_agent_tools
from letta.services.step_manager import FeedbackType
from letta.settings import tool_settings
from tests.helpers.utils import comprehensive_agent_checks, validate_context_window_overview
@@ -747,6 +748,71 @@ async def test_create_agent_include_base_tools(server: SyncServer, default_user,
assert sorted(tool_names) == sorted(expected_tools)
+def test_calculate_multi_agent_tools(set_letta_environment):
+ """Test that calculate_multi_agent_tools excludes local-only tools in production."""
+ result = calculate_multi_agent_tools()
+
+ if set_letta_environment == "PRODUCTION":
+ # Production environment should exclude local-only tools
+ expected_tools = set(MULTI_AGENT_TOOLS) - set(LOCAL_ONLY_MULTI_AGENT_TOOLS)
+ assert result == expected_tools, "Production should exclude local-only multi-agent tools"
+ assert not set(LOCAL_ONLY_MULTI_AGENT_TOOLS).intersection(result), "Production should not include local-only tools"
+
+ # Verify specific tools
+ assert "send_message_to_agent_and_wait_for_reply" in result, "Standard multi-agent tools should be in production"
+ assert "send_message_to_agents_matching_tags" in result, "Standard multi-agent tools should be in production"
+ assert "send_message_to_agent_async" not in result, "Local-only tools should not be in production"
+ else:
+ # Non-production environment should include all multi-agent tools
+ assert result == set(MULTI_AGENT_TOOLS), "Non-production should include all multi-agent tools"
+ assert set(LOCAL_ONLY_MULTI_AGENT_TOOLS).issubset(result), "Non-production should include local-only tools"
+
+ # Verify specific tools
+ assert "send_message_to_agent_and_wait_for_reply" in result, "All multi-agent tools should be in non-production"
+ assert "send_message_to_agents_matching_tags" in result, "All multi-agent tools should be in non-production"
+ assert "send_message_to_agent_async" in result, "Local-only tools should be in non-production"
+
+
+async def test_upsert_base_tools_excludes_local_only_in_production(server: SyncServer, default_user, set_letta_environment, event_loop):
+ """Test that upsert_base_tools excludes local-only multi-agent tools in production."""
+ # Upsert all base tools
+ tools = await server.tool_manager.upsert_base_tools_async(actor=default_user)
+ tool_names = {tool.name for tool in tools}
+
+ if set_letta_environment == "PRODUCTION":
+ # Production environment should exclude local-only multi-agent tools
+ for local_only_tool in LOCAL_ONLY_MULTI_AGENT_TOOLS:
+ assert local_only_tool not in tool_names, f"Local-only tool '{local_only_tool}' should not be upserted in production"
+
+ # But should include standard multi-agent tools
+ standard_multi_agent_tools = set(MULTI_AGENT_TOOLS) - set(LOCAL_ONLY_MULTI_AGENT_TOOLS)
+ for standard_tool in standard_multi_agent_tools:
+ assert standard_tool in tool_names, f"Standard multi-agent tool '{standard_tool}' should be upserted in production"
+ else:
+ # Non-production environment should include all multi-agent tools
+ for tool in MULTI_AGENT_TOOLS:
+ assert tool in tool_names, f"Multi-agent tool '{tool}' should be upserted in non-production"
+
+
+async def test_upsert_multi_agent_tools_only(server: SyncServer, default_user, set_letta_environment, event_loop):
+ """Test that upserting only multi-agent tools respects production filtering."""
+ from letta.orm.enums import ToolType
+
+ # Upsert only multi-agent tools
+ tools = await server.tool_manager.upsert_base_tools_async(actor=default_user, allowed_types={ToolType.LETTA_MULTI_AGENT_CORE})
+ tool_names = {tool.name for tool in tools}
+
+ if set_letta_environment == "PRODUCTION":
+ # Should only have non-local multi-agent tools
+ expected_tools = set(MULTI_AGENT_TOOLS) - set(LOCAL_ONLY_MULTI_AGENT_TOOLS)
+ assert tool_names == expected_tools, "Production multi-agent upsert should exclude local-only tools"
+ assert "send_message_to_agent_async" not in tool_names, "Local-only async tool should not be upserted in production"
+ else:
+ # Should have all multi-agent tools
+ assert tool_names == set(MULTI_AGENT_TOOLS), "Non-production multi-agent upsert should include all tools"
+ assert "send_message_to_agent_async" in tool_names, "Local-only async tool should be upserted in non-production"
+
+
@pytest.mark.asyncio
async def test_create_agent_with_default_source(server: SyncServer, default_user, print_tool, default_block, event_loop):
"""Test agent creation with include_default_source=True"""