google-adk 1.7.0__py3-none-any.whl → 1.8.0__py3-none-any.whl

google/adk/tools/computer_use/base_computer.py

@@ -0,0 +1,265 @@
+# Copyright 2025 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 __future__ import annotations
+
+import abc
+from enum import Enum
+from typing import Literal
+from typing import Optional
+
+import pydantic
+
+from ...utils.feature_decorator import experimental
+
+
+@experimental
+class ComputerEnvironment(str, Enum):
+  """Case insensitive enum for computer environments."""
+
+  ENVIRONMENT_UNSPECIFIED = "ENVIRONMENT_UNSPECIFIED"
+  """Defaults to browser."""
+  ENVIRONMENT_BROWSER = "ENVIRONMENT_BROWSER"
+  """Operates in a web browser."""
+
+
+@experimental
+class ComputerState(pydantic.BaseModel):
+  """Represents the current state of the computer environment.
+
+  Attributes:
+    screenshot: The screenshot in PNG format as bytes.
+    url: The current URL of the webpage being displayed.
+  """
+
+  screenshot: bytes = pydantic.Field(
+      default=None, description="Screenshot in PNG format"
+  )
+  url: Optional[str] = pydantic.Field(
+      default=None, description="Current webpage URL"
+  )
+
+
+@experimental
+class BaseComputer(abc.ABC):
+  """async defines an interface for computer environments.
+
+  This abstract base class async defines the standard interface for controlling
+  computer environments, including web browsers and other interactive systems.
+  """
+
+  @abc.abstractmethod
+  async def screen_size(self) -> tuple[int, int]:
+    """Returns the screen size of the environment.
+
+    Returns:
+      A tuple of (width, height) in pixels.
+    """
+
+  @abc.abstractmethod
+  async def open_web_browser(self) -> ComputerState:
+    """Opens the web browser.
+
+    Returns:
+      The current state after opening the browser.
+    """
+
+  @abc.abstractmethod
+  async def click_at(self, x: int, y: int) -> ComputerState:
+    """Clicks at a specific x, y coordinate on the webpage.
+
+    The 'x' and 'y' values are absolute values, scaled to the height and width of the screen.
+
+    Args:
+      x: The x-coordinate to click at.
+      y: The y-coordinate to click at.
+
+    Returns:
+      The current state after clicking.
+    """
+
+  @abc.abstractmethod
+  async def hover_at(self, x: int, y: int) -> ComputerState:
+    """Hovers at a specific x, y coordinate on the webpage.
+
+    May be used to explore sub-menus that appear on hover.
+    The 'x' and 'y' values are absolute values, scaled to the height and width of the screen.
+
+    Args:
+      x: The x-coordinate to hover at.
+      y: The y-coordinate to hover at.
+
+    Returns:
+      The current state after hovering.
+    """
+
+  @abc.abstractmethod
+  async def type_text_at(
+      self,
+      x: int,
+      y: int,
+      text: str,
+      press_enter: bool = True,
+      clear_before_typing: bool = True,
+  ) -> ComputerState:
+    """Types text at a specific x, y coordinate.
+
+    The system automatically presses ENTER after typing. To disable this, set `press_enter` to False.
+    The system automatically clears any existing content before typing the specified `text`. To disable this, set `clear_before_typing` to False.
+    The 'x' and 'y' values are absolute values, scaled to the height and width of the screen.
+
+    Args:
+      x: The x-coordinate to type at.
+      y: The y-coordinate to type at.
+      text: The text to type.
+      press_enter: Whether to press ENTER after typing.
+      clear_before_typing: Whether to clear existing content before typing.
+
+    Returns:
+      The current state after typing.
+    """
+
+  @abc.abstractmethod
+  async def scroll_document(
+      self, direction: Literal["up", "down", "left", "right"]
+  ) -> ComputerState:
+    """Scrolls the entire webpage "up", "down", "left" or "right" based on direction.
+
+    Args:
+      direction: The direction to scroll.
+
+    Returns:
+      The current state after scrolling.
+    """
+
+  @abc.abstractmethod
+  async def scroll_at(
+      self,
+      x: int,
+      y: int,
+      direction: Literal["up", "down", "left", "right"],
+      magnitude: int,
+  ) -> ComputerState:
+    """Scrolls up, down, right, or left at a x, y coordinate by magnitude.
+
+    The 'x' and 'y' values are absolute values, scaled to the height and width of the screen.
+
+    Args:
+      x: The x-coordinate to scroll at.
+      y: The y-coordinate to scroll at.
+      direction: The direction to scroll.
+      magnitude: The amount to scroll.
+
+    Returns:
+      The current state after scrolling.
+    """
+
+  @abc.abstractmethod
+  async def wait(self, seconds: int) -> ComputerState:
+    """Waits for n seconds to allow unfinished webpage processes to complete.
+
+    Args:
+      seconds: The number of seconds to wait.
+
+    Returns:
+      The current state after waiting.
+    """
+
+  @abc.abstractmethod
+  async def go_back(self) -> ComputerState:
+    """Navigates back to the previous webpage in the browser history.
+
+    Returns:
+      The current state after navigating back.
+    """
+
+  @abc.abstractmethod
+  async def go_forward(self) -> ComputerState:
+    """Navigates forward to the next webpage in the browser history.
+
+    Returns:
+      The current state after navigating forward.
+    """
+
+  @abc.abstractmethod
+  async def search(self) -> ComputerState:
+    """Directly jumps to a search engine home page.
+
+    Used when you need to start with a search. For example, this is used when
+    the current website doesn't have the information needed or because a new
+    task is being started.
+
+    Returns:
+      The current state after navigating to search.
+    """
+
+  @abc.abstractmethod
+  async def navigate(self, url: str) -> ComputerState:
+    """Navigates directly to a specified URL.
+
+    Args:
+      url: The URL to navigate to.
+
+    Returns:
+      The current state after navigation.
+    """
+
+  @abc.abstractmethod
+  async def key_combination(self, keys: list[str]) -> ComputerState:
+    """Presses keyboard keys and combinations, such as "control+c" or "enter".
+
+    Args:
+      keys: List of keys to press in combination.
+
+    Returns:
+      The current state after key press.
+    """
+
+  @abc.abstractmethod
+  async def drag_and_drop(
+      self, x: int, y: int, destination_x: int, destination_y: int
+  ) -> ComputerState:
+    """Drag and drop an element from a x, y coordinate to a destination destination_y, destination_x coordinate.
+
+    The 'x', 'y', 'destination_y' and 'destination_x' values are absolute values, scaled to the height and width of the screen.
+
+    Args:
+      x: The x-coordinate to start dragging from.
+      y: The y-coordinate to start dragging from.
+      destination_x: The x-coordinate to drop at.
+      destination_y: The y-coordinate to drop at.
+
+    Returns:
+      The current state after drag and drop.
+    """
+
+  @abc.abstractmethod
+  async def current_state(self) -> ComputerState:
+    """Returns the current state of the current webpage.
+
+    Returns:
+      The current environment state.
+    """
+
+  async def initialize(self) -> None:
+    """Initialize the computer."""
+    pass
+
+  async def close(self) -> None:
+    """Cleanup resource of the computer."""
+    pass
+
+  @abc.abstractmethod
+  async def environment(self) -> ComputerEnvironment:
+    """Returns the environment of the computer."""

