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

Author: rohityan

contributing/samples/local_environment/README.md

@@ -0,0 +1,21 @@
+# Local Environment Sample
+
+This sample demonstrates how to use the `LocalEnvironment` with the `EnvironmentToolset` to allow an agent to interact with the local filesystem and execute commands.
+
+## Description
+
+The agent is configured with the `EnvironmentToolset`, which provides tools for file I/O (reading, writing) and command execution within a local environment. This allows the agent to perform tasks that involve creating files, modifying them, and running local scripts or commands.
+
+## Sample Usage
+
+You can interact with the agent by providing prompts that require file operations and command execution.
+
+### Example Prompt
+
+> "Write a Python file named `hello.py` to the working directory that prints 'Hello from ADK!'. Then read the file to verify its contents, and finally execute it using a command."
+
+### Expected Behavior
+
+1.  **Write File**: The agent uses a tool to write `hello.py` with the content `print("Hello from ADK!")`.
+2.  **Read File**: The agent uses a tool to read `hello.py` and verify the content.
+3.  **Execute Command**: The agent uses a tool to run `python3 hello.py` and returns the output.

contributing/samples/local_environment/__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/local_environment/agent.py

@@ -0,0 +1,34 @@
+# 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 google.adk import Agent
+from google.adk.environment import LocalEnvironment
+from google.adk.tools.environment import EnvironmentToolset
+
+root_agent = Agent(
+    model="gemini-2.5-pro",
+    name="local_environment_agent",
+    description="A simple agent that demonstrates local environment usage.",
+    instruction="""
+    You are a helpful AI assistant that can use the local environment to
+    execute commands and file I/O. Follow the rules of the environment and the
+    user's instructions.
+    """,
+    tools=[
+        EnvironmentToolset(
+            environment=LocalEnvironment(),
+        ),
+    ],
+)

contributing/samples/toolbox_agent/README.md

@@ -19,7 +19,7 @@ Run the following command to download and install the MCP Toolbox binary.
 
 ```bash
 export OS="linux/amd64" # one of linux/amd64, darwin/arm64, darwin/amd64, or windows/amd64
-curl -O https://storage.googleapis.com/genai-toolbox/v0.28.0/$OS/toolbox
+curl -O https://storage.googleapis.com/genai-toolbox/v0.31.0/$OS/toolbox
 chmod +x toolbox
 ```
 

pyproject.toml

@@ -165,12 +165,12 @@ extensions = [
   "llama-index-embeddings-google-genai>=0.3.0", # For files retrieval using LlamaIndex.
   "lxml>=5.3.0",                                # For load_web_page tool.
   "pypika>=0.50.0",                             # For crewai->chromadb dependency
-  "toolbox-adk>=0.7.0, <0.8.0",                 # For tools.toolbox_toolset.ToolboxToolset
+  "toolbox-adk>=1.0.0, <2.0.0",                 # For tools.toolbox_toolset.ToolboxToolset
 ]
 
 otel-gcp = ["opentelemetry-instrumentation-google-genai>=0.6b0, <1.0.0"]
 
-toolbox = ["toolbox-adk>=0.7.0, <0.8.0"]
+toolbox = ["toolbox-adk>=1.0.0, <2.0.0"]
 
 slack = ["slack-bolt>=1.22.0"]
 

src/google/adk/integrations/agent_registry/agent_registry.py

@@ -37,17 +37,70 @@
 from a2a.types import TransportProtocol as A2ATransport
 from google.adk.agents.readonly_context import ReadonlyContext
 from google.adk.agents.remote_a2a_agent import RemoteA2aAgent
+from google.adk.telemetry.tracing import GCP_MCP_SERVER_DESTINATION_ID
+from google.adk.tools.base_tool import BaseTool
+from google.adk.tools.mcp_tool.mcp_session_manager import SseConnectionParams
+from google.adk.tools.mcp_tool.mcp_session_manager import StdioConnectionParams
 from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
 from google.adk.tools.mcp_tool.mcp_toolset import McpToolset
 import google.auth
 import google.auth.transport.requests
 import httpx
+from mcp import StdioServerParameters
+from typing_extensions import override
 
 logger = logging.getLogger("google_adk." + __name__)
 
 AGENT_REGISTRY_BASE_URL = "https://agentregistry.googleapis.com/v1alpha"
 
 
