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

google/adk/tools/application_integration_tool/application_integration_toolset.py

@@ -12,6 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from __future__ import annotations
+
 import logging
 from typing import List
 from typing import Optional
@@ -42,43 +44,39 @@ logger = logging.getLogger("google_adk." + __name__)
 # TODO(cheliu): Apply a common toolset interface
 class ApplicationIntegrationToolset(BaseToolset):
   """ApplicationIntegrationToolset generates tools from a given Application
-
   Integration or Integration Connector resource.
-  Example Usage:
-  ```
-  # Get all available tools for an integration with api trigger
-  application_integration_toolset = ApplicationIntegrationToolset(
 
-      project="test-project",
-      location="us-central1"
-      integration="test-integration",
-      triggers=["api_trigger/test_trigger"],
-      service_account_credentials={...},
-  )
+  Example Usage::
 
-  # Get all available tools for a connection using entity operations and
-  # actions
-  # Note: Find the list of supported entity operations and actions for a
-  connection
-  # using integration connector apis:
-  #
-  https://cloud.google.com/integration-connectors/docs/reference/rest/v1/projects.locations.connections.connectionSchemaMetadata
-  application_integration_toolset = ApplicationIntegrationToolset(
-      project="test-project",
-      location="us-central1"
-      connection="test-connection",
-      entity_operations=["EntityId1": ["LIST","CREATE"], "EntityId2": []],
-      #empty list for actions means all operations on the entity are supported
-      actions=["action1"],
-      service_account_credentials={...},
-  )
+    # Get all available tools for an integration with api trigger
+    application_integration_toolset = ApplicationIntegrationToolset(
+        project="test-project",
+        location="us-central1"
+        integration="test-integration",
+        triggers=["api_trigger/test_trigger"],
+        service_account_credentials={...},
+    )
+
+    # Get all available tools for a connection using entity operations and
+    # actions
+    # Note: Find the list of supported entity operations and actions for a
+    # connection using integration connector apis:
+    # https://cloud.google.com/integration-connectors/docs/reference/rest/v1/projects.locations.connections.connectionSchemaMetadata
+    application_integration_toolset = ApplicationIntegrationToolset(
+        project="test-project",
+        location="us-central1"
+        connection="test-connection",
+        entity_operations=["EntityId1": ["LIST","CREATE"], "EntityId2": []],
+        #empty list for actions means all operations on the entity are supported
+        actions=["action1"],
+        service_account_credentials={...},
+    )
 
-  # Feed the toolset to agent
-  agent = LlmAgent(tools=[
-      ...,
-      application_integration_toolset,
-  ])
-  ```
+    # Feed the toolset to agent
+    agent = LlmAgent(tools=[
+        ...,
+        application_integration_toolset,
+    ])
   """
 
   def __init__(
@@ -122,11 +120,11 @@ class ApplicationIntegrationToolset(BaseToolset):
 
     Raises:
         ValueError: If none of the following conditions are met:
-            - `integration` is provided.
-            - `connection` is provided and at least one of `entity_operations`
-              or `actions` is provided.
+          - ``integration`` is provided.
+          - ``connection`` is provided and at least one of ``entity_operations``
+            or ``actions`` is provided.
         Exception: If there is an error during the initialization of the
-            integration or connection client.
+          integration or connection client.
     """
     super().__init__(tool_filter=tool_filter)
     self.project = project

google/adk/tools/application_integration_tool/integration_connector_tool.py

@@ -45,13 +45,12 @@ class IntegrationConnectorTool(BaseTool):
   * Generates request params and body
   * Attaches auth credentials to API call.
 
-  Example:
-  ```
+  Example::
+
     # Each API operation in the spec will be turned into its own tool
     # Name of the tool is the operationId of that operation, in snake case
     operations = OperationGenerator().parse(openapi_spec_dict)
     tool = [RestApiTool.from_parsed_operation(o) for o in operations]
-  ```
   """
 
   EXCLUDE_FIELDS = [

google/adk/tools/base_tool.py

@@ -49,11 +49,11 @@ class BaseTool(ABC):
   def _get_declaration(self) -> Optional[types.FunctionDeclaration]:
     """Gets the OpenAPI specification of this tool in the form of a FunctionDeclaration.
 
-    NOTE
-    - Required if subclass uses the default implementation of
-      `process_llm_request` to add function declaration to LLM request.
-    - Otherwise, can be skipped, e.g. for a built-in GoogleSearch tool for
-      Gemini.
+    NOTE:
+      - Required if subclass uses the default implementation of
+        `process_llm_request` to add function declaration to LLM request.
+      - Otherwise, can be skipped, e.g. for a built-in GoogleSearch tool for
+        Gemini.
 
     Returns:
       The FunctionDeclaration of this tool, or None if it doesn't need to be
@@ -66,10 +66,10 @@ class BaseTool(ABC):
   ) -> Any:
     """Runs the tool with the given arguments and context.
 
-    NOTE
-    - Required if this tool needs to run at the client side.
-    - Otherwise, can be skipped, e.g. for a built-in GoogleSearch tool for
-      Gemini.
+    NOTE:
+      - Required if this tool needs to run at the client side.
+      - Otherwise, can be skipped, e.g. for a built-in GoogleSearch tool for
+        Gemini.
 
     Args:
       args: The LLM-filled arguments.

google/adk/tools/base_toolset.py

@@ -12,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from __future__ import annotations
 
 from abc import ABC
 from abc import abstractmethod
@@ -64,7 +65,7 @@ class BaseToolset(ABC):
     """Return all tools in the toolset based on the provided context.
 
     Args:
-      readony_context (ReadonlyContext, optional): Context used to filter tools
+      readonly_context (ReadonlyContext, optional): Context used to filter tools
         available to the agent. If None, all tools in the toolset are returned.
 
     Returns:
@@ -75,10 +76,11 @@ class BaseToolset(ABC):
   async def close(self) -> None:
     """Performs cleanup and releases resources held by the toolset.
 
-    NOTE: This method is invoked, for example, at the end of an agent server's
-    lifecycle or when the toolset is no longer needed. Implementations
-    should ensure that any open connections, files, or other managed
-    resources are properly released to prevent leaks.
+    NOTE:
+      This method is invoked, for example, at the end of an agent server's
+      lifecycle or when the toolset is no longer needed. Implementations
+      should ensure that any open connections, files, or other managed
+      resources are properly released to prevent leaks.
     """
 
   def _is_tool_selected(

google/adk/tools/bigquery/__init__.py

@@ -20,11 +20,11 @@ definition. The rationales to have customized tool are:
 
 1. BigQuery APIs have functions overlaps and LLM can't tell what tool to use
 2. BigQuery APIs have a lot of parameters with some rarely used, which are not
- LLM-friendly
+   LLM-friendly
 3. We want to provide more high-level tools like forecasting, RAG, segmentation,
- etc.
+   etc.
 4. We want to provide extra access guardrails in those tools. For example,
- execute_sql can't arbitrarily mutate existing data.
+   execute_sql can't arbitrarily mutate existing data.
 """
 
 from .bigquery_credentials import BigQueryCredentialsConfig

google/adk/tools/enterprise_search_tool.py

@@ -19,6 +19,8 @@ from typing import TYPE_CHECKING
 from google.genai import types
 from typing_extensions import override
 
+from ..utils.model_name_utils import is_gemini_1_model
+from ..utils.model_name_utils import is_gemini_model
 from .base_tool import BaseTool
 from .tool_context import ToolContext
 
@@ -47,8 +49,8 @@ class EnterpriseWebSearchTool(BaseTool):
       tool_context: ToolContext,
       llm_request: LlmRequest,
   ) -> None:
-    if llm_request.model and 'gemini-' in llm_request.model:
-      if 'gemini-1' in llm_request.model and llm_request.config.tools:
+    if is_gemini_model(llm_request.model):
+      if is_gemini_1_model(llm_request.model) and llm_request.config.tools:
         raise ValueError(
             'Enterprise web search tool can not be used with other tools in'
             ' Gemini 1.x.'

google/adk/tools/google_api_tool/google_api_tool.py

@@ -12,6 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from __future__ import annotations
+
 from typing import Any
 from typing import Dict
 from typing import Optional
@@ -23,7 +25,9 @@ from .. import BaseTool
 from ...auth import AuthCredential
 from ...auth import AuthCredentialTypes
 from ...auth import OAuth2Auth
+from ...auth.auth_credential import ServiceAccount
 from ..openapi_tool import RestApiTool
+from ..openapi_tool.auth.auth_helpers import service_account_scheme_credential
 from ..tool_context import ToolContext
 
 
@@ -34,6 +38,7 @@ class GoogleApiTool(BaseTool):
       rest_api_tool: RestApiTool,
       client_id: Optional[str] = None,
       client_secret: Optional[str] = None,
+      service_account: Optional[ServiceAccount] = None,
   ):
     super().__init__(
         name=rest_api_tool.name,
@@ -41,7 +46,10 @@ class GoogleApiTool(BaseTool):
         is_long_running=rest_api_tool.is_long_running,
     )
     self._rest_api_tool = rest_api_tool
-    self.configure_auth(client_id, client_secret)
+    if service_account is not None:
+      self.configure_sa_auth(service_account)
+    else:
+      self.configure_auth(client_id, client_secret)
 
   @override
   def _get_declaration(self) -> FunctionDeclaration:
@@ -63,3 +71,10 @@ class GoogleApiTool(BaseTool):
             client_secret=client_secret,
         ),
     )