google/adk/tools/computer_use/computer_use_tool.py

@@ -0,0 +1,166 @@
+# Copyright 2025 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 __future__ import annotations
+
+import base64
+import logging
+from typing import Any
+from typing import Callable
+
+from google.genai import types
+from typing_extensions import override
+
+from ...models.llm_request import LlmRequest
+from ...utils.feature_decorator import experimental
+from ..function_tool import FunctionTool
+from ..tool_context import ToolContext
+from .base_computer import ComputerState
+
+logger = logging.getLogger("google_adk." + __name__)
+
+
+@experimental
+class ComputerUseTool(FunctionTool):
+  """A tool that wraps computer control functions for use with LLMs.
+
+  This tool automatically normalizes coordinates from a virtual coordinate space
+  (by default 1000x1000) to the actual screen size. This allows LLMs to work
+  with a consistent coordinate system regardless of the actual screen dimensions,
+  making their output more predictable and easier to handle.
+  """
+
+  def __init__(
+      self,
+      *,
+      func: Callable[..., Any],
+      screen_size: tuple[int, int],
+      virtual_screen_size: tuple[int, int] = (1000, 1000),
+  ):
+    """Initialize the ComputerUseTool.
+
+    Args:
+      func: The computer control function to wrap.
+      screen_size: The actual screen size as (width, height) in pixels.
+        This represents the real dimensions of the target screen/display.
+      virtual_screen_size: The virtual coordinate space dimensions as (width, height)
+        that the LLM uses to specify coordinates. Coordinates from the LLM are
+        automatically normalized from this virtual space to the actual screen_size.
+        Default is (1000, 1000), meaning the LLM thinks it's working with a
+        1000x1000 pixel screen regardless of the actual screen dimensions.
+
+    Raises:
+      ValueError: If screen_size or virtual_screen_size is not a valid tuple
+        of positive integers.
+    """
+    super().__init__(func=func)
+    self._screen_size = screen_size
+    self._coordinate_space = virtual_screen_size
+
+    # Validate screen size
+    if not isinstance(screen_size, tuple) or len(screen_size) != 2:
+      raise ValueError("screen_size must be a tuple of (width, height)")
+    if screen_size[0] <= 0 or screen_size[1] <= 0:
+      raise ValueError("screen_size dimensions must be positive")
+
+    # Validate virtual screen size
+    if (
+        not isinstance(virtual_screen_size, tuple)
+        or len(virtual_screen_size) != 2
+    ):
+      raise ValueError("virtual_screen_size must be a tuple of (width, height)")
+    if virtual_screen_size[0] <= 0 or virtual_screen_size[1] <= 0:
+      raise ValueError("virtual_screen_size dimensions must be positive")
+
+  def _normalize_x(self, x: int) -> int:
+    """Normalize x coordinate from virtual screen space to actual screen width."""
+    if not isinstance(x, (int, float)):
+      raise ValueError(f"x coordinate must be numeric, got {type(x)}")
+
+    normalized = int(x / self._coordinate_space[0] * self._screen_size[0])
+    # Clamp to screen bounds
+    return max(0, min(normalized, self._screen_size[0] - 1))
+
+  def _normalize_y(self, y: int) -> int:
+    """Normalize y coordinate from virtual screen space to actual screen height."""
+    if not isinstance(y, (int, float)):
+      raise ValueError(f"y coordinate must be numeric, got {type(y)}")
+
+    normalized = int(y / self._coordinate_space[1] * self._screen_size[1])
+    # Clamp to screen bounds
+    return max(0, min(normalized, self._screen_size[1] - 1))
+
+  @override
+  async def run_async(
+      self, *, args: dict[str, Any], tool_context: ToolContext
+  ) -> Any:
+    """Run the computer control function with normalized coordinates."""
+
+    try:
+      # Normalize coordinates if present
+      if "x" in args:
+        original_x = args["x"]
+        args["x"] = self._normalize_x(args["x"])
+        logger.debug("Normalized x: %s -> %s", original_x, args["x"])
+
+      if "y" in args:
+        original_y = args["y"]
+        args["y"] = self._normalize_y(args["y"])
+        logger.debug("Normalized y: %s -> %s", original_y, args["y"])
+
+      # Handle destination coordinates for drag and drop
+      if "destination_x" in args:
+        original_dest_x = args["destination_x"]
+        args["destination_x"] = self._normalize_x(args["destination_x"])
+        logger.debug(
+            "Normalized destination_x: %s -> %s",
+            original_dest_x,
+            args["destination_x"],
+        )
+
+      if "destination_y" in args:
+        original_dest_y = args["destination_y"]
+        args["destination_y"] = self._normalize_y(args["destination_y"])
+        logger.debug(
+            "Normalized destination_y: %s -> %s",
+            original_dest_y,
+            args["destination_y"],
+        )
+
+      # Execute the actual computer control function
+      result = await super().run_async(args=args, tool_context=tool_context)
+
+      # Process the result if it's an EnvironmentState
+      if isinstance(result, ComputerState):
+        return {
+            "image": {
+                "mimetype": "image/png",
+                "data": base64.b64encode(result.screenshot).decode("utf-8"),
+            },
+            "url": result.url,
+        }
+
+      return result
+
+    except Exception as e:
+      logger.error("Error in ComputerUseTool.run_async: %s", e)
+      raise
+
+  @override
+  async def process_llm_request(
+      self, *, tool_context: ToolContext, llm_request: LlmRequest
+  ) -> None:
+    """ComputerUseToolset will add this tool to the LLM request and add computer
+    use configuration to the LLM request."""
+    pass

