chore: provide a way to disable model check for builtin tools

Co-authored-by: George Weale <gweale@google.com>
PiperOrigin-RevId: 872503435

src/google/adk/code_executors/built_in_code_executor.py

@@ -20,6 +20,7 @@ from typing_extensions import override
 from ..agents.invocation_context import InvocationContext
 from ..models import LlmRequest
 from ..utils.model_name_utils import is_gemini_2_or_above
+from ..utils.model_name_utils import is_gemini_model_id_check_disabled
 from .base_code_executor import BaseCodeExecutor
 from .code_execution_utils import CodeExecutionInput
 from .code_execution_utils import CodeExecutionResult
@@ -42,7 +43,8 @@ class BuiltInCodeExecutor(BaseCodeExecutor):
 
   def process_llm_request(self, llm_request: LlmRequest) -> None:
     """Pre-process the LLM request for Gemini 2.0+ models to use the code execution tool."""
-    if is_gemini_2_or_above(llm_request.model):
+    model_check_disabled = is_gemini_model_id_check_disabled()
+    if is_gemini_2_or_above(llm_request.model) or model_check_disabled:
       llm_request.config = llm_request.config or types.GenerateContentConfig()
       llm_request.config.tools = llm_request.config.tools or []
       llm_request.config.tools.append(

src/google/adk/tools/enterprise_search_tool.py

@@ -21,6 +21,7 @@ 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 ..utils.model_name_utils import is_gemini_model_id_check_disabled
 from .base_tool import BaseTool
 from .tool_context import ToolContext
 
@@ -54,14 +55,16 @@ class EnterpriseWebSearchTool(BaseTool):
       tool_context: ToolContext,
       llm_request: LlmRequest,
   ) -> None:
-    if is_gemini_model(llm_request.model):
+    model_check_disabled = is_gemini_model_id_check_disabled()
+    llm_request.config = llm_request.config or types.GenerateContentConfig()
+    llm_request.config.tools = llm_request.config.tools or []
+
+    if is_gemini_model(llm_request.model) or model_check_disabled:
       if is_gemini_1_model(llm_request.model) and llm_request.config.tools:
         raise ValueError(
             'Enterprise Web Search tool cannot 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(enterprise_web_search=types.EnterpriseWebSearch())
       )

src/google/adk/tools/google_maps_grounding_tool.py

@@ -21,6 +21,7 @@ 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 ..utils.model_name_utils import is_gemini_model_id_check_disabled
 from .base_tool import BaseTool
 from .tool_context import ToolContext
 
@@ -49,13 +50,14 @@ class GoogleMapsGroundingTool(BaseTool):
       tool_context: ToolContext,
       llm_request: LlmRequest,
   ) -> None:
+    model_check_disabled = is_gemini_model_id_check_disabled()
     llm_request.config = llm_request.config or types.GenerateContentConfig()
     llm_request.config.tools = llm_request.config.tools or []
     if is_gemini_1_model(llm_request.model):
       raise ValueError(
           'Google Maps grounding tool cannot be used with Gemini 1.x models.'
       )
-    elif is_gemini_model(llm_request.model):
+    elif is_gemini_model(llm_request.model) or model_check_disabled:
       llm_request.config.tools.append(
           types.Tool(google_maps=types.GoogleMaps())
       )

src/google/adk/tools/google_search_tool.py

@@ -21,6 +21,7 @@ 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 ..utils.model_name_utils import is_gemini_model_id_check_disabled
 from .base_tool import BaseTool
 from .tool_context import ToolContext
 
@@ -67,6 +68,7 @@ class GoogleSearchTool(BaseTool):
     if self.model is not None:
       llm_request.model = self.model
 
+    model_check_disabled = is_gemini_model_id_check_disabled()
     llm_request.config = llm_request.config or types.GenerateContentConfig()
     llm_request.config.tools = llm_request.config.tools or []
     if is_gemini_1_model(llm_request.model):
@@ -77,7 +79,7 @@ class GoogleSearchTool(BaseTool):
       llm_request.config.tools.append(
           types.Tool(google_search_retrieval=types.GoogleSearchRetrieval())
       )
