letta-nightly 0.7.20.dev20250521104258__py3-none-any.whl → 0.7.21.dev20250522104246__py3-none-any.whl

letta/services/tool_executor/tool_executor.py

@@ -1,35 +1,64 @@
+import asyncio
+import json
 import math
 import traceback
 from abc import ABC, abstractmethod
-from typing import Any, Dict, Optional
+from textwrap import shorten
+from typing import Any, Dict, List, Literal, Optional
 
 from letta.constants import (
     COMPOSIO_ENTITY_ENV_VAR_KEY,
     CORE_MEMORY_LINE_NUMBER_WARNING,
     READ_ONLY_BLOCK_EDIT_ERROR,
     RETRIEVAL_QUERY_DEFAULT_PAGE_SIZE,
+    WEB_SEARCH_CLIP_CONTENT,
+    WEB_SEARCH_INCLUDE_SCORE,
+    WEB_SEARCH_SEPARATOR,
 )
 from letta.functions.ast_parsers import coerce_dict_args_by_annotations, get_function_annotations_from_source
 from letta.functions.composio_helpers import execute_composio_action_async, generate_composio_action_from_func_name
 from letta.helpers.composio_helpers import get_composio_api_key
 from letta.helpers.json_helpers import json_dumps
+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
+from letta.schemas.letta_message_content import TextContent
+from letta.schemas.message import MessageCreate
 from letta.schemas.sandbox_config import SandboxConfig
 from letta.schemas.tool import Tool
 from letta.schemas.tool_execution_result import ToolExecutionResult
 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
 from letta.services.passage_manager import PassageManager
 from letta.services.tool_sandbox.e2b_sandbox import AsyncToolSandboxE2B
 from letta.services.tool_sandbox.local_sandbox import AsyncToolSandboxLocal
 from letta.settings import tool_settings
+from letta.tracing import trace_method
 from letta.utils import get_friendly_error_msg
 
+logger = get_logger(__name__)
+
 
 class ToolExecutor(ABC):
     """Abstract base class for tool executors."""
 
+    def __init__(
+        self,
+        message_manager: MessageManager,
+        agent_manager: AgentManager,
+        block_manager: BlockManager,
+        passage_manager: PassageManager,
+        actor: User,
+    ):
+        self.message_manager = message_manager
+        self.agent_manager = agent_manager
+        self.block_manager = block_manager
+        self.passage_manager = passage_manager
+        self.actor = actor
+
     @abstractmethod
     def execute(
         self,
@@ -493,17 +522,113 @@ class LettaCoreToolExecutor(ToolExecutor):
 class LettaMultiAgentToolExecutor(ToolExecutor):
     """Executor for LETTA multi-agent core tools."""
 
-    # TODO: Implement
-    # def execute(self, function_name: str, function_args: dict, agent: "Agent", tool: Tool) -> ToolExecutionResult:
-    #     callable_func = get_function_from_module(LETTA_MULTI_AGENT_TOOL_MODULE_NAME, function_name)
-    #     function_args["self"] = agent  # need to attach self to arg since it's dynamically linked
-    #     function_response = callable_func(**function_args)
-    #     return ToolExecutionResult(func_return=function_response)
+    async def execute(
+        self,
+        function_name: str,
+        function_args: dict,
+        agent_state: AgentState,
+        tool: Tool,
+        actor: User,
+        sandbox_config: Optional[SandboxConfig] = None,
+        sandbox_env_vars: Optional[Dict[str, Any]] = None,
+    ) -> ToolExecutionResult:
+        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,
+        }
+
+        if function_name not in function_map:
+            raise ValueError(f"Unknown function: {function_name}")
+
+        # Execute the appropriate function
+        function_args_copy = function_args.copy()  # Make a copy to avoid modifying the original
+        function_response = await function_map[function_name](agent_state, **function_args_copy)
+        return ToolExecutionResult(
+            status="success",
+            func_return=function_response,
+        )
+
+    async def send_message_to_agent_and_wait_for_reply(self, agent_state: AgentState, message: str, other_agent_id: str) -> str:
+        augmented_message = (
+            f"[Incoming message from agent with ID '{agent_state.id}' - to reply to this message, "
+            f"make sure to use the 'send_message' at the end, and the system will notify the sender of your response] "
+            f"{message}"
+        )
+
+        return str(await self._process_agent(agent_id=other_agent_id, message=augmented_message))
+
+    async def send_message_to_agent_async(self, agent_state: AgentState, message: str, other_agent_id: str) -> str:
+        # 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"
+
+    async def send_message_to_agents_matching_tags(
+        self, agent_state: AgentState, message: str, match_all: List[str], match_some: List[str]
+    ) -> str:
+        # Find matching agents
+        matching_agents = self.agent_manager.list_agents_matching_tags(actor=self.actor, match_all=match_all, match_some=match_some)
+        if not matching_agents:
+            return str([])
+
+        augmented_message = (
+            "[Incoming message from external Letta agent - to reply to this message, "
+            "make sure to use the 'send_message' at the end, and the system will notify "
+            "the sender of your response] "
+            f"{message}"
+        )
+
+        tasks = [
+            asyncio.create_task(self._process_agent(agent_id=agent_state.id, message=augmented_message)) for agent_state in matching_agents
+        ]
+        results = await asyncio.gather(*tasks)
+        return str(results)
+
+    async def _process_agent(self, agent_id: str, message: str) -> Dict[str, Any]:
+        from letta.agents.letta_agent import LettaAgent
+
+        try:
+            letta_agent = LettaAgent(
+                agent_id=agent_id,
+                message_manager=self.message_manager,
+                agent_manager=self.agent_manager,
+                block_manager=self.block_manager,
+                passage_manager=self.passage_manager,
+                actor=self.actor,
+            )
+
+            letta_response = await letta_agent.step([MessageCreate(role=MessageRole.system, content=[TextContent(text=message)])])
+            messages = letta_response.messages
+
+            send_message_content = [message.content for message in messages if isinstance(message, AssistantMessage)]
+
+            return {
+                "agent_id": agent_id,
+                "response": send_message_content if send_message_content else ["<no response>"],
+            }
+
+        except Exception as e:
+            return {
+                "agent_id": agent_id,
+                "error": str(e),
+                "type": type(e).__name__,
+            }
 
 
 class ExternalComposioToolExecutor(ToolExecutor):
     """Executor for external Composio tools."""
 
