docs: add E2B Sandbox Tools page (#5647)

Document the new E2BExecTool, E2BPythonTool, and E2BFileTool — agent
tools that run shell commands, Python, and filesystem ops inside
isolated E2B remote sandboxes. Adds the page under tools/ai-ml/ and
wires it into the navigation in docs.json.

Co-authored-by: iris-clawd <iris@crewai.com>
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

docs/en/tools/ai-ml/e2bsandboxtools.mdx

@@ -0,0 +1,196 @@
+---
+title: E2B Sandbox Tools
+description: The `E2BExecTool`, `E2BPythonTool`, and `E2BFileTool` give CrewAI agents shell, Python, and filesystem access inside isolated, ephemeral E2B remote sandboxes.
+icon: box
+mode: "wide"
+---
+
+# E2B Sandbox Tools
+
+## Description
+
+The E2B sandbox tools let CrewAI agents run code in isolated, ephemeral VMs hosted by [E2B](https://e2b.dev). Three tools share a common base class and connection model:
+
+- `E2BExecTool` — execute shell commands.
+- `E2BPythonTool` — execute Python in a Jupyter-style code interpreter (returns stdout, stderr, and rich results such as charts, dataframes, HTML, SVG, and PNG).
+- `E2BFileTool` — perform filesystem operations (read, write, append, list, delete, mkdir, info, exists), including binary content via base64.
+
+Use these tools when you want to give an agent the ability to run arbitrary code or perform file operations without exposing the host environment.
+
+## Installation
+
+Install the `e2b` extra for `crewai-tools` and set your E2B API key:
+
+```shell
+uv add "crewai-tools[e2b]"
+```
+
+```shell
+export E2B_API_KEY="e2b_..."
+```
+
+## Tools
+
+### `E2BExecTool`
+
+Runs shell commands inside the sandbox via `sandbox.commands.run`.
+
+**Arguments**
+
+- `command: str` — Required. The shell command to execute.
+- `cwd: str | None` — Optional. Working directory for the command.
+- `envs: dict[str, str] | None` — Optional. Per-call environment variables.
+- `timeout: float | None` — Optional. Timeout in seconds.
+
+**Returns**
+
+```json
+{
+  "exit_code": 0,
+  "stdout": "...",
+  "stderr": "...",
+  "error": null
+}
+```
+
+### `E2BPythonTool`
+
+Runs Python code in a Jupyter-style code interpreter using the `e2b_code_interpreter` SDK.
+
+**Arguments**
+
+- `code: str` — Required. The code to execute.
+- `language: str | None` — Optional. Language identifier (defaults to Python).
+- `envs: dict[str, str] | None` — Optional. Per-call environment variables.
+- `timeout: float | None` — Optional. Timeout in seconds.
+
+**Returns**
+
+```json
+{
+  "text": "...",
+  "stdout": "...",
+  "stderr": "...",
+  "error": null,
+  "results": [],
+  "execution_count": 1
+}
+```
+
+`results` can include charts, dataframes, HTML, SVG, and PNG output produced by the cell.
+
+### `E2BFileTool`
+
+Performs filesystem operations inside the sandbox. Auto-creates parent directories on write and handles binary content via base64.
+
+**Arguments**
+
+- `action: "read" | "write" | "append" | "list" | "delete" | "mkdir" | "info" | "exists"` — Required.
+- `path: str` — Required. Target path inside the sandbox.
+- `content: str | None` — Optional. Content for `write` / `append`. Base64-encoded when `binary=True`.
+- `binary: bool` — Optional. Treat `content` as binary (base64). Default `False`.
+- `depth: int` — Optional. Recursion depth for `list`.
+
+## Shared parameters (`E2BBaseTool`)
+
+All three tools accept the same connection / lifecycle parameters:
+
+- `api_key: SecretStr | None` — Falls back to the `E2B_API_KEY` environment variable.
+- `domain: str | None` — Falls back to the `E2B_DOMAIN` environment variable.
+- `template: str | None` — Custom sandbox template or snapshot.
+- `persistent: bool` — Default `False`. See [Sandbox modes](#sandbox-modes).
+- `sandbox_id: str | None` — Attach to an existing sandbox.
+- `sandbox_timeout: int` — Idle timeout in seconds. Default `300`.
+- `envs: dict[str, str] | None` — Environment variables injected at sandbox creation.
+- `metadata: dict[str, str] | None` — Metadata attached at sandbox creation.
+
+## Sandbox modes
+
+| Mode | How to activate | Sandbox lifetime |
+| --- | --- | --- |
+| Ephemeral (default) | `persistent=False` | A new sandbox is created and killed for every `_run` call. |
+| Persistent | `persistent=True` | A sandbox is lazily created on the first call and killed at process exit via `atexit`. |
+| Attach | `sandbox_id="sbx_..."` | The tool attaches to an existing sandbox and never kills it. |
+
+Use ephemeral mode for one-off tasks — it minimizes blast radius. Use persistent mode when an agent needs to keep state across multiple tool calls (e.g. a shell session plus filesystem ops on the same files). Use attach mode when an outside system manages the sandbox lifecycle.
+
+## Examples
+
+### One-shot Python (ephemeral)
+
+```python Code
+from crewai_tools import E2BPythonTool
+
+tool = E2BPythonTool()
+result = tool.run(code="print(sum(range(10)))")
+```
+
+### Persistent shell + filesystem session
+
+```python Code
+from crewai_tools import E2BExecTool, E2BFileTool
+
+exec_tool = E2BExecTool(persistent=True)
+file_tool = E2BFileTool(persistent=True)
+```
+
+When the process exits, both tools clean up the sandbox via `atexit`.
+
+### Attach to an existing sandbox
+
+```python Code
+from crewai_tools import E2BExecTool
+
+tool = E2BExecTool(sandbox_id="sbx_...")
+```
+
+The tool will not kill a sandbox it attached to.
+
+### Custom template, timeout, env vars, and metadata
+
+```python Code
+from crewai_tools import E2BExecTool
+
+tool = E2BExecTool(
+    persistent=True,
+    template="my-custom-template",
+    sandbox_timeout=600,
+    envs={"MY_FLAG": "1"},
+    metadata={"owner": "crewai-agent"},
+)
+```
+
+### Full agent example
+
+```python Code
+from crewai import Agent, Crew, Process, Task
+from crewai_tools import E2BPythonTool
+
+python_tool = E2BPythonTool()
+
+analyst = Agent(
+    role="Data Analyst",
+    goal="Run Python in a sandbox to answer analytical questions",
+    backstory="An analyst who delegates computation to an isolated E2B sandbox.",
+    tools=[python_tool],
+    verbose=True,
+)
+
+task = Task(
+    description="Compute the mean of [1, 2, 3, 4, 5] and return the result.",
+    expected_output="The numerical mean.",
+    agent=analyst,
+)
+
+crew = Crew(agents=[analyst], tasks=[task], process=Process.sequential)
+result = crew.kickoff()
+```
+
+## Security considerations
+
+These tools give agents arbitrary shell, Python, and filesystem access inside the sandbox. The sandbox isolates execution from your host, but you should still treat tool output as untrusted and design with prompt-injection in mind:
+
+- Ephemeral mode is the primary blast-radius control — every `_run` call gets a fresh VM. Prefer it unless persistent state is required.
+- Persistent and attached sandboxes accumulate state across calls. Anything seeded into them (credentials, tokens, files) is reachable by every subsequent tool invocation, including ones whose inputs were influenced by untrusted content.
+- Avoid injecting secrets into long-lived sandboxes that an agent can read or exfiltrate. Use short-lived credentials and the smallest scope necessary.
+- `sandbox_timeout` bounds idle time but does not cap total execution. Set it to the smallest value that fits your workload.