agno-opensandbox-toolkit 0.1.0__tar.gz

agno_opensandbox_toolkit-0.1.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.3
+Name: agno-opensandbox-toolkit
+Version: 0.1.0
+Summary: OpenSandbox support for the Agno agent framework
+Keywords: agno,opensandbox,sandbox,ai-agent,toolkit
+Author: Valeryi Savich
+Author-email: Valeryi Savich <relrin78@gmail.com>
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Requires-Dist: agno==2.5.16
+Requires-Dist: opensandbox==0.1.7
+Requires-Dist: opensandbox-code-interpreter==0.1.2 ; extra == 'code-interpreter'
+Requires-Python: >=3.10, <4
+Provides-Extra: code-interpreter
+Description-Content-Type: text/markdown
+
+# agno-opensandbox-toolkit
+
+[![CI](https://github.com/Relrin/agno-opensandbox-toolkit/actions/workflows/ci.yml/badge.svg)](https://github.com/Relrin/agno-opensandbox-toolkit/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/agno-opensandbox-toolkit)](https://pypi.org/project/agno-opensandbox-toolkit/)
+[![Python](https://img.shields.io/pypi/pyversions/agno-opensandbox-toolkit)](https://pypi.org/project/agno-opensandbox-toolkit/)
+[![License](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
+
+[OpenSandbox](https://github.com/alibaba/OpenSandbox) support for the
+[Agno](https://github.com/agno-agi/agno) agent framework.
+
+Give your Agno agents the ability to execute shell commands, manage files, and run code
+in secure, isolated OpenSandbox containers.
+
+## Installation
+
+```bash
+# Base: shell commands + file operations
+uv add agno-opensandbox-toolkit
+
+# With code interpreter support (Python, JS, Java, Go, Bash)
+uv add "agno-opensandbox-toolkit[code-interpreter]"
+```
+
+## Prerequisites
+
+You need a running OpenSandbox server. The quickest way:
+
+```bash
+uv pip install opensandbox-server
+opensandbox-server init-config ~/.sandbox.toml --example docker
+opensandbox-server
+```
+
+See the [OpenSandbox docs](https://github.com/alibaba/OpenSandbox/blob/main/server/README.md)
+for full setup instructions.
+
+## Quick Start
+
+```python
+from agno.agent import Agent
+from agno.models.openai import OpenAIChat
+from agno_opensandbox_toolkit import OpenSandboxTools
+
+agent = Agent(
+    name="Sandbox Agent",
+    model=OpenAIChat(id="gpt-4o-mini"),
+    tools=[OpenSandboxTools()],
+    markdown=True,
+)
+
+agent.print_response("Create a file /tmp/hello.py that prints 'Hello from OpenSandbox!', then run it")
+```
+
+## Configuration
+
+| Parameter | Env Variable | Default | Description |
+|---|---|---|---|
+| `domain` | `OPENSANDBOX_DOMAIN` | `localhost:8080` | OpenSandbox server address |
+| `api_key` | `OPENSANDBOX_API_KEY` | `""` | API key for authentication |
+| `protocol` | — | `http` | Connection protocol (`http` or `https`) |
+| `image` | — | `ubuntu` | Container image |
+| `timeout_minutes` | — | `10` | Sandbox TTL |
+| `sandbox_env` | — | `{}` | Env vars inside sandbox |
+| `sandbox_resources` | — | `None` | e.g. `{"cpu": "2", "memory": "4Gi"}` |
+| `sandbox_entrypoint` | — | `None` | Custom entrypoint command list |
+| `sandbox_metadata` | — | `None` | Metadata labels dict |
+| `enable_code_interpreter` | — | `False` | Enable `run_code` tool |
+| `persistent` | — | `True` | Reuse sandbox across calls |
+| `sandbox_id` | — | `None` | Reconnect to existing sandbox |
+
+## Available Tools
+
+| Tool | Description |
+|---|---|
+| `run_shell_command` | Execute bash commands |
+| `create_file` | Create/update files |
+| `read_file` | Read file content |
+| `list_files` | List directory contents |
+| `delete_file` | Delete files/directories |
+| `change_directory` | Change working directory |
+| `get_sandbox_status` | Get sandbox info |
+| `shutdown_sandbox` | Kill the sandbox |
+| `run_code` | Execute code via interpreter (optional) |
+
+## License
+
+The project is published under the BSD 3-Clause license. For details see the [LICENSE](https://github.com/Relrin/agno-opensandbox-toolkit/blob/master/LICENSE) file.

agno_opensandbox_toolkit-0.1.0/README.md

@@ -0,0 +1,87 @@
+# agno-opensandbox-toolkit
+
+[![CI](https://github.com/Relrin/agno-opensandbox-toolkit/actions/workflows/ci.yml/badge.svg)](https://github.com/Relrin/agno-opensandbox-toolkit/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/agno-opensandbox-toolkit)](https://pypi.org/project/agno-opensandbox-toolkit/)
+[![Python](https://img.shields.io/pypi/pyversions/agno-opensandbox-toolkit)](https://pypi.org/project/agno-opensandbox-toolkit/)
+[![License](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
+
+[OpenSandbox](https://github.com/alibaba/OpenSandbox) support for the
+[Agno](https://github.com/agno-agi/agno) agent framework.
+
+Give your Agno agents the ability to execute shell commands, manage files, and run code
+in secure, isolated OpenSandbox containers.
+
+## Installation
+
+```bash
+# Base: shell commands + file operations
+uv add agno-opensandbox-toolkit
+
+# With code interpreter support (Python, JS, Java, Go, Bash)
+uv add "agno-opensandbox-toolkit[code-interpreter]"
+```
+
+## Prerequisites
+
+You need a running OpenSandbox server. The quickest way:
+
+```bash
+uv pip install opensandbox-server
+opensandbox-server init-config ~/.sandbox.toml --example docker
+opensandbox-server
+```
+
+See the [OpenSandbox docs](https://github.com/alibaba/OpenSandbox/blob/main/server/README.md)
+for full setup instructions.
+
+## Quick Start
+
+```python
+from agno.agent import Agent
+from agno.models.openai import OpenAIChat
+from agno_opensandbox_toolkit import OpenSandboxTools
+
+agent = Agent(
+    name="Sandbox Agent",
+    model=OpenAIChat(id="gpt-4o-mini"),
+    tools=[OpenSandboxTools()],
+    markdown=True,
+)
+
+agent.print_response("Create a file /tmp/hello.py that prints 'Hello from OpenSandbox!', then run it")
+```
+
+## Configuration
+
+| Parameter | Env Variable | Default | Description |
+|---|---|---|---|
+| `domain` | `OPENSANDBOX_DOMAIN` | `localhost:8080` | OpenSandbox server address |
+| `api_key` | `OPENSANDBOX_API_KEY` | `""` | API key for authentication |
+| `protocol` | — | `http` | Connection protocol (`http` or `https`) |
+| `image` | — | `ubuntu` | Container image |
+| `timeout_minutes` | — | `10` | Sandbox TTL |
+| `sandbox_env` | — | `{}` | Env vars inside sandbox |
+| `sandbox_resources` | — | `None` | e.g. `{"cpu": "2", "memory": "4Gi"}` |
+| `sandbox_entrypoint` | — | `None` | Custom entrypoint command list |
+| `sandbox_metadata` | — | `None` | Metadata labels dict |
+| `enable_code_interpreter` | — | `False` | Enable `run_code` tool |
+| `persistent` | — | `True` | Reuse sandbox across calls |
+| `sandbox_id` | — | `None` | Reconnect to existing sandbox |
+
+## Available Tools
+
+| Tool | Description |
+|---|---|
+| `run_shell_command` | Execute bash commands |
+| `create_file` | Create/update files |
+| `read_file` | Read file content |
+| `list_files` | List directory contents |
+| `delete_file` | Delete files/directories |
+| `change_directory` | Change working directory |
+| `get_sandbox_status` | Get sandbox info |
+| `shutdown_sandbox` | Kill the sandbox |
+| `run_code` | Execute code via interpreter (optional) |
+
+## License
+
+The project is published under the BSD 3-Clause license. For details see the [LICENSE](https://github.com/Relrin/agno-opensandbox-toolkit/blob/master/LICENSE) file.

agno_opensandbox_toolkit-0.1.0/pyproject.toml

@@ -0,0 +1,69 @@
+[project]
+name = "agno-opensandbox-toolkit"
+version = "0.1.0"
+description = "OpenSandbox support for the Agno agent framework"
+readme = "README.md"
+authors = [
+    { name = "Valeryi Savich", email = "relrin78@gmail.com" }
+]
+requires-python = ">=3.10,<4"
+keywords = ["agno", "opensandbox", "sandbox", "ai-agent", "toolkit"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: BSD License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "agno==2.5.16",
+    "opensandbox==0.1.7",
+]
+
+[project.optional-dependencies]
+code-interpreter = [
+    "opensandbox-code-interpreter==0.1.2",
+]
+
+[build-system]
+requires = ["uv_build>=0.10.12,<0.11.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "mypy==1.20.0",
+    "pytest===9.0.3",
+    "pytest-asyncio==1.3.0",
+    "pytest-cov==7.1.0",
+    "respx==0.23.1",
+    "ruff==0.15.10",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+markers = [
+    "integration: requires a running OpenSandbox server (deselect with '-m not integration')",
+    "e2e: end-to-end tests requiring LLM API key + OpenSandbox server",
+]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 120
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+packages = ["agno_opensandbox_toolkit"]
+mypy_path = "src"

agno_opensandbox_toolkit-0.1.0/src/agno_opensandbox_toolkit/__init__.py

@@ -0,0 +1,3 @@
+from agno_opensandbox_toolkit.tools import OpenSandboxTools
+
+__all__ = ["OpenSandboxTools"]

agno_opensandbox_toolkit-0.1.0/src/agno_opensandbox_toolkit/_constants.py

@@ -0,0 +1,38 @@
+from textwrap import dedent
+
+DEFAULT_IMAGE = "ubuntu"
+CODE_INTERPRETER_IMAGE = "opensandbox/code-interpreter:v1.0.2"
+CODE_INTERPRETER_ENTRYPOINT = ["/opt/opensandbox/code-interpreter.sh"]
+DEFAULT_WORKING_DIRECTORY = "/root"
+
+DEFAULT_INSTRUCTIONS = dedent(
+    """\
+    You have access to a persistent OpenSandbox sandbox for code execution.
+    The sandbox maintains state across interactions. And our goal is to provide working, executed code examples.
+    
+    Available tools:
+    - `run_code`: Execute code in the sandbox (requires code-interpreter image)
+    - `run_shell_command`: Execute shell commands (bash)
+    - `create_file`: Create or update files
+    - `read_file`: Read file contents
+    - `list_files`: List directory contents
+    - `delete_file`: Delete files or directories
+    - `change_directory`: Change the working directory
+    - `get_sandbox_status`: Get the sandbox status
+    - `shutdown_sandbox`: Shut down the sandbox
+    
+    When users ask for code (Python, JavaScript, TypeScript, etc.), you should:
+    1. Write the code
+    2. Execute it using run_code tool
+    3. Show the actual output/results
+    4. Never just provide code without executing it
+    
+    Recommended workflow:
+    1. Before running any code, check if required packages for the target languages are installed
+    2. Install missing packages, e.g. run_shell_command("pip install package1 package2")
+    3. When running scripts, capture both output AND errors
+    4. If a script produces no output, check for errors or add print statements
+
+    IMPORTANT: Always use single quotes for the content parameter when creating files
+    """
+)

agno_opensandbox_toolkit-0.1.0/src/agno_opensandbox_toolkit/tools.py

@@ -0,0 +1,556 @@
+import json
+import stat
+from datetime import timedelta
+from os import getenv
+from pathlib import PurePosixPath
+from typing import Any
+
+from agno.agent import Agent
+from agno.team import Team
+from agno.tools import Toolkit
+from agno.utils.log import log_debug, log_error, log_info, log_warning
+
+from agno_opensandbox_toolkit._constants import (
+    CODE_INTERPRETER_ENTRYPOINT,
+    CODE_INTERPRETER_IMAGE,
+    DEFAULT_IMAGE,
+    DEFAULT_INSTRUCTIONS,
+    DEFAULT_WORKING_DIRECTORY,
+)
+
+try:
+    from opensandbox import SandboxSync
+    from opensandbox.config import ConnectionConfigSync
+    from opensandbox.models.execd import Execution, RunCommandOpts
+except ImportError as _err:
+    raise ImportError("`opensandbox` not installed. Please install using `pip install opensandbox`") from _err
+
+_CODE_INTERPRETER_AVAILABLE = False
+try:
+    from code_interpreter import CodeInterpreterSync
+    from code_interpreter.models.code import SupportedLanguage
+
+    _CODE_INTERPRETER_AVAILABLE = True
+except ImportError:
+    pass
+
+
+class OpenSandboxTools(Toolkit):
+    """
+    OpenSandbox integration toolkit for Agno agents.
+
+    Provides sandboxed code execution, shell commands, and file operations
+    via the OpenSandbox platform. Follows the same patterns as the built-in
+    DaytonaTools and E2BTools integrations.
+    """
+
+    def __init__(
+        self,
+        domain: str | None = None,
+        api_key: str | None = None,
+        protocol: str = "http",
+        image: str | None = None,
+        timeout_minutes: int = 10,
+        sandbox_env: dict[str, str] | None = None,
+        sandbox_resources: dict[str, str] | None = None,
+        sandbox_metadata: dict[str, str] | None = None,
+        sandbox_entrypoint: list[str] | None = None,
+        sandbox_id: str | None = None,
+        persistent: bool = True,
+        enable_code_interpreter: bool = False,
+        instructions: str | None = None,
+        add_instructions: bool = False,
+        **kwargs: Any,
+    ):
+        """
+        Initialize OpenSandbox toolkit for Agno agents.
+
+        Args:
+            domain: OpenSandbox server domain (default: env OPENSANDBOX_DOMAIN or "localhost:8080").
+            api_key: API key (default: env OPENSANDBOX_API_KEY or "").
+            protocol: Connection protocol, "http" or "https" (default: "http").
+            image: Container image for the sandbox (default: "ubuntu",
+                   auto-set to code-interpreter image when enable_code_interpreter=True).
+            timeout_minutes: Sandbox TTL in minutes.
+            sandbox_env: Environment variables to set inside the sandbox.
+            sandbox_resources: Resource limits e.g. {"cpu": "2", "memory": "4Gi"}.
+            sandbox_metadata: User metadata labels for the sandbox.
+            sandbox_entrypoint: Custom entrypoint command list.
+            sandbox_id: Existing sandbox ID to reconnect to (skips creation).
+            persistent: If True, store sandbox ID in agent.session_state for reuse.
+            enable_code_interpreter: If True, adds `run_code` tool (requires
+                                     `opensandbox-code-interpreter` package).
+            instructions: Custom instructions string (replaces default).
+            add_instructions: If True, prepend instructions to agent system prompt.
+        """
+        self.domain = domain or getenv("OPENSANDBOX_DOMAIN", "localhost:8080")
+        self.api_key = api_key or getenv("OPENSANDBOX_API_KEY", "")
+
+        self.sandbox_id = sandbox_id
+        self.persistent = persistent
+        self.timeout_minutes = timeout_minutes
+        self.sandbox_env = sandbox_env or {}
+        self.sandbox_resources = sandbox_resources
+        self.sandbox_metadata = sandbox_metadata or {}
+        self.sandbox_entrypoint = sandbox_entrypoint
+        self.enable_code_interpreter = enable_code_interpreter
+
+        if enable_code_interpreter:
+            self.image = image or CODE_INTERPRETER_IMAGE
+            if self.sandbox_entrypoint is None:
+                self.sandbox_entrypoint = CODE_INTERPRETER_ENTRYPOINT
+        else:
+            self.image = image or DEFAULT_IMAGE
+
+        if enable_code_interpreter and not _CODE_INTERPRETER_AVAILABLE:
+            raise ImportError(
+                "`opensandbox-code-interpreter` not installed. "
+                "Please install using `pip install opensandbox-code-interpreter`"
+            )
+
+        self._sandbox: SandboxSync | None = None
+        self._interpreter: Any | None = None
+
+        self._connection_config = ConnectionConfigSync(
+            domain=self.domain,
+            api_key=self.api_key,
+            protocol=protocol,
+        )
+
+        _instructions = instructions or DEFAULT_INSTRUCTIONS
+
+        tools: list[Any] = [
+            self.run_shell_command,
+            self.create_file,
+            self.read_file,
+            self.list_files,
+            self.delete_file,
+            self.change_directory,
+            self.get_sandbox_status,
+            self.shutdown_sandbox,
+        ]
+
+        if enable_code_interpreter:
+            tools.append(self.run_code)
+
+        super().__init__(
+            name="opensandbox_tools",
+            tools=tools,
+            instructions=_instructions,
+            add_instructions=add_instructions,
+            **kwargs,
+        )
+
+    def _get_working_directory(self, agent: Agent | Team) -> str:
+        """Get the current working directory from agent session state."""
+        if agent and hasattr(agent, "session_state"):
+            if agent.session_state is None:
+                agent.session_state = {}
+            return str(agent.session_state.get("working_directory", DEFAULT_WORKING_DIRECTORY))
+        return DEFAULT_WORKING_DIRECTORY
+
+    def _set_working_directory(self, agent: Agent | Team, directory: str) -> None:
+        """Set the working directory in agent session state."""
+        if agent and hasattr(agent, "session_state"):
+            if agent.session_state is None:
+                agent.session_state = {}
+            agent.session_state["working_directory"] = directory
+            log_info(f"Updated working directory to: {directory}")
+
+    def _get_or_create_sandbox(self, agent: Agent | Team) -> SandboxSync:
+        """Get existing sandbox or create new one. Stores ID in agent session_state."""
+        try:
+            sandbox = None
+
+            # Reuse cached sandbox instance
+            if self._sandbox is not None:
+                return self._sandbox
+
+            # Use explicit sandbox_id from constructor
+            if self.sandbox_id:
+                try:
+                    sandbox = SandboxSync.connect(
+                        self.sandbox_id,
+                        connection_config=self._connection_config,
+                    )
+                    log_debug(f"Connected to explicit sandbox: {self.sandbox_id}")
+                except Exception as e:
+                    log_debug(f"Failed to connect to sandbox {self.sandbox_id}: {e}")
+                    sandbox = None
+
+            # Use persistent sandbox from session state
+            elif self.persistent and hasattr(agent, "session_state"):
+                if agent.session_state is None:
+                    agent.session_state = {}
+
+                saved_id = agent.session_state.get("opensandbox_id")
+                if saved_id:
+                    try:
+                        sandbox = SandboxSync.connect(
+                            saved_id,
+                            connection_config=self._connection_config,
+                        )
+                        log_debug(f"Reconnected to persistent sandbox: {saved_id}")
+                    except Exception as e:
+                        log_debug(f"Failed to reconnect to sandbox {saved_id}: {e}")
+                        sandbox = None
+
+            # Create new sandbox
+            if sandbox is None:
+                sandbox = self._create_new_sandbox(agent)
+
+            self._sandbox = sandbox
+            return sandbox
+
+        except Exception as e:
+            log_warning(f"Error in sandbox management, creating new sandbox: {e}")  # type: ignore[no-untyped-call]
+            sandbox = self._create_new_sandbox(agent)
+            self._sandbox = sandbox
+            return sandbox
+
+    def _create_new_sandbox(self, agent: Agent | Team | None = None) -> SandboxSync:
+        """Create a new OpenSandbox instance."""
+        try:
+            metadata = self.sandbox_metadata.copy()
+            metadata.setdefault("created_by", "agno_opensandbox_toolkit")
+
+            create_kwargs: dict[str, Any] = {
+                "connection_config": self._connection_config,
+                "timeout": timedelta(minutes=self.timeout_minutes),
+                "env": self.sandbox_env,
+                "metadata": metadata,
+            }
+
+            if self.sandbox_resources:
+                create_kwargs["resource"] = self.sandbox_resources
+
+            if self.sandbox_entrypoint:
+                create_kwargs["entrypoint"] = self.sandbox_entrypoint
+
+            sandbox = SandboxSync.create(self.image, **create_kwargs)
+
+            # Store sandbox ID for persistence
+            if self.persistent and agent and hasattr(agent, "session_state"):
+                if agent.session_state is None:
+                    agent.session_state = {}
+                agent.session_state["opensandbox_id"] = sandbox.id
+
+            log_info(f"Created new OpenSandbox: {sandbox.id}")
+            return sandbox
+
+        except Exception as e:
+            log_error(f"Error creating OpenSandbox: {e}")  # type: ignore[no-untyped-call]
+            raise
+
+    def _get_or_create_interpreter(self, sandbox: SandboxSync) -> Any:
+        """Lazily create the code interpreter."""
+        if self._interpreter is not None:
+            return self._interpreter
+        self._interpreter = CodeInterpreterSync.create(sandbox=sandbox)
+        log_info("Created CodeInterpreter for sandbox")
+        return self._interpreter
+
+    def _format_execution(self, execution: Execution) -> str:
+        """Format an Execution result into a readable string."""
+        parts: list[str] = []
+
+        # Combined stdout + result text via SDK property
+        text = execution.text
+        if text:
+            parts.append(text)
+
+        # Stderr (not included in .text)
+        if execution.logs and execution.logs.stderr:
+            stderr_lines = [msg.text for msg in execution.logs.stderr]
+            stderr_text = "\n".join(stderr_lines)
+            if stderr_text.strip():
+                parts.append(f"STDERR:\n{stderr_text}")
+
+        # Error info
+        if execution.error:
+            parts.append(f"ERROR: {execution.error}")
+
+        return "\n".join(parts) if parts else "Command executed successfully with no output."
+
+    def _resolve_path(self, file_path: str, cwd: str) -> str:
+        """
+        Resolve a file path relative to the current working directory.
+
+        Uses PurePosixPath since the sandbox is always Linux.
+        """
+        path = PurePosixPath(file_path)
+        if path.is_absolute():
+            return str(path)
+        return str(PurePosixPath(cwd) / path)
+
+    def run_code(self, agent: Agent | Team, code: str, language: str = "python") -> str:
+        """
+        Execute code in the OpenSandbox code interpreter.
+
+        Args:
+            agent: An Agno agent instance or a group of agents
+            code: The source code to execute.
+            language: Programming language — "python", "javascript", "typescript",
+                      "java", "go", or "bash" (default: "python").
+
+        Returns:
+            Execution output as a string, or error details.
+        """
+        try:
+            from agno.utils.code_execution import prepare_python_code
+
+            current_sandbox = self._get_or_create_sandbox(agent)
+            interpreter = self._get_or_create_interpreter(current_sandbox)
+
+            # Map string language to enum
+            lang_map = {
+                "python": SupportedLanguage.PYTHON,
+                "javascript": SupportedLanguage.JAVASCRIPT,
+                "typescript": SupportedLanguage.TYPESCRIPT,
+                "java": SupportedLanguage.JAVA,
+                "go": SupportedLanguage.GO,
+                "bash": SupportedLanguage.BASH,
+            }
+            lang_enum = lang_map.get(language.lower(), SupportedLanguage.PYTHON)
+
+            if lang_enum == SupportedLanguage.PYTHON:
+                code = prepare_python_code(code)
+
+            result = interpreter.codes.run(code, language=lang_enum)
+            return self._format_execution(result)
+
+        except Exception as e:
+            return json.dumps({"status": "error", "message": f"Error executing code: {e!s}"})
+
+    def run_shell_command(self, agent: Agent | Team, command: str) -> str:
+        """
+        Execute a shell command in the OpenSandbox environment.
+
+        Args:
+            agent: An Agno agent instance or a group of agents
+            command: Shell command to execute (e.g., "ls -la /tmp").
+
+        Returns:
+            Command output as a string.
+        """
+        try:
+            current_sandbox = self._get_or_create_sandbox(agent)
+            cwd = self._get_working_directory(agent)
+
+            if command.strip().startswith("cd "):
+                new_dir = command.strip()[3:].strip()
+                new_path = PurePosixPath(new_dir)
+
+                if not new_path.is_absolute():
+                    new_path = PurePosixPath(cwd) / new_path
+
+                new_path_str = str(new_path)
+
+                test_result = current_sandbox.commands.run(
+                    f"test -d '{new_path_str}' && echo 'exists' || echo 'not found'",
+                    opts=RunCommandOpts(working_directory="/"),
+                )
+                stdout_text = test_result.text
+                if "exists" in stdout_text:
+                    self._set_working_directory(agent, new_path_str)
+                    return f"Changed directory to: {new_path_str}"
+                else:
+                    return f"Error: Directory {new_path_str} not found"
+
+            execution = current_sandbox.commands.run(
+                command,
+                opts=RunCommandOpts(working_directory=cwd),
+            )
+            return self._format_execution(execution)
+
+        except Exception as e:
+            return json.dumps({"status": "error", "message": f"Error executing command: {e!s}"})
+
+    def create_file(self, agent: Agent | Team, file_path: str, content: str) -> str:
+        """
+        Create or update a file in the sandbox.
+
+        Args:
+            agent: An Agno agent instance or a group of agents
+            file_path: Path to the file (relative to current directory or absolute).
+            content: Content to write to the file.
+
+        Returns:
+            Success message or error.
+        """
+        try:
+            current_sandbox = self._get_or_create_sandbox(agent)
+            cwd = self._get_working_directory(agent)
+            resolved = self._resolve_path(file_path, cwd)
+
+            # Create parent directories
+            parent_dir = str(PurePosixPath(resolved).parent)
+            if parent_dir and parent_dir != "/":
+                current_sandbox.commands.run(
+                    f"mkdir -p '{parent_dir}'",
+                    opts=RunCommandOpts(working_directory="/"),
+                )
+
+            # Write file via SDK
+            current_sandbox.files.write_file(resolved, content)
+
+            return f"File created/updated: {resolved}"
+
+        except Exception as e:
+            return json.dumps({"status": "error", "message": f"Error creating file: {e!s}"})
+
+    def read_file(self, agent: Agent | Team, file_path: str) -> str:
+        """
+        Read a file from the sandbox.
+
+        Args:
+            agent: An Agno agent instance or a group of agents
+            file_path: Path to the file (relative to current directory or absolute).
+
+        Returns:
+            File content or error message.
+        """
+        try:
+            current_sandbox = self._get_or_create_sandbox(agent)
+            cwd = self._get_working_directory(agent)
+            resolved = self._resolve_path(file_path, cwd)
+
+            content = current_sandbox.files.read_file(resolved)
+            return content
+
+        except Exception as e:
+            return json.dumps({"status": "error", "message": f"Error reading file: {e!s}"})
+
+    def list_files(self, agent: Agent | Team, directory: str | None = None) -> str:
+        """
+        List files in a directory.
+
+        Args:
+            agent: An Agno agent instance or a group of agents
+            directory: Directory to list (defaults to current working directory).
+
+        Returns:
+            List of files and directories as formatted string.
+        """
+        try:
+            current_sandbox = self._get_or_create_sandbox(agent)
+            cwd = self._get_working_directory(agent)
+
+            dir_path = cwd if directory is None else self._resolve_path(directory, cwd)
+
+            execution = current_sandbox.commands.run(
+                f"ls -la '{dir_path}'",
+                opts=RunCommandOpts(working_directory="/"),
+            )
+
+            output = self._format_execution(execution)
+            return f"Contents of {dir_path}:\n{output}"
+
+        except Exception as e:
+            return json.dumps({"status": "error", "message": f"Error listing files: {e!s}"})
+
+    def delete_file(self, agent: Agent | Team, file_path: str) -> str:
+        """
+        Delete a file or directory from the sandbox.
+
+        Args:
+            agent: An Agno agent instance or a group of agents
+            file_path: Path to the file or directory (relative or absolute).
+
+        Returns:
+            Success message or error.
+        """
+        try:
+            current_sandbox = self._get_or_create_sandbox(agent)
+            cwd = self._get_working_directory(agent)
+            resolved = self._resolve_path(file_path, cwd)
+
+            # Determine if target is a file or directory via file info
+            try:
+                info = current_sandbox.files.get_file_info([resolved])
+                if resolved in info:
+                    entry_info = info[resolved]
+                    # Check if directory using Unix mode bits
+                    if stat.S_ISDIR(entry_info.mode):
+                        current_sandbox.files.delete_directories([resolved])
+                    else:
+                        current_sandbox.files.delete_files([resolved])
+                else:
+                    # Path not found in info, try both
+                    current_sandbox.files.delete_files([resolved])
+            except Exception:
+                # Fallback to shell rm if SDK methods fail
+                current_sandbox.commands.run(
+                    f"rm -rf '{resolved}'",
+                    opts=RunCommandOpts(working_directory="/"),
+                )
+
+            return f"Deleted: {resolved}"
+
+        except Exception as e:
+            return json.dumps({"status": "error", "message": f"Error deleting file: {e!s}"})
+
+    def change_directory(self, agent: Agent | Team, directory: str) -> str:
+        """
+        Change the current working directory.
+
+        Args:
+            agent: An Agno agent instance or a group of agents
+            directory: Directory to change to (relative or absolute).
+
+        Returns:
+            Success message or error.
+        """
+        try:
+            return self.run_shell_command(agent, f"cd {directory}")
+        except Exception as e:
+            return json.dumps({"status": "error", "message": f"Error changing directory: {e!s}"})
+
+    def get_sandbox_status(self, agent: Agent | Team) -> str:
+        """
+        Get the current status of the sandbox.
+
+        Args:
+            agent: An Agno agent instance or a group of agents
+
+        Returns:
+            Sandbox status information.
+        """
+        try:
+            current_sandbox = self._get_or_create_sandbox(agent)
+            sandbox_id = getattr(current_sandbox, "id", "Unknown")
+            return json.dumps(
+                {
+                    "status": "success",
+                    "sandbox_id": sandbox_id,
+                    "image": self.image,
+                    "working_directory": self._get_working_directory(agent),
+                }
+            )
+        except Exception as e:
+            return json.dumps({"status": "error", "message": f"Error getting status: {e!s}"})
+
+    def shutdown_sandbox(self, agent: Agent | Team) -> str:
+        """
+        Shut down the sandbox immediately.
+
+        Args:
+            agent: An Agno agent instance or a group of agents
+
+        Returns:
+            Success message or error.
+        """
+        try:
+            current_sandbox = self._get_or_create_sandbox(agent)
+            current_sandbox.kill()
+            self._sandbox = None
+            self._interpreter = None
+
+            # Clear session state
+            if self.persistent and hasattr(agent, "session_state") and agent.session_state:
+                agent.session_state.pop("opensandbox_id", None)
+                agent.session_state.pop("working_directory", None)
+
+            return json.dumps({"status": "success", "message": "Sandbox shut down successfully"})
+        except Exception as e:
+            return json.dumps({"status": "error", "message": f"Error shutting down: {e!s}"})