Merge branch 'main' into docs/openapi-session-endpoint-docs-update

Author: akshay-kumar-bm

contributing/samples/agent_tool_with_grounding_metadata/__init__.py

@@ -0,0 +1,15 @@
+# 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.
+
+from . import agent

contributing/samples/agent_tool_with_grounding_metadata/agent.py

@@ -0,0 +1,74 @@
+# 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.
+
+import os
+import random
+
+from dotenv import load_dotenv
+from google.adk import Agent
+from google.adk.tools.agent_tool import AgentTool
+from google.adk.tools.tool_context import ToolContext
+from google.adk.tools.vertex_ai_search_tool import VertexAiSearchTool
+
+load_dotenv(override=True)
+
+VERTEXAI_DATASTORE_ID = os.getenv("VERTEXAI_DATASTORE_ID")
+if not VERTEXAI_DATASTORE_ID:
+  raise ValueError("VERTEXAI_DATASTORE_ID environment variable not set")
+
+
+def roll_die(sides: int, tool_context: ToolContext) -> int:
+  """Roll a die and return the rolled result.
+
+  Args:
+    sides: The integer number of sides the die has.
+
+  Returns:
+    An integer of the result of rolling the die.
+  """
+  result = random.randint(1, sides)
+  if "rolls" not in tool_context.state:
+    tool_context.state["rolls"] = []
+
+  tool_context.state["rolls"] = tool_context.state["rolls"] + [result]
+  return result
+
+
+vertex_ai_search_agent = Agent(
+    model="gemini-3-flash-preview",
+    name="vertex_ai_search_agent",
+    description="An agent for performing Vertex AI search.",
+    tools=[
+        VertexAiSearchTool(
+            data_store_id=VERTEXAI_DATASTORE_ID,
+        )
+    ],
+)
+
+root_agent = Agent(
+    model="gemini-3.1-pro-preview",
+    name="hello_world_agent",
+    description="A hello world agent with multiple tools.",
+    instruction="""
+      You are a helpful assistant which can help user to roll dice and search for information.
+      - Use `roll_die` tool to roll dice.
+      - Use `vertex_ai_search_agent` to search for Google Agent Development Kit (ADK) information in the datastore.
+    """,
+    tools=[
+        roll_die,
+        AgentTool(
+            agent=vertex_ai_search_agent, propagate_grounding_metadata=True
+        ),
+    ],
+)

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.
+    """