google/adk/tools/computer_use/computer_use_toolset.py

@@ -0,0 +1,220 @@
+# Copyright 2025 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 __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any
+from typing import Callable
+from typing import Optional
+from typing import Union
+
+from google.genai import types
+from typing_extensions import override
+
+from ...agents.readonly_context import ReadonlyContext
+from ...models.llm_request import LlmRequest
+from ...utils.feature_decorator import experimental
+from ..base_toolset import BaseToolset
+from ..tool_context import ToolContext
+from .base_computer import BaseComputer
+from .computer_use_tool import ComputerUseTool
+
+# Methods that should be excluded when creating tools from BaseComputer methods
+EXCLUDED_METHODS = {"screen_size", "environment", "close"}
+
+logger = logging.getLogger("google_adk." + __name__)
+
+
+@experimental
+class ComputerUseToolset(BaseToolset):
+
+  def __init__(
+      self,
+      *,
+      computer: BaseComputer,
+  ):
+    super().__init__()
+    self._computer = computer
+    self._initialized = False
+    self._tools = None
+
+  async def _ensure_initialized(self) -> None:
+    if not self._initialized:
+      await self._computer.initialize()
+      self._initialized = True
+
+  @staticmethod
+  async def adapt_computer_use_tool(
+      method_name: str,
+      adapter_func: Union[
+          Callable[[Callable[..., Any]], Callable[..., Any]],
+          Callable[[Callable[..., Any]], Any],
+      ],
+      llm_request: LlmRequest,
+  ) -> None:
+    """Adapt a computer use tool by replacing it with a modified version.
+
+    Args:
+      method_name: The name of the method (of BaseComputer class) to adapt (e.g. 'wait').
+      adapter_func: A function that accepts existing computer use async function and returns a new computer use async function.
+        Can be either sync or async function. The name of the returned function will be used as the new tool name.
+      llm_request: The LLM request containing the tools dictionary.
+    """
+    # Validate that the method is a valid BaseComputer method
+    if method_name in EXCLUDED_METHODS:
+      logger.warning(
+          "Method %s is not a valid BaseComputer method", method_name
+      )
+      return
+
+    # Check if it's a method defined in BaseComputer class
+    attr = getattr(BaseComputer, method_name, None)
+    if attr is None or not callable(attr):
+      logger.warning(
+          "Method %s is not a valid BaseComputer method", method_name
+      )
+      return
+
+    if method_name not in llm_request.tools_dict:
+      logger.warning("Method %s not found in tools_dict", method_name)
+      return
+
+    original_tool = llm_request.tools_dict[method_name]
+
+    # Create the adapted function using the adapter
+    # Handle both sync and async adapter functions
+    if asyncio.iscoroutinefunction(adapter_func):
+      # If adapter_func is async, await it to get the adapted function
+      adapted_func = await adapter_func(original_tool.func)
+    else:
+      # If adapter_func is sync, call it directly
+      adapted_func = adapter_func(original_tool.func)
+
+    # Get the name from the adapted function
+    new_method_name = adapted_func.__name__
+
+    # Create a new ComputerUseTool with the adapted function
+    adapted_tool = ComputerUseTool(
+        func=adapted_func,
+        screen_size=original_tool._screen_size,
+        virtual_screen_size=original_tool._coordinate_space,
+    )
+
+    # Add the adapted tool and remove the original
+    llm_request.tools_dict[new_method_name] = adapted_tool
+    del llm_request.tools_dict[method_name]
+
+    logger.debug(
+        "Adapted tool %s to %s with adapter function",
+        method_name,
+        new_method_name,
+    )
+
+  @override
+  async def get_tools(
+      self,
+      readonly_context: Optional[ReadonlyContext] = None,
+  ) -> list[ComputerUseTool]:
+    if self._tools:
+      return self._tools
+    await self._ensure_initialized()
+    # Get screen size for tool configuration
+    screen_size = await self._computer.screen_size()
+
+    # Get all methods defined in Computer abstract base class, excluding specified methods
+    computer_methods = []
+
+    # Get all methods defined in the Computer ABC interface
+    for method_name in dir(BaseComputer):
+      # Skip private methods (starting with underscore)
+      if method_name.startswith("_"):
+        continue
+
+      # Skip excluded methods
+      if method_name in EXCLUDED_METHODS:
+        continue
+
+      # Check if it's a method defined in Computer class
+      attr = getattr(BaseComputer, method_name, None)
+      if attr is not None and callable(attr):
+        # Get the corresponding method from the concrete instance
+        instance_method = getattr(self._computer, method_name)
+        computer_methods.append(instance_method)
+
+    # Create ComputerUseTool instances for each method
+
+    self._tools = [
+        ComputerUseTool(
+            func=method,
+            screen_size=screen_size,
+        )
+        for method in computer_methods
+    ]
+    return self._tools
+
+  @override
+  async def close(self) -> None:
+    await self._computer.close()
+
+  @override
+  async def process_llm_request(
+      self, *, tool_context: ToolContext, llm_request: LlmRequest
+  ) -> None:
+    """Add its tools to the LLM request and add computer
+    use configuration to the LLM request."""
+    try:
+
+      # Add this tool to the tools dictionary
+      if not self._tools:
+        await self.get_tools()
+
+      for tool in self._tools:
+        llm_request.tools_dict[tool.name] = tool
+
+      # Initialize config if needed
+      llm_request.config = llm_request.config or types.GenerateContentConfig()
+      llm_request.config.tools = llm_request.config.tools or []
+
+      # Check if computer use is already configured
+      for tool in llm_request.config.tools:
+        if (
+            isinstance(tool, (types.Tool, types.ToolDict))
+            and hasattr(tool, "computer_use")
+            and tool.computer_use
+        ):
+          logger.debug("Computer use already configured in LLM request")
+          return
+
+      # Add computer use tool configuration
+      computer_environment = await self._computer.environment()
+      environment = getattr(
+          types.Environment,
+          computer_environment.name,
+          types.Environment.ENVIRONMENT_BROWSER,
+      )
+      llm_request.config.tools.append(
+          types.Tool(
+              computer_use=types.ToolComputerUse(environment=environment)
+          )
+      )
+      logger.debug(
+          "Added computer use tool with environment: %s",
+          environment,
+      )
+
+    except Exception as e:
+      logger.error("Error in ComputerUseToolset.process_llm_request: %s", e)
+      raise

