ADK changes

Co-authored-by: Shangjie Chen <deanchen@google.com>
PiperOrigin-RevId: 890694124

Author: DeanChensj

src/google/adk/environment/__init__.py

@@ -0,0 +1,27 @@
+# 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.
+
+"""Agent environments."""
+
+from __future__ import annotations
+
+from ._base_environment import BaseEnvironment
+from ._base_environment import ExecutionResult
+from ._local_environment import LocalEnvironment
+
+__all__ = [
+    'BaseEnvironment',
+    'ExecutionResult',
+    'LocalEnvironment',
+]

src/google/adk/environment/_base_environment.py

@@ -0,0 +1,124 @@
+# 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.
+
+"""Base class for agent environments."""
+
+from __future__ import annotations
+
+from abc import ABC
+from abc import abstractmethod
+import dataclasses
+from pathlib import Path
+from typing import Optional
+
+from ..utils.feature_decorator import experimental
+
+
+@dataclasses.dataclass
+class ExecutionResult:
+  """Result of a command execution."""
+
+  exit_code: int = 0
+  """The exit code of the process."""
+
+  stdout: str = ""
+  """Standard output captured from the process."""
+
+  stderr: str = ""
+  """Standard error captured from the process."""
+
+  timed_out: bool = False
+  """Whether the execution exceeded the timeout."""
+
+
+@experimental
+class BaseEnvironment(ABC):
+  """Abstract base class for code execution environments.
+
+  An environment provides the ability to execute shell commands,
+  read files, and write files within a working directory.  Concrete
+  implementations include local subprocess execution, sandboxed
+  execution, container environments, and cloud-hosted environments.
+
+  Lifecycle:
+    1. Construct the environment (``__init__``).
+    2. Call ``initialize()`` before first use.
+    3. Use ``execute``, ``read_file``, ``write_file``.
+    4. Call ``close()`` when done.
+  """
+
+  async def initialize(self) -> None:
+    """Initialize the environment (e.g. create working directory).
+
+    Called before first use. The default implementation is a
+    no-op. Sub-classes should ensure this method is idempotent.
+    """
+
+  async def close(self) -> None:
+    """Release resources held by the environment.
+
+    Called when the environment is no longer needed. The default
+    implementation is a no-op. Sub-classes should ensure this method is
+    idempotent.
+    """
+
+  @property
+  @abstractmethod
+  def working_dir(self) -> Path:
+    """The absolute path to the environment's working directory."""
+
+  @abstractmethod
+  async def execute(
+      self,
+      command: str,
+      *,
+      timeout: Optional[float] = None,
+  ) -> ExecutionResult:
+    """Execute a shell command in the working directory.
+
+    Args:
+      command: The shell command string to execute.
+      timeout: Maximum execution time in seconds.  ``None`` means
+        no limit.
+
+    Returns:
+      An ``ExecutionResult`` with exit code, stdout, stderr, and
+      timeout status.
+    """
+
+  @abstractmethod
+  async def read_file(self, path: Path) -> bytes:
+    """Read a file from the environment filesystem.
+
+    Args:
+      path: Absolute or working-dir-relative path to the file.
+
+    Returns:
+      The raw file contents as bytes.
+
+    Raises:
+      FileNotFoundError: If the file does not exist.
+    """
+
+  @abstractmethod
+  async def write_file(self, path: Path, content: str | bytes) -> None:
+    """Write content to a file in the environment's filesystem.
+
+    Parent directories are created automatically if they do not
+    exist.
+
+    Args:
+      path: Absolute or working-dir-relative path to the file.
+      content: The string or raw bytes to write.
+    """

src/google/adk/environment/_local_environment.py

