Class ContainerCodeExecutor

java.lang.Object
com.google.adk.JsonBaseModel
com.google.adk.codeexecutors.BaseCodeExecutor
com.google.adk.codeexecutors.ContainerCodeExecutor
All Implemented Interfaces:
AutoCloseable
public class ContainerCodeExecutor extends BaseCodeExecutor implements AutoCloseable
A code executor that runs code in a Docker container.

Code is run via docker exec (as in ADK Python), so the image only needs python3 on its PATH; any image ENTRYPOINT is bypassed. By default a single container is created on first use and reused for every executeCode(InvocationContext, CodeExecutionUtils.CodeExecutionInput) call, as in ADK Python. With the strict sandbox enabled, each execution instead runs in a fresh container that is force-removed afterwards, so one execution cannot observe or affect another's environment.

Sandboxing is opt-in. By default the execution container is unrestricted (network enabled, writable filesystem, no resource or time limits), matching the previous behavior so existing callers are not broken; a warning is logged when it is used this way. Call setStrictSandbox(true) to harden each container: no network (unless re-enabled via setNetworkEnabled(boolean)), all Linux capabilities dropped, no privilege escalation, a read-only root filesystem with a small writable /tmp tmpfs, memory/PID limits, and a wall-clock execution timeout. Strict sandboxing becomes the default in ADK 2.0.

The execution timeout and memory limit used by the strict sandbox are configurable via setExecutionTimeoutSeconds(long) and setMemoryLimitBytes(long).

This executor holds a DockerClient; call close() (or rely on the registered JVM shutdown hook) to release its connections and threads. As with ADK Python, an abrupt JVM termination (e.g. SIGKILL) during an execution may leave a container behind.

  • Constructor Details

    • ContainerCodeExecutor

      @Deprecated public ContainerCodeExecutor(String baseUrl, String image, String dockerPath)
      Deprecated.
      Use one of the static factory methods instead.
      Initializes the ContainerCodeExecutor. Either dockerPath or image must be set.

  • Method Details

    • fromImage

      public static ContainerCodeExecutor fromImage(String baseUrl, String image)
      Creates a ContainerCodeExecutor from an image.
      Parameters:
      baseUrl - The base url of the user hosted Docker client.
      image - The tag of the predefined image or custom image to run on the container.

    • fromImage

      public static ContainerCodeExecutor fromImage(String image)
      Creates a ContainerCodeExecutor from an image.
      Parameters:
      image - The tag of the predefined image or custom image to run on the container.

    • fromDockerPath

      public static ContainerCodeExecutor fromDockerPath(String baseUrl, String dockerPath)
      Creates a ContainerCodeExecutor from a Dockerfile path.
      Parameters:
      baseUrl - The base url of the user hosted Docker client.
      dockerPath - The path to the directory containing the Dockerfile.

    • fromDockerPath

      public static ContainerCodeExecutor fromDockerPath(String dockerPath)
      Creates a ContainerCodeExecutor from a Dockerfile path.
      Parameters:
      dockerPath - The path to the directory containing the Dockerfile.

    • setNetworkEnabled

      public ContainerCodeExecutor setNetworkEnabled(boolean networkEnabled)
      Enables or disables container networking when the strict sandbox is on. In strict mode networking is disabled by default so executed code cannot reach the network (including the cloud metadata endpoint); pass true to allow it. Has no effect unless setStrictSandbox(boolean) is enabled — without the sandbox the container always has network access.

    • setExecutionTimeoutSeconds

      public ContainerCodeExecutor setExecutionTimeoutSeconds(long executionTimeoutSeconds)
      Sets the maximum wall-clock time (in seconds) a single execution may run, in the strict sandbox, before its container is force-removed (killed). Defaults to 60 seconds. Has no effect unless setStrictSandbox(boolean) is enabled.

    • setMemoryLimitBytes

      public ContainerCodeExecutor setMemoryLimitBytes(long memoryLimitBytes)
      Sets the per-execution container memory limit, in bytes, used by the strict sandbox. Defaults to 512 MiB. Has no effect unless setStrictSandbox(boolean) is enabled.

    • setStrictSandbox

      public ContainerCodeExecutor setStrictSandbox(boolean strictSandbox)
      Enables the strict sandbox. When enabled, each execution runs in its own fresh container (force-removed afterwards) that is hardened: no network (unless re-enabled via setNetworkEnabled(boolean)), all Linux capabilities dropped, no privilege escalation, a read-only root filesystem (writable /tmp only), memory/PID limits, and a wall-clock timeout. While disabled, a single unrestricted container is reused across executions, as before.

      Disabled by default so enabling the sandbox is not a breaking change for existing callers. While it is disabled a warning is logged, because running untrusted, model-generated code without the sandbox is dangerous. Strict sandboxing becomes the default in ADK 2.0.

    • stateful

      public boolean stateful()
      Description copied from class: BaseCodeExecutor
      Whether the code executor is stateful. Default to False.
      Overrides:
      stateful in class BaseCodeExecutor

    • optimizeDataFile

      public boolean optimizeDataFile()
      Description copied from class: BaseCodeExecutor
      If true, extract and process data files from the model request and attach them to the code executor.

      Supported data file MimeTypes are [text/csv]. Default to False.

      Overrides:
      optimizeDataFile in class BaseCodeExecutor

    • executeCode

      public CodeExecutionUtils.CodeExecutionResult executeCode(InvocationContext invocationContext, CodeExecutionUtils.CodeExecutionInput codeExecutionInput)
      Description copied from class: BaseCodeExecutor
      Executes code and return the code execution result.

      This method may perform blocking operations.

      Specified by:
      executeCode in class BaseCodeExecutor
      Parameters:
      invocationContext - The invocation context of the code execution.
      codeExecutionInput - The code execution input.
      Returns:
      The code execution result.

    • close

      public void close()
      Removes the shared container, if one was created, and closes the underlying Docker client, releasing its connections and threads.
      Specified by:
      close in interface AutoCloseable