letta-nightly 0.6.9.dev20250115104021__py3-none-any.whl → 0.6.9.dev20250116195713__py3-none-any.whl

letta/__init__.py

@@ -1,5 +1,6 @@
 __version__ = "0.6.9"
 
+
 # import clients
 from letta.client.client import LocalClient, RESTClient, create_client
 

letta/agent.py

@@ -12,6 +12,7 @@ from letta.constants import (
     FIRST_MESSAGE_ATTEMPTS,
     FUNC_FAILED_HEARTBEAT_MESSAGE,
     LETTA_CORE_TOOL_MODULE_NAME,
+    LETTA_MULTI_AGENT_TOOL_MODULE_NAME,
     LLM_MAX_TOKENS,
     MESSAGE_SUMMARY_TRUNC_KEEP_N_LAST,
     MESSAGE_SUMMARY_TRUNC_TOKEN_FRAC,
@@ -25,6 +26,7 @@ from letta.interface import AgentInterface
 from letta.llm_api.helpers import is_context_overflow_error
 from letta.llm_api.llm_api_tools import create
 from letta.local_llm.utils import num_tokens_from_functions, num_tokens_from_messages
+from letta.log import get_logger
 from letta.memory import summarize_messages
 from letta.orm import User
 from letta.orm.enums import ToolType
@@ -44,6 +46,7 @@ from letta.schemas.usage import LettaUsageStatistics
 from letta.services.agent_manager import AgentManager
 from letta.services.block_manager import BlockManager
 from letta.services.helpers.agent_manager_helper import check_supports_structured_output, compile_memory_metadata_block
+from letta.services.job_manager import JobManager
 from letta.services.message_manager import MessageManager
 from letta.services.passage_manager import PassageManager
 from letta.services.tool_execution_sandbox import ToolExecutionSandbox
@@ -128,6 +131,7 @@ class Agent(BaseAgent):
         self.message_manager = MessageManager()
         self.passage_manager = PassageManager()
         self.agent_manager = AgentManager()
+        self.job_manager = JobManager()
 
         # State needed for heartbeat pausing
 
@@ -141,6 +145,9 @@ class Agent(BaseAgent):
         # Load last function response from message history
         self.last_function_response = self.load_last_function_response()
 
+        # Logger that the Agent specifically can use, will also report the agent_state ID with the logs
+        self.logger = get_logger(agent_state.id)
+
     def load_last_function_response(self):
         """Load the last function response from message history"""
         in_context_messages = self.agent_manager.get_in_context_messages(agent_id=self.agent_state.id, actor=self.user)
@@ -205,6 +212,10 @@ class Agent(BaseAgent):
                 callable_func = get_function_from_module(LETTA_CORE_TOOL_MODULE_NAME, function_name)
                 function_args["self"] = self  # need to attach self to arg since it's dynamically linked
                 function_response = callable_func(**function_args)
+            elif target_letta_tool.tool_type == ToolType.LETTA_MULTI_AGENT_CORE:
+                callable_func = get_function_from_module(LETTA_MULTI_AGENT_TOOL_MODULE_NAME, function_name)
+                function_args["self"] = self  # need to attach self to arg since it's dynamically linked
+                function_response = callable_func(**function_args)
             elif target_letta_tool.tool_type == ToolType.LETTA_MEMORY_CORE:
                 callable_func = get_function_from_module(LETTA_CORE_TOOL_MODULE_NAME, function_name)
                 agent_state_copy = self.agent_state.__deepcopy__()
@@ -675,11 +686,15 @@ class Agent(BaseAgent):
         skip_verify: bool = False,
         stream: bool = False,  # TODO move to config?
         step_count: Optional[int] = None,
+        metadata: Optional[dict] = None,
     ) -> AgentStepResponse:
         """Runs a single step in the agent loop (generates at most one LLM call)"""
 
         try:
 