+
+  def configure_sa_auth(self, service_account: ServiceAccount):
+    auth_scheme, auth_credential = service_account_scheme_credential(
+        service_account
+    )
+    self._rest_api_tool.auth_scheme = auth_scheme
+    self._rest_api_tool.auth_credential = auth_credential

google/adk/tools/google_api_tool/google_api_toolset.py

@@ -14,18 +14,15 @@
 
 from __future__ import annotations
 
-import inspect
-import os
-from typing import Any
 from typing import List
 from typing import Optional
-from typing import Type
 from typing import Union
 
 from typing_extensions import override
 
 from ...agents.readonly_context import ReadonlyContext
 from ...auth import OpenIdConnectWithConfig
+from ...auth.auth_credential import ServiceAccount
 from ...tools.base_toolset import BaseToolset
 from ...tools.base_toolset import ToolPredicate
 from ..openapi_tool import OpenAPIToolset
@@ -48,11 +45,13 @@ class GoogleApiToolset(BaseToolset):
       client_id: Optional[str] = None,
       client_secret: Optional[str] = None,
       tool_filter: Optional[Union[ToolPredicate, List[str]]] = None,
+      service_account: Optional[ServiceAccount] = None,
   ):
     self.api_name = api_name
     self.api_version = api_version
     self._client_id = client_id
     self._client_secret = client_secret
