feat: add e2b-haystack integration for E2B cloud sandbox tools

[tholor]

partially addresses #3227

Summary

Migrates the E2B sandbox toolset prototype from deepset-ai/haystack-experimental#448 into a proper e2b-haystack integration package.

• Adds E2BSandbox for managing the lifecycle of an E2B cloud sandbox (lazy warm_up, close, full serialisation round-trip)
• Adds four Haystack Tool subclasses that share a single sandbox instance: RunBashCommandTool, ReadFileTool, WriteFileTool, ListDirectoryTool
• Adds E2BToolset (a Toolset subclass) that bundles all four tools as a convenience — just pass E2BToolset() to any Haystack Agent
• Follows the haystack_integrations/tools/ module path convention (same as mcp-haystack and github-haystack)

Test plan

• 38 unit tests pass (hatch run test:unit) — all sandbox calls are mocked, no API key needed
• Lint clean (hatch run fmt-check)
• Review examples in integrations/e2b/examples/ for correctness
• Manual smoke test with a real E2B API key (integration test, requires E2B_API_KEY)
• Maintainer to add E2B_API_KEY secret to GitHub repo for CI integration tests

🤖 Generated with Claude Code

[github-actions]

Coverage report (e2b)

Click to see where and how coverage changed

File	Statements	Missing	Coverage	Coverage (new stmts)	Lines missing
integrations/e2b/src/haystack_integrations/tools/e2b
bash_tool.py					53-55
e2b_sandbox.py
list_directory_tool.py					72, 80-81
read_file_tool.py
sandbox_toolset.py					74, 78, 82, 90-92
write_file_tool.py					67, 75-76
Project Total

This report was generated by python-coverage-comment-action

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	e2b@​2.20.2

View full report

[bogdankostic]

Looking forward to having this integration soon in Haystack!

I've left a few minor comments, mostly focused on polishing the docstrings. The only major blocker we should address IMO is the deserialization logic for individual tools to ensure the sandbox environments remain consistent within one pipeline.

[bogdankostic]

If a user builds an Agent with the four tools passed individually (sharing one E2BSandbox) rather than via E2BToolset, and then serializes/deserializes the pipeline, each tool's from_dict constructs its own independent E2BSandbox, breaking the shared state of the tools.

I tried this out by adapting build_pipeline in e2b_pipeline_example:

def build_pipeline() -> Pipeline:
    sandbox = E2BSandbox(sandbox_template="base", timeout=120)
    tools = [
        WriteFileTool(sandbox=sandbox),
        RunBashCommandTool(sandbox=sandbox),
    ]
    agent = Agent(
        chat_generator=OpenAIChatGenerator(model="gpt-4o-mini"),
        tools=tools,
        system_prompt=(
            "You are a helpful coding assistant with access to a live Linux sandbox. "
            "Use the available tools freely to write files and run commands."
        ),
        max_agent_steps=10,
    )
    pipeline = Pipeline()
    pipeline.add_component("agent", agent)
    return pipeline

Executing the script with this version of build_pipeline, we get the following error:

e2b_pipeline_example.py", line 88, in verify_roundtrip
    assert len(sandbox_ids) == 1, "Tools should share a single sandbox after round-trip"
           ^^^^^^^^^^^^^^^^^^^^^
AssertionError: Tools should share a single sandbox after round-trip

[tholor]

@bogdankostic good point - do we have a similar pattern somewhere else in haystack that we can follow here for serializing a shared object?

[bogdankostic]

I don't think there's a straightforwar way to preserve a shared E2BSandbox across individually-serialized tools. The round-trip would need some form of cross-tool deduplication.

A quick solution would be to log a warning in each tool's to_dict pointing users at E2BToolset for the serialize/deserialize path.

Something like:

def to_dict(self) -> dict[str, Any]:
    logger.warning(
        "Serializing %s standalone will not preserve a shared E2BSandbox "
        "across tools after deserialization. If you need to serialize an "
        "agentic pipeline (e.g. to YAML) with multiple E2B tools sharing "
        "one sandbox, use E2BToolset instead.",
        type(self).__name__,
    )
    return {
        "type": generate_qualified_class_name(type(self)),
        "data": {"sandbox": self._e2b_sandbox.to_dict()},
    }

WDYT?

[tholor]

Hm ok ... I guess the above warning but we the simplest approach.
I explored one alternative to make the round-trip work (see latest commit):

• Identity-based dedup inside E2BSandbox.from_dict — give each E2BSandbox a UUID at construction, serialize it, and have from_dict consult a class-level weakref.WeakValueDictionary to return the already-restored instance for the same UUID. Transparent to all callers (tools, toolset, ad-hoc usage).

Pro: Enables production / platform use cases, where you regularly have to serialize / deserialize pipelines. Showing an warning there is not really useful and we should then rather disable the standalone tools for such cases and always push users directly to "E2BToolset"

Con: Makes the code more complex.

What do you think? @sjrl @bogdankostic

[bogdankostic]

I just tried it out, works like a charm 🙌🏼

[bogdankostic]

Nice, looking good now, just found one minor improvement related to changing the default value of api_key that I will directly change.