+            # Extract job_id from metadata if present
+            job_id = metadata.get("job_id") if metadata else None
+
             # Step 0: update core memory
             # only pulling latest block data if shared memory is being used
             current_persisted_memory = Memory(
@@ -754,9 +769,17 @@ class Agent(BaseAgent):
                     f"last response total_tokens ({current_total_tokens}) < {MESSAGE_SUMMARY_WARNING_FRAC * int(self.agent_state.llm_config.context_window)}"
                 )
 
+            # Persisting into Messages
             self.agent_state = self.agent_manager.append_to_in_context_messages(
                 all_new_messages, agent_id=self.agent_state.id, actor=self.user
             )
+            if job_id:
+                for message in all_new_messages:
+                    self.job_manager.add_message_to_job(
+                        job_id=job_id,
+                        message_id=message.id,
+                        actor=self.user,
+                    )
 
             return AgentStepResponse(
                 messages=all_new_messages,
@@ -784,6 +807,7 @@ class Agent(BaseAgent):
                     first_message_retry_limit=first_message_retry_limit,
                     skip_verify=skip_verify,
                     stream=stream,
+                    metadata=metadata,
                 )
 
             else:

letta/client/client.py

@@ -22,14 +22,17 @@ from letta.schemas.environment_variables import (
 )
 from letta.schemas.file import FileMetadata
 from letta.schemas.job import Job
+from letta.schemas.letta_message import LettaMessage, LettaMessageUnion
 from letta.schemas.letta_request import LettaRequest, LettaStreamingRequest
 from letta.schemas.letta_response import LettaResponse, LettaStreamingResponse
 from letta.schemas.llm_config import LLMConfig
 from letta.schemas.memory import ArchivalMemorySummary, ChatMemory, CreateArchivalMemory, Memory, RecallMemorySummary
 from letta.schemas.message import Message, MessageCreate, MessageUpdate
+from letta.schemas.openai.chat_completion_response import UsageStatistics
 from letta.schemas.openai.chat_completions import ToolCall
 from letta.schemas.organization import Organization
 from letta.schemas.passage import Passage
+from letta.schemas.run import Run
 from letta.schemas.sandbox_config import E2BSandboxConfig, LocalSandboxConfig, SandboxConfig, SandboxConfigCreate, SandboxConfigUpdate
 from letta.schemas.source import Source, SourceCreate, SourceUpdate
 from letta.schemas.tool import Tool, ToolCreate, ToolUpdate
@@ -433,11 +436,22 @@ class RESTClient(AbstractClient):
         self._default_llm_config = default_llm_config
         self._default_embedding_config = default_embedding_config
 
-    def list_agents(self, tags: Optional[List[str]] = None, match_all_tags: bool = False) -> List[AgentState]:
-        params = {"match_all_tags": match_all_tags}
+    def list_agents(
+        self, tags: Optional[List[str]] = None, query_text: Optional[str] = None, limit: int = 50, cursor: Optional[str] = None
+    ) -> List[AgentState]:
+        params = {"limit": limit}
         if tags:
             params["tags"] = tags
+            params["match_all_tags"] = False
+
+        if query_text:
+            params["query_text"] = query_text
+
+        if cursor:
+            params["cursor"] = cursor
+
         response = requests.get(f"{self.base_url}/{self.api_prefix}/agents", headers=self.headers, params=params)
+        print(f"\nLIST RESPONSE\n{response.json()}\n")
         return [AgentState(**agent) for agent in response.json()]
 
     def agent_exists(self, agent_id: str) -> bool:
@@ -543,6 +557,7 @@ class RESTClient(AbstractClient):
             "embedding_config": embedding_config if embedding_config else self._default_embedding_config,
             "initial_message_sequence": initial_message_sequence,
             "tags": tags,
+            "include_base_tools": include_base_tools,
         }
 
         # Only add name if it's not None
@@ -983,7 +998,7 @@ class RESTClient(AbstractClient):
         role: str,
         agent_id: Optional[str] = None,
         name: Optional[str] = None,