+    self._service_account = service_account
     self._openapi_toolset = self._load_toolset_with_oidc_auth()
     self.tool_filter = tool_filter
 
@@ -61,10 +60,10 @@ class GoogleApiToolset(BaseToolset):
       self, readonly_context: Optional[ReadonlyContext] = None
   ) -> List[GoogleApiTool]:
     """Get all tools in the toolset."""
-    tools = []
-
     return [
-        GoogleApiTool(tool, self._client_id, self._client_secret)
+        GoogleApiTool(
+            tool, self._client_id, self._client_secret, self._service_account
+        )
         for tool in await self._openapi_toolset.get_tools(readonly_context)
         if self._is_tool_selected(tool, readonly_context)
     ]
@@ -106,6 +105,9 @@ class GoogleApiToolset(BaseToolset):
     self._client_id = client_id
     self._client_secret = client_secret
 
+  def configure_sa_auth(self, service_account: ServiceAccount):
+    self._service_account = service_account
+
   @override
   async def close(self):
     if self._openapi_toolset:

google/adk/tools/google_api_tool/google_api_toolsets.py

@@ -12,12 +12,14 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from __future__ import annotations
 
 import logging
 from typing import List
 from typing import Optional
 from typing import Union
 
+from ...auth.auth_credential import ServiceAccount
 from ..base_toolset import ToolPredicate
 from .google_api_toolset import GoogleApiToolset
 
