Merge branch 'strands-agents:main' into feature/agent-config-clean

Author: Unshure

src/strands/event_loop/event_loop.py

@@ -15,13 +15,7 @@
 
 from opentelemetry import trace as trace_api
 
-from ..experimental.hooks import (
-    AfterModelInvocationEvent,
-    BeforeModelInvocationEvent,
-)
-from ..hooks import (
-    MessageAddedEvent,
-)
+from ..hooks import AfterModelCallEvent, BeforeModelCallEvent, MessageAddedEvent
 from ..telemetry.metrics import Trace
 from ..telemetry.tracer import get_tracer
 from ..tools._validator import validate_and_prepare_tools
@@ -133,7 +127,7 @@ async def event_loop_cycle(agent: "Agent", invocation_state: dict[str, Any]) ->
         )
         with trace_api.use_span(model_invoke_span):
             agent.hooks.invoke_callbacks(
-                BeforeModelInvocationEvent(
+                BeforeModelCallEvent(
                     agent=agent,
                 )
             )
@@ -149,9 +143,9 @@ async def event_loop_cycle(agent: "Agent", invocation_state: dict[str, Any]) ->
                 invocation_state.setdefault("request_state", {})
 
                 agent.hooks.invoke_callbacks(
-                    AfterModelInvocationEvent(
+                    AfterModelCallEvent(
                         agent=agent,
-                        stop_response=AfterModelInvocationEvent.ModelStopResponse(
+                        stop_response=AfterModelCallEvent.ModelStopResponse(
                             stop_reason=stop_reason,
                             message=message,
                         ),
@@ -170,7 +164,7 @@ async def event_loop_cycle(agent: "Agent", invocation_state: dict[str, Any]) ->
                     tracer.end_span_with_error(model_invoke_span, str(e), e)
 
                 agent.hooks.invoke_callbacks(
-                    AfterModelInvocationEvent(
+                    AfterModelCallEvent(
                         agent=agent,
                         exception=e,
                     )

src/strands/experimental/hooks/events.py

@@ -3,121 +3,19 @@
 This module defines the events that are emitted as Agents run through the lifecycle of a request.
 """
 
-from dataclasses import dataclass
-from typing import Any, Optional
-
-from ...hooks import HookEvent
-from ...types.content import Message
-from ...types.streaming import StopReason
-from ...types.tools import AgentTool, ToolResult, ToolUse
-
-
-@dataclass
-class BeforeToolInvocationEvent(HookEvent):
-    """Event triggered before a tool is invoked.
-
-    This event is fired just before the agent executes a tool, allowing hook
-    providers to inspect, modify, or replace the tool that will be executed.
-    The selected_tool can be modified by hook callbacks to change which tool
-    gets executed.
-
-    Attributes:
-        selected_tool: The tool that will be invoked. Can be modified by hooks
-            to change which tool gets executed. This may be None if tool lookup failed.
-        tool_use: The tool parameters that will be passed to selected_tool.
-        invocation_state: Keyword arguments that will be passed to the tool.
-    """
-
-    selected_tool: Optional[AgentTool]
-    tool_use: ToolUse
-    invocation_state: dict[str, Any]
-
-    def _can_write(self, name: str) -> bool:
-        return name in ["selected_tool", "tool_use"]
-
-
-@dataclass
-class AfterToolInvocationEvent(HookEvent):
-    """Event triggered after a tool invocation completes.
-
-    This event is fired after the agent has finished executing a tool,
-    regardless of whether the execution was successful or resulted in an error.
-    Hook providers can use this event for cleanup, logging, or post-processing.
-
-    Note: This event uses reverse callback ordering, meaning callbacks registered
-    later will be invoked first during cleanup.
-
-    Attributes:
-        selected_tool: The tool that was invoked. It may be None if tool lookup failed.
-        tool_use: The tool parameters that were passed to the tool invoked.
-        invocation_state: Keyword arguments that were passed to the tool
-        result: The result of the tool invocation. Either a ToolResult on success
-            or an Exception if the tool execution failed.
-    """
-
-    selected_tool: Optional[AgentTool]
-    tool_use: ToolUse
-    invocation_state: dict[str, Any]
-    result: ToolResult
-    exception: Optional[Exception] = None
-
-    def _can_write(self, name: str) -> bool:
-        return name == "result"
-
-    @property
-    def should_reverse_callbacks(self) -> bool:
-        """True to invoke callbacks in reverse order."""
-        return True
-
-
-@dataclass
-class BeforeModelInvocationEvent(HookEvent):
-    """Event triggered before the model is invoked.
-
-    This event is fired just before the agent calls the model for inference,
-    allowing hook providers to inspect or modify the messages and configuration
-    that will be sent to the model.
-
-    Note: This event is not fired for invocations to structured_output.
-    """
-
-    pass
-
-
-@dataclass
-class AfterModelInvocationEvent(HookEvent):
-    """Event triggered after the model invocation completes.
-
-    This event is fired after the agent has finished calling the model,
-    regardless of whether the invocation was successful or resulted in an error.
-    Hook providers can use this event for cleanup, logging, or post-processing.
-
-    Note: This event uses reverse callback ordering, meaning callbacks registered
-    later will be invoked first during cleanup.
-
-    Note: This event is not fired for invocations to structured_output.
-
-    Attributes:
-        stop_response: The model response data if invocation was successful, None if failed.
-        exception: Exception if the model invocation failed, None if successful.
-    """
-
-    @dataclass
-    class ModelStopResponse:
-        """Model response data from successful invocation.
-
-        Attributes:
-            stop_reason: The reason the model stopped generating.
-            message: The generated message from the model.
-        """
-
-        message: Message
-        stop_reason: StopReason
-
-    stop_response: Optional[ModelStopResponse] = None
-    exception: Optional[Exception] = None
-
-    @property
-    def should_reverse_callbacks(self) -> bool:
-        """True to invoke callbacks in reverse order."""
-        return True
+import warnings
+from typing import TypeAlias
+
+from ...hooks.events import AfterModelCallEvent, AfterToolCallEvent, BeforeModelCallEvent, BeforeToolCallEvent
+
+warnings.warn(
+    "These events have been moved to production with updated names. Use BeforeModelCallEvent, "
+    "AfterModelCallEvent, BeforeToolCallEvent, and AfterToolCallEvent from strands.hooks instead.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+BeforeToolInvocationEvent: TypeAlias = BeforeToolCallEvent
+AfterToolInvocationEvent: TypeAlias = AfterToolCallEvent
+BeforeModelInvocationEvent: TypeAlias = BeforeModelCallEvent
+AfterModelInvocationEvent: TypeAlias = AfterModelCallEvent

src/strands/hooks/__init__.py

@@ -31,19 +31,29 @@ def log_end(self, event: AfterInvocationEvent) -> None:
 
 from .events import (
     AfterInvocationEvent,
+    AfterModelCallEvent,
+    AfterToolCallEvent,
     AgentInitializedEvent,
     BeforeInvocationEvent,
+    BeforeModelCallEvent,
+    BeforeToolCallEvent,
     MessageAddedEvent,
 )
-from .registry import HookCallback, HookEvent, HookProvider, HookRegistry
+from .registry import BaseHookEvent, HookCallback, HookEvent, HookProvider, HookRegistry
 
 __all__ = [
     "AgentInitializedEvent",
     "BeforeInvocationEvent",
+    "BeforeToolCallEvent",
+    "AfterToolCallEvent",
+    "BeforeModelCallEvent",
+    "AfterModelCallEvent",
     "AfterInvocationEvent",
     "MessageAddedEvent",
     "HookEvent",
     "HookProvider",
     "HookCallback",
     "HookRegistry",
+    "HookEvent",
+    "BaseHookEvent",
 ]

src/strands/hooks/events.py

@@ -4,8 +4,11 @@
 """
 
 from dataclasses import dataclass
+from typing import Any, Optional
 
 from ..types.content import Message
+from ..types.streaming import StopReason
+from ..types.tools import AgentTool, ToolResult, ToolUse
 from .registry import HookEvent
 
 
@@ -78,3 +81,114 @@ class MessageAddedEvent(HookEvent):
     """
 
     message: Message
+
+
+@dataclass
+class BeforeToolCallEvent(HookEvent):
+    """Event triggered before a tool is invoked.
+
+    This event is fired just before the agent executes a tool, allowing hook
+    providers to inspect, modify, or replace the tool that will be executed.
+    The selected_tool can be modified by hook callbacks to change which tool
+    gets executed.
+
+    Attributes:
+        selected_tool: The tool that will be invoked. Can be modified by hooks
+            to change which tool gets executed. This may be None if tool lookup failed.
+        tool_use: The tool parameters that will be passed to selected_tool.
+        invocation_state: Keyword arguments that will be passed to the tool.
+    """
+
+    selected_tool: Optional[AgentTool]
+    tool_use: ToolUse
+    invocation_state: dict[str, Any]
+
+    def _can_write(self, name: str) -> bool:
+        return name in ["selected_tool", "tool_use"]
+
+
+@dataclass
+class AfterToolCallEvent(HookEvent):
+    """Event triggered after a tool invocation completes.
+
+    This event is fired after the agent has finished executing a tool,
+    regardless of whether the execution was successful or resulted in an error.
+    Hook providers can use this event for cleanup, logging, or post-processing.
+
+    Note: This event uses reverse callback ordering, meaning callbacks registered
+    later will be invoked first during cleanup.
+
+    Attributes:
+        selected_tool: The tool that was invoked. It may be None if tool lookup failed.
+        tool_use: The tool parameters that were passed to the tool invoked.
+        invocation_state: Keyword arguments that were passed to the tool
+        result: The result of the tool invocation. Either a ToolResult on success
+            or an Exception if the tool execution failed.
+    """
+
+    selected_tool: Optional[AgentTool]
+    tool_use: ToolUse
+    invocation_state: dict[str, Any]
+    result: ToolResult
+    exception: Optional[Exception] = None
+
+    def _can_write(self, name: str) -> bool:
+        return name == "result"
+
+    @property
+    def should_reverse_callbacks(self) -> bool:
+        """True to invoke callbacks in reverse order."""
+        return True
+
+
+@dataclass
+class BeforeModelCallEvent(HookEvent):
+    """Event triggered before the model is invoked.
+
+    This event is fired just before the agent calls the model for inference,
+    allowing hook providers to inspect or modify the messages and configuration
+    that will be sent to the model.
+
+    Note: This event is not fired for invocations to structured_output.
+    """
+
+    pass
+
+
+@dataclass
+class AfterModelCallEvent(HookEvent):
+    """Event triggered after the model invocation completes.
+
+    This event is fired after the agent has finished calling the model,
+    regardless of whether the invocation was successful or resulted in an error.
+    Hook providers can use this event for cleanup, logging, or post-processing.
+
+    Note: This event uses reverse callback ordering, meaning callbacks registered
+    later will be invoked first during cleanup.
+
+    Note: This event is not fired for invocations to structured_output.
+
+    Attributes:
+        stop_response: The model response data if invocation was successful, None if failed.
+        exception: Exception if the model invocation failed, None if successful.
+    """
+
+    @dataclass
+    class ModelStopResponse:
+        """Model response data from successful invocation.
+
+        Attributes:
+            stop_reason: The reason the model stopped generating.
+            message: The generated message from the model.
+        """
+
+        message: Message
+        stop_reason: StopReason
+
+    stop_response: Optional[ModelStopResponse] = None
+    exception: Optional[Exception] = None
+
+    @property
+    def should_reverse_callbacks(self) -> bool:
+        """True to invoke callbacks in reverse order."""
+        return True

src/strands/hooks/registry.py

@@ -15,14 +15,8 @@
 
 
 @dataclass
-class HookEvent:
-    """Base class for all hook events.
-
-    Attributes:
-        agent: The agent instance that triggered this event.
-    """
-
-    agent: "Agent"
+class BaseHookEvent:
+    """Base class for all hook events."""
 
     @property
     def should_reverse_callbacks(self) -> bool:
@@ -66,10 +60,21 @@ def __setattr__(self, name: str, value: Any) -> None:
         raise AttributeError(f"Property {name} is not writable")
 
 
-TEvent = TypeVar("TEvent", bound=HookEvent, contravariant=True)
+@dataclass
+class HookEvent(BaseHookEvent):
+    """Base class for single agent hook events.
+
+    Attributes:
+        agent: The agent instance that triggered this event.
+    """
+
+    agent: "Agent"
+
+
+TEvent = TypeVar("TEvent", bound=BaseHookEvent, contravariant=True)
 """Generic for adding callback handlers - contravariant to allow adding handlers which take in base classes."""
 
-TInvokeEvent = TypeVar("TInvokeEvent", bound=HookEvent)
+TInvokeEvent = TypeVar("TInvokeEvent", bound=BaseHookEvent)
 """Generic for invoking events - non-contravariant to enable returning events."""
 
 

src/strands/hooks/rules.md

@@ -9,6 +9,7 @@
 
 - All hook events have a suffix of `Event`
 - Paired events follow the naming convention of `Before{Item}Event` and `After{Item}Event`
+- Pre actions in the name. i.e. prefer `BeforeToolCallEvent` over `BeforeToolEvent`.
 
 ## Paired Events
 
@@ -17,4 +18,4 @@
 
 ## Writable Properties
 
-For events with writable properties, those values are re-read after invoking the hook callbacks and used in subsequent processing. For example, `BeforeToolInvocationEvent.selected_tool` is writable - after invoking the callback for `BeforeToolInvocationEvent`, the `selected_tool` takes effect for the tool call.
+For events with writable properties, those values are re-read after invoking the hook callbacks and used in subsequent processing. For example, `BeforeToolEvent.selected_tool` is writable - after invoking the callback for `BeforeToolEvent`, the `selected_tool` takes effect for the tool call.