-    ) -> Job:
+    ) -> Run:
         """
         Send a message to an agent (async, returns a job)
 
@@ -1006,7 +1021,7 @@ class RESTClient(AbstractClient):
         )
         if response.status_code != 200:
             raise ValueError(f"Failed to send message: {response.text}")
-        response = Job(**response.json())
+        response = Run(**response.json())
 
         return response
 
@@ -1980,6 +1995,153 @@ class RESTClient(AbstractClient):
             raise ValueError(f"Failed to update block: {response.text}")
         return Block(**response.json())
 
+    def get_run_messages(
+        self,
+        run_id: str,
+        cursor: Optional[str] = None,
+        limit: Optional[int] = 100,
+        ascending: bool = True,
+        role: Optional[MessageRole] = None,
+    ) -> List[LettaMessageUnion]:
+        """
+        Get messages associated with a job with filtering options.
+
+        Args:
+            job_id: ID of the job
+            cursor: Cursor for pagination
+            limit: Maximum number of messages to return
+            ascending: Sort order by creation time
+            role: Filter by message role (user/assistant/system/tool)
+        Returns:
+            List of messages matching the filter criteria
+        """
+        params = {
+            "cursor": cursor,
+            "limit": limit,
+            "ascending": ascending,
+            "role": role,
+        }
+        # Remove None values
+        params = {k: v for k, v in params.items() if v is not None}
+
+        response = requests.get(f"{self.base_url}/{self.api_prefix}/runs/{run_id}/messages", params=params)
+        if response.status_code != 200:
+            raise ValueError(f"Failed to get run messages: {response.text}")
+        return [LettaMessage(**message) for message in response.json()]
+
+    def get_run_usage(
+        self,
+        run_id: str,
+    ) -> List[UsageStatistics]:
+        """
+        Get usage statistics associated with a job.
+
+        Args:
+            job_id (str): ID of the job
+
+        Returns:
+            List[UsageStatistics]: List of usage statistics associated with the job
+        """
+        response = requests.get(
+            f"{self.base_url}/{self.api_prefix}/runs/{run_id}/usage",
+            headers=self.headers,
+        )
+        if response.status_code != 200:
+            raise ValueError(f"Failed to get run usage statistics: {response.text}")
+        return [UsageStatistics(**stat) for stat in [response.json()]]
+
+    def get_run(self, run_id: str) -> Run:
+        """
+        Get a run by ID.
+
+        Args:
+            run_id (str): ID of the run
+
+        Returns:
+            run (Run): Run
+        """
+        response = requests.get(
+            f"{self.base_url}/{self.api_prefix}/runs/{run_id}",
+            headers=self.headers,
+        )
+        if response.status_code != 200:
+            raise ValueError(f"Failed to get run: {response.text}")
+        return Run(**response.json())
+
+    def delete_run(self, run_id: str) -> None:
+        """
+        Delete a run by ID.
+
+        Args:
+            run_id (str): ID of the run
+        """
+        response = requests.delete(
+            f"{self.base_url}/{self.api_prefix}/runs/{run_id}",
+            headers=self.headers,
+        )
+        if response.status_code != 200:
+            raise ValueError(f"Failed to delete run: {response.text}")
+
+    def list_runs(self) -> List[Run]:
+        """
+        List all runs.
+
+        Returns:
+            runs (List[Run]): List of runs
+        """
+        response = requests.get(
+            f"{self.base_url}/{self.api_prefix}/runs",
+            headers=self.headers,
+        )
+        if response.status_code != 200:
+            raise ValueError(f"Failed to list runs: {response.text}")
+        return [Run(**run) for run in response.json()]
+
+    def list_active_runs(self) -> List[Run]:
+        """
+        List all active runs.
+
+        Returns:
+            runs (List[Run]): List of active runs
+        """
+        response = requests.get(
+            f"{self.base_url}/{self.api_prefix}/runs/active",
+            headers=self.headers,
+        )
+        if response.status_code != 200:
+            raise ValueError(f"Failed to list active runs: {response.text}")
+        return [Run(**run) for run in response.json()]
+
+    def get_tags(
+        self,
+        cursor: Optional[str] = None,
+        limit: Optional[int] = None,
+        query_text: Optional[str] = None,
+    ) -> List[str]:
+        """
+        Get a list of all unique tags.
+
+        Args:
+            cursor: Optional cursor for pagination (last tag seen)
+            limit: Optional maximum number of tags to return
+            query_text: Optional text to filter tags
+
+        Returns:
+            List[str]: List of unique tags
+        """
+        params = {}
+        if cursor:
+            params["cursor"] = cursor
+        if limit:
+            params["limit"] = limit
+        if query_text:
+            params["query_text"] = query_text
+
+        response = requests.get(f"{self.base_url}/{self.api_prefix}/tags", headers=self.headers, params=params)
+        if response.status_code != 200:
+            raise ValueError(f"Failed to get tags: {response.text}")
+        return response.json()
+
 
 class LocalClient(AbstractClient):
     """
