chore: Move spanner tools to integration folder

wukath · copybara-github · commit ab4b9526fc9e · 2026-03-04T17:24:31.000-08:00
Added a deprecation warning in the old tools/spanner/__init__.py

Co-authored-by: Kathy Wu &lt;wukathy@google.com&gt;
PiperOrigin-RevId: 878742289
diff --git a/contributing/samples/spanner/README.md b/contributing/samples/spanner/README.md
@@ -3,7 +3,7 @@
 ## Introduction
 
 This sample agent demonstrates the Spanner first-party tools in ADK,
-distributed via the `google.adk.tools.spanner` module. These tools include:
+distributed via the `google.adk.integrations.spanner` module. These tools include:
 
 1. `list_table_names`
 
diff --git a/contributing/samples/spanner/agent.py b/contributing/samples/spanner/agent.py
@@ -16,13 +16,13 @@
 
 from google.adk.agents.llm_agent import LlmAgent
 from google.adk.auth.auth_credential import AuthCredentialTypes
+from google.adk.integrations.spanner.settings import Capabilities
+from google.adk.integrations.spanner.settings import QueryResultMode
+from google.adk.integrations.spanner.settings import SpannerToolSettings
+from google.adk.integrations.spanner.spanner_credentials import SpannerCredentialsConfig
+from google.adk.integrations.spanner.spanner_toolset import SpannerToolset
+import google.adk.integrations.spanner.utils as spanner_tool_utils
 from google.adk.tools.google_tool import GoogleTool
-from google.adk.tools.spanner.settings import Capabilities
-from google.adk.tools.spanner.settings import QueryResultMode
-from google.adk.tools.spanner.settings import SpannerToolSettings
-from google.adk.tools.spanner.spanner_credentials import SpannerCredentialsConfig
-from google.adk.tools.spanner.spanner_toolset import SpannerToolset
-import google.adk.tools.spanner.utils as spanner_tool_utils
 from google.adk.tools.tool_context import ToolContext
 import google.auth
 from google.auth.credentials import Credentials
diff --git a/contributing/samples/spanner_rag_agent/README.md b/contributing/samples/spanner_rag_agent/README.md
@@ -4,7 +4,7 @@
 
 This sample demonstrates how to build an intelligent Retrieval Augmented
 Generation (RAG) agent using the flexible, built-in Spanner tools available
