feat(environment): Add EnvironmentToolset for file I/O and command execution

This change introduces a new EnvironmentToolset within the ADK, providing tools to interact with a BaseEnvironment. The toolset includes Execute, ReadFile, EditFile, WriteFile. System instructions are injected to guide the LLM on workspace usage and file manipulation.

Co-authored-by: Liang Wu <wuliang@google.com>
PiperOrigin-RevId: 890672569

Author: wuliang229

src/google/adk/tools/environment/__init__.py

@@ -0,0 +1,23 @@
+# 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.
+
+"""Environment toolset for command execution and file I/O."""
+
+from __future__ import annotations
+
+from ._environment_toolset import EnvironmentToolset
+
+__all__ = [
+    'EnvironmentToolset',
+]

src/google/adk/tools/environment/_constants.py

@@ -0,0 +1,46 @@
+# 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.
+
+"""Constants for the environment toolset."""
+
+from __future__ import annotations
+
+# ---------------------------------------------------------------------------
+# Default limits
+# ---------------------------------------------------------------------------
+
+DEFAULT_TIMEOUT = 30
+"""Default execution timeout in seconds."""
+
+MAX_OUTPUT_CHARS = 30_000
+"""Maximum characters returned to the LLM per tool call."""
+
+# ---------------------------------------------------------------------------
+# System instruction templates
+# ---------------------------------------------------------------------------
+
+ENVIRONMENT_INSTRUCTION = """\
+Your environment is at {working_dir}/
+
+# Environment Rules
+
+DO:
+- Chain sequential, dependent commands with `&&` in a single `Execute` call
+- To read existing files, always use the `ReadFile` tool. Use `EditFile` to modify existing files.
+
+DON'T:
+- Use `Execute` to run cat, head, or tail when `ReadFile` tools can do the job
+- Combine `EditFile` or `ReadFile` with `Execute` in the same response (Instead, call the file tool first, then `Execute` in the next turn)
+- Use multiple `Execute` calls for dependent commands (they run in parallel)
+"""

src/google/adk/tools/environment/_environment_toolset.py

@@ -0,0 +1,109 @@
+# 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.
+
+"""Environment toolset that provides tools to interact with an environment."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+from typing import Optional
+from typing import TYPE_CHECKING
+
+from typing_extensions import override
+
+from ...utils.feature_decorator import experimental
+from ..base_toolset import BaseToolset
+from ._constants import ENVIRONMENT_INSTRUCTION
+from ._tools import _EditFileTool
+from ._tools import _ExecuteTool
+from ._tools import _ReadFileTool
+from ._tools import _WriteFileTool
+
+if TYPE_CHECKING:
+  from ...agents.readonly_context import ReadonlyContext
+  from ...environments._base_environment import BaseEnvironment
+  from ...models.llm_request import LlmRequest
+  from ..base_tool import BaseTool
+  from ..tool_context import ToolContext
+
+logger = logging.getLogger('google_adk.' + __name__)
+
+
+@experimental
+class EnvironmentToolset(BaseToolset):
+  """Toolset providing tools to interact with an environment.
+
+  Tools provided:
+    - **Execute** -- run shell commands
+    - **ReadFile** -- read file contents
+    - **EditFile** -- surgical text replacement
+    - **WriteFile**q -- create/overwrite files
+
+  The toolset injects an environment-level system instruction on each
+  LLM call that establishes environment identity and tool selection
+  rules.
+  """
+
+  def __init__(
+      self,
+      *,
+      environment: BaseEnvironment,
+      **kwargs: Any,
+  ):
+    """Create an environment toolset.
+
+    Args:
+      environment: The environment used to execute commands and
+        perform file I/O.
+      **kwargs: Forwarded to ``BaseToolset.__init__``.
+    """
+    super().__init__(**kwargs)
+    self._environment = environment
+    self._environment_initialized = False
+
+  @override
+  async def get_tools(
+      self,
+      readonly_context: Optional[ReadonlyContext] = None,
+  ) -> list[BaseTool]:
+    if not self._environment_initialized:
+      await self._environment.initialize()
+      self._environment_initialized = True
+    return [
+        _ExecuteTool(self._environment),
+        _ReadFileTool(self._environment),
+        _EditFileTool(self._environment),
+        _WriteFileTool(self._environment),
+    ]
+
+  @override
+  async def process_llm_request(
+      self, *, tool_context: ToolContext, llm_request: LlmRequest
+  ) -> None:
+    """Inject environment-level system instruction."""
+    if not self._environment_initialized:
+      await self._environment.initialize()
+      self._environment_initialized = True
+    working_dir = self._environment.working_dir
+    instruction = ENVIRONMENT_INSTRUCTION.format(
+        working_dir=working_dir,
+    )
+    llm_request.append_instructions([instruction])
+
+  @override
+  async def close(self) -> None:
+    if self._environment_initialized:
+      await self._environment.close()
+      self._environment_initialized = False