Skip to content

Google ADK Integration Guide ​

中文

Use CubeSandbox as the code execution environment for a Google Agent Development Kit agent. Google ADK supports Python function tools, and CubeSandbox exposes an E2B-compatible API, so an ADK agent can call a normal Python tool while the generated code runs inside an isolated CubeSandbox MicroVM.

This guide follows the "agent on the host, code in the sandbox" pattern. The ADK runtime, model credentials, and local project stay on the host; only the tool's code execution crosses into CubeSandbox.

Integration Target and Version ​

ComponentBaseline
Google ADKPython package google-adk==2.7.1
Python3.10+
CubeSandboxE2B-compatible CubeAPI, a reachable CubeProxy data plane, and a template that supports run_code
SDK pathe2b==2.26.0 and e2b-code-interpreter==2.8.1, pointed at CubeAPI through E2B_API_URL

Google ADK is evolving quickly, so the runnable example pins the ADK package. The E2B packages are pinned to a pair (e2b==2.26.0 and e2b-code-interpreter==2.8.1) that plain pip can install and that has been verified against a live CubeSandbox deployment using the sandbox-code:latest template. Revalidate the live run_code path before changing package versions or using this example as a production baseline.

Prerequisites ​

  • A running CubeSandbox deployment with CubeAPI reachable, normally at http://<cube-host>:3000.
  • Data-plane reachability for the official E2B SDK. A one-click local deployment includes CoreDNS; production deployments should configure wildcard DNS, and local setups without wildcard DNS can use the E2B development sidecar.
  • A CubeSandbox template ID. Use a template that supports the E2B code interpreter run_code path.
  • Python 3.10+ on the machine running the ADK agent.
  • A Google API key or another ADK-supported model configuration.

Control plane and data plane

E2B_API_URL selects the CubeAPI control-plane endpoint. The official E2B SDK also connects to per-sandbox data-plane hostnames when run_code executes. Configure wildcard DNS for production deployments, or use the E2B development sidecar for local development without wildcard DNS. If your deployment uses TLS with a self-signed certificate, set CUBE_SSL_CERT_FILE so the example can export SSL_CERT_FILE before opening the sandbox. SSL_CERT_FILE is process-global; use a CA bundle that also preserves model-provider TLS trust, or leave it unset when CubeAPI is served with a public certificate.

Setup ​

Install the example:

bash
cd examples/google-adk-integration
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env

Configure .env:

VariablePurpose
E2B_API_URLCubeAPI control-plane URL, for example http://<cube-host>:3000
E2B_API_KEYE2B-compatible key accepted by your CubeAPI auth callback, or e2b_000000 when auth is disabled
CUBE_TEMPLATE_IDCubeSandbox template ID used for temporary tool sandboxes
GOOGLE_API_KEYGoogle model API key used by ADK
GOOGLE_ADK_MODELADK model name, for example gemini-2.5-flash
CUBE_SANDBOX_TIMEOUTOptional sandbox lifetime bound in seconds, passed to Sandbox.create(timeout=...); defaults to 300
CUBE_RUN_CODE_TIMEOUTOptional per-call execution timeout in seconds, passed to sandbox.run_code(timeout=...); defaults to 60
CUBE_USE_DEV_SIDECAROptional local-development switch. Set to true to call the E2B dev-sidecar before sandbox creation
CUBE_REMOTE_PROXY_BASERequired when CUBE_USE_DEV_SIDECAR=true; CubeProxy data-plane endpoint for the sidecar, for example https://127.0.0.1:11443 in dev-env
CUBE_SSL_CERT_FILEOptional CubeSandbox CA bundle for self-signed deployments

Integration Snippet ​

Expose a CubeSandbox execution function as an ADK tool:

python
from google.adk import Agent

from cube_code_tool import run_python_in_cube

root_agent = Agent(
    name="cube_code_agent",
    model="gemini-2.5-flash",
    instruction=(
        "When Python code needs to run, call run_python_in_cube so execution "
        "happens inside an isolated CubeSandbox MicroVM."
    ),
    tools=[run_python_in_cube],
)