@@ -29,11 +31,14 @@ class BigQueryToolset(GoogleApiToolset):
 
   def __init__(
       self,
-      client_id: str = None,
-      client_secret: str = None,
+      client_id: Optional[str] = None,
+      client_secret: Optional[str] = None,
       tool_filter: Optional[Union[ToolPredicate, List[str]]] = None,
+      service_account: Optional[ServiceAccount] = None,
   ):
-    super().__init__("bigquery", "v2", client_id, client_secret, tool_filter)
+    super().__init__(
+        "bigquery", "v2", client_id, client_secret, tool_filter, service_account
+    )
 
 
 class CalendarToolset(GoogleApiToolset):
@@ -41,11 +46,14 @@ class CalendarToolset(GoogleApiToolset):
 
   def __init__(
       self,
-      client_id: str = None,
-      client_secret: str = None,
+      client_id: Optional[str] = None,
+      client_secret: Optional[str] = None,
       tool_filter: Optional[Union[ToolPredicate, List[str]]] = None,
+      service_account: Optional[ServiceAccount] = None,
   ):
-    super().__init__("calendar", "v3", client_id, client_secret, tool_filter)
+    super().__init__(
+        "calendar", "v3", client_id, client_secret, tool_filter, service_account
+    )
 
 
 class GmailToolset(GoogleApiToolset):
@@ -53,11 +61,14 @@ class GmailToolset(GoogleApiToolset):
 
   def __init__(
       self,
-      client_id: str = None,
-      client_secret: str = None,
+      client_id: Optional[str] = None,
+      client_secret: Optional[str] = None,
       tool_filter: Optional[Union[ToolPredicate, List[str]]] = None,
+      service_account: Optional[ServiceAccount] = None,
   ):
-    super().__init__("gmail", "v1", client_id, client_secret, tool_filter)
+    super().__init__(
+        "gmail", "v1", client_id, client_secret, tool_filter, service_account
+    )
 
 
 class YoutubeToolset(GoogleApiToolset):
@@ -65,11 +76,14 @@ class YoutubeToolset(GoogleApiToolset):
 
   def __init__(
       self,
-      client_id: str = None,
-      client_secret: str = None,
+      client_id: Optional[str] = None,
+      client_secret: Optional[str] = None,
       tool_filter: Optional[Union[ToolPredicate, List[str]]] = None,
+      service_account: Optional[ServiceAccount] = None,
   ):
-    super().__init__("youtube", "v3", client_id, client_secret, tool_filter)
+    super().__init__(
+        "youtube", "v3", client_id, client_secret, tool_filter, service_account
+    )
 
 
 class SlidesToolset(GoogleApiToolset):
@@ -77,11 +91,14 @@ class SlidesToolset(GoogleApiToolset):
 
   def __init__(
       self,
-      client_id: str = None,
-      client_secret: str = None,
+      client_id: Optional[str] = None,
+      client_secret: Optional[str] = None,
       tool_filter: Optional[Union[ToolPredicate, List[str]]] = None,
+      service_account: Optional[ServiceAccount] = None,
   ):
-    super().__init__("slides", "v1", client_id, client_secret, tool_filter)
+    super().__init__(
+        "slides", "v1", client_id, client_secret, tool_filter, service_account
+    )
 
 
 class SheetsToolset(GoogleApiToolset):
@@ -89,9 +106,10 @@ class SheetsToolset(GoogleApiToolset):
 
   def __init__(
       self,
-      client_id: str = None,
-      client_secret: str = None,
+      client_id: Optional[str] = None,
+      client_secret: Optional[str] = None,
       tool_filter: Optional[Union[ToolPredicate, List[str]]] = None,
+      service_account: Optional[ServiceAccount] = None,
   ):
     super().__init__("sheets", "v4", client_id, client_secret, tool_filter)
 