@@ -2038,10 +2200,12 @@ class LocalClient(AbstractClient):
         self.organization = self.server.get_organization_or_default(self.org_id)
 
     # agents
-    def list_agents(self, tags: Optional[List[str]] = None, match_all_tags: bool = False) -> List[AgentState]:
+    def list_agents(
+        self, query_text: Optional[str] = None, tags: Optional[List[str]] = None, limit: int = 100, cursor: Optional[str] = None
+    ) -> List[AgentState]:
         self.interface.clear()
 
-        return self.server.agent_manager.list_agents(actor=self.user, tags=tags, match_all_tags=match_all_tags)
+        return self.server.agent_manager.list_agents(actor=self.user, tags=tags, query_text=query_text, limit=limit, cursor=cursor)
 
     def agent_exists(self, agent_id: Optional[str] = None, agent_name: Optional[str] = None) -> bool:
         """
@@ -2087,6 +2251,7 @@ class LocalClient(AbstractClient):
         tool_ids: Optional[List[str]] = None,
         tool_rules: Optional[List[BaseToolRule]] = None,
         include_base_tools: Optional[bool] = True,
+        include_multi_agent_tools: bool = False,
         # metadata
         metadata: Optional[Dict] = {"human:": DEFAULT_HUMAN, "persona": DEFAULT_PERSONA},
         description: Optional[str] = None,
@@ -2104,6 +2269,7 @@ class LocalClient(AbstractClient):
             tools (List[str]): List of tools
             tool_rules (Optional[List[BaseToolRule]]): List of tool rules
             include_base_tools (bool): Include base tools
+            include_multi_agent_tools (bool): Include multi agent tools
             metadata (Dict): Metadata
             description (str): Description
             tags (List[str]): Tags for filtering agents
@@ -2113,11 +2279,6 @@ class LocalClient(AbstractClient):
         """
         # construct list of tools
         tool_ids = tool_ids or []
-        tool_names = []
-        if include_base_tools:
-            tool_names += BASE_TOOLS
-            tool_names += BASE_MEMORY_TOOLS
-        tool_ids += [self.server.tool_manager.get_tool_by_name(tool_name=name, actor=self.user).id for name in tool_names]
 
         # check if default configs are provided
         assert embedding_config or self._default_embedding_config, f"Embedding config must be provided"
@@ -2140,6 +2301,7 @@ class LocalClient(AbstractClient):
             "tool_ids": tool_ids,
             "tool_rules": tool_rules,
             "include_base_tools": include_base_tools,
+            "include_multi_agent_tools": include_multi_agent_tools,
             "system": system,
             "agent_type": agent_type,
             "llm_config": llm_config if llm_config else self._default_llm_config,
@@ -3433,3 +3595,104 @@ class LocalClient(AbstractClient):
         if label:
             data["label"] = label
         return self.server.block_manager.update_block(block_id, actor=self.user, block_update=BlockUpdate(**data))
