feat: emit ExperimentalWarning when agent kwarg is used

    Adds a custom ExperimentalWarning (subclass of FutureWarning) that is
    emitted when a listener explicitly requests the `agent` argument,
    informing developers that this feature is experimental and subject to
    change.

    Co-Authored-By: William Bergamin <wbergamin@salesforce.com>

Author: mwbrooks

slack_bolt/adapter/__init__.py

@@ -1,2 +1 @@
-"""Adapter modules for running Bolt apps along with Web frameworks or Socket Mode.
-"""
+"""Adapter modules for running Bolt apps along with Web frameworks or Socket Mode."""

slack_bolt/kwargs_injection/async_utils.py

@@ -1,9 +1,11 @@
 import inspect
 import logging
+import warnings
 from typing import Callable, Dict, MutableSequence, Optional, Any
 
 from slack_bolt.request.async_request import AsyncBoltRequest
 from slack_bolt.response import BoltResponse
+from slack_bolt.warning import ExperimentalWarning
 from .async_args import AsyncArgs
 from slack_bolt.request.payload_utils import (
     to_options,
@@ -86,6 +88,12 @@ def build_async_required_kwargs(
     # Defer agent creation to avoid constructing AsyncBoltAgent on every request
     if "agent" in required_arg_names or "args" in required_arg_names:
         all_available_args["agent"] = request.context.agent
+        if "agent" in required_arg_names:
+            warnings.warn(
+                "The agent listener argument is experimental and may change in future versions.",
+                category=ExperimentalWarning,
+                stacklevel=2,  # Point to the caller, not this internal helper
+            )
 
     if len(required_arg_names) > 0:
         # To support instance/class methods in a class for listeners/middleware,

slack_bolt/kwargs_injection/utils.py

@@ -1,9 +1,11 @@
 import inspect
 import logging
+import warnings
 from typing import Callable, Dict, MutableSequence, Optional, Any
 
 from slack_bolt.request import BoltRequest
 from slack_bolt.response import BoltResponse
+from slack_bolt.warning import ExperimentalWarning
 from .args import Args
 from slack_bolt.request.payload_utils import (
     to_options,
@@ -85,6 +87,12 @@ def build_required_kwargs(
     # Defer agent creation to avoid constructing BoltAgent on every request
     if "agent" in required_arg_names or "args" in required_arg_names:
         all_available_args["agent"] = request.context.agent
+        if "agent" in required_arg_names:
+            warnings.warn(
+                "The agent listener argument is experimental and may change in future versions.",
+                category=ExperimentalWarning,
+                stacklevel=2,  # Point to the caller, not this internal helper
+            )
 
     if len(required_arg_names) > 0:
         # To support instance/class methods in a class for listeners/middleware,

slack_bolt/warning/__init__.py

@@ -0,0 +1,7 @@
+"""Bolt specific warning types."""
+
+
+class ExperimentalWarning(FutureWarning):
+    """Warning for features that are still in experimental phase."""
+
+    pass

tests/scenario_tests/test_events_agent.py

@@ -2,11 +2,13 @@
 from time import sleep
 from unittest.mock import patch, MagicMock
 
+import pytest
 from slack_sdk.web import WebClient
 from slack_sdk.web.chat_stream import ChatStream
 
 from slack_bolt import App, BoltRequest, BoltContext, BoltAgent
 from slack_bolt.agent.agent import BoltAgent as BoltAgentDirect
+from slack_bolt.warning import ExperimentalWarning
 from tests.mock_web_api_server import (
     setup_mock_web_api_server,
     cleanup_mock_web_api_server,
@@ -188,6 +190,29 @@ def test_agent_import_from_agent_module(self):
 
         assert ImportedBoltAgent is BoltAgentDirect
 
+    def test_agent_kwarg_emits_experimental_warning(self):
+        app = App(client=self.web_client)
+
+        state = {"called": False}
+
+        def assert_target_called():
+            count = 0
+            while state["called"] is False and count < 20:
+                sleep(0.1)
+                count += 1
+            assert state["called"] is True
+            state["called"] = False
+
+        @app.event("app_mention")
+        def handle_mention(agent: BoltAgent):
+            state["called"] = True
+
+        request = BoltRequest(body=app_mention_event_body, mode="socket_mode")
+        with pytest.warns(ExperimentalWarning, match="agent listener argument is experimental"):
+            response = app.dispatch(request)
+        assert response.status == 200
+        assert_target_called()
+
 
 # ---- Test event bodies ----
 

tests/scenario_tests_async/test_events_agent.py

@@ -10,6 +10,7 @@
 from slack_bolt.app.async_app import AsyncApp
 from slack_bolt.context.async_context import AsyncBoltContext
 from slack_bolt.request.async_request import AsyncBoltRequest
+from slack_bolt.warning import ExperimentalWarning
 from tests.mock_web_api_server import (
     cleanup_mock_web_api_server_async,
     setup_mock_web_api_server_async,
@@ -206,6 +207,30 @@ async def test_agent_import_from_agent_module(self):
 
         assert ImportedAsyncBoltAgent is AsyncBoltAgent
 
+    @pytest.mark.asyncio
+    async def test_agent_kwarg_emits_experimental_warning(self):
+        app = AsyncApp(client=self.web_client)
+
+        state = {"called": False}
+
+        async def assert_target_called():
+            count = 0
+            while state["called"] is False and count < 20:
+                await asyncio.sleep(0.1)
+                count += 1
+            assert state["called"] is True
+            state["called"] = False
+
+        @app.event("app_mention")
+        async def handle_mention(agent: AsyncBoltAgent):
+            state["called"] = True
+
+        request = AsyncBoltRequest(body=app_mention_event_body, mode="socket_mode")
+        with pytest.warns(ExperimentalWarning, match="agent listener argument is experimental"):
+            response = await app.async_dispatch(request)
+            assert response.status == 200
+            await assert_target_called()
+
 
 # ---- Test event bodies ----