feat(hooks): add AgentResult to AfterInvocationEvent (#1125)

The AfterInvocationEvent hook event did not provide access to the AgentResult, making it difficult for hooks to perform actions based on the outcome of an agent's invocation. This PR updates the AfterInvocationEvent to include an optional AgentResult. The Agent.invoke method now captures the AgentResult and passes it to the AfterInvocationEvent. New tests have been added to verify the functionality and immutability of the event.

Author: Ratish1

src/strands/agent/agent.py

@@ -56,7 +56,7 @@
 from ..tools.registry import ToolRegistry
 from ..tools.structured_output._structured_output_context import StructuredOutputContext
 from ..tools.watcher import ToolWatcher
-from ..types._events import AgentResultEvent, InitEventLoopEvent, ModelStreamChunkEvent, TypedEvent
+from ..types._events import AgentResultEvent, EventLoopStopEvent, InitEventLoopEvent, ModelStreamChunkEvent, TypedEvent
 from ..types.agent import AgentInput
 from ..types.content import ContentBlock, Message, Messages, SystemContentBlock
 from ..types.exceptions import ContextWindowOverflowException
@@ -621,6 +621,7 @@ async def _run_loop(
         """
         await self.hooks.invoke_callbacks_async(BeforeInvocationEvent(agent=self))
 
+        agent_result: AgentResult | None = None
         try:
             yield InitEventLoopEvent()
 
@@ -648,9 +649,13 @@ async def _run_loop(
                         self._session_manager.redact_latest_message(self.messages[-1], self)
                 yield event
 
+            # Capture the result from the final event if available
+            if isinstance(event, EventLoopStopEvent):
+                agent_result = AgentResult(*event["stop"])
+
         finally:
             self.conversation_manager.apply_management(self)
-            await self.hooks.invoke_callbacks_async(AfterInvocationEvent(agent=self))
+            await self.hooks.invoke_callbacks_async(AfterInvocationEvent(agent=self, result=agent_result))
 
     async def _execute_event_loop_cycle(
         self, invocation_state: dict[str, Any], structured_output_context: StructuredOutputContext | None = None

src/strands/hooks/events.py

@@ -5,10 +5,13 @@
 
 import uuid
 from dataclasses import dataclass
-from typing import Any, Optional
+from typing import TYPE_CHECKING, Any, Optional
 
 from typing_extensions import override
 
+if TYPE_CHECKING:
+    from ..agent.agent_result import AgentResult
+
 from ..types.content import Message
 from ..types.interrupt import _Interruptible
 from ..types.streaming import StopReason
@@ -60,8 +63,15 @@ class AfterInvocationEvent(HookEvent):
       - Agent.__call__
       - Agent.stream_async
       - Agent.structured_output
+
+    Attributes:
+        result: The result of the agent invocation, if available.
+            This will be None when invoked from structured_output methods, as those return typed output directly rather
+            than AgentResult.
     """
 
+    result: "AgentResult | None" = None
+
     @property
     def should_reverse_callbacks(self) -> bool:
         """True to invoke callbacks in reverse order."""

tests/strands/agent/hooks/test_events.py

@@ -2,6 +2,7 @@
 
 import pytest
 
+from strands.agent.agent_result import AgentResult
 from strands.hooks import (
     AfterInvocationEvent,
     AfterToolCallEvent,
@@ -10,6 +11,7 @@
     BeforeToolCallEvent,
     MessageAddedEvent,
 )
+from strands.types.content import Message
 from strands.types.tools import ToolResult, ToolUse
 
 
@@ -138,3 +140,22 @@ def test_after_tool_invocation_event_cannot_write_properties(after_tool_event):
         after_tool_event.invocation_state = {}
     with pytest.raises(AttributeError, match="Property exception is not writable"):
         after_tool_event.exception = Exception("test")
+
+
+def test_after_invocation_event_properties_not_writable(agent):
+    """Test that properties are not writable after initialization."""
+    mock_message: Message = {"role": "assistant", "content": [{"text": "test"}]}
+    mock_result = AgentResult(
+        stop_reason="end_turn",
+        message=mock_message,
+        metrics={},
+        state={},
+    )
+
+    event = AfterInvocationEvent(agent=agent, result=None)
+
+    with pytest.raises(AttributeError, match="Property result is not writable"):
+        event.result = mock_result
+
+    with pytest.raises(AttributeError, match="Property agent is not writable"):
+        event.agent = Mock()

tests/strands/agent/test_agent_hooks.py

@@ -147,7 +147,7 @@ def test_agent_tool_call(agent, hook_provider, agent_tool):
 def test_agent__call__hooks(agent, hook_provider, agent_tool, mock_model, tool_use):
     """Verify that the correct hook events are emitted as part of __call__."""
 
-    agent("test message")
+    result = agent("test message")
 
     length, events = hook_provider.get_events()
 
@@ -197,7 +197,7 @@ def test_agent__call__hooks(agent, hook_provider, agent_tool, mock_model, tool_u
     )
     assert next(events) == MessageAddedEvent(agent=agent, message=agent.messages[3])
 
-    assert next(events) == AfterInvocationEvent(agent=agent)
+    assert next(events) == AfterInvocationEvent(agent=agent, result=result)
 
     assert len(agent.messages) == 4
 
@@ -210,8 +210,10 @@ async def test_agent_stream_async_hooks(agent, hook_provider, agent_tool, mock_m
     assert hook_provider.events_received == [BeforeInvocationEvent(agent=agent)]
 
     # iterate the rest
-    async for _ in iterator:
-        pass
+    result = None
+    async for item in iterator:
+        if "result" in item:
+            result = item["result"]
 
     length, events = hook_provider.get_events()
 
@@ -261,7 +263,7 @@ async def test_agent_stream_async_hooks(agent, hook_provider, agent_tool, mock_m
     )
     assert next(events) == MessageAddedEvent(agent=agent, message=agent.messages[3])
 
-    assert next(events) == AfterInvocationEvent(agent=agent)
+    assert next(events) == AfterInvocationEvent(agent=agent, result=result)
 
     assert len(agent.messages) == 4