feat: add e2b sandbox

.gitignore

@@ -160,6 +160,7 @@ cython_debug/
 .DS_Store
 .local
 sandbox
+!dynamiq/sandbox/
 
 # Chainlit
 .chainlit

dynamiq/nodes/agents/agent.py

@@ -20,8 +20,8 @@
 from dynamiq.nodes.agents.utils import SummarizationConfig, ToolCacheEntry, XMLParser
 from dynamiq.nodes.node import Node, NodeDependency
 from dynamiq.nodes.tools.context_manager import ContextManagerTool
-from dynamiq.nodes.tools.todo_tools import TodoItem, TodoWriteTool
 from dynamiq.nodes.tools.parallel_tool_calls import PARALLEL_TOOL_NAME, ParallelToolCallsInputSchema
+from dynamiq.nodes.tools.todo_tools import TodoItem, TodoWriteTool
 from dynamiq.nodes.types import Behavior, InferenceMode
 from dynamiq.prompts import Message, MessageRole, VisionMessage, VisionMessageTextContent
 from dynamiq.runnables import RunnableConfig

dynamiq/nodes/agents/base.py

@@ -36,6 +36,7 @@
 from dynamiq.nodes.tools.python_code_executor import PythonCodeExecutor
 from dynamiq.prompts import Message, MessageRole, Prompt, VisionMessage, VisionMessageTextContent
 from dynamiq.runnables import RunnableConfig, RunnableResult, RunnableStatus
+from dynamiq.sandbox.base import SandboxConfig
 from dynamiq.storages.file.base import FileStore, FileStoreConfig
 from dynamiq.storages.file.in_memory import InMemoryFileStore
 from dynamiq.utils.logger import logger
@@ -212,6 +213,7 @@ class Agent(Node):
         default_factory=lambda: FileStoreConfig(enabled=False, backend=InMemoryFileStore()),
         description="Configuration for file storage used by the agent.",
     )