google/adk/tools/exit_loop_tool.py

@@ -21,3 +21,4 @@ def exit_loop(tool_context: ToolContext):
   Call this function only when you are instructed to do so.
   """
   tool_context.actions.escalate = True
+  tool_context.actions.skip_summarization = True

google/adk/tools/langchain_tool.py

@@ -59,15 +59,26 @@ class LangchainTool(FunctionTool):
       name: Optional[str] = None,
       description: Optional[str] = None,
   ):
-    # Check if the tool has a 'run' method
     if not hasattr(tool, 'run') and not hasattr(tool, '_run'):
-      raise ValueError("Langchain tool must have a 'run' or '_run' method")
+      raise ValueError(
+          "Tool must be a Langchain tool, have a 'run' or '_run' method."
+      )
 
     # Determine which function to use
     if isinstance(tool, StructuredTool):
       func = tool.func
-    else:
+      # For async tools, func might be None but coroutine exists
+      if func is None and hasattr(tool, 'coroutine') and tool.coroutine:
+        func = tool.coroutine
+    elif hasattr(tool, '_run') or hasattr(tool, 'run'):
       func = tool._run if hasattr(tool, '_run') else tool.run
+    else:
+      raise ValueError(
+          "This is not supported. Tool must be a Langchain tool, have a 'run'"
+          " or '_run' method. The tool is: ",
+          type(tool),
+      )
+
     super().__init__(func)
     # run_manager is a special parameter for langchain tool
     self._ignore_params.append('run_manager')

google/adk/tools/openapi_tool/openapi_spec_parser/openapi_spec_parser.py

@@ -111,6 +111,11 @@ class OpenApiSpecParser:
         if operation_dict is None:
           continue
 
+        # Append path-level parameters
+        operation_dict["parameters"] = operation_dict.get(
+            "parameters", []
+        ) + path_item.get("parameters", [])
+
         # If operation ID is missing, assign an operation id based on path
         # and method
         if "operationId" not in operation_dict: