introduce multiagent events and persistence hooks

Author: JackYPCOnline

src/strands/experimental/multiagent_session/__init__.py renamed to src/strands/experimental/multiagent_hooks/__init__.py

@@ -4,19 +4,20 @@
 enabling resumable execution after interruptions or failures.
 """
 
+from personal.saved.multiagent_state import MultiAgentState, MultiAgentType
+from personal.saved.multiagent_state_adapter import MultiAgentAdapter
+
 from .multiagent_events import (
-    AfterGraphInvocationEvent,
+    AfterMultiAgentInvocationEvent,
     AfterNodeInvocationEvent,
-    BeforeGraphInvocationEvent,
+    BeforeMultiAgentInvocationEvent,
     BeforeNodeInvocationEvent,
     MultiAgentInitializationEvent,
 )
-from .multiagent_state import MultiAgentState, MultiAgentType
-from .multiagent_state_adapter import MultiAgentAdapter
 
 __all__ = [
-    "BeforeGraphInvocationEvent",
-    "AfterGraphInvocationEvent",
+    "BeforeMultiAgentInvocationEvent",
+    "AfterMultiAgentInvocationEvent",
     "MultiAgentInitializationEvent",
     "BeforeNodeInvocationEvent",
     "AfterNodeInvocationEvent",

src/strands/experimental/multiagent_session/multiagent_events.py renamed to src/strands/experimental/multiagent_hooks/multiagent_events.py

@@ -1,87 +1,82 @@
 """Multi-agent execution lifecycle events for hook system integration.
 
-This module defines event classes that are triggered at key points during
-multi-agent orchestrator execution, enabling hooks to respond to lifecycle
-events for purposes like persistence, monitoring, and debugging.
-
-Event Types:
-- Initialization: When orchestrator starts up
-- Before/After Graph: Start/end of overall execution
-- Before/After Node: Start/end of individual node execution
+These events are fired by orchestrators (Graph/Swarm) at key points so
+hooks can persist, monitor, or debug execution. No intermediate state model
+is used—hooks read from the orchestrator directly.
 """
 
 from dataclasses import dataclass
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
-from ...hooks.registry import HookEvent
-from .multiagent_state import MultiAgentState
+from ...hooks.registry import HookEventBase
 
 if TYPE_CHECKING:
     from ...multiagent.base import MultiAgentBase
 
 
 @dataclass
-class MultiAgentInitializationEvent(HookEvent):
+class MultiAgentInitializationEvent(HookEventBase):
     """Event triggered when multi-agent orchestrator initializes.
 
     Attributes:
         orchestrator: The multi-agent orchestrator instance
-        state: Current state of the orchestrator
+        invocation_state: Configuration that user pass in
     """
 
     orchestrator: "MultiAgentBase"
-    state: MultiAgentState
+    invocation_state: dict[str, Any]
 
 
 @dataclass
-class BeforeGraphInvocationEvent(HookEvent):
+class BeforeMultiAgentInvocationEvent(HookEventBase):
     """Event triggered before orchestrator execution begins.
 
     Attributes:
         orchestrator: The multi-agent orchestrator instance
-        state: Current state before execution starts
+        invocation_state: Configuration that user pass in
     """
 
     orchestrator: "MultiAgentBase"
-    state: MultiAgentState
+    invocation_state: dict[str, Any]
 
 
 @dataclass
-class BeforeNodeInvocationEvent(HookEvent):
+class BeforeNodeInvocationEvent(HookEventBase):
     """Event triggered before individual node execution.
 
     Attributes:
         orchestrator: The multi-agent orchestrator instance
-        next_node_to_execute: ID of the node about to be executed
+        invocation_state: Configuration that user pass in
     """
 
     orchestrator: "MultiAgentBase"
     next_node_to_execute: str
+    invocation_state: dict[str, Any]
 
 
 @dataclass
-class AfterNodeInvocationEvent(HookEvent):
+class AfterNodeInvocationEvent(HookEventBase):
     """Event triggered after individual node execution completes.
 
     Attributes:
         orchestrator: The multi-agent orchestrator instance
         executed_node: ID of the node that just completed execution
-        state: Updated state after node execution
+        invocation_state: Configuration that user pass in
     """
 
     orchestrator: "MultiAgentBase"
     executed_node: str
-    state: MultiAgentState
+    invocation_state: dict[str, Any]
 
 
 @dataclass
-class AfterGraphInvocationEvent(HookEvent):
+class AfterMultiAgentInvocationEvent(HookEventBase):
     """Event triggered after orchestrator execution completes.
 
     Attributes:
         orchestrator: The multi-agent orchestrator instance
-        state: Final state after execution completes
+        invocation_state: Configuration that user pass in
     """
 
     orchestrator: "MultiAgentBase"
-    state: MultiAgentState
+    invocation_state: dict[str, Any]

src/strands/experimental/multiagent_session/persistence_hooks.py renamed to src/strands/experimental/multiagent_hooks/persistence_hooks.py

@@ -11,30 +11,17 @@
 """
 
 import threading
-from typing import Optional
 
 from ...hooks.registry import HookProvider, HookRegistry
 from ...multiagent.base import MultiAgentBase
 from ...session import SessionManager
 from .multiagent_events import (
-    AfterGraphInvocationEvent,
+    AfterMultiAgentInvocationEvent,
     AfterNodeInvocationEvent,
-    BeforeGraphInvocationEvent,
+    BeforeMultiAgentInvocationEvent,
     BeforeNodeInvocationEvent,
     MultiAgentInitializationEvent,
-    MultiAgentState,
 )
-from .multiagent_state_adapter import MultiAgentAdapter
-
-
-def _get_multiagent_state(
-    multiagent_state: Optional[MultiAgentState],
-    orchestrator: MultiAgentBase,
-) -> MultiAgentState:
-    if multiagent_state is not None:
-        return multiagent_state
-
-    return MultiAgentAdapter.create_multi_agent_state(orchestrator=orchestrator)
 
 
 class MultiAgentHook(HookProvider):
@@ -67,17 +54,18 @@ def register_hooks(self, registry: HookRegistry, **kwargs: object) -> None:
             **kwargs: Additional keyword arguments (unused)
         """
         registry.add_callback(MultiAgentInitializationEvent, self._on_initialization)
-        registry.add_callback(BeforeGraphInvocationEvent, self._on_before_graph)
+        registry.add_callback(BeforeMultiAgentInvocationEvent, self._on_initialization)
         registry.add_callback(BeforeNodeInvocationEvent, self._on_before_node)
         registry.add_callback(AfterNodeInvocationEvent, self._on_after_node)
-        registry.add_callback(AfterGraphInvocationEvent, self._on_after_graph)
+        registry.add_callback(AfterMultiAgentInvocationEvent, self._on_after_Execution)
 
     def _on_initialization(self, event: MultiAgentInitializationEvent):
         """Persist state when multi-agent orchestrator initializes."""
-        self._persist(_get_multiagent_state(event.state, event.orchestrator))
+        self._persist(event.orchestrator)
+        pass
 
-    def _on_before_graph(self, event: BeforeGraphInvocationEvent):
-        """Hook called before graph execution starts."""
+    def _on_before_Invocation(self, event: MultiAgentInitializationEvent):
+        """Persist state when multi-agent orchestrator initializes."""
         pass
 
     def _on_before_node(self, event: BeforeNodeInvocationEvent):
@@ -86,21 +74,20 @@ def _on_before_node(self, event: BeforeNodeInvocationEvent):
 
     def _on_after_node(self, event: AfterNodeInvocationEvent):
         """Persist state after each node completes execution."""
-        multi_agent_state = _get_multiagent_state(multiagent_state=event.state, orchestrator=event.orchestrator)
-        self._persist(multi_agent_state)
+        self._persist(event.orchestrator)
 
-    def _on_after_graph(self, event: AfterGraphInvocationEvent):
+    def _on_after_Execution(self, event: AfterMultiAgentInvocationEvent):
         """Persist final state after graph execution completes."""
-        multiagent_state = _get_multiagent_state(multiagent_state=event.state, orchestrator=event.orchestrator)
-        self._persist(multiagent_state)
+        self._persist(event.orchestrator)
 
-    def _persist(self, multiagent_state: MultiAgentState) -> None:
+    def _persist(self, orchestrator: MultiAgentBase) -> None:
         """Persist the provided MultiAgentState using the configured SessionManager.
 
         This method is synchronized across threads/tasks to avoid write races.
 
         Args:
-            multiagent_state: State to persist
+            orchestrator: State to persist
         """
+        current_state = orchestrator.get_state_from_orchestrator()
         with self._lock:
-            self._session_manager.write_multi_agent_state(multiagent_state)
+            self._session_manager.write_multi_agent_state(current_state)