Skip to content

e2b.md

Latest commit

 

History

History
418 lines (277 loc) · 9.38 KB

e2b.md

File metadata and controls

418 lines (277 loc) · 9.38 KB
title E2B
id integrations-e2b
description E2B integration for Haystack
slug /integrations-e2b

haystack_integrations.tools.e2b.bash_tool

RunBashCommandTool

Bases: Tool

A :class:~haystack.tools.Tool that executes bash commands inside an E2B sandbox.

Pass the same :class:E2BSandbox instance to multiple tool classes so they all operate in the same live sandbox environment.

Usage example

from haystack_integrations.tools.e2b import E2BSandbox, RunBashCommandTool, ReadFileTool

sandbox = E2BSandbox()
agent = Agent(
    chat_generator=...,
    tools=[
        RunBashCommandTool(sandbox=sandbox),
        ReadFileTool(sandbox=sandbox),
    ],
)

init

__init__(sandbox: E2BSandbox) -> None

Create a RunBashCommandTool.

Parameters:

  • sandbox (E2BSandbox) – The :class:E2BSandbox instance that will execute commands.

to_dict

to_dict() -> dict[str, Any]

Serialize this tool to a dictionary.

from_dict

from_dict(data: dict[str, Any]) -> RunBashCommandTool

Deserialize a RunBashCommandTool from a dictionary.

haystack_integrations.tools.e2b.e2b_sandbox

E2BSandbox

Manages the lifecycle of an E2B cloud sandbox.

Instantiate this class and pass it to one or more E2B tool classes (RunBashCommandTool, ReadFileTool, WriteFileTool, ListDirectoryTool) to share a single sandbox environment across all tools. All tools that receive the same E2BSandbox instance operate inside the same live sandbox process.

Usage example

from haystack.components.generators.chat import OpenAIChatGenerator
from haystack.components.agents import Agent

from haystack_integrations.tools.e2b import (
    E2BSandbox,
    RunBashCommandTool,
    ReadFileTool,
    WriteFileTool,
    ListDirectoryTool,
)

sandbox = E2BSandbox()
agent = Agent(
    chat_generator=OpenAIChatGenerator(model="gpt-4o"),
    tools=[
        RunBashCommandTool(sandbox=sandbox),
        ReadFileTool(sandbox=sandbox),
        WriteFileTool(sandbox=sandbox),
        ListDirectoryTool(sandbox=sandbox),
    ],
)

Lifecycle is handled automatically by the Agent's pipeline. If you use the tools standalone, call :meth:warm_up before the first tool invocation:

sandbox.warm_up()
# ... use tools ...
sandbox.close()

init

__init__(
    api_key: Secret = Secret.from_env_var("E2B_API_KEY", strict=True),
    sandbox_template: str = "base",
    timeout: int = 120,
    environment_vars: dict[str, str] | None = None,
    instance_id: str | None = None,
) -> None

Create an E2BSandbox instance.

Parameters:

  • api_key (Secret) – E2B API key.
  • sandbox_template (str) – E2B sandbox template name.
  • timeout (int) – Sandbox inactivity timeout in seconds.
  • environment_vars (dict[str, str] | None) – Optional environment variables to inject into the sandbox.
  • instance_id (str | None) – Stable identifier preserved across to_dict/from_dict. When omitted, a fresh UUID is generated. Tools that share the same E2BSandbox instance inherit this id, which is what lets them re-share the instance after a serialization round-trip. Distinct from the cloud-side sandbox id assigned by E2B at warm-up.

warm_up

warm_up() -> None

Establish the connection to the E2B sandbox.

Idempotent -- calling it multiple times has no effect if the sandbox is already running.

Raises:

  • RuntimeError – If the E2B sandbox cannot be created.

close

close() -> None

Shut down the E2B sandbox and release all associated resources.

Call this when you are done to avoid leaving idle sandboxes running.

to_dict

to_dict() -> dict[str, Any]

Serialize the sandbox configuration to a dictionary.

Returns:

  • dict[str, Any] – Dictionary containing the serialised configuration.

from_dict

from_dict(data: dict[str, Any]) -> E2BSandbox

Deserialize an :class:E2BSandbox from a dictionary.

Multiple tools that shared a single :class:E2BSandbox before serialization will share the same restored instance: each tool's from_dict consults a process-wide cache keyed on instance_id. A cache hit is only honored when the full serialized config (api_key, template, timeout, environment_vars) matches the cached entry — a crafted YAML with a guessed id but a different config falls through to a fresh instance and never observes the cached one.

Parameters:

  • data (dict[str, Any]) – Dictionary created by :meth:to_dict.