+    @trace_method
     async def execute(
         self,
         function_name: str,
@@ -595,6 +720,7 @@ class ExternalMCPToolExecutor(ToolExecutor):
 class SandboxToolExecutor(ToolExecutor):
     """Executor for sandboxed tools."""
 
+    @trace_method
     async def execute(
         self,
         function_name: str,
@@ -674,3 +800,106 @@ class SandboxToolExecutor(ToolExecutor):
             func_return=error_message,
             stderr=[stderr],
         )
+
+
+class LettaBuiltinToolExecutor(ToolExecutor):
+    """Executor for built in Letta tools."""
+
+    @trace_method
+    async def execute(
+        self,
+        function_name: str,
+        function_args: dict,
+        agent_state: AgentState,
+        tool: Tool,
+        actor: User,
+        sandbox_config: Optional[SandboxConfig] = None,
+        sandbox_env_vars: Optional[Dict[str, Any]] = None,
+    ) -> ToolExecutionResult:
+        function_map = {"run_code": self.run_code, "web_search": self.web_search}
+
+        if function_name not in function_map:
+            raise ValueError(f"Unknown function: {function_name}")
+
+        # Execute the appropriate function
+        function_args_copy = function_args.copy()  # Make a copy to avoid modifying the original
+        function_response = await function_map[function_name](**function_args_copy)
+
+        return ToolExecutionResult(
+            status="success",
+            func_return=function_response,
+        )
+
+    async def run_code(self, code: str, language: Literal["python", "js", "ts", "r", "java"]) -> str:
+        from e2b_code_interpreter import AsyncSandbox
+
+        if tool_settings.e2b_api_key is None:
+            raise ValueError("E2B_API_KEY is not set")
+
+        sbx = await AsyncSandbox.create(api_key=tool_settings.e2b_api_key)
+        params = {"code": code}
+        if language != "python":
+            # Leave empty for python
+            params["language"] = language
+
+        res = self._llm_friendly_result(await sbx.run_code(**params))
+        return json.dumps(res, ensure_ascii=False)
+
+    def _llm_friendly_result(self, res):
+        out = {
+            "results": [r.text if hasattr(r, "text") else str(r) for r in res.results],
+            "logs": {
+                "stdout": getattr(res.logs, "stdout", []),
+                "stderr": getattr(res.logs, "stderr", []),
+            },
+        }
+        err = getattr(res, "error", None)
+        if err is not None:
+            out["error"] = err
+        return out
+
+    async def web_search(agent_state: "AgentState", query: str) -> str:
+        """
+        Search the web for information.
+        Args:
+            query (str): The query to search the web for.
+        Returns:
+            str: The search results.
+        """
+
+        try:
+            from tavily import AsyncTavilyClient
+        except ImportError:
+            raise ImportError("tavily is not installed in the tool execution environment")
+
+        # Check if the API key exists
+        if tool_settings.tavily_api_key is None:
+            raise ValueError("TAVILY_API_KEY is not set")
+
+        # Instantiate client and search
+        tavily_client = AsyncTavilyClient(api_key=tool_settings.tavily_api_key)
+        search_results = await tavily_client.search(query=query, auto_parameters=True)
+
+        results = search_results.get("results", [])
+        if not results:
+            return "No search results found."
+
+        # ---- format for the LLM -------------------------------------------------
+        formatted_blocks = []
+        for idx, item in enumerate(results, start=1):
+            title = item.get("title") or "Untitled"
+            url = item.get("url") or "Unknown URL"
+            # keep each content snippet reasonably short so you don’t blow up context
+            content = (
+                shorten(item.get("content", "").strip(), width=600, placeholder=" …")
+                if WEB_SEARCH_CLIP_CONTENT
+                else item.get("content", "").strip()
+            )
+            score = item.get("score")
+            if WEB_SEARCH_INCLUDE_SCORE:
+                block = f"\nRESULT {idx}:\n" f"Title: {title}\n" f"URL: {url}\n" f"Relevance score: {score:.4f}\n" f"Content: {content}\n"
+            else:
+                block = f"\nRESULT {idx}:\n" f"Title: {title}\n" f"URL: {url}\n" f"Content: {content}\n"
+            formatted_blocks.append(block)
+
+        return WEB_SEARCH_SEPARATOR.join(formatted_blocks)

letta/services/tool_manager.py

@@ -1,3 +1,4 @@
+import asyncio
 import importlib
 import warnings
 from typing import List, Optional
@@ -9,6 +10,7 @@ from letta.constants import (
     BASE_TOOLS,
     BASE_VOICE_SLEEPTIME_CHAT_TOOLS,
     BASE_VOICE_SLEEPTIME_TOOLS,
+    BUILTIN_TOOLS,
     LETTA_TOOL_SET,
     MCP_TOOL_TAG_NAME_PREFIX,
     MULTI_AGENT_TOOLS,
@@ -59,6 +61,32 @@ class ToolManager:
 
         return tool
 
+    @enforce_types
+    async def create_or_update_tool_async(self, pydantic_tool: PydanticTool, actor: PydanticUser) -> PydanticTool:
+        """Create a new tool based on the ToolCreate schema."""
+        tool_id = await self.get_tool_id_by_name_async(tool_name=pydantic_tool.name, actor=actor)
+        if tool_id:
+            # Put to dict and remove fields that should not be reset
+            update_data = pydantic_tool.model_dump(exclude_unset=True, exclude_none=True)
+
+            # If there's anything to update
+            if update_data:
+                # In case we want to update the tool type
+                # Useful if we are shuffling around base tools
+                updated_tool_type = None
+                if "tool_type" in update_data:
+                    updated_tool_type = update_data.get("tool_type")
+                tool = await self.update_tool_by_id_async(tool_id, ToolUpdate(**update_data), actor, updated_tool_type=updated_tool_type)
+            else:
+                printd(
+                    f"`create_or_update_tool` was called with user_id={actor.id}, organization_id={actor.organization_id}, name={pydantic_tool.name}, but found existing tool with nothing to update."
+                )
+                tool = await self.get_tool_by_id_async(tool_id, actor=actor)
+        else:
+            tool = await self.create_tool_async(pydantic_tool, actor=actor)
+
+        return tool
+
     @enforce_types
     def create_or_update_mcp_tool(self, tool_create: ToolCreate, mcp_server_name: str, actor: PydanticUser) -> PydanticTool:
         metadata = {MCP_TOOL_TAG_NAME_PREFIX: {"server_name": mcp_server_name}}
@@ -96,6 +124,21 @@ class ToolManager:
             tool.create(session, actor=actor)  # Re-raise other database-related errors
         return tool.to_pydantic()
 
+    @enforce_types
+    async def create_tool_async(self, pydantic_tool: PydanticTool, actor: PydanticUser) -> PydanticTool:
+        """Create a new tool based on the ToolCreate schema."""
+        async with db_registry.async_session() as session:
+            # Set the organization id at the ORM layer
+            pydantic_tool.organization_id = actor.organization_id
+            # Auto-generate description if not provided
+            if pydantic_tool.description is None:
+                pydantic_tool.description = pydantic_tool.json_schema.get("description", None)
+            tool_data = pydantic_tool.model_dump(to_orm=True)
+
+            tool = ToolModel(**tool_data)
+            await tool.create_async(session, actor=actor)  # Re-raise other database-related errors
+        return tool.to_pydantic()
+
     @enforce_types
     def get_tool_by_id(self, tool_id: str, actor: PydanticUser) -> PydanticTool:
         """Fetch a tool by its ID."""
@@ -105,6 +148,15 @@ class ToolManager:
             # Convert the SQLAlchemy Tool object to PydanticTool
             return tool.to_pydantic()
 
+    @enforce_types
+    async def get_tool_by_id_async(self, tool_id: str, actor: PydanticUser) -> PydanticTool:
+        """Fetch a tool by its ID."""
+        async with db_registry.async_session() as session:
+            # Retrieve tool by id using the Tool model's read method
+            tool = await ToolModel.read_async(db_session=session, identifier=tool_id, actor=actor)
+            # Convert the SQLAlchemy Tool object to PydanticTool
+            return tool.to_pydantic()
+
     @enforce_types
     def get_tool_by_name(self, tool_name: str, actor: PydanticUser) -> Optional[PydanticTool]:
         """Retrieve a tool by its name and a user. We derive the organization from the user, and retrieve that tool."""
@@ -135,6 +187,16 @@ class ToolManager:
         except NoResultFound:
             return None
 
+    @enforce_types
+    async def get_tool_id_by_name_async(self, tool_name: str, actor: PydanticUser) -> Optional[str]:
+        """Retrieve a tool by its name and a user. We derive the organization from the user, and retrieve that tool."""
+        try:
+            async with db_registry.async_session() as session:
+                tool = await ToolModel.read_async(db_session=session, name=tool_name, actor=actor)
+                return tool.id
+        except NoResultFound:
+            return None
+
     @enforce_types
     async def list_tools_async(self, actor: PydanticUser, after: Optional[str] = None, limit: Optional[int] = 50) -> List[PydanticTool]:
         """List all tools with optional pagination."""
@@ -204,6 +266,35 @@ class ToolManager:
             # Save the updated tool to the database
             return tool.update(db_session=session, actor=actor).to_pydantic()
 
+    @enforce_types
+    async def update_tool_by_id_async(
+        self, tool_id: str, tool_update: ToolUpdate, actor: PydanticUser, updated_tool_type: Optional[ToolType] = None
+    ) -> PydanticTool:
+        """Update a tool by its ID with the given ToolUpdate object."""
+        async with db_registry.async_session() as session:
+            # Fetch the tool by ID
+            tool = await ToolModel.read_async(db_session=session, identifier=tool_id, actor=actor)
+
+            # Update tool attributes with only the fields that were explicitly set
+            update_data = tool_update.model_dump(to_orm=True, exclude_none=True)
+            for key, value in update_data.items():
+                setattr(tool, key, value)
+
+            # If source code is changed and a new json_schema is not provided, we want to auto-refresh the schema
+            if "source_code" in update_data.keys() and "json_schema" not in update_data.keys():
+                pydantic_tool = tool.to_pydantic()
+                new_schema = derive_openai_json_schema(source_code=pydantic_tool.source_code)
+
+                tool.json_schema = new_schema
+                tool.name = new_schema["name"]
+
+            if updated_tool_type:
+                tool.tool_type = updated_tool_type
+
+            # Save the updated tool to the database
+            tool = await tool.update_async(db_session=session, actor=actor)
+            return tool.to_pydantic()
+
     @enforce_types
     def delete_tool_by_id(self, tool_id: str, actor: PydanticUser) -> None:
         """Delete a tool by its ID."""
@@ -218,7 +309,7 @@ class ToolManager:
     def upsert_base_tools(self, actor: PydanticUser) -> List[PydanticTool]:
         """Add default tools in base.py and multi_agent.py"""
         functions_to_schema = {}
-        module_names = ["base", "multi_agent", "voice"]
+        module_names = ["base", "multi_agent", "voice", "builtin"]
 
         for module_name in module_names:
             full_module_name = f"letta.functions.function_sets.{module_name}"
@@ -254,6 +345,9 @@ class ToolManager:
                 elif name in BASE_VOICE_SLEEPTIME_TOOLS or name in BASE_VOICE_SLEEPTIME_CHAT_TOOLS:
                     tool_type = ToolType.LETTA_VOICE_SLEEPTIME_CORE
                     tags = [tool_type.value]
+                elif name in BUILTIN_TOOLS:
+                    tool_type = ToolType.LETTA_BUILTIN
+                    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}"
@@ -275,3 +369,68 @@ class ToolManager:
 
         # TODO: Delete any base tools that are stale
         return tools
+
+    @enforce_types
+    async def upsert_base_tools_async(self, actor: PydanticUser) -> List[PydanticTool]:
+        """Add default tools in base.py and multi_agent.py"""
+        functions_to_schema = {}
+        module_names = ["base", "multi_agent", "voice", "builtin"]
+
+        for module_name in module_names:
+            full_module_name = f"letta.functions.function_sets.{module_name}"
+            try:
+                module = importlib.import_module(full_module_name)
+            except Exception as e:
+                # Handle other general exceptions
+                raise e
+
+            try:
+                # Load the function set
+                functions_to_schema.update(load_function_set(module))
+            except ValueError as e:
+                err = f"Error loading function set '{module_name}': {e}"
+                warnings.warn(err)
+
+        # create tool in db
+        tools = []
+        for name, schema in functions_to_schema.items():
+            if name in LETTA_TOOL_SET:
+                if name in BASE_TOOLS:
+                    tool_type = ToolType.LETTA_CORE
+                    tags = [tool_type.value]
+                elif name in BASE_MEMORY_TOOLS:
+                    tool_type = ToolType.LETTA_MEMORY_CORE
+                    tags = [tool_type.value]
+                elif name in MULTI_AGENT_TOOLS:
+                    tool_type = ToolType.LETTA_MULTI_AGENT_CORE
+                    tags = [tool_type.value]
+                elif name in BASE_SLEEPTIME_TOOLS:
+                    tool_type = ToolType.LETTA_SLEEPTIME_CORE
+                    tags = [tool_type.value]
+                elif name in BASE_VOICE_SLEEPTIME_TOOLS or name in BASE_VOICE_SLEEPTIME_CHAT_TOOLS:
+                    tool_type = ToolType.LETTA_VOICE_SLEEPTIME_CORE
+                    tags = [tool_type.value]
+                elif name in BUILTIN_TOOLS:
+                    tool_type = ToolType.LETTA_BUILTIN
+                    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}"
+                    )
+
+                # create to tool
+                tools.append(
+                    self.create_or_update_tool_async(
+                        PydanticTool(
+                            name=name,
+                            tags=tags,
+                            source_type="python",
+                            tool_type=tool_type,
+                            return_char_limit=BASE_FUNCTION_RETURN_CHAR_LIMIT,
+                        ),
+                        actor=actor,
+                    )
+                )
+
+        # TODO: Delete any base tools that are stale
+        return await asyncio.gather(*tools)