@@ -0,0 +1,160 @@
+# 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.
+
+"""Local subprocess code execution environment."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+from pathlib import Path
+import shutil
+import tempfile
+from typing import Optional
+
+from typing_extensions import override
+
+from ..utils.feature_decorator import experimental
+from .base_environment import BaseEnvironment
+from .base_environment import ExecutionResult
+
+logger = logging.getLogger('google_adk.' + __name__)
+
+
+@experimental
+class LocalEnvironment(BaseEnvironment):
+  """Execute commands via local ``asyncio`` subprocesses.
+
+  When ``working_dir`` is not specified, a temporary directory is
+  created on ``initialize()`` and removed on ``close()``.
+  """
+
+  def __init__(
+      self,
+      *,
+      working_dir: Optional[Path] = None,
+      env_vars: Optional[dict[str, str]] = None,
+  ):
+    """Create a local environment.
+
+    Args:
+      working_dir: Absolute path to the workspace directory.  If
+        ``None``, a temporary directory is created during
+        ``initialize()``.
+      env_vars: Extra environment variables merged into the subprocess
+        environment.
+    """
+    self._working_dir = working_dir
+    self._env_vars = env_vars
+    self._auto_created = False
+
+  @property
+  @override
+  def working_dir(self) -> Path:
+    if self._working_dir is None:
+      raise RuntimeError('`working_dir` is not set. Call initialize() first.')
+    return self._working_dir
+
+  @override
+  async def initialize(self) -> None:
+    if self._working_dir is None:
+      self._working_dir = Path(tempfile.mkdtemp(prefix='adk_workspace_'))
+      self._auto_created = True
+      logger.debug('Created temporary folder: %s', self._working_dir)
+    else:
+      os.makedirs(self._working_dir, exist_ok=True)
+
+  @override
+  async def close(self) -> None:
+    if self._auto_created and self._working_dir:
+      shutil.rmtree(self._working_dir, ignore_errors=True)
+      logger.debug('Removed temporary workspace: %s', self._working_dir)
+      self._working_dir = None
+
+
+  @override
+  async def execute(
+      self,
+      command: str,
+      *,
+      timeout: Optional[float] = None,
+  ) -> ExecutionResult:
+    if self._working_dir is None:
+      raise RuntimeError('`working_dir` is not set. Call initialize() first.')
+
+    proc_env = os.environ.copy()
+    if self._env_vars:
+      proc_env.update(self._env_vars)
+
+    proc = await asyncio.create_subprocess_shell(
+        command,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+        cwd=self._working_dir,
+        env=proc_env,
+    )
+
+    timed_out = False
+    try:
+      stdout_bytes, stderr_bytes = await asyncio.wait_for(
+          proc.communicate(), timeout=timeout
+      )
+    except asyncio.TimeoutError:
+      timed_out = True
+      proc.kill()
+      stdout_bytes, stderr_bytes = await proc.communicate()
+
+    return ExecutionResult(
+        exit_code=proc.returncode or 0,
+        stdout=stdout_bytes.decode('utf-8', errors='replace'),
+        stderr=stderr_bytes.decode('utf-8', errors='replace'),
+        timed_out=timed_out,
+    )
+
+  @override
+  async def read_file(self, path: str) -> bytes:
+    if self._working_dir is None:
+      raise RuntimeError('`working_dir` is not set. Call initialize() first.')
+
+    path = self._resolve_path(path)
+    return await asyncio.to_thread(self._sync_read, path)
+
+  @override
+  async def write_file(self, path: str, content: str | bytes) -> None:
+    if self._working_dir is None:
+      raise RuntimeError('`working_dir` is not set. Call initialize() first.')
+
+    path = self._resolve_path(path)
+    return await asyncio.to_thread(self._sync_write, path, content)
+
+
+  def _resolve_path(self, path: str) -> str:
+    """Resolve a relative path against the working directory."""
+    if os.path.isabs(path):
+      return path
+    return os.path.join(self._working_dir, path)
+
+  @staticmethod
+  def _sync_read(path: str) -> bytes:
+    with open(path, 'rb') as f:
+      return f.read()
+
+  @staticmethod
+  def _sync_write(path: str, content: str | bytes) -> None:
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    mode = 'w' if isinstance(content, str) else 'wb'
+    kwargs = {'encoding': 'utf-8'} if isinstance(content, str) else {}
+    with open(path, mode, **kwargs) as f:
+      f.write(content)