feat(integrations): Add E2BEnvironment for remote sandbox workspaces

Jacksunwei · copybara-github · commit 92d608f83e68 · 2026-06-09T15:40:45.000-07:00
Merge google#6031 > **Stacked on google#6030** (`fix/experimental-typing`). This PR targets that branch; please review/merge google#6030 first, after which this will be retargeted to `main`. ## Summary Adds `E2BEnvironment`, a `BaseEnvironment` backed by an [E2B](https://e2b.dev) sandbox. It gives agents a persistent remote workspace for shell execution, file CRUD, and on-demand installs (`pip`/`apt`) without touching the host machine. - The sandbox TTL is bounded to cap credit usage and is extended on each operation; an expired idle sandbox is transparently recreated. - Lazy-imports the SDK behind a new `e2b` extra, so the base package stays lean. - Includes a data-analysis sample that downloads a public (GCS-hosted) dataset and analyzes it inside the sandbox. ## Usage ```python from google.adk.integrations.e2b import E2BEnvironment from google.adk.tools.environment import EnvironmentToolset toolset = EnvironmentToolset(environment=E2BEnvironment()) ``` ## Test plan - [x] `pytest tests/unittests/integrations/e2b/` (14 passed) - [x] `pyright src/google/adk/integrations/e2b/_e2b_environment.py` — 0 errors - [x] Sample agent loads (`contributing/samples/environment_and_skills/e2b_environment`) - [ ] Manual run against a live E2B sandbox (requires `E2B_API_KEY`) Co-authored-by: Wei Sun (Jack) <weisun@google.com> COPYBARA_INTEGRATE_REVIEW=google#6031 from google:feat/e2b f2b5584 PiperOrigin-RevId: 929443164
diff --git a/contributing/samples/environment_and_skills/e2b_environment/README.md b/contributing/samples/environment_and_skills/e2b_environment/README.md
@@ -0,0 +1,90 @@
+# E2B Environment Sample
+
+## Overview
+
+A small data analysis agent that uses the `E2BEnvironment` with the
+`EnvironmentToolset` to download public datasets and analyze them inside an
+[E2B](https://e2b.dev) remote sandbox.
+
+Instead of running on the local machine, all commands and file operations
+execute in an isolated remote sandbox with internet access. Asked a question,
+the agent downloads a public dataset (a GCS-hosted world population /
+demographics dataset by default), installs `pandas` on demand, writes a short
+analysis script, runs it, and reports the result — all without touching the
+user's machine. This makes the sandbox a natural fit for running
+model-generated code safely and keeping the host clean.
+
+The sandbox has a bounded time-to-live (`timeout`, in seconds) to cap credit
+usage. The TTL is reset on every operation, so an actively used workspace never
+expires mid-task; after genuine idle it expires and is transparently recreated
+on the next operation (note: workspace state such as installed packages and
+files is lost on recreation).
+
+## Prerequisites
+
+1. Install the `e2b` extra:
+
+   ```bash
+   pip install google-adk[e2b]
+   ```
+
+1. Set your E2B API key (get one at https://e2b.dev):
+
+   ```bash
+   export E2B_API_KEY="your-api-key"
+   ```
+
+## Sample Inputs
+
+- `Download the world demographics dataset and tell me which country has the largest population.`
+
+  The agent downloads the dataset, installs `pandas`, filters to country-level
+  rows, and finds the maximum. Expected: China (`CN`), ≈ 1.44 billion, just
+  ahead of India (`IN`) at ≈ 1.38 billion.
+
+- `For the United States, what is the urban vs rural population split?`
+
+  A follow-up to the previous turn. Because the sandbox persists across the
+  session, the agent reuses the already-downloaded CSV and the installed
+  `pandas` — it only writes and runs a new script. Expected for `US`: urban
+  ≈ 270.7 million vs rural ≈ 57.6 million (out of ≈ 331 million total).
+
+- `Using https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.csv, how many US states are listed?`
+
+  Demonstrates pointing the agent at your own dataset URL instead of the
+  default.
+
+## Graph
+
+```mermaid
+graph TD
+    User -->|question| Agent[data_analysis_agent]
+    Agent -->|EnvironmentToolset| Sandbox[E2BEnvironment sandbox]
+    Sandbox -->|download / install / run| Agent
+    Agent -->|answer| User
+```
+
+## How To
+
+The agent is a standalone `Agent` (no workflow graph) wired to a single
+`EnvironmentToolset` whose `environment` is an `E2BEnvironment`:
+
+```python
+from google.adk.integrations.e2b import E2BEnvironment
+from google.adk.tools.environment import EnvironmentToolset
+
+EnvironmentToolset(
+    environment=E2BEnvironment(image="base", timeout=300),
+)
+```
+
+- `image` selects the E2B template (defaults to the public `base` template).
+- `timeout` bounds the sandbox lifetime in seconds to cap credit usage; it is
+  reset on every operation.
+
+The default GCS-hosted demographics CSV is a standard CSV with a header row.
+Each row is one location identified by `location_key`: country-level rows use a
+two-letter ISO code (e.g. `US`, `CN`), while subregions use keys containing an
+underscore (e.g. `US_CA`). The agent's instruction documents this schema — in
+particular, to filter out underscore keys when a question is about countries —
+so the generated analysis script parses and aggregates the file correctly.
diff --git a/contributing/samples/environment_and_skills/e2b_environment/__init__.py b/contributing/samples/environment_and_skills/e2b_environment/__init__.py
@@ -0,0 +1,15 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from . import agent
diff --git a/contributing/samples/environment_and_skills/e2b_environment/agent.py b/contributing/samples/environment_and_skills/e2b_environment/agent.py
@@ -0,0 +1,52 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""A data analysis agent that runs Python in an E2B remote sandbox."""
+
+from google.adk import Agent
+from google.adk.integrations.e2b import E2BEnvironment
+from google.adk.tools.environment import EnvironmentToolset
+
+root_agent = Agent(
+    name="data_analysis_agent",
+    description=(
+        "A data analysis agent that downloads public datasets and analyzes"
+        " them inside an E2B remote sandbox."
+    ),
+    instruction="""\
+You are a data analysis assistant. You work inside an isolated E2B remote
+sandbox that has internet access, where you can safely download data and run
+Python, so you never touch the user's machine.
+
+To analyze a dataset:
+1. Download it from the internet into the working directory, e.g. with
+   `curl -O <url>` or `wget <url>`. If the user does not give a URL, use the
+   public world demographics dataset hosted on Google Cloud Storage at
+   https://storage.googleapis.com/covid19-open-data/v3/demographics.csv
+2. Install whatever you need on demand, e.g. `pip install pandas`.
+3. Write a short Python script that loads the data and computes the answer.
+4. Run the script and report the result, showing the numbers you found.
+
+Notes on the demographics CSV above: it is a proper CSV with a header row.
+Each row is one location, identified by `location_key`. Country-level rows use
+a two-letter ISO code (e.g. `US`, `CN`, `IN`); subregions use keys containing
+an underscore (e.g. `US_CA`), so filter those out when you want countries only.
+Useful columns include `population`, `population_male`, `population_female`,
+`population_urban`, `population_rural`, and `population_density`.
+
+Prefer writing a script and executing it over guessing. If a command fails,
+read the error, fix the script, and try again.
+""",
+    tools=[EnvironmentToolset(environment=E2BEnvironment())],
+)
diff --git a/pyproject.toml b/pyproject.toml
@@ -69,6 +69,7 @@ optional-dependencies.agent-identity = [
 ]
 optional-dependencies.all = [
   "anyio>=4.9,<5",
+  "e2b>=2,<3",
   "google-api-python-client>=2.157,<3",
   "google-cloud-aiplatform[agent-engines]>=1.148.1,<2",
   "google-cloud-bigquery>=2.2",
@@ -122,6 +123,9 @@ optional-dependencies.docs = [
   "sphinx-rtd-theme",
 ]
 
+optional-dependencies.e2b = [
+  "e2b>=2,<3", # For E2BEnvironment remote sandbox.
+]
 optional-dependencies.eval = [
   "gepa>=0.1",
   "google-cloud-aiplatform[evaluation]>=1.148",
@@ -187,6 +191,7 @@ optional-dependencies.test = [
   "anthropic>=0.78",                                                 # For anthropic model tests; 0.78 introduced ThinkingConfigAdaptiveParam (required for Claude Opus 4.7).
   "anyio>=4.9,<5",
   "crewai[tools]; python_version>='3.11' and python_version<'3.12'", # For CrewaiTool tests; chromadb/pypika fail on 3.12+
+  "e2b>=2,<3",
   "gepa>=0.1",
   "google-api-python-client>=2.157,<3",
   "google-cloud-aiplatform[agent-engines,evaluation]>=1.148.1,<2",
diff --git a/src/google/adk/integrations/e2b/__init__.py b/src/google/adk/integrations/e2b/__init__.py
@@ -0,0 +1,38 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""E2B sandbox integration.
+
+This module provides a BaseEnvironment implementation backed by an E2B
+remote sandbox, offering a persistent remote workspace for file CRUD,
+shell execution, and on-demand software installs.
+
+Requires the ``e2b`` extra: ``pip install google-adk[e2b]``.
+
+Example:
+  ```python
+  from google.adk.integrations.e2b import E2BEnvironment
+
+  env = E2BEnvironment(image="base", timeout=300)
+  await env.initialize()
+  result = await env.execute("pip install requests")
+  await env.close()
+  ```
+"""
+
+from ._e2b_environment import E2BEnvironment
+
+__all__ = [
+    'E2BEnvironment',
+]
diff --git a/src/google/adk/integrations/e2b/_e2b_environment.py b/src/google/adk/integrations/e2b/_e2b_environment.py
diff --git a/tests/unittests/integrations/e2b/test_e2b_environment.py b/tests/unittests/integrations/e2b/test_e2b_environment.py