-    elif is_gemini_model(llm_request.model):
+    elif is_gemini_model(llm_request.model) or model_check_disabled:
       llm_request.config.tools.append(
           types.Tool(google_search=types.GoogleSearch())
       )

src/google/adk/tools/retrieval/vertex_ai_rag_retrieval.py

@@ -24,6 +24,7 @@ from google.genai import types
 from typing_extensions import override
 
 from ...utils.model_name_utils import is_gemini_2_or_above
+from ...utils.model_name_utils import is_gemini_model_id_check_disabled
 from ..tool_context import ToolContext
 from .base_retrieval_tool import BaseRetrievalTool
 
@@ -63,7 +64,8 @@ class VertexAiRagRetrieval(BaseRetrievalTool):
       llm_request: LlmRequest,
   ) -> None:
     # Use Gemini built-in Vertex AI RAG tool for Gemini 2 models.
-    if is_gemini_2_or_above(llm_request.model):
+    model_check_disabled = is_gemini_model_id_check_disabled()
+    if is_gemini_2_or_above(llm_request.model) or model_check_disabled:
       llm_request.config = (
           types.GenerateContentConfig()
           if not llm_request.config

src/google/adk/tools/url_context_tool.py

@@ -21,6 +21,7 @@ from typing_extensions import override
 
 from ..utils.model_name_utils import is_gemini_1_model
 from ..utils.model_name_utils import is_gemini_2_or_above
+from ..utils.model_name_utils import is_gemini_model_id_check_disabled
 from .base_tool import BaseTool
 from .tool_context import ToolContext
 
@@ -46,11 +47,12 @@ class UrlContextTool(BaseTool):
       tool_context: ToolContext,
       llm_request: LlmRequest,
   ) -> None:
+    model_check_disabled = is_gemini_model_id_check_disabled()
     llm_request.config = llm_request.config or types.GenerateContentConfig()
     llm_request.config.tools = llm_request.config.tools or []
     if is_gemini_1_model(llm_request.model):
       raise ValueError('Url context tool cannot be used in Gemini 1.x.')
-    elif is_gemini_2_or_above(llm_request.model):
+    elif is_gemini_2_or_above(llm_request.model) or model_check_disabled:
       llm_request.config.tools.append(
           types.Tool(url_context=types.UrlContext())
       )

src/google/adk/tools/vertex_ai_search_tool.py

@@ -24,6 +24,7 @@ from typing_extensions import override
 from ..agents.readonly_context import ReadonlyContext
 from ..utils.model_name_utils import is_gemini_1_model
 from ..utils.model_name_utils import is_gemini_model
+from ..utils.model_name_utils import is_gemini_model_id_check_disabled
 from .base_tool import BaseTool
 from .tool_context import ToolContext
 
@@ -141,14 +142,16 @@ class VertexAiSearchTool(BaseTool):
       tool_context: ToolContext,
       llm_request: LlmRequest,
   ) -> None:
-    if is_gemini_model(llm_request.model):
+    model_check_disabled = is_gemini_model_id_check_disabled()
+    llm_request.config = llm_request.config or types.GenerateContentConfig()
+    llm_request.config.tools = llm_request.config.tools or []
+
+    if is_gemini_model(llm_request.model) or model_check_disabled:
       if is_gemini_1_model(llm_request.model) and llm_request.config.tools:
         raise ValueError(
             'Vertex AI search tool cannot 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 []
 
       # Build the search config (can be overridden by subclasses)
       vertex_ai_search_config = self._build_vertex_ai_search_config(

src/google/adk/utils/model_name_utils.py

@@ -22,6 +22,19 @@ from typing import Optional
 from packaging.version import InvalidVersion
 from packaging.version import Version
 
+from .env_utils import is_env_enabled
+
+_DISABLE_GEMINI_MODEL_ID_CHECK_ENV_VAR = 'ADK_DISABLE_GEMINI_MODEL_ID_CHECK'
+
+
+def is_gemini_model_id_check_disabled() -> bool:
+  """Returns True when Gemini model-id validation should be bypassed.
+
+  This opt-in environment variable is intended for internal usage where model
+  ids may not follow the public ``gemini-*`` naming convention.
+  """
+  return is_env_enabled(_DISABLE_GEMINI_MODEL_ID_CHECK_ENV_VAR)
+
 
 def extract_model_name(model_string: str) -> str:
   """Extract the actual model name from either simple or path-based format.

tests/unittests/code_executors/test_built_in_code_executor.py

@@ -97,6 +97,22 @@ def test_process_llm_request_non_gemini_2_model(
   )
 
 
+def test_process_llm_request_non_gemini_2_model_with_disabled_check(
+    built_in_executor: BuiltInCodeExecutor,
+    monkeypatch,
+):
+  """Tests non-Gemini models pass when model-id check is disabled."""
+  monkeypatch.setenv("ADK_DISABLE_GEMINI_MODEL_ID_CHECK", "true")
+  llm_request = LlmRequest(model="internal-model-v1")
+
+  built_in_executor.process_llm_request(llm_request)
+
+  assert llm_request.config is not None
+  assert llm_request.config.tools == [
+      types.Tool(code_execution=types.ToolCodeExecution())
+  ]
+
+
 def test_process_llm_request_no_model_name(
     built_in_executor: BuiltInCodeExecutor,
 ):

tests/unittests/tools/retrieval/test_vertex_ai_rag_retrieval.py

@@ -145,3 +145,43 @@ def test_vertex_rag_retrieval_for_gemini_2_x():
       )
   ]
   assert 'rag_retrieval' not in mockModel.requests[0].tools_dict
+
+
+def test_vertex_rag_retrieval_for_non_gemini_with_disabled_check(monkeypatch):
+  monkeypatch.setenv('ADK_DISABLE_GEMINI_MODEL_ID_CHECK', 'true')
+  responses = [
+      'response1',
+  ]
+  mockModel = testing_utils.MockModel.create(responses=responses)
+  mockModel.model = 'internal-model-v1'
+
+  agent = Agent(
+      name='root_agent',
+      model=mockModel,
+      tools=[
+          VertexAiRagRetrieval(
+              name='rag_retrieval',
+              description='rag_retrieval',
+              rag_corpora=[
+                  'projects/123456789/locations/us-central1/ragCorpora/1234567890'
+              ],
+          )
+      ],
+  )
+  runner = testing_utils.InMemoryRunner(agent)
+  runner.run('test1')
+
+  assert len(mockModel.requests) == 1
+  assert len(mockModel.requests[0].config.tools) == 1
+  assert mockModel.requests[0].config.tools == [
+      types.Tool(
+          retrieval=types.Retrieval(
+              vertex_rag_store=types.VertexRagStore(
+                  rag_corpora=[
+                      'projects/123456789/locations/us-central1/ragCorpora/1234567890'
+                  ]
+              )
+          )
+      )
+  ]
+  assert 'rag_retrieval' not in mockModel.requests[0].tools_dict

tests/unittests/tools/test_enterprise_web_search_tool.py

@@ -76,6 +76,25 @@ async def test_process_llm_request_failure_with_non_gemini_models():
   assert 'is not supported for model' in str(exc_info.value)
 
 
+@pytest.mark.asyncio
+async def test_process_llm_request_non_gemini_with_disabled_check(monkeypatch):
+  monkeypatch.setenv('ADK_DISABLE_GEMINI_MODEL_ID_CHECK', 'true')
+  tool = EnterpriseWebSearchTool()
+  llm_request = LlmRequest(
+      model='internal-model-v1', config=types.GenerateContentConfig()
+  )
+  tool_context = await _create_tool_context()
+
+  await tool.process_llm_request(
+      tool_context=tool_context, llm_request=llm_request
+  )
+
+  assert (
+      llm_request.config.tools[0].enterprise_web_search
+      == types.EnterpriseWebSearch()
+  )
+
+
 @pytest.mark.asyncio
 async def test_process_llm_request_failure_with_multiple_tools_gemini_1_models():
   tool = EnterpriseWebSearchTool()

tests/unittests/tools/test_google_maps_grounding_tool.py

@@ -0,0 +1,92 @@
+# 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.
+
+from google.adk.agents.invocation_context import InvocationContext
+from google.adk.agents.sequential_agent import SequentialAgent
+from google.adk.models.llm_request import LlmRequest
+from google.adk.sessions.in_memory_session_service import InMemorySessionService
+from google.adk.tools.google_maps_grounding_tool import GoogleMapsGroundingTool
+from google.adk.tools.tool_context import ToolContext
+from google.genai import types
+import pytest
+
+
+async def _create_tool_context() -> ToolContext:
+  session_service = InMemorySessionService()
+  session = await session_service.create_session(
+      app_name='test_app', user_id='test_user'
+  )
+  agent = SequentialAgent(name='test_agent')
+  invocation_context = InvocationContext(
+      invocation_id='invocation_id',
+      agent=agent,
+      session=session,
+      session_service=session_service,
+  )
+  return ToolContext(invocation_context=invocation_context)
+
+
+class TestGoogleMapsGroundingTool:
+  """Tests for GoogleMapsGroundingTool."""
+
+  @pytest.mark.asyncio
+  async def test_process_llm_request_with_gemini_2_model(self):
+    tool = GoogleMapsGroundingTool()
+    tool_context = await _create_tool_context()
+    llm_request = LlmRequest(
+        model='gemini-2.5-pro', config=types.GenerateContentConfig()
+    )
+
+    await tool.process_llm_request(
+        tool_context=tool_context, llm_request=llm_request
+    )
+
+    assert llm_request.config.tools is not None
+    assert len(llm_request.config.tools) == 1
+    assert llm_request.config.tools[0].google_maps is not None
+
+  @pytest.mark.asyncio
+  async def test_process_llm_request_with_non_gemini_model_raises_error(self):
+    tool = GoogleMapsGroundingTool()
+    tool_context = await _create_tool_context()
+    llm_request = LlmRequest(
+        model='claude-3-sonnet', config=types.GenerateContentConfig()
+    )
+
+    with pytest.raises(
+        ValueError,
+        match='Google maps tool is not supported for model claude-3-sonnet',
+    ):
+      await tool.process_llm_request(
+          tool_context=tool_context, llm_request=llm_request
+      )
+
+  @pytest.mark.asyncio
+  async def test_process_llm_request_with_non_gemini_and_disabled_check(
+      self, monkeypatch
+  ):
+    monkeypatch.setenv('ADK_DISABLE_GEMINI_MODEL_ID_CHECK', 'true')
+    tool = GoogleMapsGroundingTool()
+    tool_context = await _create_tool_context()
+    llm_request = LlmRequest(
+        model='internal-model-v1', config=types.GenerateContentConfig()
+    )
+
+    await tool.process_llm_request(
+        tool_context=tool_context, llm_request=llm_request
+    )
+
+    assert llm_request.config.tools is not None
+    assert len(llm_request.config.tools) == 1
+    assert llm_request.config.tools[0].google_maps is not None

tests/unittests/tools/test_google_search_tool.py

@@ -268,6 +268,27 @@ class TestGoogleSearchTool:
           tool_context=tool_context, llm_request=llm_request
       )
 
+  @pytest.mark.asyncio
+  async def test_process_llm_request_with_non_gemini_model_and_disabled_check(
+      self, monkeypatch
+  ):
+    """Test non-Gemini model can pass when model-id check is disabled."""
+    monkeypatch.setenv('ADK_DISABLE_GEMINI_MODEL_ID_CHECK', 'true')
+    tool = GoogleSearchTool()
+    tool_context = await _create_tool_context()
+
+    llm_request = LlmRequest(
+        model='internal-model-v1', config=types.GenerateContentConfig()
+    )
+
+    await tool.process_llm_request(
+        tool_context=tool_context, llm_request=llm_request
+    )
+
+    assert llm_request.config.tools is not None
+    assert len(llm_request.config.tools) == 1
+    assert llm_request.config.tools[0].google_search is not None
+
   @pytest.mark.asyncio
   async def test_process_llm_request_with_path_based_non_gemini_model_raises_error(
       self,

tests/unittests/tools/test_url_context_tool.py

@@ -190,6 +190,27 @@ class TestUrlContextTool:
           tool_context=tool_context, llm_request=llm_request
       )
 
+  @pytest.mark.asyncio
+  async def test_process_llm_request_with_non_gemini_model_and_disabled_check(
+      self, monkeypatch
+  ):
+    """Test non-Gemini model can pass when model-id check is disabled."""
+    monkeypatch.setenv('ADK_DISABLE_GEMINI_MODEL_ID_CHECK', 'true')
+    tool = UrlContextTool()
+    tool_context = await _create_tool_context()
+
+    llm_request = LlmRequest(
+        model='internal-model-v1', config=types.GenerateContentConfig()
+    )
+
+    await tool.process_llm_request(
+        tool_context=tool_context, llm_request=llm_request
+    )
+
+    assert llm_request.config.tools is not None
+    assert len(llm_request.config.tools) == 1
+    assert llm_request.config.tools[0].url_context is not None
+
   @pytest.mark.asyncio
   async def test_process_llm_request_with_path_based_non_gemini_model_raises_error(
       self,

tests/unittests/tools/test_vertex_ai_search_tool.py

@@ -376,6 +376,29 @@ class TestVertexAiSearchTool:
           tool_context=tool_context, llm_request=llm_request
       )
 
+  @pytest.mark.asyncio
+  async def test_process_llm_request_with_non_gemini_model_and_disabled_check(
+      self, monkeypatch
+  ):
+    """Test non-Gemini model can pass when model-id check is disabled."""
+    monkeypatch.setenv('ADK_DISABLE_GEMINI_MODEL_ID_CHECK', 'true')
+    tool = VertexAiSearchTool(data_store_id='test_data_store')
+    tool_context = await _create_tool_context()
+
+    llm_request = LlmRequest(
+        model='internal-model-v1', config=types.GenerateContentConfig()
+    )
+
+    await tool.process_llm_request(
+        tool_context=tool_context, llm_request=llm_request
+    )
+
+    assert llm_request.config.tools is not None
+    assert len(llm_request.config.tools) == 1
+    retrieval_tool = llm_request.config.tools[0]
+    assert retrieval_tool.retrieval is not None
+    assert retrieval_tool.retrieval.vertex_ai_search is not None
+
   @pytest.mark.asyncio
   async def test_process_llm_request_with_path_based_non_gemini_model_raises_error(
       self,

tests/unittests/utils/test_model_name_utils.py

@@ -18,6 +18,7 @@ from google.adk.utils.model_name_utils import extract_model_name
 from google.adk.utils.model_name_utils import is_gemini_1_model
 from google.adk.utils.model_name_utils import is_gemini_2_or_above
 from google.adk.utils.model_name_utils import is_gemini_model
+from google.adk.utils.model_name_utils import is_gemini_model_id_check_disabled
 
 
 class TestExtractModelName:
@@ -318,3 +319,15 @@ class TestModelNameUtilsIntegration:
           f'Inconsistent Gemini 2.0+ classification for {simple_model} vs'
           f' {path_model}'
       )
+
+
+class TestGeminiModelIdCheckFlag:
+  """Tests for Gemini model-id check override flag."""
+
+  def test_default_is_disabled(self, monkeypatch):
+    monkeypatch.delenv('ADK_DISABLE_GEMINI_MODEL_ID_CHECK', raising=False)
+    assert is_gemini_model_id_check_disabled() is False
+
+  def test_true_enables_check_bypass(self, monkeypatch):
+    monkeypatch.setenv('ADK_DISABLE_GEMINI_MODEL_ID_CHECK', 'true')
+    assert is_gemini_model_id_check_disabled() is True