remove legacy steer method

Author: dbschmigelski

src/strands/experimental/steering/core/handler.py

@@ -35,7 +35,6 @@
 """
 
 import logging
-import warnings
 from abc import ABC
 from typing import TYPE_CHECKING, Any
 
@@ -96,7 +95,7 @@ async def _provide_tool_steering_guidance(self, event: BeforeToolCallEvent) -> N
         logger.debug("tool_name=<%s> | providing tool steering guidance", tool_name)
 
         try:
-            action = await self.steer_before_tool(event.agent, event.tool_use)
+            action = await self.steer_before_tool(agent=event.agent, tool_use=event.tool_use)
         except Exception as e:
             logger.debug("tool_name=<%s>, error=<%s> | tool steering handler guidance failed", tool_name, e)
             return
@@ -141,7 +140,7 @@ async def _provide_model_steering_guidance(self, event: AfterModelCallEvent) ->
 
         try:
             action = await self.steer_after_model(
-                event.agent, event.stop_response.message, event.stop_response.stop_reason
+                agent=event.agent, message=event.stop_response.message, stop_reason=event.stop_response.stop_reason
             )
         except Exception as e:
             logger.debug("error=<%s> | model steering handler guidance failed", e)
@@ -167,7 +166,7 @@ async def _handle_model_steering_action(self, action: ModelSteeringAction, event
         else:
             raise ValueError(f"Unknown steering action type for model response: {action}")
 
-    async def steer_before_tool(self, agent: "Agent", tool_use: ToolUse, **kwargs: Any) -> ToolSteeringAction:
+    async def steer_before_tool(self, *, agent: "Agent", tool_use: ToolUse, **kwargs: Any) -> ToolSteeringAction:
         """Provide contextual guidance before tool execution.
 
         This method is called before a tool is executed, allowing the handler to:
@@ -191,7 +190,7 @@ async def steer_before_tool(self, agent: "Agent", tool_use: ToolUse, **kwargs: A
         return Proceed(reason="Default implementation: allowing tool execution")
 
     async def steer_after_model(
-        self, agent: "Agent", message: Message, stop_reason: StopReason, **kwargs: Any
+        self, *, agent: "Agent", message: Message, stop_reason: StopReason, **kwargs: Any
     ) -> ModelSteeringAction:
         """Provide contextual guidance after model response.
 
@@ -216,27 +215,3 @@ async def steer_after_model(
             Override this method to implement custom model steering logic
         """
         return Proceed(reason="Default implementation: accepting model response")
-
-    async def steer(self, agent: "Agent", tool_use: ToolUse, **kwargs: Any) -> SteeringAction:
-        """Provide contextual guidance to help agent navigate complex workflows.
-
-        .. deprecated::
-            Use `steer_before_tool` instead. This method will be removed in a future version.
-
-        Args:
-            agent: The agent instance
-            tool_use: The tool use object with name and arguments
-            **kwargs: Additional keyword arguments for guidance evaluation
-
-        Returns:
-            SteeringAction indicating how to guide the agent's next action
-
-        Note:
-            Access steering context via self.steering_context
-        """
-        warnings.warn(
-            "steer() is deprecated and will be removed in a future version. Use steer_before_tool() instead.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        return await self.steer_before_tool(agent, tool_use, **kwargs)

src/strands/experimental/steering/handlers/llm/llm_handler.py

@@ -58,7 +58,7 @@ def __init__(
         self.prompt_mapper = prompt_mapper or DefaultPromptMapper()
         self.model = model
 
-    async def steer_before_tool(self, agent: "Agent", tool_use: ToolUse, **kwargs: Any) -> ToolSteeringAction:
+    async def steer_before_tool(self, *, agent: "Agent", tool_use: ToolUse, **kwargs: Any) -> ToolSteeringAction:
         """Provide contextual guidance for tool usage.
 
         Args:

tests/strands/experimental/steering/core/test_handler.py

@@ -1,6 +1,5 @@
 """Unit tests for steering handler base class."""
 
-import warnings
 from unittest.mock import AsyncMock, Mock
 
 import pytest
@@ -15,7 +14,7 @@
 class TestSteeringHandler(SteeringHandler):
     """Test implementation of SteeringHandler."""
 
-    async def steer_before_tool(self, agent, tool_use, **kwargs):
+    async def steer_before_tool(self, *, agent, tool_use, **kwargs):
         return Proceed(reason="Test proceed")
 
 
@@ -66,7 +65,7 @@ async def test_proceed_action_flow():
     """Test complete flow with Proceed action."""
 
     class ProceedHandler(SteeringHandler):
-        async def steer_before_tool(self, agent, tool_use, **kwargs):
+        async def steer_before_tool(self, *, agent, tool_use, **kwargs):
             return Proceed(reason="Test proceed")
 
     handler = ProceedHandler()
@@ -85,7 +84,7 @@ async def test_guide_action_flow():
     """Test complete flow with Guide action."""
 
     class GuideHandler(SteeringHandler):
-        async def steer_before_tool(self, agent, tool_use, **kwargs):
+        async def steer_before_tool(self, *, agent, tool_use, **kwargs):
             return Guide(reason="Test guidance")
 
     handler = GuideHandler()
@@ -105,7 +104,7 @@ async def test_interrupt_action_approved_flow():
     """Test complete flow with Interrupt action when approved."""
 
     class InterruptHandler(SteeringHandler):
-        async def steer_before_tool(self, agent, tool_use, **kwargs):
+        async def steer_before_tool(self, *, agent, tool_use, **kwargs):
             return Interrupt(reason="Need approval")
 
     handler = InterruptHandler()
@@ -124,7 +123,7 @@ async def test_interrupt_action_denied_flow():
     """Test complete flow with Interrupt action when denied."""
 
     class InterruptHandler(SteeringHandler):
-        async def steer_before_tool(self, agent, tool_use, **kwargs):
+        async def steer_before_tool(self, *, agent, tool_use, **kwargs):
             return Interrupt(reason="Need approval")
 
     handler = InterruptHandler()
@@ -144,7 +143,7 @@ async def test_unknown_action_flow():
     """Test complete flow with unknown action type raises error."""
 
     class UnknownActionHandler(SteeringHandler):
-        async def steer_before_tool(self, agent, tool_use, **kwargs):
+        async def steer_before_tool(self, *, agent, tool_use, **kwargs):
             return Mock()  # Not a valid SteeringAction
 
     handler = UnknownActionHandler()
@@ -160,7 +159,7 @@ def test_register_steering_hooks_override():
     """Test that _register_steering_hooks can be overridden."""
 
     class CustomHandler(SteeringHandler):
-        async def steer_before_tool(self, agent, tool_use, **kwargs):
+        async def steer_before_tool(self, *, agent, tool_use, **kwargs):
             return Proceed(reason="Custom")
 
         def register_hooks(self, registry, **kwargs):
@@ -201,7 +200,7 @@ def __init__(self, context_callbacks=None):
         providers = [MockContextProvider(context_callbacks)] if context_callbacks else None
         super().__init__(context_providers=providers)
 
-    async def steer_before_tool(self, agent, tool_use, **kwargs):
+    async def steer_before_tool(self, *, agent, tool_use, **kwargs):
         return Proceed(reason="Test proceed")
 
 
@@ -285,7 +284,7 @@ async def test_model_steering_proceed_action_flow():
     """Test model steering with Proceed action."""
 
     class ModelProceedHandler(SteeringHandler):
-        async def steer_after_model(self, agent, message, stop_reason, **kwargs):
+        async def steer_after_model(self, *, agent, message, stop_reason, **kwargs):
             return Proceed(reason="Model response accepted")
 
     handler = ModelProceedHandler()
@@ -309,7 +308,7 @@ async def test_model_steering_guide_action_flow():
     """Test model steering with Guide action sets retry and adds message."""
 
     class ModelGuideHandler(SteeringHandler):
-        async def steer_after_model(self, agent, message, stop_reason, **kwargs):
+        async def steer_after_model(self, *, agent, message, stop_reason, **kwargs):
             return Guide(reason="Please improve your response")
 
     handler = ModelGuideHandler()
@@ -342,7 +341,7 @@ def __init__(self):
             super().__init__()
             self.steer_called = False
 
-        async def steer_after_model(self, agent, message, stop_reason, **kwargs):
+        async def steer_after_model(self, *, agent, message, stop_reason, **kwargs):
             self.steer_called = True
             return Proceed(reason="Should not be called")
 
@@ -361,7 +360,7 @@ async def test_model_steering_unknown_action_raises_error():
     """Test model steering with unknown action type raises error."""
 
     class UnknownModelActionHandler(SteeringHandler):
-        async def steer_after_model(self, agent, message, stop_reason, **kwargs):
+        async def steer_after_model(self, *, agent, message, stop_reason, **kwargs):
             return Mock()  # Not a valid ModelSteeringAction
 
     handler = UnknownModelActionHandler()
@@ -382,7 +381,7 @@ async def test_model_steering_exception_handling():
     """Test model steering handles exceptions gracefully."""
 
     class ExceptionModelHandler(SteeringHandler):
-        async def steer_after_model(self, agent, message, stop_reason, **kwargs):
+        async def steer_after_model(self, *, agent, message, stop_reason, **kwargs):
             raise RuntimeError("Test exception")
 
     handler = ExceptionModelHandler()
@@ -407,7 +406,7 @@ async def test_tool_steering_exception_handling():
     """Test tool steering handles exceptions gracefully."""
 
     class ExceptionToolHandler(SteeringHandler):
-        async def steer_before_tool(self, agent, tool_use, **kwargs):
+        async def steer_before_tool(self, *, agent, tool_use, **kwargs):
             raise RuntimeError("Test exception")
 
     handler = ExceptionToolHandler()
@@ -431,7 +430,7 @@ async def test_default_steer_before_tool_returns_proceed():
     tool_use = {"name": "test_tool"}
 
     # Call the parent's default implementation
-    result = await SteeringHandler.steer_before_tool(handler, agent, tool_use)
+    result = await SteeringHandler.steer_before_tool(handler, agent=agent, tool_use=tool_use)
 
     assert isinstance(result, Proceed)
     assert "Default implementation" in result.reason
@@ -446,30 +445,12 @@ async def test_default_steer_after_model_returns_proceed():
     stop_reason = "end_turn"
 
     # Call the parent's default implementation
-    result = await SteeringHandler.steer_after_model(handler, agent, message, stop_reason)
+    result = await SteeringHandler.steer_after_model(handler, agent=agent, message=message, stop_reason=stop_reason)
 
     assert isinstance(result, Proceed)
     assert "Default implementation" in result.reason
 
 
-# Deprecated steer() method test
-@pytest.mark.asyncio
-async def test_deprecated_steer_method_emits_warning():
-    """Test deprecated steer() method emits DeprecationWarning."""
-    handler = TestSteeringHandler()
-    agent = Mock()
-    tool_use = {"name": "test_tool"}
-
-    with warnings.catch_warnings(record=True) as w:
-        warnings.simplefilter("always")
-        result = await handler.steer(agent, tool_use)
-
-        assert len(w) == 1
-        assert issubclass(w[0].category, DeprecationWarning)
-        assert "steer() is deprecated" in str(w[0].message)
-        assert isinstance(result, Proceed)
-
-
 def test_register_hooks_registers_model_steering():
     """Test that register_hooks registers model steering callback."""
     handler = TestSteeringHandler()

tests_integ/steering/test_model_steering.py

@@ -23,7 +23,7 @@ def __init__(self, should_guide: bool = False, guidance_message: str = ""):
         self.call_count = 0
 
     async def steer_after_model(
-        self, agent: Agent, message: Message, stop_reason: StopReason, **kwargs
+        self, *, agent: Agent, message: Message, stop_reason: StopReason, **kwargs
     ) -> ModelSteeringAction:
         """Steer after model response."""
         self.call_count += 1
@@ -75,7 +75,7 @@ def __init__(self):
             self.retry_done = False
 
         async def steer_after_model(
-            self, agent: Agent, message: Message, stop_reason: StopReason, **kwargs
+            self, *, agent: Agent, message: Message, stop_reason: StopReason, **kwargs
         ) -> ModelSteeringAction:
             if not self.retry_done:
                 self.retry_done = True
@@ -109,7 +109,7 @@ def __init__(self):
             self.call_count = 0
 
         async def steer_after_model(
-            self, agent: Agent, message: Message, stop_reason: StopReason, **kwargs
+            self, *, agent: Agent, message: Message, stop_reason: StopReason, **kwargs
         ) -> ModelSteeringAction:
             self.call_count += 1
 
@@ -160,7 +160,7 @@ def __init__(self, required_tool: str):
             self.guidance_given = False
 
         async def steer_after_model(
-            self, agent: Agent, message: Message, stop_reason: StopReason, **kwargs
+            self, *, agent: Agent, message: Message, stop_reason: StopReason, **kwargs
         ) -> ModelSteeringAction:
             # Only check when model is trying to end the turn
             if stop_reason != "end_turn":

tests_integ/steering/test_tool_steering.py

@@ -1,7 +1,5 @@
 """Integration tests for tool steering (steer_before_tool)."""
 
-import warnings
-
 import pytest
 
 from strands import Agent, tool
@@ -32,7 +30,7 @@ async def test_llm_steering_handler_proceed():
     agent = Agent(tools=[send_notification])
     tool_use = {"name": "send_notification", "input": {"recipient": "user", "message": "hello"}}
 
-    effect = await handler.steer_before_tool(agent, tool_use)
+    effect = await handler.steer_before_tool(agent=agent, tool_use=tool_use)
 
     assert isinstance(effect, Proceed)
 
@@ -50,7 +48,7 @@ async def test_llm_steering_handler_guide():
     agent = Agent(tools=[send_email, send_notification])
     tool_use = {"name": "send_email", "input": {"recipient": "user", "message": "hello"}}
 
-    effect = await handler.steer_before_tool(agent, tool_use)
+    effect = await handler.steer_before_tool(agent=agent, tool_use=tool_use)
 
     assert isinstance(effect, Guide)
 
@@ -66,31 +64,11 @@ async def test_llm_steering_handler_interrupt():
     agent = Agent(tools=[send_email])
     tool_use = {"name": "send_email", "input": {"recipient": "user", "message": "hello"}}
 
-    effect = await handler.steer_before_tool(agent, tool_use)
+    effect = await handler.steer_before_tool(agent=agent, tool_use=tool_use)
 
     assert isinstance(effect, Interrupt)
 
 
-@pytest.mark.asyncio
-async def test_deprecated_steer_method_emits_warning():
-    """Test deprecated steer() method emits DeprecationWarning."""
-    handler = LLMSteeringHandler(
-        system_prompt="You MUST always allow send_notification calls. ALWAYS return proceed decision."
-    )
-
-    agent = Agent(tools=[send_notification])
-    tool_use = {"name": "send_notification", "input": {"recipient": "user", "message": "hello"}}
-
-    with warnings.catch_warnings(record=True) as w:
-        warnings.simplefilter("always")
-        effect = await handler.steer(agent, tool_use)
-
-        assert len(w) == 1
-        assert issubclass(w[0].category, DeprecationWarning)
-        assert "steer() is deprecated" in str(w[0].message)
-        assert isinstance(effect, Proceed)
-
-
 def test_agent_with_tool_steering_e2e():
     """End-to-end test of agent with steering handler guiding tool choice."""
     handler = LLMSteeringHandler(