letta/services/tool_sandbox/e2b_sandbox.py

@@ -6,6 +6,7 @@ from letta.schemas.sandbox_config import SandboxConfig, SandboxType
 from letta.schemas.tool import Tool
 from letta.schemas.tool_execution_result import ToolExecutionResult
 from letta.services.tool_sandbox.base import AsyncToolSandboxBase
+from letta.tracing import log_event, trace_method
 from letta.utils import get_friendly_error_msg
 
 logger = get_logger(__name__)
@@ -27,6 +28,7 @@ class AsyncToolSandboxE2B(AsyncToolSandboxBase):
         super().__init__(tool_name, args, user, tool_object, sandbox_config=sandbox_config, sandbox_env_vars=sandbox_env_vars)
         self.force_recreate = force_recreate
 
+    @trace_method
     async def run(
         self,
         agent_state: Optional[AgentState] = None,
@@ -44,6 +46,7 @@ class AsyncToolSandboxE2B(AsyncToolSandboxBase):
 
         return result
 
+    @trace_method
     async def run_e2b_sandbox(
         self, agent_state: Optional[AgentState] = None, additional_env_vars: Optional[Dict] = None
     ) -> ToolExecutionResult:
@@ -81,10 +84,21 @@ class AsyncToolSandboxE2B(AsyncToolSandboxBase):
             env_vars.update(additional_env_vars)
         code = self.generate_execution_script(agent_state=agent_state)
 
+        log_event(
+            "e2b_execution_started",
+            {"tool": self.tool_name, "sandbox_id": e2b_sandbox.sandbox_id, "code": code, "env_vars": env_vars},
+        )
         execution = await e2b_sandbox.run_code(code, envs=env_vars)
-
         if execution.results:
             func_return, agent_state = self.parse_best_effort(execution.results[0].text)
+            log_event(
+                "e2b_execution_succeeded",
+                {
+                    "tool": self.tool_name,
+                    "sandbox_id": e2b_sandbox.sandbox_id,
+                    "func_return": func_return,
+                },
+            )
         elif execution.error:
             logger.error(f"Executing tool {self.tool_name} raised a {execution.error.name} with message: \n{execution.error.value}")
             logger.error(f"Traceback from e2b sandbox: \n{execution.error.traceback}")
@@ -92,7 +106,25 @@ class AsyncToolSandboxE2B(AsyncToolSandboxBase):
                 function_name=self.tool_name, exception_name=execution.error.name, exception_message=execution.error.value
             )
             execution.logs.stderr.append(execution.error.traceback)