-in the ADK's `google.adk.tools.spanner` module, including how to create
+in the ADK's `google.adk.integrations.spanner` module, including how to create
 customized Spanner tools by extending the existing ones.
 
 [Spanner](https://cloud.google.com/spanner/docs) is a fully managed,
@@ -199,10 +199,10 @@ There are a few options to perform similarity search:
 
     ```py
     from google.adk.agents.llm_agent import LlmAgent
-    from google.adk.tools.spanner.settings import Capabilities
-    from google.adk.tools.spanner.settings import SpannerToolSettings
-    from google.adk.tools.spanner.settings import SpannerVectorStoreSettings
-    from google.adk.tools.spanner.spanner_toolset import SpannerToolset
+    from google.adk.integrations.spanner.settings import Capabilities
+    from google.adk.integrations.spanner.settings import SpannerToolSettings
+    from google.adk.integrations.spanner.settings import SpannerVectorStoreSettings
+    from google.adk.integrations.spanner.spanner_toolset import SpannerToolset
 
     # credentials_config = SpannerCredentialsConfig(...)
 
@@ -267,9 +267,9 @@ There are a few options to perform similarity search:
 
     ```py
     from google.adk.agents.llm_agent import LlmAgent
-    from google.adk.tools.spanner.settings import Capabilities
-    from google.adk.tools.spanner.settings import SpannerToolSettings
-    from google.adk.tools.spanner.spanner_toolset import SpannerToolset
+    from google.adk.integrations.spanner.settings import Capabilities
+    from google.adk.integrations.spanner.settings import SpannerToolSettings
+    from google.adk.integrations.spanner.spanner_toolset import SpannerToolset
 
     # credentials_config = SpannerCredentialsConfig(...)
 
@@ -312,7 +312,7 @@ There are a few options to perform similarity search:
     from google.adk.agents.llm_agent import LlmAgent
 
     from google.adk.tools.google_tool import GoogleTool
-    from google.adk.tools.spanner import search_tool
+    from google.adk.integrations.spanner import search_tool
     import google.auth
     from google.auth.credentials import Credentials
 
diff --git a/contributing/samples/spanner_rag_agent/agent.py b/contributing/samples/spanner_rag_agent/agent.py
@@ -16,11 +16,11 @@
 
 from google.adk.agents.llm_agent import LlmAgent
 from google.adk.auth.auth_credential import AuthCredentialTypes
-from google.adk.tools.spanner.settings import Capabilities
-from google.adk.tools.spanner.settings import SpannerToolSettings
-from google.adk.tools.spanner.settings import SpannerVectorStoreSettings
-from google.adk.tools.spanner.spanner_credentials import SpannerCredentialsConfig
-from google.adk.tools.spanner.spanner_toolset import SpannerToolset
+from google.adk.integrations.spanner.settings import Capabilities
+from google.adk.integrations.spanner.settings import SpannerToolSettings
+from google.adk.integrations.spanner.settings import SpannerVectorStoreSettings
+from google.adk.integrations.spanner.spanner_credentials import SpannerCredentialsConfig
+from google.adk.integrations.spanner.spanner_toolset import SpannerToolset
 import google.auth
 
 # Define an appropriate credential type
diff --git a/src/google/adk/integrations/spanner/__init__.py b/src/google/adk/integrations/spanner/__init__.py
@@ -0,0 +1,40 @@
+# 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.
+
+"""Spanner Tools (Experimental).
+
+Spanner 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. A dedicated Spanner toolset to provide an easier, integrated way to interact
+with Spanner database and tables for building AI Agent applications quickly.
+2. We want to provide more high-level tools like Search, ML.Predict, and Graph
+etc.
+3. We want to provide extra access guardrails and controls in those tools.
+For example, execute_sql can't arbitrarily mutate existing data.
+4. We want to provide Spanner best practices and knowledge assistants for ad-hoc
+analytics queries.
+5. Use Spanner Toolset for more customization and control to interact with
+Spanner database and tables.
+"""
+
+from . import spanner_credentials
+from .spanner_toolset import SpannerToolset
+
+SpannerCredentialsConfig = spanner_credentials.SpannerCredentialsConfig
+__all__ = [
+    "SpannerToolset",
+    "SpannerCredentialsConfig",
+]
diff --git a/src/google/adk/integrations/spanner/client.py b/src/google/adk/integrations/spanner/client.py
diff --git a/src/google/adk/integrations/spanner/metadata_tool.py b/src/google/adk/integrations/spanner/metadata_tool.py
diff --git a/src/google/adk/integrations/spanner/query_tool.py b/src/google/adk/integrations/spanner/query_tool.py
@@ -22,7 +22,7 @@
 from google.auth.credentials import Credentials
 
 from . import utils
-from ..tool_context import ToolContext
+from ...tools.tool_context import ToolContext
 from .settings import QueryResultMode
 from .settings import SpannerToolSettings
 
diff --git a/src/google/adk/integrations/spanner/search_tool.py b/src/google/adk/integrations/spanner/search_tool.py
diff --git a/src/google/adk/integrations/spanner/settings.py b/src/google/adk/integrations/spanner/settings.py
diff --git a/src/google/adk/integrations/spanner/spanner_credentials.py b/src/google/adk/integrations/spanner/spanner_credentials.py
@@ -16,7 +16,7 @@
 
 from ...features import experimental
 from ...features import FeatureName
-from .._google_credentials import BaseGoogleCredentialsConfig
+from ...tools._google_credentials import BaseGoogleCredentialsConfig
 
 SPANNER_TOKEN_CACHE_KEY = "spanner_token_cache"
 SPANNER_DEFAULT_SCOPE = [
diff --git a/src/google/adk/integrations/spanner/spanner_toolset.py b/src/google/adk/integrations/spanner/spanner_toolset.py
@@ -19,11 +19,11 @@
 from typing import Union
 
 from google.adk.agents.readonly_context import ReadonlyContext
-from google.adk.tools.spanner import metadata_tool
-from google.adk.tools.spanner import query_tool
-from google.adk.tools.spanner import search_tool
 from typing_extensions import override
 
+from . import metadata_tool
+from . import query_tool
+from . import search_tool
 from ...features import experimental
 from ...features import FeatureName
 from ...tools.base_tool import BaseTool
diff --git a/src/google/adk/integrations/spanner/utils.py b/src/google/adk/integrations/spanner/utils.py
@@ -29,7 +29,7 @@
 from . import client
 from ...features import experimental
 from ...features import FeatureName
-from ..tool_context import ToolContext
+from ...tools.tool_context import ToolContext
 from .settings import QueryResultMode
 from .settings import SpannerToolSettings
 from .settings import SpannerVectorStoreSettings
diff --git a/src/google/adk/tools/spanner/__init__.py b/src/google/adk/tools/spanner/__init__.py
@@ -12,26 +12,18 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Spanner Tools (Experimental).
+"""Backward compatibility for google.adk.tools.spanner."""
 
-Spanner 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:
+import warnings
 
-1. A dedicated Spanner toolset to provide an easier, integrated way to interact
-with Spanner database and tables for building AI Agent applications quickly.
-2. We want to provide more high-level tools like Search, ML.Predict, and Graph
-etc.
-3. We want to provide extra access guardrails and controls in those tools.
-For example, execute_sql can't arbitrarily mutate existing data.
-4. We want to provide Spanner best practices and knowledge assistants for ad-hoc
-analytics queries.
-5. Use Spanner Toolset for more customization and control to interact with
-Spanner database and tables.
-"""
+from google.adk.integrations.spanner import spanner_credentials
+from google.adk.integrations.spanner.spanner_toolset import SpannerToolset
 
-from . import spanner_credentials
-from .spanner_toolset import SpannerToolset
+warnings.warn(
+    "google.adk.tools.spanner is moved to google.adk.integrations.spanner.",
+    DeprecationWarning,
+    stacklevel=2,
+)
 
 SpannerCredentialsConfig = spanner_credentials.SpannerCredentialsConfig
 __all__ = [
diff --git a/tests/integration/spanner/__init__.py b/tests/integration/spanner/__init__.py
@@ -10,4 +10,4 @@
 # 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.
+# limitations under the License.
diff --git a/tests/integration/spanner/test_metadata_tool.py b/tests/integration/spanner/test_metadata_tool.py
@@ -15,7 +15,7 @@
 from unittest.mock import MagicMock
 from unittest.mock import patch
 
-from google.adk.tools.spanner import metadata_tool
+from google.adk.integrations.spanner import metadata_tool
 from google.cloud.spanner_admin_database_v1.types import DatabaseDialect
 import pytest
 
@@ -35,7 +35,7 @@ def mock_spanner_ids():
   }
 
 
-@patch("google.adk.tools.spanner.client.get_spanner_client")
+@patch("google.adk.integrations.spanner.client.get_spanner_client")
 def test_list_table_names_success(
     mock_get_spanner_client, mock_spanner_ids, mock_credentials
 ):
@@ -60,7 +60,7 @@ def test_list_table_names_success(
   assert result["results"] == ["table1"]
 
 
-@patch("google.adk.tools.spanner.client.get_spanner_client")
+@patch("google.adk.integrations.spanner.client.get_spanner_client")
 def test_list_table_names_error(
     mock_get_spanner_client, mock_spanner_ids, mock_credentials
 ):
@@ -76,7 +76,7 @@ def test_list_table_names_error(
   assert result["error_details"] == "Test Exception"
 
 
-@patch("google.adk.tools.spanner.client.get_spanner_client")
+@patch("google.adk.integrations.spanner.client.get_spanner_client")
 def test_get_table_schema_success(
     mock_get_spanner_client, mock_spanner_ids, mock_credentials
 ):
@@ -154,7 +154,7 @@ def test_get_table_schema_success(
   )
 
 
-@patch("google.adk.tools.spanner.client.get_spanner_client")
+@patch("google.adk.integrations.spanner.client.get_spanner_client")
 def test_list_table_indexes_success(
     mock_get_spanner_client, mock_spanner_ids, mock_credentials
 ):
@@ -192,7 +192,7 @@ def test_list_table_indexes_success(
   assert result["results"][0]["INDEX_NAME"] == "PRIMARY_KEY"
 
 
-@patch("google.adk.tools.spanner.client.get_spanner_client")
+@patch("google.adk.integrations.spanner.client.get_spanner_client")
 def test_list_table_indexes_circular_row_fallback_to_string(
     mock_get_spanner_client, mock_spanner_ids, mock_credentials
 ):
@@ -231,7 +231,7 @@ def test_list_table_indexes_circular_row_fallback_to_string(
   assert isinstance(result["results"][0], str)
 
 
-@patch("google.adk.tools.spanner.client.get_spanner_client")
+@patch("google.adk.integrations.spanner.client.get_spanner_client")
 def test_list_table_index_columns_success(
     mock_get_spanner_client, mock_spanner_ids, mock_credentials
 ):
@@ -268,7 +268,7 @@ def test_list_table_index_columns_success(
   assert result["results"][0]["COLUMN_NAME"] == "col1"
 
 
-@patch("google.adk.tools.spanner.client.get_spanner_client")
+@patch("google.adk.integrations.spanner.client.get_spanner_client")
 def test_list_named_schemas_success(
     mock_get_spanner_client, mock_spanner_ids, mock_credentials
 ):
diff --git a/tests/integration/spanner/test_search_tool.py b/tests/integration/spanner/test_search_tool.py
@@ -15,9 +15,9 @@
 from unittest import mock
 from unittest.mock import MagicMock
 
-from google.adk.tools.spanner import client
-from google.adk.tools.spanner import search_tool
-from google.adk.tools.spanner import utils
+from google.adk.integrations.spanner import client
+from google.adk.integrations.spanner import search_tool
+from google.adk.integrations.spanner import utils
 from google.cloud.spanner_admin_database_v1.types import DatabaseDialect
 import pytest
 
diff --git a/tests/integration/spanner/test_spanner_client.py b/tests/integration/spanner/test_spanner_client.py
@@ -18,7 +18,7 @@
 import re
 from unittest import mock
 
-from google.adk.tools.spanner.client import get_spanner_client
+from google.adk.integrations.spanner.client import get_spanner_client
 from google.auth.exceptions import DefaultCredentialsError
 from google.oauth2.credentials import Credentials
 import pytest
diff --git a/tests/integration/spanner/test_spanner_credentials.py b/tests/integration/spanner/test_spanner_credentials.py
@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from google.adk.tools.spanner.spanner_credentials import SpannerCredentialsConfig
+from google.adk.integrations.spanner.spanner_credentials import SpannerCredentialsConfig
 # Mock the Google OAuth and API dependencies
 import google.auth.credentials
 import google.oauth2.credentials
diff --git a/tests/integration/spanner/test_spanner_query_tool.py b/tests/integration/spanner/test_spanner_query_tool.py
@@ -17,13 +17,13 @@
 import textwrap
 from unittest import mock
 
+from google.adk.integrations.spanner import query_tool
+from google.adk.integrations.spanner import settings
+from google.adk.integrations.spanner.settings import QueryResultMode
+from google.adk.integrations.spanner.settings import SpannerToolSettings
+from google.adk.integrations.spanner.spanner_credentials import SpannerCredentialsConfig
+from google.adk.integrations.spanner.spanner_toolset import SpannerToolset
 from google.adk.tools.base_tool import BaseTool
-from google.adk.tools.spanner import query_tool
-from google.adk.tools.spanner import settings
-from google.adk.tools.spanner.settings import QueryResultMode
-from google.adk.tools.spanner.settings import SpannerToolSettings
-from google.adk.tools.spanner.spanner_credentials import SpannerCredentialsConfig
-from google.adk.tools.spanner.spanner_toolset import SpannerToolset
 from google.adk.tools.tool_context import ToolContext
 from google.auth.credentials import Credentials
 import pytest
diff --git a/tests/integration/spanner/test_spanner_tool_settings.py b/tests/integration/spanner/test_spanner_tool_settings.py
@@ -17,10 +17,10 @@
 import warnings
 
 from google.adk.features._feature_registry import _WARNED_FEATURES
-from google.adk.tools.spanner.settings import Capabilities
-from google.adk.tools.spanner.settings import QueryResultMode
-from google.adk.tools.spanner.settings import SpannerToolSettings
-from google.adk.tools.spanner.settings import SpannerVectorStoreSettings
+from google.adk.integrations.spanner.settings import Capabilities
+from google.adk.integrations.spanner.settings import QueryResultMode
+from google.adk.integrations.spanner.settings import SpannerToolSettings
+from google.adk.integrations.spanner.settings import SpannerVectorStoreSettings
 from pydantic import ValidationError
 import pytest
 
diff --git a/tests/integration/spanner/test_spanner_toolset.py b/tests/integration/spanner/test_spanner_toolset.py
@@ -14,11 +14,11 @@
 
 from __future__ import annotations
 
+from google.adk.integrations.spanner import SpannerCredentialsConfig
+from google.adk.integrations.spanner import SpannerToolset
+from google.adk.integrations.spanner.settings import SpannerToolSettings
+from google.adk.integrations.spanner.settings import SpannerVectorStoreSettings
 from google.adk.tools.google_tool import GoogleTool
-from google.adk.tools.spanner import SpannerCredentialsConfig
-from google.adk.tools.spanner import SpannerToolset
-from google.adk.tools.spanner.settings import SpannerToolSettings
-from google.adk.tools.spanner.settings import SpannerVectorStoreSettings
 import pytest
 
 
diff --git a/tests/integration/spanner/test_utils.py b/tests/integration/spanner/test_utils.py
@@ -16,11 +16,11 @@
 
 from unittest import mock
 
-from google.adk.tools.spanner import utils as spanner_utils
-from google.adk.tools.spanner.settings import SpannerToolSettings
-from google.adk.tools.spanner.settings import SpannerVectorStoreSettings
-from google.adk.tools.spanner.settings import TableColumn
-from google.adk.tools.spanner.settings import VectorSearchIndexSettings
+from google.adk.integrations.spanner import utils as spanner_utils
+from google.adk.integrations.spanner.settings import SpannerToolSettings
+from google.adk.integrations.spanner.settings import SpannerVectorStoreSettings
+from google.adk.integrations.spanner.settings import TableColumn
+from google.adk.integrations.spanner.settings import VectorSearchIndexSettings
 from google.cloud.spanner_admin_database_v1.types import DatabaseDialect
 from google.cloud.spanner_v1 import batch as spanner_batch
 from google.cloud.spanner_v1 import client as spanner_client_v1
diff --git a/tests/unittests/tools/test_google_tool.py b/tests/unittests/tools/test_google_tool.py
