google-adk 0.5.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

google/adk/tools/application_integration_tool/integration_connector_tool.py

@@ -12,21 +12,24 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-
 import logging
 from typing import Any
 from typing import Dict
 from typing import Optional
+from typing import Union
 
-from google.adk.tools.openapi_tool.openapi_spec_parser.rest_api_tool import RestApiTool
-from google.adk.tools.openapi_tool.openapi_spec_parser.rest_api_tool import to_gemini_schema
 from google.genai.types import FunctionDeclaration
 from typing_extensions import override
 
 from .. import BaseTool
+from ...auth.auth_credential import AuthCredential
+from ...auth.auth_schemes import AuthScheme
+from ..openapi_tool.openapi_spec_parser.rest_api_tool import RestApiTool
+from ..openapi_tool.openapi_spec_parser.rest_api_tool import to_gemini_schema
+from ..openapi_tool.openapi_spec_parser.tool_auth_handler import ToolAuthHandler
 from ..tool_context import ToolContext
 
-logger = logging.getLogger(__name__)
+logger = logging.getLogger('google_adk.' + __name__)
 
 
 class IntegrationConnectorTool(BaseTool):
@@ -56,6 +59,7 @@ class IntegrationConnectorTool(BaseTool):
       'entity',
       'operation',
       'action',
