Skip to content

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.py
index 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 = True
def __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 = True
return flow_cls
diff --git a/lib/crewai/src/crewai/experimental/conversational_mixin.py b/lib/crewai/src/crewai/experimental/conversational_mixin.py
index 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 before
the 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.id
crewai_event_bus.emit(
diff --git a/lib/crewai/src/crewai/flow/conversational_definition.py b/lib/crewai/src/crewai/flow/conversational_definition.py
index 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 = None
llm: Any = None
router: FlowConversationalRouterDefinition | None = None
diff --git a/lib/crewai/tests/test_flow_conversation.py b/lib/crewai/tests/test_flow_conversation.py
index 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.py
index 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()