The simplified tool shape keeps the Cube-specific logic in one place. The runnable example includes additional environment loading, stderr handling, sidecar setup, and cross-version output normalization:

python
import os

from e2b_code_interpreter import Sandbox

def run_python_in_cube(code: str) -> dict:
    template_id = os.environ["CUBE_TEMPLATE_ID"]
    with Sandbox.create(template=template_id, timeout=300) as sandbox:
        execution = sandbox.run_code(code, timeout=60)
        stdout = "".join(str(item) for item in execution.logs.stdout)
        stderr = "".join(str(item) for item in execution.logs.stderr)
        return {
            "stdout": stdout,
            "stderr": stderr,
            "text": execution.text,
            "error": str(execution.error) if execution.error else None,
        }

Compared with a host-side Python tool, only the tool body changes. The ADK agent still sees a regular function tool with structured inputs and outputs.

The runnable example also supports CUBE_USE_DEV_SIDECAR=true for local development without wildcard DNS. That mode calls the sidecar setup from examples/e2b-dev-sidecar before sandbox creation, so configure that example's CUBE_REMOTE_PROXY_* variables in this example's .env file or export them in the ADK process environment. Do not rely on examples/e2b-dev-sidecar/.env; this example does not load that file.

Migrating a local ADK code tool ​

diff
- def run_python(code: str) -> dict:
-     completed = subprocess.run(["python3", "-c", code], capture_output=True, text=True)
-     return {"stdout": completed.stdout, "stderr": completed.stderr}
+ def run_python(code: str) -> dict:
+     return run_python_in_cube(code)

The agent definition can remain unchanged if it already references the original code execution tool. Update prompts or result handling if they depend on fields that differ from this example's stdout, text, error, and results_count shape. The runnable example also returns stderr so the agent can inspect tracebacks and diagnostic output from failed runs.

Runnable Demo ​

Run the offline wiring check first:

bash
cd examples/google-adk-integration
python smoke_test.py

Expected output:

text
GOOGLE_ADK_CUBE_SMOKE_OK

Then run the ADK agent from the parent directory:

bash
cd examples
adk run google-adk-integration

Ask:

text
Run Python in the sandbox to calculate the first 10 Fibonacci numbers.

The agent calls run_python_in_cube, creates a temporary CubeSandbox from CUBE_TEMPLATE_ID, executes the generated Python code, returns the tool output, and deletes the temporary sandbox when the tool call finishes.

Going Further ​

  • Reuse a sandbox per session: the example creates one temporary sandbox per tool call for simplicity. For multi-step notebooks, keep a sandbox handle in a session-scoped service and delete it when the ADK session ends.
  • Timeouts: set CUBE_SANDBOX_TIMEOUT or pass a fixed timeout to Sandbox.create(...) for the sandbox lifetime. Set CUBE_RUN_CODE_TIMEOUT or pass timeout=... to sandbox.run_code(...) for the per-call execution limit.
  • Network policy: create sandboxes with Cube-specific egress controls when generated code must only reach approved hosts. See network policy.
  • Credential handling: keep model provider keys on the host. If sandboxed code must call an external API, prefer Cube's Egress Proxy and credential injection flow instead of placing raw secrets in the VM.
  • Templates: preinstall heavy dependencies in the template image so each ADK tool call starts quickly from a ready snapshot.

Caveats ​

  • The example validates imports and wiring offline. A full live run requires a reachable CubeSandbox deployment and a run_code-capable template.
  • If you upgrade e2b or e2b-code-interpreter beyond the pinned versions, revalidate the live run_code path against your CubeSandbox deployment.
  • Google ADK's native Agent Runtime Code Execution tool targets Google Cloud Agent Runtime. This guide uses a custom ADK function tool so CubeSandbox can provide the execution backend.
  • The default example creates and deletes a sandbox for each tool call. That is easiest to review, but not the lowest-latency shape for long multi-step tasks.

References ​