+      'dynamic_auth_config',
   ]
 
   OPTIONAL_FIELDS = [
@@ -75,6 +79,8 @@ class IntegrationConnectorTool(BaseTool):
       operation: str,
       action: str,
       rest_api_tool: RestApiTool,
+      auth_scheme: Optional[Union[AuthScheme, str]] = None,
+      auth_credential: Optional[Union[AuthCredential, str]] = None,
   ):
     """Initializes the ApplicationIntegrationTool.
 
@@ -101,18 +107,20 @@ class IntegrationConnectorTool(BaseTool):
         name=name,
         description=description,
     )
-    self.connection_name = connection_name
-    self.connection_host = connection_host
-    self.connection_service_name = connection_service_name
-    self.entity = entity
-    self.operation = operation
-    self.action = action
-    self.rest_api_tool = rest_api_tool
+    self._connection_name = connection_name
+    self._connection_host = connection_host
+    self._connection_service_name = connection_service_name
+    self._entity = entity
+    self._operation = operation
+    self._action = action
+    self._rest_api_tool = rest_api_tool
+    self._auth_scheme = auth_scheme
+    self._auth_credential = auth_credential
 
   @override
   def _get_declaration(self) -> FunctionDeclaration:
     """Returns the function declaration in the Gemini Schema format."""
-    schema_dict = self.rest_api_tool._operation_parser.get_json_schema()
+    schema_dict = self._rest_api_tool._operation_parser.get_json_schema()
     for field in self.EXCLUDE_FIELDS:
       if field in schema_dict['properties']:
         del schema_dict['properties'][field]
@@ -126,34 +134,69 @@ class IntegrationConnectorTool(BaseTool):
     )
     return function_decl
 
+  def _prepare_dynamic_euc(self, auth_credential: AuthCredential) -> str:
+    if (
+        auth_credential
+        and auth_credential.http
+        and auth_credential.http.credentials
+        and auth_credential.http.credentials.token
+    ):
+      return auth_credential.http.credentials.token
+    return None
+
   @override
   async def run_async(
       self, *, args: dict[str, Any], tool_context: Optional[ToolContext]
   ) -> Dict[str, Any]:
-    args['connection_name'] = self.connection_name
-    args['service_name'] = self.connection_service_name
-    args['host'] = self.connection_host
-    args['entity'] = self.entity
-    args['operation'] = self.operation
-    args['action'] = self.action
+
+    tool_auth_handler = ToolAuthHandler.from_tool_context(
+        tool_context, self._auth_scheme, self._auth_credential
+    )
+    auth_result = tool_auth_handler.prepare_auth_credentials()
+
+    if auth_result.state == 'pending':
+      return {
+          'pending': True,
+          'message': 'Needs your authorization to access your data.',
+      }
+
+    # Attach parameters from auth into main parameters list
+    if auth_result.auth_credential:
+      # Attach parameters from auth into main parameters list
+      auth_credential_token = self._prepare_dynamic_euc(
+          auth_result.auth_credential
+      )
+      if auth_credential_token:
+        args['dynamic_auth_config'] = {
+            'oauth2_auth_code_flow.access_token': auth_credential_token
+        }
+      else:
+        args['dynamic_auth_config'] = {'oauth2_auth_code_flow.access_token': {}}
+
+    args['connection_name'] = self._connection_name
+    args['service_name'] = self._connection_service_name
+    args['host'] = self._connection_host
+    args['entity'] = self._entity
+    args['operation'] = self._operation
+    args['action'] = self._action
     logger.info('Running tool: %s with args: %s', self.name, args)
-    return self.rest_api_tool.call(args=args, tool_context=tool_context)
+    return self._rest_api_tool.call(args=args, tool_context=tool_context)
 
   def __str__(self):
     return (
         f'ApplicationIntegrationTool(name="{self.name}",'
         f' description="{self.description}",'
-        f' connection_name="{self.connection_name}", entity="{self.entity}",'
-        f' operation="{self.operation}", action="{self.action}")'
+        f' connection_name="{self._connection_name}", entity="{self._entity}",'
+        f' operation="{self._operation}", action="{self._action}")'
     )
 
   def __repr__(self):
     return (
         f'ApplicationIntegrationTool(name="{self.name}",'
         f' description="{self.description}",'
-        f' connection_name="{self.connection_name}",'
-        f' connection_host="{self.connection_host}",'
-        f' connection_service_name="{self.connection_service_name}",'
-        f' entity="{self.entity}", operation="{self.operation}",'
-        f' action="{self.action}", rest_api_tool={repr(self.rest_api_tool)})'
+        f' connection_name="{self._connection_name}",'
+        f' connection_host="{self._connection_host}",'
+        f' connection_service_name="{self._connection_service_name}",'
+        f' entity="{self._entity}", operation="{self._operation}",'
+        f' action="{self._action}", rest_api_tool={repr(self._rest_api_tool)})'
     )

google/adk/tools/base_toolset.py

@@ -0,0 +1,96 @@
+# 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 abc import ABC
+from abc import abstractmethod
+from typing import List
+from typing import Optional
+from typing import Protocol
+from typing import runtime_checkable
+from typing import Union
+
+from ..agents.readonly_context import ReadonlyContext
+from .base_tool import BaseTool
+
+
+@runtime_checkable
+class ToolPredicate(Protocol):
+  """Base class for a predicate that defines the interface to decide whether a
+
+  tool should be exposed to LLM. Toolset implementer could consider whether to
+  accept such instance in the toolset's constructor and apply the predicate in
+  get_tools method.
+  """
+
+  def __call__(
+      self, tool: BaseTool, readonly_context: Optional[ReadonlyContext] = None
+  ) -> bool:
+    """Decide whether the passed-in tool should be exposed to LLM based on the
+
+    current context. True if the tool is usable by the LLM.
+
+    It's used to filter tools in the toolset.
+    """
+
+
+class BaseToolset(ABC):
+  """Base class for toolset.
+
+  A toolset is a collection of tools that can be used by an agent.
+  """
+
+  def __init__(
+      self, *, tool_filter: Optional[Union[ToolPredicate, List[str]]] = None
+  ):
+    self.tool_filter = tool_filter
+
+  @abstractmethod
+  async def get_tools(
+      self,
+      readonly_context: Optional[ReadonlyContext] = None,
+  ) -> list[BaseTool]:
+    """Return all tools in the toolset based on the provided context.
+
+    Args:
+      readony_context (ReadonlyContext, optional): Context used to filter tools
+        available to the agent. If None, all tools in the toolset are returned.
+
+    Returns:
+      list[BaseTool]: A list of tools available under the specified context.
+    """
+
+  @abstractmethod
+  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.
+    """
+
+  def _is_tool_selected(
+      self, tool: BaseTool, readonly_context: ReadonlyContext
+  ) -> bool:
+    if not self.tool_filter:
+      return True
+
+    if isinstance(self.tool_filter, ToolPredicate):
+      return self.tool_filter(tool, readonly_context)
+
+    if isinstance(self.tool_filter, list):
+      return tool.name in self.tool_filter
+
+    return False

google/adk/tools/bigquery/__init__.py