+
+    def get_run_messages(
+        self,
+        run_id: str,
+        cursor: Optional[str] = None,
+        limit: Optional[int] = 100,
+        ascending: bool = True,
+        role: Optional[MessageRole] = None,
+    ) -> List[LettaMessageUnion]:
+        """
+        Get messages associated with a job with filtering options.
+
+        Args:
+            run_id: ID of the run
+            cursor: Cursor for pagination
+            limit: Maximum number of messages to return
+            ascending: Sort order by creation time
+            role: Filter by message role (user/assistant/system/tool)
+
+        Returns:
+            List of messages matching the filter criteria
+        """
+        params = {
+            "cursor": cursor,
+            "limit": limit,
+            "ascending": ascending,
+            "role": role,
+        }
+        return self.server.job_manager.get_run_messages_cursor(run_id=run_id, actor=self.user, **params)
+
+    def get_run_usage(
+        self,
+        run_id: str,
+    ) -> List[UsageStatistics]:
+        """
+        Get usage statistics associated with a job.
+
+        Args:
+            run_id (str): ID of the run
+
+        Returns:
+            List[UsageStatistics]: List of usage statistics associated with the run
+        """
+        usage = self.server.job_manager.get_job_usage(job_id=run_id, actor=self.user)
+        return [
+            UsageStatistics(completion_tokens=stat.completion_tokens, prompt_tokens=stat.prompt_tokens, total_tokens=stat.total_tokens)
+            for stat in usage
+        ]
+
+    def get_run(self, run_id: str) -> Run:
+        """
+        Get a run by ID.
+
+        Args:
+            run_id (str): ID of the run
+
+        Returns:
+            run (Run): Run
+        """
+        return self.server.job_manager.get_job_by_id(job_id=run_id, actor=self.user)
+
+    def delete_run(self, run_id: str) -> None:
+        """
+        Delete a run by ID.
+
+        Args:
+            run_id (str): ID of the run
+        """
+        return self.server.job_manager.delete_job_by_id(job_id=run_id, actor=self.user)
+
+    def list_runs(self) -> List[Run]:
+        """
+        List all runs.
+
+        Returns:
+            runs (List[Run]): List of runs
+        """
+        return self.server.job_manager.list_jobs(actor=self.user, job_type=JobType.RUN)
+
+    def list_active_runs(self) -> List[Run]:
+        """
+        List all active runs.
+
+        Returns:
+            runs (List[Run]): List of active runs
+        """
+        return self.server.job_manager.list_jobs(actor=self.user, job_type=JobType.RUN, statuses=[JobStatus.created, JobStatus.running])
+
+    def get_tags(
+        self,
+        cursor: str = None,
+        limit: int = 100,
+        query_text: str = None,
+    ) -> List[str]:
+        """
+        Get all tags.
+
+        Returns:
+            tags (List[str]): List of tags
+        """
+        return self.server.agent_manager.list_tags(actor=self.user, cursor=cursor, limit=limit, query_text=query_text)

letta/constants.py

@@ -12,6 +12,7 @@ COMPOSIO_ENTITY_ENV_VAR_KEY = "COMPOSIO_ENTITY"
 COMPOSIO_TOOL_TAG_NAME = "composio"
 
 LETTA_CORE_TOOL_MODULE_NAME = "letta.functions.function_sets.base"
+LETTA_MULTI_AGENT_TOOL_MODULE_NAME = "letta.functions.function_sets.multi_agent"
 
 # String in the error message for when the context window is too large
 # Example full message:
@@ -48,6 +49,10 @@ DEFAULT_PRESET = "memgpt_chat"
 BASE_TOOLS = ["send_message", "conversation_search", "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"]
+# Multi agent tools
+MULTI_AGENT_TOOLS = ["send_message_to_specific_agent", "send_message_to_agents_matching_all_tags"]
+MULTI_AGENT_SEND_MESSAGE_MAX_RETRIES = 3
+MULTI_AGENT_SEND_MESSAGE_TIMEOUT = 20 * 60
 
 # The name of the tool used to send message to the user
 # May not be relevant in cases where the agent has multiple ways to message to user (send_imessage, send_discord_mesasge, ...)