+    sandbox: SandboxConfig = Field(default=None, description="Configuration for sandbox used by the agent.")
     file_attachment_preview_bytes: int = Field(
         default=512,
         description="Maximum number of bytes/characters from each uploaded file to surface as an inline preview.",
@@ -295,14 +297,26 @@ def __init__(self, **kwargs):
 
         self.tools = expanded_tools
 
-        if self.file_store_backend:
+        if self.sandbox:
+            # Add sandbox tools when sandbox is enabled
+
+            tools = self.sandbox.backend.get_tools(
+                llm=self.llm,
+            )
+            self.tools.extend(tools)
+
+        elif self.file_store_backend:
+            # Add file tools when file store is enabled
+            self.tools.extend(
+                [
+                    FileReadTool(file_store=self.file_store_backend, llm=self.llm),
+                    FileSearchTool(file_store=self.file_store_backend),
+                    FileListTool(file_store=self.file_store_backend),
+                ]
+            )
             if self.file_store.agent_file_write_enabled:
                 self.tools.append(FileWriteTool(file_store=self.file_store_backend))
 
-            self.tools.append(FileReadTool(file_store=self.file_store_backend, llm=self.llm))
-            self.tools.append(FileSearchTool(file_store=self.file_store_backend))
-            self.tools.append(FileListTool(file_store=self.file_store_backend))
-
         if self.parallel_tool_calls_enabled:
             # Filter out any user tools with the reserved parallel tool name
             self.tools = [t for t in self.tools if t.name != PARALLEL_TOOL_NAME]
@@ -444,6 +458,7 @@ def execute(
 
         logger.info(f"Agent {self.name} - {self.id}: started with input {log_data}")
         self.reset_run_state()
+
         config = ensure_config(config)
         self.run_on_node_execute_run(config.callbacks, **kwargs)
 
@@ -490,9 +505,14 @@ def execute(
         if files:
             if not self.file_store_backend:
                 self.file_store = FileStoreConfig(enabled=True, backend=InMemoryFileStore())
-                self.tools.append(FileReadTool(file_store=self.file_store.backend, llm=self.llm))
-                self.tools.append(FileSearchTool(file_store=self.file_store.backend))
-                self.tools.append(FileListTool(file_store=self.file_store.backend))
+                # Add file tools
+                self.tools.extend(
+                    [
+                        FileReadTool(file_store=self.file_store_backend, llm=self.llm),
+                        FileSearchTool(file_store=self.file_store_backend),
+                        FileListTool(file_store=self.file_store_backend),
+                    ]
+                )
 
                 new_tool_description = self.tool_description
                 self.system_prompt_manager.set_initial_variable("tool_description", new_tool_description)
@@ -546,7 +566,7 @@ def execute(
             if filtered_files:
                 execution_result["files"] = filtered_files
                 logger.info(
-                    f"Agent {self.name} - {self.id}: returning {len(filtered_files)} generated file(s) in FileStore"
+                    f"Agent {self.name} - {self.id}: returning {len(filtered_files)} generated file(s) in file store"
                 )
 
         logger.info(f"Node {self.name} - {self.id}: finished with RESULT:\n{str(result)[:200]}...")
@@ -962,7 +982,7 @@ def _run_tool(
         return tool_result_content_processed, output_files
 
     def _ensure_named_files(self, files: list[io.BytesIO | bytes]) -> list[io.BytesIO | bytes]:
-        """Ensure all uploaded files have name and description attributes and store them in file_store if available."""
+        """Ensure all uploaded files have name and description attributes and store them in file store if available."""
         named = []
         for i, f in enumerate(files):
             if isinstance(f, bytes):
@@ -980,7 +1000,7 @@ def _ensure_named_files(self, files: list[io.BytesIO | bytes]) -> list[io.BytesI
                             overwrite=True,
                         )
                     except Exception as e:
-                        logger.warning(f"Failed to store file {bio.name} in file_store: {e}")
+                        logger.warning(f"Failed to store file {bio.name} in file store: {e}")
 
                 named.append(bio)
             elif isinstance(f, io.BytesIO):
@@ -1002,7 +1022,7 @@ def _ensure_named_files(self, files: list[io.BytesIO | bytes]) -> list[io.BytesI
                             overwrite=True,
                         )
                     except Exception as e:
-                        logger.warning(f"Failed to store file {f.name} in file_store: {e}")
+                        logger.warning(f"Failed to store file {f.name} in file store: {e}")
 
                 named.append(f)
             else:
@@ -1234,6 +1254,22 @@ def _build_child_agent_context(self, child_agent: "Agent") -> dict[str, Any]:
 
         return child_context
 
+    def cleanup(self) -> None:
+        """Cleanup agent resources (sandbox, etc.)."""
+        if self.sandbox and hasattr(self.sandbox.backend, "close"):
+            try:
+                self.sandbox.backend.close()
+            except Exception as e:
+                logger.warning(f"Agent {self.name} - {self.id}: failed to close sandbox: {e}")
+
+    def __del__(self):
+        """Destructor - attempt to cleanup on garbage collection."""
+        try:
+            self.cleanup()
+        except Exception:
+            # Cannot reliably log in __del__, just suppress
+            ...  # noqa: E701
+
     def get_clone_attr_initializers(self) -> dict[str, Callable[[Node], Any]]:
         base = super().get_clone_attr_initializers()
         from dynamiq.prompts import Prompt

dynamiq/sandbox/__init__.py

@@ -0,0 +1,9 @@
+from .base import Sandbox, SandboxConfig, ShellCommandResult
+from .e2b import E2BSandbox
+
+__all__ = [
+    "Sandbox",
+    "SandboxConfig",
+    "ShellCommandResult",
+    "E2BSandbox",
+]

dynamiq/sandbox/base.py

@@ -0,0 +1,129 @@
+"""Base file storage interface and common data structures."""
+
+import abc
+from functools import cached_property
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, computed_field
+
+from dynamiq.nodes.node import Node
+
+
+class ShellCommandResult(BaseModel):
+    """Result of a shell command execution."""
+
+    stdout: str
+    stderr: str
+    exit_code: int | None
+
+
+class Sandbox(abc.ABC, BaseModel):
+    """Abstract base class for sandbox implementations.
+
+    This interface provides a unified way to interact with different
+    sandbox backends (in-memory, file system, E2B, Docker, etc.).
+    Sandboxes provide file storage and can be extended to support
+    code execution and other isolated environment capabilities.
+    """
+
+    @computed_field
+    @cached_property
+    def type(self) -> str:
+        """Returns the backend type as a string."""
+        return f"{self.__module__.rsplit('.', 1)[0]}.{self.__class__.__name__}"
+
+    def to_dict(self, **kwargs) -> dict[str, Any]:
+        """Convert the Sandbox instance to a dictionary.
+
+        Returns:
+            dict: Dictionary representation of the Sandbox instance.
+        """
+        for param in ("include_secure_params", "for_tracing"):
+            kwargs.pop(param, None)
+        data = self.model_dump(**kwargs)
+        data["type"] = self.type
+        return data
+
+    def run_command(
+        self,
+        command: str,
+        timeout: int = 60,
+        background: bool = False,
+    ) -> ShellCommandResult:
+        """Execute a shell command in the sandbox.
+
+        This is an optional capability. Subclasses that support command execution
+        should override this method. The base implementation raises NotImplementedError.
+
+        Args:
+            command: Shell command or script to execute.
+            timeout: Timeout in seconds (default 60).
+            background: If True, run command in background (no output).
+
+        Returns:
+            ShellCommandResult with stdout, stderr, and exit_code.
+
+        Raises:
+            NotImplementedError: If the sandbox does not support command execution.
+        """
+        raise NotImplementedError(
+            f"{self.__class__.__name__} does not support command execution. "
+            "Use a sandbox backend that supports shell commands (e.g., E2BSandbox)."
+        )
+
+    def get_tools(
+        self,
+        llm: Any = None,
+        file_write_enabled: bool = False,
+    ) -> list[Node]:
+        """Return tools this sandbox provides for agent use.
+
+        Base implementation returns an empty list. Subclasses can override
+        to add tools specific to their sandbox type (e.g., shell execution).
+
+        Args:
+            llm: LLM instance for tools that need it.
+            file_write_enabled: Whether to include file write tool.
+
+        Returns:
+            List of tool instances (Node objects).
+        """
+        # Lazy import to avoid circular dependency
+        from dynamiq.sandbox.tools.shell import SandboxShellTool
+
+        shell_tool = SandboxShellTool(
+            name="shell",
+            sandbox=self,
+        )
+        return [shell_tool]
+
+
+class SandboxConfig(BaseModel):
+    """Configuration for sandbox and related features.
+
+    Attributes:
+        enabled: Whether sandbox is enabled.
+        backend: The sandbox backend to use.
+        agent_file_write_enabled: Whether the agent can write files.
+        todo_enabled: Whether to enable todo management tools (stored in ._agent/todos.json).
+        config: Additional configuration options.
+    """
+
+    enabled: bool = False
+    backend: Sandbox = Field(..., description="Sandbox backend to use.")
+    todo_enabled: bool = Field(
+        default=False, description="Whether to enable todo management tools (todos stored in ._agent/todos.json)."
+    )
+    config: dict[str, Any] = Field(default_factory=dict)
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    def to_dict(self, **kwargs) -> dict[str, Any]:
+        """Convert the SandboxConfig instance to a dictionary."""
+        for_tracing = kwargs.pop("for_tracing", False)
+        if for_tracing and not self.enabled:
+            return {"enabled": False}
+        kwargs.pop("include_secure_params", None)
+        config_data = self.model_dump(exclude={"backend"}, **kwargs)
+        config_data["backend"] = self.backend.to_dict()
+        return config_data