@@ -0,0 +1,28 @@
+# 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.
+
+"""BigQuery Tools. (Experimental)
+
+BigQuery Tools under this module are hand crafted and customized while the tools
+under google.adk.tools.google_api_tool are auto generated based on API
+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
+3. We want to provide more high-level tools like forecasting, RAG, segmentation,
+ etc.
+4. We want to provide extra access guardrails in those tools. For example,
+ execute_sql can't arbitrarily mutate existing data.
+"""

google/adk/tools/bigquery/bigquery_credentials.py

@@ -0,0 +1,216 @@
+# 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
+
+from typing import List
+from typing import Optional
+
+from fastapi.openapi.models import OAuth2
+from fastapi.openapi.models import OAuthFlowAuthorizationCode
+from fastapi.openapi.models import OAuthFlows
+from google.auth.exceptions import RefreshError
+from google.auth.transport.requests import Request
+from google.oauth2.credentials import Credentials
+from pydantic import BaseModel
+from pydantic import model_validator
+
+from ...auth import AuthConfig
+from ...auth import AuthCredential
+from ...auth import AuthCredentialTypes
+from ...auth import OAuth2Auth
+from ..tool_context import ToolContext
+
+BIGQUERY_TOKEN_CACHE_KEY = "bigquery_token_cache"
+
+
+class BigQueryCredentialsConfig(BaseModel):
+  """Configuration for Google API tools. (Experimental)"""
+
+  # Configure the model to allow arbitrary types like Credentials
+  model_config = {"arbitrary_types_allowed": True}
+
+  credentials: Optional[Credentials] = None
+  """the existing oauth credentials to use. If set,this credential will be used
+  for every end user, end users don't need to be involved in the oauthflow. This
+  field is mutually exclusive with client_id, client_secret and scopes.
+  Don't set this field unless you are sure this credential has the permission to
+  access every end user's data.
+
+  Example usage: when the agent is deployed in Google Cloud environment and
+  the service account (used as application default credentials) has access to
+  all the required BigQuery resource. Setting this credential to allow user to
+  access the BigQuery resource without end users going through oauth flow.
+
+  To get application default credential: `google.auth.default(...)`. See more
+  details in https://cloud.google.com/docs/authentication/application-default-credentials.
+
+  When the deployed environment cannot provide a pre-existing credential,
+  consider setting below client_id, client_secret and scope for end users to go
+  through oauth flow, so that agent can access the user data.
+  """
+  client_id: Optional[str] = None
+  """the oauth client ID to use."""
+  client_secret: Optional[str] = None
+  """the oauth client secret to use."""
+  scopes: Optional[List[str]] = None
+  """the scopes to use.
+  """
+
+  @model_validator(mode="after")
+  def __post_init__(self) -> BigQueryCredentialsConfig:
+    """Validate that either credentials or client ID/secret are provided."""
+    if not self.credentials and (not self.client_id or not self.client_secret):
+      raise ValueError(
+          "Must provide either credentials or client_id abd client_secret pair."
+      )
+    if self.credentials and (
+        self.client_id or self.client_secret or self.scopes
+    ):
+      raise ValueError(
+          "Cannot provide both existing credentials and"
+          " client_id/client_secret/scopes."
+      )
+
+    if self.credentials:
+      self.client_id = self.credentials.client_id
+      self.client_secret = self.credentials.client_secret
+      self.scopes = self.credentials.scopes
+    return self
+
+
+class BigQueryCredentialsManager:
+  """Manages Google API credentials with automatic refresh and OAuth flow handling.
+
+  This class centralizes credential management so multiple tools can share
+  the same authenticated session without duplicating OAuth logic.
+  """
+
+  def __init__(self, credentials_config: BigQueryCredentialsConfig):
+    """Initialize the credential manager.
+
+    Args:
+        credentials_config: Credentials containing client id and client secrete
+        or default credentials
+    """
+    self.credentials_config = credentials_config
+
+  async def get_valid_credentials(
+      self, tool_context: ToolContext
+  ) -> Optional[Credentials]:
+    """Get valid credentials, handling refresh and OAuth flow as needed.
+
+    Args:
+        tool_context: The tool context for OAuth flow and state management
+
+    Returns:
+        Valid Credentials object, or None if OAuth flow is needed
+    """
+    # First, try to get credentials from the tool context
+    creds_json = tool_context.state.get(BIGQUERY_TOKEN_CACHE_KEY, None)
+    creds = (
+        Credentials.from_authorized_user_info(
+            creds_json, self.credentials_config.scopes
+        )
+        if creds_json
+        else None
+    )
+
+    # If credentails are empty use the default credential
+    if not creds:
+      creds = self.credentials_config.credentials
+
+    # Check if we have valid credentials
+    if creds and creds.valid:
+      return creds
+
+    # Try to refresh expired credentials
+    if creds and creds.expired and creds.refresh_token:
+      try:
+        creds.refresh(Request())
+        if creds.valid:
+          # Cache the refreshed credentials
+          tool_context.state[BIGQUERY_TOKEN_CACHE_KEY] = creds.to_json()
+          return creds
+      except RefreshError:
+        # Refresh failed, need to re-authenticate
+        pass
+
+    # Need to perform OAuth flow
+    return await self._perform_oauth_flow(tool_context)
+
+  async def _perform_oauth_flow(
+      self, tool_context: ToolContext
+  ) -> Optional[Credentials]:
+    """Perform OAuth flow to get new credentials.
+
+    Args:
+        tool_context: The tool context for OAuth flow
+        required_scopes: Set of required OAuth scopes
+
+    Returns:
+        New Credentials object, or None if flow is in progress
+    """
+
+    # Create OAuth configuration
+    auth_scheme = OAuth2(
+        flows=OAuthFlows(
+            authorizationCode=OAuthFlowAuthorizationCode(
+                authorizationUrl="https://accounts.google.com/o/oauth2/auth",
+                tokenUrl="https://oauth2.googleapis.com/token",
+                scopes={
+                    scope: f"Access to {scope}"
+                    for scope in self.credentials_config.scopes
+                },
+            )
+        )
+    )
+
+    auth_credential = AuthCredential(
+        auth_type=AuthCredentialTypes.OAUTH2,
+        oauth2=OAuth2Auth(
+            client_id=self.credentials_config.client_id,
+            client_secret=self.credentials_config.client_secret,
+        ),
+    )
+
+    # Check if OAuth response is available
+    auth_response = tool_context.get_auth_response(
+        AuthConfig(auth_scheme=auth_scheme, raw_auth_credential=auth_credential)
+    )
+
+    if auth_response:
+      # OAuth flow completed, create credentials
+      creds = Credentials(
+          token=auth_response.oauth2.access_token,
+          refresh_token=auth_response.oauth2.refresh_token,
+          token_uri=auth_scheme.flows.authorizationCode.tokenUrl,
+          client_id=self.credentials_config.client_id,
+          client_secret=self.credentials_config.client_secret,
+          scopes=list(self.credentials_config.scopes),
+      )
+
+      # Cache the new credentials
+      tool_context.state[BIGQUERY_TOKEN_CACHE_KEY] = creds.to_json()
+
+      return creds
+    else:
+      # Request OAuth flow
+      tool_context.request_credential(
+          AuthConfig(
+              auth_scheme=auth_scheme,
+              raw_auth_credential=auth_credential,
+          )
+      )
+      return None

