feat(integrations): Add OpenSandboxEnvironment for remote sandbox workspaces #6758

🔴 Required Information

Is your feature request related to a specific problem?

Google ADK provides BaseEnvironment and EnvironmentToolset for persistent
workspace operations, and currently includes native remote environment
integrations for E2B and Daytona. OpenSandbox users cannot configure the
standard ADK environment tools with an OpenSandbox backend without maintaining
a custom BaseEnvironment adapter or replacing the standard toolset with
project-specific tools.

This makes it harder to use the same ADK agent against a locally hosted or
remotely hosted OpenSandbox deployment while preserving ADK's normal lifecycle,
command execution, and file-operation semantics.

Describe the Solution You'd Like

Add an experimental OpenSandboxEnvironment integration under
google.adk.integrations.opensandbox:

from google.adk.integrations.opensandbox import OpenSandboxEnvironment
from google.adk.tools.environment import EnvironmentToolset

toolset = EnvironmentToolset(
    environment=OpenSandboxEnvironment(
        image="python:3.11",
        timeout=300,
    )
)

The proposed adapter implements the existing BaseEnvironment contract and
does not require changes to that interface. Its initial scope is:

• create an owned sandbox or attach to a caller-owned sandbox;
• start from an image or snapshot;
• execute commands with working directory, environment variables, stdout,
  stderr, exit code, and timeout mapping;
• read and write binary files and normalize missing files to
  FileNotFoundError;
• renew the lifetime of owned sandboxes before operations;
• destroy owned sandboxes while leaving attached sandboxes running;
• keep the OpenSandbox SDK behind an optional google-adk[opensandbox] extra.

The integration would follow the public API, optional-dependency, feature flag,
sample, and unit-test structure already used by E2BEnvironment and
DaytonaEnvironment.

Impact on your work

This would let teams use ADK's standard EnvironmentToolset with an
OpenSandbox deployment instead of maintaining a parallel tool implementation.
It also allows the sandbox runtime and deployment model to remain an
OpenSandbox concern while the agent code uses the same ADK environment API.

There is no hard external deadline. We would like maintainer feedback on the
integration shape before preparing an upstream pull request.

Willingness to contribute

Yes. A working prototype is available at:

https://github.com/jianpingpei/adk-python/tree/feat/opensandbox-environment

The prototype currently has 28 focused unit tests and 60 passing related tests
covering OpenSandbox, E2B, Daytona, and EnvironmentToolset. It has also been
verified against a real local OpenSandbox Docker runtime and with a real
model-driven ADK agent calling WriteFile, Execute, and ReadFile. Any pull
request would be rebased onto the latest main and would include reproducible,
sanitized E2E commands and output.

🟡 Recommended Information

Describe Alternatives You've Considered

1. Keep the adapter outside ADK. This works, but each user must discover,
   install, and maintain a compatibility layer for an experimental ADK API.
2. Expose custom OpenSandbox tools directly to the agent. This bypasses
   EnvironmentToolset, duplicates its tool behavior and instructions, and
   makes switching environment backends harder.
3. Use an existing hosted backend integration. E2B and Daytona are useful
   options, but they do not connect an ADK application to an existing
   OpenSandbox deployment.

Proposed API / Implementation

The implementation would be a small BaseEnvironment subclass plus:

• google.adk.integrations.opensandbox public export;
• an opensandbox>=0.1.15,<0.2 optional extra;
• an experimental feature registry entry;
• focused unit tests using mocked SDK boundaries;
• an upstream-style sample using EnvironmentToolset;
• manual Runner/Agent E2E evidence using a real sandbox.

No new lifecycle abstraction or change to existing environment integrations is
proposed.

Additional Context

• OpenSandbox project: https://github.com/opensandbox-group/OpenSandbox
• Existing E2B integration precedent: feat(integrations): Add E2BEnvironment for remote sandbox workspaces #6031

Questions for maintainers:

1. Is google.adk.integrations.opensandbox.OpenSandboxEnvironment the desired
   location and naming for this backend?
2. Should the first contribution include only the code integration and sample,
   with user-facing documentation submitted separately to google/adk-docs?