+# An MCPToolset for a single registered MCP server. Adds the special
+# gcp.mcp.server.destination.id custom_metadata key on each returned tool. This special key is
+# added to execute_tool spans in google.adk.telemetry.tracing
+class AgentRegistrySingleMcpToolset(McpToolset):
+
+  def __init__(
+      self,
+      *,
+      destination_resource_id: str | None,
+      connection_params: (
+          StdioServerParameters
+          | StdioConnectionParams
+          | SseConnectionParams
+          | StreamableHTTPConnectionParams
+      ),
+      tool_name_prefix: str | None = None,
+      header_provider: (
+          Callable[[ReadonlyContext], Dict[str, str]] | None
+      ) = None,
+  ):
+    super().__init__(
+        connection_params=connection_params,
+        tool_name_prefix=tool_name_prefix,
+        header_provider=header_provider,
+    )
+    self.destination_resource_id = destination_resource_id
+
+  @override
+  async def get_tools(
+      self, readonly_context: ReadonlyContext | None = None
+  ) -> List[BaseTool]:
+    tools = await super().get_tools(readonly_context)
+
+    # Noop if there is no destination_resource_id
+    if self.destination_resource_id is None:
+      return tools
+
+    for tool in tools:
+      if not tool.custom_metadata:
+        tool.custom_metadata = {}
+
+      tool.custom_metadata[GCP_MCP_SERVER_DESTINATION_ID] = (
+          self.destination_resource_id
+      )
+    return tools
+
+
 class _ProtocolType(str, Enum):
   """Supported agent protocol types."""
 
@@ -196,6 +249,9 @@ def get_mcp_toolset(self, mcp_server_name: str) -> McpToolset:
     """Constructs an McpToolset instance from a registered MCP Server."""
     server_details = self.get_mcp_server(mcp_server_name)
     name = self._clean_name(server_details.get("displayName", mcp_server_name))
+    mcp_server_id = server_details.get("mcpServerId")
+    if not isinstance(mcp_server_id, str):
+      mcp_server_id = None
 
     endpoint_uri = self._get_connection_uri(
         server_details, protocol_binding=A2ATransport.jsonrpc
@@ -210,7 +266,8 @@ def get_mcp_toolset(self, mcp_server_name: str) -> McpToolset:
     connection_params = StreamableHTTPConnectionParams(
         url=endpoint_uri, headers=self._get_auth_headers()
     )
-    return McpToolset(
+    return AgentRegistrySingleMcpToolset(
+        destination_resource_id=mcp_server_id,
         connection_params=connection_params,
         tool_name_prefix=name,
         header_provider=self._header_provider,

src/google/adk/memory/vertex_ai_memory_bank_service.py

@@ -397,11 +397,9 @@ def _get_api_client(self) -> vertexai.AsyncClient:
     """
     import vertexai
 
-    return vertexai.Client(
-        project=self._project,
-        location=self._location,
-        api_key=self._express_mode_api_key,
-    ).aio
+    if self._express_mode_api_key:
+      return vertexai.Client(api_key=self._express_mode_api_key).aio
+    return vertexai.Client(project=self._project, location=self._location).aio
 
 
 def _should_filter_out_event(content: types.Content) -> bool:

src/google/adk/sessions/vertex_ai_session_service.py

@@ -376,11 +376,15 @@ def _get_api_client(self) -> vertexai.AsyncClient:
     """
     import vertexai
 
+    if self._express_mode_api_key:
+      return vertexai.Client(
+          http_options=self._api_client_http_options_override(),
+          api_key=self._express_mode_api_key,
+      ).aio
     return vertexai.Client(
         project=self._project,
         location=self._location,
         http_options=self._api_client_http_options_override(),
-        api_key=self._express_mode_api_key,
     ).aio
 
 

src/google/adk/telemetry/tracing.py

@@ -83,6 +83,11 @@
 
 USER_CONTENT_ELIDED = '<elided>'
 
+# Used to associate a span with a destination resource for AppHub. Tools with
+# this key in their BaseTool.custom_metadata will have the mapping added as a
+# span attribute
+GCP_MCP_SERVER_DESTINATION_ID = 'gcp.mcp.server.destination.id'
+
 # Needed to avoid circular imports
 if TYPE_CHECKING:
   from ..agents.base_agent import BaseAgent
@@ -190,6 +195,14 @@ def trace_tool_call(
     else:
       span.set_attribute(ERROR_TYPE, type(error).__name__)
 
+  # Special case for client side association with a remote tool call
+  if (
+      tool.custom_metadata
+      and GCP_MCP_SERVER_DESTINATION_ID in tool.custom_metadata
+  ):
+    destination_id = tool.custom_metadata[GCP_MCP_SERVER_DESTINATION_ID]
+    span.set_attribute(GCP_MCP_SERVER_DESTINATION_ID, destination_id)
+
   # Setting empty llm request and response (as UI expect these) while not
   # applicable for tool_response.
   span.set_attribute('gcp.vertex.agent.llm_request', '{}')

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',
+]