google/adk/tools/bigquery/bigquery_tool.py

@@ -0,0 +1,116 @@
+# 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.
+
+
+import inspect
+from typing import Any
+from typing import Callable
+from typing import Optional
+
+from google.oauth2.credentials import Credentials
+from typing_extensions import override
+
+from ..function_tool import FunctionTool
+from ..tool_context import ToolContext
+from .bigquery_credentials import BigQueryCredentialsConfig
+from .bigquery_credentials import BigQueryCredentialsManager
+
+
+class BigQueryTool(FunctionTool):
+  """GoogleApiTool class for tools that call Google APIs.
+
+  This class is for developers to handcraft customized Google API tools rather
+  than auto generate Google API tools based on API specs.
+
+  This class handles all the OAuth complexity, credential management,
+  and common Google API patterns so subclasses can focus on their
+  specific functionality.
+  """
+
+  def __init__(
+      self,
+      func: Callable[..., Any],
+      credentials: Optional[BigQueryCredentialsConfig] = None,
+  ):
+    """Initialize the Google API tool.
+
+    Args:
+        func: callable that impelments the tool's logic, can accept one
+          'credential" parameter
+        credentials: credentials used to call Google API. If None, then we don't
+          hanlde the auth logic
+    """
+    super().__init__(func=func)
+    self._ignore_params.append("credentials")
+    self.credentials_manager = (
+        BigQueryCredentialsManager(credentials) if credentials else None
+    )
+
+  @override
+  async def run_async(
+      self, *, args: dict[str, Any], tool_context: ToolContext
+  ) -> Any:
+    """Main entry point for tool execution with credential handling.
+
+    This method handles all the OAuth complexity and then delegates
+    to the subclass's run_async_with_credential method.
+    """
+    try:
+      # Get valid credentials
+      credentials = (
+          await self.credentials_manager.get_valid_credentials(tool_context)
+          if self.credentials_manager
+          else None
+      )
+
+      if credentials is None and self.credentials_manager:
+        # OAuth flow in progress
+        return (
+            "User authorization is required to access Google services for"
+            f" {self.name}. Please complete the authorization flow."
+        )
+
+      # Execute the tool's specific logic with valid credentials
+
+      return await self._run_async_with_credential(
+          credentials, args, tool_context
+      )
+
+    except Exception as ex:
+      return {
+          "status": "ERROR",
+          "error_details": str(ex),
+      }
+
+  async def _run_async_with_credential(
+      self,
+      credentials: Credentials,
+      args: dict[str, Any],
+      tool_context: ToolContext,
+  ) -> Any:
+    """Execute the tool's specific logic with valid credentials.
+
+    Args:
+        credentials: Valid Google OAuth credentials
+        args: Arguments passed to the tool
+        tool_context: Tool execution context
+
+    Returns:
+        The result of the tool execution
+    """
+    args_to_call = args.copy()
+    signature = inspect.signature(self.func)
+    if "credentials" in signature.parameters:
+      args_to_call["credentials"] = credentials
+    return await super().run_async(args=args_to_call, tool_context=tool_context)