+            log_event(
+                "e2b_execution_failed",
+                {
+                    "tool": self.tool_name,
+                    "sandbox_id": e2b_sandbox.sandbox_id,
+                    "error_type": execution.error.name,
+                    "error_message": execution.error.value,
+                    "func_return": func_return,
+                },
+            )
         else:
+            log_event(
+                "e2b_execution_empty",
+                {
+                    "tool": self.tool_name,
+                    "sandbox_id": e2b_sandbox.sandbox_id,
+                    "status": "no_results_no_error",
+                },
+            )
             raise ValueError(f"Tool {self.tool_name} returned execution with None")
 
         return ToolExecutionResult(
@@ -110,24 +142,54 @@ class AsyncToolSandboxE2B(AsyncToolSandboxBase):
         exception_class = builtins_dict.get(e2b_execution.error.name, Exception)
         return exception_class(e2b_execution.error.value)
 
+    @trace_method
     async def create_e2b_sandbox_with_metadata_hash(self, sandbox_config: SandboxConfig) -> "Sandbox":
         from e2b_code_interpreter import AsyncSandbox
 
         state_hash = sandbox_config.fingerprint()
         e2b_config = sandbox_config.get_e2b_config()
 
+        log_event(
+            "e2b_sandbox_create_started",
+            {
+                "sandbox_fingerprint": state_hash,
+                "e2b_config": e2b_config.model_dump(),
+            },
+        )
+
         if e2b_config.template:
             sbx = await AsyncSandbox.create(sandbox_config.get_e2b_config().template, metadata={self.METADATA_CONFIG_STATE_KEY: state_hash})
         else:
-            # no template
             sbx = await AsyncSandbox.create(
                 metadata={self.METADATA_CONFIG_STATE_KEY: state_hash}, **e2b_config.model_dump(exclude={"pip_requirements"})
             )
 
-        # install pip requirements
+        log_event(
+            "e2b_sandbox_create_finished",
+            {
+                "sandbox_id": sbx.sandbox_id,
+                "sandbox_fingerprint": state_hash,
+            },
+        )
+
         if e2b_config.pip_requirements:
             for package in e2b_config.pip_requirements:
+                log_event(
+                    "e2b_pip_install_started",
+                    {
+                        "sandbox_id": sbx.sandbox_id,
+                        "package": package,
+                    },
+                )
                 await sbx.commands.run(f"pip install {package}")
+                log_event(
+                    "e2b_pip_install_finished",
+                    {
+                        "sandbox_id": sbx.sandbox_id,
+                        "package": package,
+                    },
+                )
+
         return sbx
 
     async def list_running_e2b_sandboxes(self):