Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.
feat(flow): make conversational opt-in unmistakable (#7031)
João Mouraf0e00df0360b
diff --git a/lib/crewai/src/crewai/experimental/conversational.py b/lib/crewai/src/crewai/experimental/conversational.pyindex ac20b9a4f..6f5ac869b 100644--- a/lib/crewai/src/crewai/experimental/conversational.py+++ b/lib/crewai/src/crewai/experimental/conversational.py@@ -96,8 +96,17 @@ class ConversationConfig:defer_trace_finalization: bool = Truedef __call__(self, flow_cls: type[Any]) -> type[Any]:- """Use this config as a class decorator."""+ """Use this config as a class decorator.++ Decorating a Flow also opts it into conversational mode. Every field+ here is consumed only by the conversational runtime, so a decorated Flow+ that was not conversational would silently discard its whole config:+ ``handle_turn()`` would return ``None`` without appending or raising.+ Setting ``conversational = True`` explicitly is still supported and is+ the way to opt in without a config.+ """flow_cls.conversational_config = self+ flow_cls.conversational = Truereturn flow_clsdiff --git a/lib/crewai/src/crewai/experimental/conversational_mixin.py b/lib/crewai/src/crewai/experimental/conversational_mixin.pyindex e3da7b8c9..3a47cd480 100644--- a/lib/crewai/src/crewai/experimental/conversational_mixin.py+++ b/lib/crewai/src/crewai/experimental/conversational_mixin.py@@ -293,11 +293,22 @@ class _ConversationalMixin:conversational ``Flow``. Signature and semantics may change beforethe feature graduates from ``crewai.experimental``.- Available only when ``conversational = True`` is set on the subclass.- Stashes the message + session_id as pending turn state, runs kickoff- (which restores from persist and then applies the pending turn), and- promotes the result to an assistant message when the handler didn't.+ Available only when ``conversational = True`` is set on the subclass+ (``@ConversationConfig`` sets it for you). Stashes the message ++ session_id as pending turn state, runs kickoff (which restores from+ persist and then applies the pending turn), and promotes the result to+ an assistant message when the handler didn't.++ Raises:+ ValueError: If the flow is not conversational. Without this the+ turn is a silent no-op: no route handlers are registered, the+ message is never appended, and ``None`` comes back."""+ if not self._is_conversational_enabled():+ raise ValueError(+ "Flow.handle_turn() is only available on conversational flows"+ )+state = cast(ConversationState, self.state)sid = session_id or state.idcrewai_event_bus.emit(diff --git a/lib/crewai/src/crewai/flow/conversational_definition.py b/lib/crewai/src/crewai/flow/conversational_definition.pyindex 75a4a689b..5cd7dd13f 100644--- a/lib/crewai/src/crewai/flow/conversational_definition.py+++ b/lib/crewai/src/crewai/flow/conversational_definition.py@@ -26,9 +26,21 @@ class FlowConversationalRouterDefinition(BaseModel):class FlowConversationalDefinition(BaseModel):- """Static conversational Flow configuration."""-- enabled: bool = False+ """Static conversational Flow configuration.++ The block is absent (``FlowDefinition.conversational is None``) on flows+ that are not conversational, so declaring it at all is the opt-in.+ """++ enabled: bool = Field(+ default=True,+ description=(+ "Whether conversational mode is active. Declaring the conversational "+ "block is the opt-in, so this defaults to true; set it to false to "+ "keep the configuration while turning chat off."+ ),+ examples=[True],+ )system_prompt: str | None = Nonellm: Any = Nonerouter: FlowConversationalRouterDefinition | None = Nonediff --git a/lib/crewai/tests/test_flow_conversation.py b/lib/crewai/tests/test_flow_conversation.pyindex 60d610e86..ce8f1293d 100644--- a/lib/crewai/tests/test_flow_conversation.py+++ b/lib/crewai/tests/test_flow_conversation.py@@ -2136,3 +2136,136 @@ class TestNestedCrewTracing:"nested AgentExecutor flows inside a deferred parent Flow must ""not finalize the parent trace batch")+++class TestConversationalOptIn:+ """``@ConversationConfig`` opts a Flow into conversational mode."""++ def test_decorator_alone_enables_conversational_mode(self) -> None:+ @ConversationConfig(llm="gpt-4o-mini")+ class DecoratedFlow(Flow[ConversationState]):+ @listen("order")+ def handle_order(self) -> str:+ """Order status questions."""+ return "on the way"++ definition = DecoratedFlow.flow_definition()++ assert definition.conversational is not None+ assert definition.conversational.enabled is True+ assert definition.conversational.llm == "gpt-4o-mini"++ def test_decorator_alone_registers_the_builtin_methods(self) -> None:+ @ConversationConfig()+ class DecoratedFlow(Flow[ConversationState]):+ pass++ methods = DecoratedFlow.flow_definition().methods++ assert "route_conversation" in methods+ assert methods["route_conversation"].start is True+ assert methods["route_conversation"].router is True+ assert "converse_turn" in methods+ assert "end_conversation" in methods++ def test_decorator_alone_runs_a_turn(self) -> None:+ @ConversationConfig()+ class DecoratedFlow(Flow[ConversationState]):+ @listen("converse")+ def converse_turn(self) -> str:+ return "handled"++ flow = DecoratedFlow()++ assert flow.handle_turn("hello") == "handled"+ assert [(m.role, m.content) for m in flow.state.messages] == [+ ("user", "hello"),+ ("assistant", "handled"),+ ]++ def test_decorator_alone_defers_trace_finalization(self) -> None:+ @ConversationConfig()+ class DecoratedFlow(Flow[ConversationState]):+ pass++ assert DecoratedFlow()._should_defer_trace_finalization() is True++ def test_explicit_flag_without_a_config_still_opts_in(self) -> None:+ class FlagOnlyFlow(Flow[ConversationState]):+ conversational = True++ definition = FlagOnlyFlow.flow_definition()++ assert definition.conversational is not None+ assert definition.conversational.enabled is True+ assert FlagOnlyFlow()._is_conversational_enabled() is True++ def test_flow_with_neither_stays_non_conversational(self) -> None:+ class PlainFlow(Flow):+ @start()+ def begin(self) -> str:+ return "begin"++ definition = PlainFlow.flow_definition()++ assert definition.conversational is None+ assert set(definition.methods) == {"begin"}+ assert PlainFlow.conversational is False++ def test_decorator_does_not_leak_the_flag_onto_other_flows(self) -> None:+ @ConversationConfig()+ class DecoratedFlow(Flow[ConversationState]):+ pass++ class LaterPlainFlow(Flow):+ @start()+ def begin(self) -> str:+ return "begin"++ assert DecoratedFlow.conversational is True+ assert LaterPlainFlow.conversational is False+ assert Flow.conversational is False+ assert LaterPlainFlow.flow_definition().conversational is None+++class TestHandleTurnGuard:+ """``handle_turn`` fails loudly on a non-conversational Flow."""++ def test_handle_turn_rejects_non_conversational_flows(self) -> None:+ class PlainFlow(Flow[ConversationState]):+ @start()+ def begin(self) -> str:+ return "begin"++ with pytest.raises(+ ValueError,+ match="Flow.handle_turn\\(\\) is only available on conversational flows",+ ):+ PlainFlow().handle_turn("hello")++ def test_handle_turn_guard_matches_chat_and_stream_turn(self) -> None:+ class PlainFlow(Flow[ConversationState]):+ @start()+ def begin(self) -> str:+ return "begin"++ flow = PlainFlow()++ for call in (+ lambda: flow.handle_turn("hi"),+ lambda: flow.stream_turn("hi"),+ flow.chat,+ ):+ with pytest.raises(+ ValueError, match="only available on conversational flows"+ ):+ call()++ def test_guard_does_not_fire_on_a_conversational_flow(self) -> None:+ @ConversationConfig()+ class DecoratedFlow(Flow[ConversationState]):+ @listen("converse")+ def converse_turn(self) -> str:+ return "ok"++ assert DecoratedFlow().handle_turn("hi") == "ok"diff --git a/lib/crewai/tests/test_flow_definition.py b/lib/crewai/tests/test_flow_definition.pyindex a87891318..8a714676d 100644--- a/lib/crewai/tests/test_flow_definition.py+++ b/lib/crewai/tests/test_flow_definition.py@@ -452,6 +452,67 @@ def test_flow_definition_uses_collapsed_conversational_router_start():assert methods["route_conversation"].router is True+def test_declaring_the_conversational_block_opts_in_without_enabled():+ definition = flow_definition.FlowDefinition.from_declaration(+ contents={+ "schema": "crewai.flow/v1",+ "name": "JsonChat",+ "conversational": {"llm": "gpt-4o-mini"},+ "methods": {+ "begin": {"do": {"call": "expression", "expr": "'x'"}, "start": True}+ },+ }+ )++ assert definition.conversational is not None+ assert definition.conversational.enabled is True+ assert definition.conversational.llm == "gpt-4o-mini"+++def test_conversational_block_can_be_explicitly_disabled():+ definition = flow_definition.FlowDefinition.from_declaration(+ contents={+ "schema": "crewai.flow/v1",+ "name": "JsonChat",+ "conversational": {"enabled": False, "llm": "gpt-4o-mini"},+ "methods": {+ "begin": {"do": {"call": "expression", "expr": "'x'"}, "start": True}+ },+ }+ )++ assert definition.conversational is not None+ assert definition.conversational.enabled is False+ assert definition.conversational.llm == "gpt-4o-mini"+++def test_omitting_the_conversational_block_leaves_it_none():+ definition = flow_definition.FlowDefinition.from_declaration(+ contents={+ "schema": "crewai.flow/v1",+ "name": "PlainJson",+ "methods": {+ "begin": {"do": {"call": "expression", "expr": "'x'"}, "start": True}+ },+ }+ )++ assert definition.conversational is None+++def test_flow_definition_includes_conversational_from_decorator_alone():+ @ConversationConfig(llm="gpt-4o-mini")+ class DecoratedFlow(Flow):+ pass++ definition = DecoratedFlow.flow_definition()++ assert definition.conversational is not None+ assert definition.conversational.enabled is True+ assert "route_conversation" in definition.methods+ assert "converse_turn" in definition.methods++def test_flow_definition_degrades_human_feedback_metadata(caplog):caplog.set_level(logging.WARNING, logger="crewai.flow.dsl._utils")marker = object()