Returns:

  • E2BSandbox – An :class:E2BSandbox instance ready to be warmed up. May be a previously-restored instance if the id and config match.

haystack_integrations.tools.e2b.list_directory_tool

ListDirectoryTool

Bases: Tool

A :class:~haystack.tools.Tool that lists directory contents in an E2B sandbox.

Pass the same :class:E2BSandbox instance to multiple tool classes so they all operate in the same live sandbox environment.

Usage example

from haystack_integrations.tools.e2b import E2BSandbox, ListDirectoryTool

sandbox = E2BSandbox()
agent = Agent(chat_generator=..., tools=[ListDirectoryTool(sandbox=sandbox)])

init

__init__(sandbox: E2BSandbox) -> None

Create a ListDirectoryTool.

Parameters:

  • sandbox (E2BSandbox) – The :class:E2BSandbox instance to list directories from.

to_dict

to_dict() -> dict[str, Any]

Serialize this tool to a dictionary.

from_dict

from_dict(data: dict[str, Any]) -> ListDirectoryTool

Deserialize a ListDirectoryTool from a dictionary.

haystack_integrations.tools.e2b.read_file_tool

ReadFileTool

Bases: Tool

A :class:~haystack.tools.Tool that reads files from an E2B sandbox filesystem.

Pass the same :class:E2BSandbox instance to multiple tool classes so they all operate in the same live sandbox environment.

Usage example

from haystack_integrations.tools.e2b import E2BSandbox, ReadFileTool

sandbox = E2BSandbox()
agent = Agent(chat_generator=..., tools=[ReadFileTool(sandbox=sandbox)])

init

__init__(sandbox: E2BSandbox) -> None

Create a ReadFileTool.

Parameters:

  • sandbox (E2BSandbox) – The :class:E2BSandbox instance to read files from.

to_dict

to_dict() -> dict[str, Any]

Serialize this tool to a dictionary.

from_dict

from_dict(data: dict[str, Any]) -> ReadFileTool

Deserialize a ReadFileTool from a dictionary.

haystack_integrations.tools.e2b.sandbox_toolset

E2BToolset

Bases: Toolset

A :class:~haystack.tools.Toolset that bundles all E2B sandbox tools.

All tools in the set share a single :class:E2BSandbox instance so they operate inside the same live sandbox process. The toolset owns the sandbox lifecycle: calling :meth:warm_up starts the sandbox, and serialisation round-trips preserve the shared-sandbox relationship.

Usage example

from haystack.components.generators.chat import OpenAIChatGenerator
from haystack.components.agents import Agent

from haystack_integrations.tools.e2b import E2BToolset

agent = Agent(
    chat_generator=OpenAIChatGenerator(model="gpt-4o"),
    tools=E2BToolset(),
)

init

__init__(
    api_key: Secret = Secret.from_env_var("E2B_API_KEY", strict=True),
    sandbox_template: str = "base",
    timeout: int = 120,
    environment_vars: dict[str, str] | None = None,
) -> None

Create an E2BToolset.

Parameters:

  • api_key (Secret) – E2B API key. Defaults to Secret.from_env_var("E2B_API_KEY").
  • sandbox_template (str) – E2B sandbox template name. Defaults to "base".
  • timeout (int) – Sandbox inactivity timeout in seconds. Defaults to 120.
  • environment_vars (dict[str, str] | None) – Optional environment variables to inject into the sandbox.

warm_up

warm_up() -> None

Start the shared E2B sandbox (idempotent).

close

close() -> None

Shut down the shared E2B sandbox and release cloud resources.

to_dict

to_dict() -> dict[str, Any]

Serialize this toolset to a dictionary.

from_dict

from_dict(data: dict[str, Any]) -> E2BToolset

Deserialize an E2BToolset from a dictionary.

haystack_integrations.tools.e2b.write_file_tool

WriteFileTool

Bases: Tool

A :class:~haystack.tools.Tool that writes files to an E2B sandbox filesystem.

Pass the same :class:E2BSandbox instance to multiple tool classes so they all operate in the same live sandbox environment.

Usage example

from haystack_integrations.tools.e2b import E2BSandbox, WriteFileTool

sandbox = E2BSandbox()
agent = Agent(chat_generator=..., tools=[WriteFileTool(sandbox=sandbox)])

init

__init__(sandbox: E2BSandbox) -> None

Create a WriteFileTool.

Parameters:

  • sandbox (E2BSandbox) – The :class:E2BSandbox instance to write files to.

to_dict

to_dict() -> dict[str, Any]

Serialize this tool to a dictionary.

from_dict

from_dict(data: dict[str, Any]) -> WriteFileTool

Deserialize a WriteFileTool from a dictionary.