feat: add Spanner first-party toolset (breaking change to BigQueryTool, consolidating into generic GoogleTool)

Spanner toolset support basic operations to interact with Spanner table metadata and query results.

Consolidate BigQueryTool into generic GoogleTool, so that BigQueryToolset and SpannerToolset can share.

PiperOrigin-RevId: 794259782

Author: google-genai-bot

pyproject.toml

@@ -34,6 +34,7 @@ dependencies = [
   "google-api-python-client>=2.157.0",              # Google API client discovery
   "google-cloud-aiplatform[agent_engines]>=1.95.1", # For VertexAI integrations, e.g. example store.
   "google-cloud-secret-manager>=2.22.0",            # Fetching secrets in RestAPI Tool
+  "google-cloud-spanner>=3.56.0",                   # For Spanner database
   "google-cloud-speech>=2.30.0",                    # For Audio Transcription
   "google-cloud-storage>=2.18.0, <3.0.0",           # For GCS Artifact service
   "google-genai>=1.21.1",                           # Google GenAI SDK

src/google/adk/tools/_google_credentials.py

@@ -0,0 +1,252 @@
+# 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 json
+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
+import google.auth.credentials
+from google.auth.exceptions import RefreshError
+from google.auth.transport.requests import Request
+import google.oauth2.credentials
+from pydantic import BaseModel
+from pydantic import model_validator
+
+from ..auth.auth_credential import AuthCredential
+from ..auth.auth_credential import AuthCredentialTypes
+from ..auth.auth_credential import OAuth2Auth
+from ..auth.auth_tool import AuthConfig
+from ..utils.feature_decorator import experimental
+from .tool_context import ToolContext
+
+
+@experimental
+class BaseGoogleCredentialsConfig(BaseModel):
+  """Base Google Credentials Configuration for Google API tools (Experimental).
+
+  Please do not use this in production, as it may be deprecated later.
+  """
+
+  # Configure the model to allow arbitrary types like Credentials
+  model_config = {"arbitrary_types_allowed": True}
+
+  credentials: Optional[google.auth.credentials.Credentials] = None
+  """The existing auth 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 1: When the agent is deployed in Google Cloud environment and
+  the service account (used as application default credentials) has access to
+  all the required Google Cloud resource. Setting this credential to allow user
+  to access the Google Cloud resource without end users going through oauth
+  flow.
+
+  To get application default credential, use: `google.auth.default(...)`. See
+  more details in
+  https://cloud.google.com/docs/authentication/application-default-credentials.
+
+  Example usage 2: When the agent wants to access the user's Google Cloud
+  resources using the service account key credentials.
+
+  To load service account key credentials, use:
+  `google.auth.load_credentials_from_file(...)`. See more details in
+  https://cloud.google.com/iam/docs/service-account-creds#user-managed-keys.
+
+  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."""
+
+  _token_cache_key: Optional[str] = None
+  """The key to cache the token in the tool context."""
+
+  @model_validator(mode="after")
+  def __post_init__(self) -> BaseGoogleCredentialsConfig:
+    """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 and 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 and isinstance(
+        self.credentials, google.oauth2.credentials.Credentials
+    ):
+      self.client_id = self.credentials.client_id
+      self.client_secret = self.credentials.client_secret
+      self.scopes = self.credentials.scopes
+
+    return self
+
+
+class GoogleCredentialsManager:
+  """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: BaseGoogleCredentialsConfig,
+  ):
+    """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[google.auth.credentials.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(self.credentials_config._token_cache_key, None)
+        if self.credentials_config._token_cache_key
+        else None
+    )
+    creds = (
+        google.oauth2.credentials.Credentials.from_authorized_user_info(
+            json.loads(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
+
+    # If non-oauth credentials are provided then use them as is. This helps
+    # in flows such as service account keys
+    if creds and not isinstance(creds, google.oauth2.credentials.Credentials):
+      return creds
+
+    # 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 if token cache key is set
+          if self.credentials_config._token_cache_key:
+            tool_context.state[self.credentials_config._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[google.oauth2.credentials.Credentials]:
+    """Perform OAuth flow to get new credentials.
+
+    Args:
+        tool_context: The tool context for OAuth flow
+
+    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 = google.oauth2.credentials.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 if token cache key is set
+      if self.credentials_config._token_cache_key:
+        tool_context.state[self.credentials_config._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

src/google/adk/tools/bigquery/__init__.py

@@ -28,11 +28,9 @@
 """
 
 from .bigquery_credentials import BigQueryCredentialsConfig
-from .bigquery_tool import BigQueryTool
 from .bigquery_toolset import BigQueryToolset
 
 __all__ = [
-    "BigQueryTool",
     "BigQueryToolset",
     "BigQueryCredentialsConfig",
 ]