google/adk/tools/{built_in_code_execution_tool.py → enterprise_search_tool.py}

@@ -26,16 +26,19 @@ if TYPE_CHECKING:
   from ..models import LlmRequest
 
 
-class BuiltInCodeExecutionTool(BaseTool):
-  """A built-in code execution tool that is automatically invoked by Gemini 2 models.
+class EnterpriseWebSearchTool(BaseTool):
+  """A Gemini 2+ built-in tool using web grounding for Enterprise compliance.
 
-  This tool operates internally within the model and does not require or perform
-  local code execution.
+  See the documentation for more details:
+  https://cloud.google.com/vertex-ai/generative-ai/docs/grounding/web-grounding-enterprise.
   """
 
   def __init__(self):
+    """Initializes the Vertex AI Search tool."""
     # Name and description are not used because this is a model built-in tool.
-    super().__init__(name='code_execution', description='code_execution')
+    super().__init__(
+        name='enterprise_web_search', description='enterprise_web_search'
+    )
 
   @override
   async def process_llm_request(
@@ -44,16 +47,19 @@ class BuiltInCodeExecutionTool(BaseTool):
       tool_context: ToolContext,
       llm_request: LlmRequest,
   ) -> None:
-    if llm_request.model and llm_request.model.startswith('gemini-2'):
+    if llm_request.model and llm_request.model.startswith('gemini-'):
+      if llm_request.model.startswith('gemini-1') and llm_request.config.tools:
+        raise ValueError(
+            'Enterprise web search tool can not be used with other tools in'
+            ' Gemini 1.x.'
+        )
       llm_request.config = llm_request.config or types.GenerateContentConfig()
       llm_request.config.tools = llm_request.config.tools or []
       llm_request.config.tools.append(
-          types.Tool(code_execution=types.ToolCodeExecution())
+          types.Tool(enterprise_web_search=types.EnterpriseWebSearch())
       )
     else:
       raise ValueError(
-          f'Code execution tool is not supported for model {llm_request.model}'
+          'Enterprise web search tool is not supported for model'
+          f' {llm_request.model}'
       )
-
-
-built_in_code_execution = BuiltInCodeExecutionTool()