letta/functions/function_sets/multi_agent.py

@@ -0,0 +1,96 @@
+import asyncio
+from typing import TYPE_CHECKING, List, Optional
+
+from letta.constants import MULTI_AGENT_SEND_MESSAGE_MAX_RETRIES, MULTI_AGENT_SEND_MESSAGE_TIMEOUT
+from letta.functions.helpers import async_send_message_with_retries
+from letta.orm.errors import NoResultFound
+from letta.server.rest_api.utils import get_letta_server
+
+if TYPE_CHECKING:
+    from letta.agent import Agent
+
+
+def send_message_to_specific_agent(self: "Agent", message: str, other_agent_id: str) -> Optional[str]:
+    """
+    Send a message to a specific Letta agent within the same organization.
+
+    Args:
+        message (str): The message to be sent to the target Letta agent.
+        other_agent_id (str): The identifier of the target Letta agent.
+
+    Returns:
+        Optional[str]: The response from the Letta agent. It's possible that the agent does not respond.
+    """
+    server = get_letta_server()
+
+    # Ensure the target agent is in the same org
+    try:
+        server.agent_manager.get_agent_by_id(agent_id=other_agent_id, actor=self.user)
+    except NoResultFound:
+        raise ValueError(
+            f"The passed-in agent_id {other_agent_id} either does not exist, "
+            f"or does not belong to the same org ({self.user.organization_id})."
+        )
+
+    # Async logic to send a message with retries and timeout
+    async def async_send_single_agent():
+        return await async_send_message_with_retries(
+            server=server,
+            sender_agent=self,
+            target_agent_id=other_agent_id,
+            message_text=message,
+            max_retries=MULTI_AGENT_SEND_MESSAGE_MAX_RETRIES,  # or your chosen constants
+            timeout=MULTI_AGENT_SEND_MESSAGE_TIMEOUT,  # e.g., 1200 for 20 min
+            logging_prefix="[send_message_to_specific_agent]",
+        )
+
+    # Run in the current event loop or create one if needed
+    try:
+        return asyncio.run(async_send_single_agent())
+    except RuntimeError:
+        # e.g., in case there's already an active loop
+        loop = asyncio.get_event_loop()
+        if loop.is_running():
+            return loop.run_until_complete(async_send_single_agent())
+        else:
+            raise
+
+
+def send_message_to_agents_matching_all_tags(self: "Agent", message: str, tags: List[str]) -> List[str]:
+    """
+    Send a message to all agents in the same organization that match ALL of the given tags.
+
+    Messages are sent in parallel for improved performance, with retries on flaky calls and timeouts for long-running requests.
+    This function does not use a cursor (pagination) and enforces a limit of 100 agents.
+
+    Args:
+        message (str): The message to be sent to each matching agent.
+        tags (List[str]): The list of tags that each agent must have (match_all_tags=True).
+
+    Returns:
+        List[str]: A list of responses from the agents that match all tags.
+                   Each response corresponds to one agent.
+    """
+    server = get_letta_server()
+
+    # Retrieve agents that match ALL specified tags
+    matching_agents = server.agent_manager.list_agents(actor=self.user, tags=tags, match_all_tags=True, cursor=None, limit=100)
+
+    async def send_messages_to_all_agents():
+        tasks = [
+            async_send_message_with_retries(
+                server=server,
+                sender_agent=self,
+                target_agent_id=agent_state.id,
+                message_text=message,
+                max_retries=MULTI_AGENT_SEND_MESSAGE_MAX_RETRIES,
+                timeout=MULTI_AGENT_SEND_MESSAGE_TIMEOUT,
+                logging_prefix="[send_message_to_agents_matching_all_tags]",
+            )
+            for agent_state in matching_agents
+        ]
+        # Run all tasks in parallel
+        return await asyncio.gather(*tasks)
+
+    # Run the async function and return results
+    return asyncio.run(send_messages_to_all_agents())