feat(integrations): Add E2BEnvironment for remote sandbox workspaces

[Jacksunwei]

Stacked on #6030 (fix/experimental-typing). This PR targets that branch; please review/merge #6030 first, after which this will be retargeted to main.

Summary

Adds E2BEnvironment, a BaseEnvironment backed by an E2B 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

from google.adk.integrations.e2b import E2BEnvironment
from google.adk.tools.environment import EnvironmentToolset

toolset = EnvironmentToolset(environment=E2BEnvironment())

Test plan

• pytest tests/unittests/integrations/e2b/ (14 passed)
• pyright src/google/adk/integrations/e2b/_e2b_environment.py — 0 errors
• Sample agent loads (contributing/samples/environment_and_skills/e2b_environment)
• Manual run against a live E2B sandbox (requires E2B_API_KEY)

[adk-bot]

Response from ADK Triaging Agent

Hello @Jacksunwei, thank you for creating this PR!

This is a great feature! To help get this reviewed and merged more smoothly, please address the following items in accordance with our contribution guidelines:

1. Failing Checks: It looks like the check-file-contents check is currently failing. Please inspect the CI logs, and make sure that formatting, imports, and license headers are correct (running pre-commit run --all-files locally can help with this!).
2. Logs / Execution Evidence: As this introduces a new integration/feature, could you please run the sample agent against a live E2B sandbox, complete the unchecked item in your test plan, and provide the console logs or screenshots showing the successful execution? This helps reviewers better understand the implementation and verify that everything functions as expected.

This information will help reviewers evaluate your PR more efficiently. Thanks again for your contribution!

[adk-bot]

🔍 ADK Pull Request Analysis: PR #6031

Title: feat(integrations): Add E2BEnvironment for remote sandbox workspaces
Author: @Jacksunwei
Status: OPEN
Impact: 599 additions, 0 deletions across 7 files

Executive Summary

1. Core Objective: Introduces E2BEnvironment – a secure remote container environment implementation subclassing BaseEnvironment – enabling AI agents to safely execute command lines, manage file operations, and perform pip/apt package installations in an isolated E2B remote sandbox rather than on the host machine.
2. Justification & Value: Valuable Feature - Crucial addition for security; running untested agent-generated code locally exposes users to serious hazards, which the E2B sandbox cleanly mitigates.
3. Alignment with Principles: Pass with Nits - High-quality implementation adhering cleanly to contract definitions and testing/sample rules, with minor typing style nits in the E2B class and a missing annotations import in the testing module.
4. Recommendation: Approve with Nits - Approve once minor styling improvements are applied.

Detailed Findings & Analysis

1. Objectives & Impact ("What does it do?")

• Context & Background: In ADK, code execution currently depends on LocalEnvironment, which executes subprocess commands on the host machine. PR feat(integrations): Add E2BEnvironment for remote sandbox workspaces #6031 integrates E2B remote sandboxes to isolate environment interaction from host resources.
• Implementation Mechanism:
  • Adds the private class E2BEnvironment under src/google/adk/integrations/e2b/.
  • Overrides BaseEnvironment's methods to handle sandboxed file operations (read_file, write_file) and code runs (execute).
  • Implements state keepalive TTL management (refreshing timeout on operations) and transparent automatic recreation of sandboxes that expired due to being idle.
  • Implements modern PEP-deferred dependency imports (loading E2B packages only when E2B methods are actually invoked).
• Affected Surface: Introduces high compatibility with EnvironmentToolset under the @experimental decorator flag with zero breaking modifications to existing APIs.

2. Justification & Value ("Is it a valid and useful change?")

• Workspace Verification:
  • Investigated _local_environment.py and verified local OS execution is our exclusive execution path. Sandboxed code evaluation is highly requested in multi-agent tool setups.
• Value Assessment: Highly valuable. Safely executing untested, LLM-generated operations inside on-demand sandboxes is an essential industry-standard capability for modern developer toolkits.
• Alternative Approaches: The design gracefully integrates E2B with ADK's BaseEnvironment model, which represents the most elegant framework-aligned approach.
• Scope & Depth: Systematic Fix & Root Cause - Addresses fundamental host protection, managing sandbox lifecycle, TTL restrictions, keepalive refreshes, and recreation logic flawlessly.

3. Principle & Style Alignment Checklist ("Does it follow rules?")

• Public API & Visibility Boundaries:
  • Status: Pass
  • Analysis: E2BEnvironment correctly resides in a private sub-module and is explicitly exposed in the package's init.py using the __all__ list.
• Code Quality, Typing & Conventions:
  • Status: Nits
  • Analysis:
    • 🛑 Nit (Legacy Union Type): _e2b_environment.py uses the legacy style Optional[...] on lines 53, 54, 55, 90, and 114 (e.g. Optional[str], Optional[dict[str, str]], Optional[AsyncSandbox], Optional[float]). Since this is a new module, we should adopt ADK's modern union style T | None instead (e.g., str | None).
    • 🛑 Nit (Future Import): test_e2b_environment.py is missing from __future__ import annotations at the top of the file.
• Robustness & Edge Cases:
  • Status: Pass
  • Analysis: Leverages standard type checks via isinstance, maps timeout conditions correctly to ExecutionResult(timed_out=True), handles clean fallback exception mappings for FileNotFoundError, and provides a seamless recreation strategy if the connection expires.
• Test Integrity & Quality:
  • Status: Pass
  • Analysis: Out-of-the-box unit testing in test_e2b_environment.py isolates external network dependency by cleanly stubbing e2b commands, asserts exact expected behaviors (including keepalive checks and sandbox recreation), uses clean inline test fixtures, and follows the classic Arrange-Act-Assert format perfectly.

---

🛑 Review Decision Gate

I have completed my in-depth analysis of Pull Request #6031. Please review the findings above.

How would you like to proceed with this Pull Request?

• [Option 1]: Push Back (Draft a professional, constructive feedback response with recommendations for the author to fix the legacy Optional types and the missing future import in tests).
• [Option 2]: Local Review (Checkout the PR locally under pr-triage-6031-e2b-environment, rebase onto the latest main, and run the /adk-review skill to thoroughly verify and polish before pushing to Gerrit).