Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.
feat: enhance flow event state management (#3952)
Lorenze Jay4ae8c3681505
diff --git a/lib/crewai/src/crewai/events/types/flow_events.py b/lib/crewai/src/crewai/events/types/flow_events.pyindex f436ce0fb..a35254192 100644--- a/lib/crewai/src/crewai/events/types/flow_events.py+++ b/lib/crewai/src/crewai/events/types/flow_events.py@@ -64,6 +64,7 @@ class FlowFinishedEvent(FlowEvent):flow_name: strresult: Any | None = Nonetype: str = "flow_finished"+ state: dict[str, Any] | BaseModelclass FlowPlotEvent(FlowEvent):diff --git a/lib/crewai/src/crewai/flow/flow.py b/lib/crewai/src/crewai/flow/flow.pyindex f5a51f33a..6123994e3 100644--- a/lib/crewai/src/crewai/flow/flow.py+++ b/lib/crewai/src/crewai/flow/flow.py@@ -1008,6 +1008,7 @@ class Flow(Generic[T], metaclass=FlowMeta):type="flow_finished",flow_name=self.name or self.__class__.__name__,result=final_output,+ state=self._copy_and_serialize_state(),),)if future:@@ -1109,6 +1110,7 @@ class Flow(Generic[T], metaclass=FlowMeta):dumped_params = {f"_{i}": arg for i, arg in enumerate(args)} | (kwargs or {})+future = crewai_event_bus.emit(self,MethodExecutionStartedEvent(@@ -1116,7 +1118,7 @@ class Flow(Generic[T], metaclass=FlowMeta):method_name=method_name,flow_name=self.name or self.__class__.__name__,params=dumped_params,- state=self._copy_state(),+ state=self._copy_and_serialize_state(),),)if future:@@ -1134,13 +1136,14 @@ class Flow(Generic[T], metaclass=FlowMeta):)self._completed_methods.add(method_name)+future = crewai_event_bus.emit(self,MethodExecutionFinishedEvent(type="method_execution_finished",method_name=method_name,flow_name=self.name or self.__class__.__name__,- state=self._copy_state(),+ state=self._copy_and_serialize_state(),result=result,),)@@ -1162,6 +1165,16 @@ class Flow(Generic[T], metaclass=FlowMeta):self._event_futures.append(future)raise e+ def _copy_and_serialize_state(self) -> dict[str, Any]:+ state_copy = self._copy_state()+ if isinstance(state_copy, BaseModel):+ try:+ return state_copy.model_dump(mode="json")+ except Exception:+ return state_copy.model_dump()+ else:+ return state_copy+async def _execute_listeners(self, trigger_method: FlowMethodName, result: Any) -> None:diff --git a/lib/crewai/tests/test_flow.py b/lib/crewai/tests/test_flow.pyindex cad91ace6..f9f046c68 100644--- a/lib/crewai/tests/test_flow.py+++ b/lib/crewai/tests/test_flow.py@@ -723,11 +723,11 @@ def test_structured_flow_event_emission():assert isinstance(received_events[3], MethodExecutionStartedEvent)assert received_events[3].method_name == "send_welcome_message"assert received_events[3].params == {}- assert received_events[3].state.sent is False+ assert received_events[3].state["sent"] is Falseassert isinstance(received_events[4], MethodExecutionFinishedEvent)assert received_events[4].method_name == "send_welcome_message"- assert received_events[4].state.sent is True+ assert received_events[4].state["sent"] is Trueassert received_events[4].result == "Welcome, Anakin!"assert isinstance(received_events[5], FlowFinishedEvent)diff --git a/lib/crewai/tests/utilities/test_events.py b/lib/crewai/tests/utilities/test_events.pyindex 1eeba199a..cc410a300 100644--- a/lib/crewai/tests/utilities/test_events.py+++ b/lib/crewai/tests/utilities/test_events.py@@ -26,6 +26,7 @@ from crewai.events.types.flow_events import (FlowFinishedEvent,FlowStartedEvent,MethodExecutionFailedEvent,+ MethodExecutionFinishedEvent,MethodExecutionStartedEvent,)from crewai.events.types.llm_events import (@@ -47,7 +48,7 @@ from crewai.flow.flow import Flow, listen, startfrom crewai.llm import LLMfrom crewai.task import Taskfrom crewai.tools.base_tool import BaseTool-from pydantic import Field+from pydantic import BaseModel, Fieldimport pytestfrom ..utils import wait_for_event_handlers@@ -703,6 +704,156 @@ def test_flow_emits_method_execution_failed_event():assert received_events[0].error == error+def test_flow_method_execution_started_includes_unstructured_state():+ """Test that MethodExecutionStartedEvent includes unstructured (dict) state."""+ received_events = []+ event_received = threading.Event()++ @crewai_event_bus.on(MethodExecutionStartedEvent)+ def handle_method_started(source, event):+ received_events.append(event)+ if event.method_name == "process":+ event_received.set()++ class TestFlow(Flow[dict]):+ @start()+ def begin(self):+ self.state["counter"] = 1+ self.state["message"] = "test"+ return "started"++ @listen("begin")+ def process(self):+ self.state["counter"] = 2+ return "processed"++ flow = TestFlow()+ flow.kickoff()++ assert event_received.wait(timeout=5), (+ "Timeout waiting for method execution started event"+ )++ # Find the events for each method+ begin_event = next(e for e in received_events if e.method_name == "begin")+ process_event = next(e for e in received_events if e.method_name == "process")++ # Verify state is included and is a dict+ assert begin_event.state is not None+ assert isinstance(begin_event.state, dict)+ assert "id" in begin_event.state # Auto-generated ID++ # Verify state from begin method is captured in process event+ assert process_event.state is not None+ assert isinstance(process_event.state, dict)+ assert process_event.state["counter"] == 1+ assert process_event.state["message"] == "test"+++def test_flow_method_execution_started_includes_structured_state():+ """Test that MethodExecutionStartedEvent includes structured (BaseModel) state and serializes it properly."""+ received_events = []+ event_received = threading.Event()++ class FlowState(BaseModel):+ counter: int = 0+ message: str = ""+ items: list[str] = []++ @crewai_event_bus.on(MethodExecutionStartedEvent)+ def handle_method_started(source, event):+ received_events.append(event)+ if event.method_name == "process":+ event_received.set()++ class TestFlow(Flow[FlowState]):+ @start()+ def begin(self):+ self.state.counter = 1+ self.state.message = "initial"+ self.state.items = ["a", "b"]+ return "started"++ @listen("begin")+ def process(self):+ self.state.counter += 1+ return "processed"++ flow = TestFlow()+ flow.kickoff()++ assert event_received.wait(timeout=5), (+ "Timeout waiting for method execution started event"+ )++ begin_event = next(e for e in received_events if e.method_name == "begin")+ process_event = next(e for e in received_events if e.method_name == "process")++ assert begin_event.state is not None+ assert isinstance(begin_event.state, dict)+ assert begin_event.state["counter"] == 0 # Initial state+ assert begin_event.state["message"] == ""+ assert begin_event.state["items"] == []++ assert process_event.state is not None+ assert isinstance(process_event.state, dict)+ assert process_event.state["counter"] == 1+ assert process_event.state["message"] == "initial"+ assert process_event.state["items"] == ["a", "b"]+++def test_flow_method_execution_finished_includes_serialized_state():+ """Test that MethodExecutionFinishedEvent includes properly serialized state."""+ received_events = []+ event_received = threading.Event()++ class FlowState(BaseModel):+ result: str = ""+ completed: bool = False++ @crewai_event_bus.on(MethodExecutionFinishedEvent)+ def handle_method_finished(source, event):+ received_events.append(event)+ if event.method_name == "process":+ event_received.set()++ class TestFlow(Flow[FlowState]):+ @start()+ def begin(self):+ self.state.result = "begin done"+ return "started"++ @listen("begin")+ def process(self):+ self.state.result = "process done"+ self.state.completed = True+ return "final_result"++ flow = TestFlow()+ final_output = flow.kickoff()++ assert event_received.wait(timeout=5), (+ "Timeout waiting for method execution finished event"+ )++ begin_finished = next(e for e in received_events if e.method_name == "begin")+ process_finished = next(e for e in received_events if e.method_name == "process")++ assert begin_finished.state is not None+ assert isinstance(begin_finished.state, dict)+ assert begin_finished.state["result"] == "begin done"+ assert begin_finished.state["completed"] is False+ assert begin_finished.result == "started"++ # Verify process finished event has final state and result+ assert process_finished.state is not None+ assert isinstance(process_finished.state, dict)+ assert process_finished.state["result"] == "process done"+ assert process_finished.state["completed"] is True+ assert process_finished.result == "final_result"+ assert final_output == "final_result"++@pytest.mark.vcr(filter_headers=["authorization"])def test_llm_emits_call_started_event():received_events = []