E2B Sandbox

The ag2.extensions.e2b module runs AG2 shell and code tools in isolated E2B cloud sandboxes. It implements AG2's native sandbox factory, so one environment keeps files across tool calls and cleans up deterministically.

Installation#

Install AG2, your model provider, and E2B's Python SDK:

pip install "ag2[anthropic]" "e2b>=2.0.0,<3"

Create an API key in the E2B dashboard and export it:

export E2B_API_KEY="e2b_your_api_key"

Use E2B with an agent#

Use the environment as an async context manager. Every shell and code call inside the scope runs in the same sandbox, and the sandbox is killed when the scope exits.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

import asyncio

from ag2 import Agent
from ag2.config import AnthropicConfig
from ag2.extensions.e2b import E2BEnvironment
from ag2.tools import SandboxCodeTool, SandboxShellTool

async def main() -> None:
    env = E2BEnvironment()
    async with env:
        agent = Agent(
            "developer",
            config=AnthropicConfig(model="claude-sonnet-5"),
            tools=[SandboxShellTool(env), SandboxCodeTool(env)],
        )
        reply = await agent.ask("Write hello.txt, then read it with Python.")
        print(await reply.content())

if __name__ == "__main__":
    asyncio.run(main())

The default template ships python and node, so SandboxCodeTool(env, languages=("python", "bash", "javascript")) works without a custom template. TypeScript needs a template with ts-node.

Configure the sandbox#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

from ag2.extensions.e2b import E2BEnvironment

env = E2BEnvironment(
    template="my-template",
    env_vars={"APP_ENV": "sandbox"},
    timeout=60,
    sandbox_timeout=600,
    workdir="/home/user/project",
    create_options={"metadata": {"app": "my-agent"}, "allow_internet_access": False},
)

api_key, template, and env_vars accept Variable values for per-request resolution, for example per-tenant credentials. Sandboxes are cached by their resolved values: opens that resolve to different values get different sandboxes, and opens that resolve to the same values share one, whichever conversation makes them.

E2BEnvironment satisfies WorkdirAware, so SandboxShellTool(env) reports the real working directory to the model.

Lifecycle#

E2B reclaims a sandbox once its server-side lifetime runs out. A command extends that lifetime back to sandbox_timeout when less than half of it is left, and always far enough to cover the command's own timeout, so a running command is not cut off. The lifetime is never shortened. How long an idle sandbox survives after its last command depends on when that command ran relative to the last refresh, so set sandbox_timeout with a comfortable margin above the longest pause you expect between tool calls, such as a slow model turn or a human-in-the-loop wait.

Once a sandbox is gone, the next command reports it, and the environment does not silently create a new one, because a new sandbox would not have the old one's files.

Always close the environment with async with or await env.aclose(). Closing waits for a sandbox that is still being created and kills it too, and calling aclose() again retries a kill that failed. An atexit fallback kills sandboxes that are still open when the process exits. The server-side lifetime is the backstop when neither runs, for example when a task is cancelled while E2B is still creating its sandbox.

Testing#

The bundled unit tests mock the E2B SDK and run offline, so no E2B account is needed for the AG2 test suite. Exercising the integration against real sandboxes requires an E2B account and an E2B_API_KEY.

Maintainer: @OndrejDrapalik / E2B.