feat: honor ADK_SUPPRESS_EXPERIMENTAL_FEATURE_WARNINGS

Merge #5124

Fixes #5114

PiperOrigin-RevId: 1000995317

Author: jinnigu

src/google/adk/features/_feature_registry.py

@@ -20,6 +20,7 @@
 from typing import Generator
 import warnings
 
+from ..utils.env_utils import _is_experimental_warning_suppressed
 from ..utils.env_utils import is_env_enabled
 
 
@@ -417,6 +418,12 @@ def _emit_non_stable_warning_once(
     feature_name: The feature name.
     feature_stage: The feature stage.
   """
+  if (
+      feature_stage == FeatureStage.EXPERIMENTAL
+      and _is_experimental_warning_suppressed()
+  ):
+    return
+
   if feature_name not in _WARNED_FEATURES:
     _WARNED_FEATURES.add(feature_name)
     full_message = (

src/google/adk/utils/env_utils.py

@@ -25,6 +25,9 @@
 
 _TRUTHY_ENV_VALUES = frozenset({'1', 'true', 'yes', 'on'})
 _STRICT_TRUTHY_ENV_VALUES = frozenset({'1', 'true'})
+_EXPERIMENTAL_WARNING_SUPPRESSION_ENV_VAR = (
+    'ADK_SUPPRESS_EXPERIMENTAL_FEATURE_WARNINGS'
+)
 
 
 def is_env_enabled(env_var_name: str, default: str = '0') -> bool:
@@ -93,3 +96,12 @@ def is_enterprise_mode_enabled() -> bool:
     )
     return _is_genai_env_enabled('GOOGLE_GENAI_USE_VERTEXAI')
   return False
+
+
+def _is_experimental_warning_suppressed() -> bool:
+  """Check whether experimental warnings should be suppressed.
+
+  Returns:
+    True if the general experimental warning suppression env var is truthy.
+  """
+  return is_env_enabled(_EXPERIMENTAL_WARNING_SUPPRESSION_ENV_VAR)

src/google/adk/utils/feature_decorator.py

@@ -46,10 +46,16 @@ class MyFeature:
 from typing import TypeVar
 import warnings
 
+from .env_utils import _is_experimental_warning_suppressed
 from .env_utils import is_env_enabled
 
 T = TypeVar("T")
 
+# Gating suppression on the label string avoids adding a new parameter to
+# _make_feature_decorator, which would change the public constructor signatures
+# of experimental/a2a_experimental and trip the Breaking Change Detector.
+_EXPERIMENTAL_LABEL = "EXPERIMENTAL"
+
 
 class _FeatureDecorator(Protocol):
   """A feature decorator usable with or without a message argument.
@@ -125,6 +131,8 @@ def decorator_factory(message_or_obj: Any = None) -> Any:
 def _create_decorator(
     message: str, label: str, block_usage: bool, bypass_env_var: Optional[str]
 ) -> Callable[[T], T]:
+  is_experimental = label.upper() == _EXPERIMENTAL_LABEL
+
   def decorator(obj: T) -> T:
     obj_name = getattr(obj, "__name__", type(obj).__name__)
     msg = f"[{label.upper()}] {obj_name}: {message}"
@@ -140,7 +148,11 @@ def new_init(self: Any, *args: Any, **kwargs: Any) -> Any:
             bypass_env_var
         )
 
-        if should_bypass:
+        if should_bypass or (
+            is_experimental
+            and not block_usage
+            and _is_experimental_warning_suppressed()
+        ):
           # Bypass completely - no warning, no error
           pass
         elif block_usage:
@@ -162,7 +174,11 @@ def wrapper(*args: Any, **kwargs: Any) -> Any:
             bypass_env_var
         )
 
-        if should_bypass:
+        if should_bypass or (
+            is_experimental
+            and not block_usage
+            and _is_experimental_warning_suppressed()
+        ):
           # Bypass completely - no warning, no error
           pass
         elif block_usage:
@@ -216,6 +232,10 @@ def my_wip_function():
 )
 """Mark a class or a function as an experimental feature.
 
+Set ADK_SUPPRESS_EXPERIMENTAL_FEATURE_WARNINGS=true to silence these warnings.
+This also covers @a2a_experimental and the feature-registry
+"[EXPERIMENTAL] feature X is enabled." warnings.
+
 Sample usage:
 
 ```

tests/unittests/a2a/test_experimental.py

@@ -0,0 +1,106 @@
+# 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.
+"""Tests for a2a_experimental decorator and warning suppression."""
+
+import warnings
+
+from google.adk.a2a.experimental import a2a_experimental
+import pytest
+
+
+@pytest.fixture(autouse=True)
+def clear_suppression_env_vars(monkeypatch):
+  monkeypatch.delenv(
+      "ADK_SUPPRESS_EXPERIMENTAL_FEATURE_WARNINGS", raising=False
+  )
+  monkeypatch.delenv(
+      "ADK_SUPPRESS_A2A_EXPERIMENTAL_FEATURE_WARNINGS", raising=False
+  )
+
+
+def test_a2a_experimental_class_warns_by_default():
+  """Classes decorated with @a2a_experimental warn when instantiated."""
+
+  @a2a_experimental
+  class A2aExperimentalClass:
+
+    def run(self):
+      return "running"
+
+  with warnings.catch_warnings(record=True) as w:
+    warnings.simplefilter("always")
+    feature = A2aExperimentalClass()
+    assert feature.run() == "running"
+    assert len(w) == 1
+    assert "[EXPERIMENTAL] A2aExperimentalClass:" in str(w[0].message)
+
+
+def test_a2a_experimental_function_warns_by_default():
+  """Functions decorated with @a2a_experimental warn when called."""
+
+  @a2a_experimental
+  def a2a_experimental_function():
+    return "running fn"
+
+  with warnings.catch_warnings(record=True) as w:
+    warnings.simplefilter("always")
+    assert a2a_experimental_function() == "running fn"
+    assert len(w) == 1
+    assert "[EXPERIMENTAL] a2a_experimental_function:" in str(w[0].message)
+
+
+def test_a2a_experimental_warning_suppressed_by_general_env_var(monkeypatch):
+  """General suppression env var silences @a2a_experimental warnings."""
+
+  @a2a_experimental
+  class GeneralSuppressedA2aClass:
+
+    def run(self):
+      return "running"
+
+  @a2a_experimental
+  def general_suppressed_a2a_function():
+    return "running fn"
+
+  monkeypatch.setenv("ADK_SUPPRESS_EXPERIMENTAL_FEATURE_WARNINGS", "yes")
+
+  with warnings.catch_warnings(record=True) as w:
+    warnings.simplefilter("always")
+    feature = GeneralSuppressedA2aClass()
+    assert feature.run() == "running"
+    assert general_suppressed_a2a_function() == "running fn"
+    assert not w
+
+
+def test_a2a_experimental_warning_suppressed_by_a2a_env_var(monkeypatch):
+  """A2A-specific suppression env var silences @a2a_experimental warnings."""
+
+  @a2a_experimental
+  class A2aSuppressedClass:
+
+    def run(self):
+      return "running"
+
+  @a2a_experimental
+  def a2a_suppressed_function():
+    return "running fn"
+
+  monkeypatch.setenv("ADK_SUPPRESS_A2A_EXPERIMENTAL_FEATURE_WARNINGS", "on")
+
+  with warnings.catch_warnings(record=True) as w:
+    warnings.simplefilter("always")
+    feature = A2aSuppressedClass()
+    assert feature.run() == "running"
+    assert a2a_suppressed_function() == "running fn"
+    assert not w

tests/unittests/features/test_feature_decorator.py

@@ -70,7 +70,11 @@ def reset_env_and_registry(monkeypatch):
   """Reset environment variables and registry before each test."""
   # Clean up environment variables
   for key in list(os.environ.keys()):
-    if key.startswith("ADK_ENABLE_") or key.startswith("ADK_DISABLE_"):
+    if (
+        key.startswith("ADK_ENABLE_")
+        or key.startswith("ADK_DISABLE_")
+        or key == "ADK_SUPPRESS_EXPERIMENTAL_FEATURE_WARNINGS"
+    ):
       monkeypatch.delenv(key, raising=False)
 
   # Add an existing feature to the registry

tests/unittests/features/test_feature_registry.py

@@ -43,7 +43,11 @@ def reset_env_and_registry(monkeypatch):
   """Reset environment variables, registry and overrides before each test."""
   # Clean up environment variables
   for key in list(os.environ.keys()):
-    if key.startswith("ADK_ENABLE_") or key.startswith("ADK_DISABLE_"):
+    if (
+        key.startswith("ADK_ENABLE_")
+        or key.startswith("ADK_DISABLE_")
+        or key == "ADK_SUPPRESS_EXPERIMENTAL_FEATURE_WARNINGS"
+    ):
       monkeypatch.delenv(key, raising=False)
 
   # Reset warned features set
@@ -118,6 +122,55 @@ def test_experimental_enabled_feature(self):
           w[0].message
       )
 
+  def test_experimental_warning_suppressed_by_general_env_var(
+      self, monkeypatch
+  ):
+    """General suppression env var silences registry experimental warnings."""
+    _register_feature("SUPPRESSED_EXP", FEATURE_CONFIG_EXPERIMENTAL_ENABLED)
+    monkeypatch.setenv("ADK_SUPPRESS_EXPERIMENTAL_FEATURE_WARNINGS", "yes")
+
+    with warnings.catch_warnings(record=True) as w:
+      warnings.simplefilter("always")
+      assert is_feature_enabled("SUPPRESSED_EXP")
+      assert not w
+
+  def test_enable_env_warning_suppressed_by_general_env_var(self, monkeypatch):
+    """Suppression also applies when an experimental feature is env-enabled."""
+    _register_feature("ENV_ENABLED_EXP", FEATURE_CONFIG_EXPERIMENTAL_DISABLED)
+    monkeypatch.setenv("ADK_ENABLE_ENV_ENABLED_EXP", "true")
+    monkeypatch.setenv("ADK_SUPPRESS_EXPERIMENTAL_FEATURE_WARNINGS", "on")
+
+    with warnings.catch_warnings(record=True) as w:
+      warnings.simplefilter("always")
+      assert is_feature_enabled("ENV_ENABLED_EXP")
+      assert not w
+
+  def test_override_warning_suppressed_by_general_env_var(self, monkeypatch):
+    """Suppression also applies to programmatic overrides."""
+    _register_feature(
+        "OVERRIDE_ENABLED_EXP", FEATURE_CONFIG_EXPERIMENTAL_DISABLED
+    )
+    override_feature_enabled("OVERRIDE_ENABLED_EXP", True)
+    monkeypatch.setenv("ADK_SUPPRESS_EXPERIMENTAL_FEATURE_WARNINGS", "1")
+
+    with warnings.catch_warnings(record=True) as w:
+      warnings.simplefilter("always")
+      assert is_feature_enabled("OVERRIDE_ENABLED_EXP")
+      assert not w
+
+  def test_wip_warning_not_suppressed_by_general_env_var(self, monkeypatch):
+    """The experimental suppression flag must not suppress WIP warnings."""
+    _register_feature(
+        "SUPPRESSED_WIP", FeatureConfig(FeatureStage.WIP, default_on=True)
+    )
+    monkeypatch.setenv("ADK_SUPPRESS_EXPERIMENTAL_FEATURE_WARNINGS", "true")
+
+    with warnings.catch_warnings(record=True) as w:
+      warnings.simplefilter("always")
+      assert is_feature_enabled("SUPPRESSED_WIP")
+      assert len(w) == 1
+      assert "[WIP] feature SUPPRESSED_WIP is enabled." in str(w[0].message)
+
   def test_stable_feature_enabled(self):
     """Stable features are enabled."""
     _register_feature("STABLE_FEATURE", FEATURE_CONFIG_STABLE)

tests/unittests/integrations/eventarc/test_eventarc_toolset.py

@@ -14,6 +14,7 @@
 # limitations under the License.
 
 
+import os
 import unittest
 from unittest import mock
 import warnings
@@ -71,7 +72,11 @@ async def test_close_cleans_up_clients(self, mock_client):
     await toolset.close()
     mock_client.cleanup_clients.assert_called_once()
 
+  @mock.patch.dict(
+      os.environ, {"ADK_SUPPRESS_EXPERIMENTAL_FEATURE_WARNINGS": "0"}
+  )
   def test_eventarc_toolset_experimental_warning(self):
+    """Test that EventarcToolset warns when instantiated."""
     _WARNED_FEATURES.clear()
     with warnings.catch_warnings(record=True) as w:
       warnings.simplefilter("always")
@@ -84,7 +89,11 @@ def test_eventarc_toolset_experimental_warning(self):
           any("EVENTARC_TOOLSET is enabled." in str(warn.message) for warn in w)
       )
 
+  @mock.patch.dict(
+      os.environ, {"ADK_SUPPRESS_EXPERIMENTAL_FEATURE_WARNINGS": "0"}
+  )
   def test_eventarc_tool_config_experimental_warning(self):
+    """Test that EventarcToolConfig warns when instantiated."""
     _WARNED_FEATURES.clear()
     with warnings.catch_warnings(record=True) as w:
       warnings.simplefilter("always")

tests/unittests/tools/spanner/test_spanner_tool_settings.py

@@ -26,9 +26,12 @@
 
 
 @pytest.fixture(autouse=True)
-def reset_warned_features():
-  """Reset warned features before each test."""
+def reset_warned_features(monkeypatch):
+  """Reset warned features and warning suppression before each test."""
   _WARNED_FEATURES.clear()
+  monkeypatch.delenv(
+      "ADK_SUPPRESS_EXPERIMENTAL_FEATURE_WARNINGS", raising=False
+  )
 
 
 def common_spanner_vector_store_settings(vector_length=None):
@@ -46,6 +49,7 @@ def common_spanner_vector_store_settings(vector_length=None):
 def test_spanner_tool_settings_experimental_warning():
   """Test SpannerToolSettings experimental warning."""
   with warnings.catch_warnings(record=True) as w:
+    warnings.simplefilter("always")
     SpannerToolSettings()
     assert len(w) == 1
     assert "SPANNER_TOOL_SETTINGS is enabled." in str(w[0].message)

tests/unittests/utils/test_env_utils.py

@@ -14,6 +14,7 @@
 
 import warnings
 
+from google.adk.utils.env_utils import _is_experimental_warning_suppressed
 from google.adk.utils.env_utils import is_enterprise_mode_enabled
 from google.adk.utils.env_utils import is_env_enabled
 import pytest
@@ -129,3 +130,9 @@ def test_is_enterprise_mode_enabled_defaults_to_false(monkeypatch):
   monkeypatch.delenv('GOOGLE_GENAI_USE_VERTEXAI', raising=False)
 
   assert is_enterprise_mode_enabled() is False
+
+
+def test_is_experimental_warning_suppressed_checks_general_env(monkeypatch):
+  """General suppression env var disables experimental warnings."""
+  monkeypatch.setenv('ADK_SUPPRESS_EXPERIMENTAL_FEATURE_WARNINGS', 'yes')
+  assert _is_experimental_warning_suppressed()