@@ -101,8 +119,11 @@ class DocsToolset(GoogleApiToolset):
 
   def __init__(
       self,
-      client_id: str = None,
-      client_secret: str = None,
+      client_id: Optional[str] = None,
+      client_secret: Optional[str] = None,
       tool_filter: Optional[Union[ToolPredicate, List[str]]] = None,
+      service_account: Optional[ServiceAccount] = None,
   ):
-    super().__init__("docs", "v1", client_id, client_secret, tool_filter)
+    super().__init__(
+        "docs", "v1", client_id, client_secret, tool_filter, service_account
+    )

google/adk/tools/google_search_tool.py

@@ -19,6 +19,8 @@ from typing import TYPE_CHECKING
 from google.genai import types
 from typing_extensions import override
 
+from ..utils.model_name_utils import is_gemini_1_model
+from ..utils.model_name_utils import is_gemini_model
 from .base_tool import BaseTool
 from .tool_context import ToolContext
 
@@ -46,7 +48,7 @@ class GoogleSearchTool(BaseTool):
   ) -> None:
     llm_request.config = llm_request.config or types.GenerateContentConfig()
     llm_request.config.tools = llm_request.config.tools or []
-    if llm_request.model and 'gemini-1' in llm_request.model:
+    if is_gemini_1_model(llm_request.model):
       if llm_request.config.tools:
         raise ValueError(
             'Google search tool can not be used with other tools in Gemini 1.x.'
@@ -54,7 +56,7 @@ class GoogleSearchTool(BaseTool):
       llm_request.config.tools.append(
           types.Tool(google_search_retrieval=types.GoogleSearchRetrieval())
       )
-    elif llm_request.model and 'gemini-' in llm_request.model:
+    elif is_gemini_model(llm_request.model):
       llm_request.config.tools.append(
           types.Tool(google_search=types.GoogleSearch())
       )

google/adk/tools/langchain_tool.py

@@ -41,14 +41,13 @@ class LangchainTool(FunctionTool):
       name: Optional override for the tool's name
       description: Optional override for the tool's description
 
-  Examples:
-      ```python
+  Examples::
+
       from langchain.tools import DuckDuckGoSearchTool
       from google.genai.tools import LangchainTool
 
       search_tool = DuckDuckGoSearchTool()
       wrapped_tool = LangchainTool(search_tool)
-      ```
   """
 
   _langchain_tool: Union[BaseTool, object]

google/adk/tools/long_running_tool.py

@@ -12,7 +12,13 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from __future__ import annotations
+
 from typing import Callable
+from typing import Optional
+
+from google.genai import types
+from typing_extensions import override
 
 from .function_tool import FunctionTool
 
@@ -37,3 +43,18 @@ class LongRunningFunctionTool(FunctionTool):
   def __init__(self, func: Callable):
     super().__init__(func)
     self.is_long_running = True
+
+  @override
+  def _get_declaration(self) -> Optional[types.FunctionDeclaration]:
+    declaration = super()._get_declaration()
+    if declaration:
+      instruction = (
+          "\n\nNOTE: This is a long-running operation. Do not call this tool"
+          " again if it has already returned some intermediate or pending"
+          " status."
+      )
+      if declaration.description:
+        declaration.description += instruction
+      else:
+        declaration.description = instruction.lstrip()
+    return declaration

google/adk/tools/mcp_tool/mcp_toolset.py

@@ -61,28 +61,27 @@ class MCPToolset(BaseToolset):
   that can be used by an agent. It properly implements the BaseToolset
   interface for easy integration with the agent framework.
 
-  Usage:
-  ```python
-  toolset = MCPToolset(
-      connection_params=StdioServerParameters(
-          command='npx',
-          args=["-y", "@modelcontextprotocol/server-filesystem"],
-      ),
-      tool_filter=['read_file', 'list_directory']  # Optional: filter specific tools
-  )
-
-  # Use in an agent
-  agent = LlmAgent(
-      model='gemini-2.0-flash',
-      name='enterprise_assistant',
-      instruction='Help user accessing their file systems',
-      tools=[toolset],
-  )
-
-  # Cleanup is handled automatically by the agent framework
-  # But you can also manually close if needed:
-  # await toolset.close()
-  ```
+  Usage::
+
+    toolset = MCPToolset(
+        connection_params=StdioServerParameters(
+            command='npx',
+            args=["-y", "@modelcontextprotocol/server-filesystem"],
+        ),
+        tool_filter=['read_file', 'list_directory']  # Optional: filter specific tools
+    )
+
+    # Use in an agent
+    agent = LlmAgent(
+        model='gemini-2.0-flash',
+        name='enterprise_assistant',
+        instruction='Help user accessing their file systems',
+        tools=[toolset],
+    )
+
+    # Cleanup is handled automatically by the agent framework
+    # But you can also manually close if needed:
+    # await toolset.close()
   """
 
   def __init__(
@@ -103,12 +102,12 @@ class MCPToolset(BaseToolset):
 
     Args:
       connection_params: The connection parameters to the MCP server. Can be:
-        `StdioConnectionParams` for using local mcp server (e.g. using `npx` or
-        `python3`); or `SseConnectionParams` for a local/remote SSE server; or
-        `StreamableHTTPConnectionParams` for local/remote Streamable http
-        server. Note, `StdioServerParameters` is also supported for using local
-        mcp server (e.g. using `npx` or `python3` ), but it does not support
-        timeout, and we recommend to use `StdioConnectionParams` instead when
+        ``StdioConnectionParams`` for using local mcp server (e.g. using ``npx`` or
+        ``python3``); or ``SseConnectionParams`` for a local/remote SSE server; or
+        ``StreamableHTTPConnectionParams`` for local/remote Streamable http
+        server. Note, ``StdioServerParameters`` is also supported for using local
+        mcp server (e.g. using ``npx`` or ``python3`` ), but it does not support
+        timeout, and we recommend to use ``StdioConnectionParams`` instead when
         timeout is needed.
       tool_filter: Optional filter to select specific tools. Can be either: - A
         list of tool names to include - A ToolPredicate function for custom

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

@@ -12,6 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from __future__ import annotations
+
 import json
 import logging
 from typing import Any
@@ -39,8 +41,8 @@ logger = logging.getLogger("google_adk." + __name__)
 class OpenAPIToolset(BaseToolset):
   """Class for parsing OpenAPI spec into a list of RestApiTool.
 
-  Usage:
-  ```
+  Usage::
+
     # Initialize OpenAPI toolset from a spec string.
     openapi_toolset = OpenAPIToolset(spec_str=openapi_spec_str,
       spec_str_type="json")
@@ -55,7 +57,6 @@ class OpenAPIToolset(BaseToolset):
     agent = Agent(
       tools=[openapi_toolset.get_tool('tool_name')]
     )
-  ```
   """
 
   def __init__(
@@ -70,8 +71,8 @@ class OpenAPIToolset(BaseToolset):
   ):
     """Initializes the OpenAPIToolset.
 
-    Usage:
-    ```
+    Usage::
+
       # Initialize OpenAPI toolset from a spec string.
       openapi_toolset = OpenAPIToolset(spec_str=openapi_spec_str,
         spec_str_type="json")
@@ -86,7 +87,6 @@ class OpenAPIToolset(BaseToolset):
       agent = Agent(
         tools=[openapi_toolset.get_tool('tool_name')]
       )
-    ```
 
     Args:
       spec_dict: The OpenAPI spec dictionary. If provided, it will be used
@@ -96,10 +96,10 @@ class OpenAPIToolset(BaseToolset):
       spec_str_type: The type of the OpenAPI spec string. Can be "json" or
         "yaml".
       auth_scheme: The auth scheme to use for all tools. Use AuthScheme or use
-        helpers in `google.adk.tools.openapi_tool.auth.auth_helpers`
+        helpers in ``google.adk.tools.openapi_tool.auth.auth_helpers``
       auth_credential: The auth credential to use for all tools. Use
         AuthCredential or use helpers in
-        `google.adk.tools.openapi_tool.auth.auth_helpers`
+        ``google.adk.tools.openapi_tool.auth.auth_helpers``
       tool_filter: The filter used to filter the tools in the toolset. It can be
         either a tool predicate or a list of tool names of the tools to expose.
     """