Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.
feat(flow): let a declaration drive conversational mode (#7032)
João Moura6f16e741aa80
diff --git a/lib/crewai/src/crewai/experimental/conversational_mixin.py b/lib/crewai/src/crewai/experimental/conversational_mixin.pyindex 3a47cd480..17bbbd9f2 100644--- a/lib/crewai/src/crewai/experimental/conversational_mixin.py+++ b/lib/crewai/src/crewai/experimental/conversational_mixin.py@@ -51,9 +51,13 @@ from crewai.flow.conversation import (get_conversation_messages,receive_user_message as _receive_user_message,)+from crewai.flow.conversational_definition import (+ FlowConversationalDefinition,+ FlowConversationalRouterDefinition,+)from crewai.flow.dsl import listen, startfrom crewai.flow.dsl._utils import _method_action, _set_flow_method_definition-from crewai.flow.flow_definition import FlowMethodDefinition+from crewai.flow.flow_definition import FlowDefinition, FlowMethodDefinitionfrom crewai.utilities.types import LLMMessage@@ -79,6 +83,63 @@ def _iter_condition_labels(condition: Any) -> set[str]:return set()+def _router_config_from_definition(+ definition: FlowConversationalRouterDefinition,+) -> RouterConfig:+ """Build a live ``RouterConfig`` from its serializable form."""+ response_format = definition.response_format+ if response_format is not None and not (+ isinstance(response_format, type) and issubclass(response_format, BaseModel)+ ):+ # A declaration can only carry a ``module:qualname`` ref or a schema+ # dict here, and ``_router_response_format`` hands its result straight+ # to ``llm.call(response_format=...)``, which needs a real class.+ # Dropping it falls back to the synthesized single-field model.+ logger.warning(+ "Ignoring conversational router response_format %r: a declaration "+ "cannot carry a model class. The router will use its synthesized "+ "response format instead.",+ response_format,+ )+ response_format = None++ return RouterConfig(+ prompt=definition.prompt,+ response_format=response_format,+ llm=definition.llm,+ routes=definition.routes,+ route_descriptions=definition.route_descriptions,+ default_intent=definition.default_intent,+ fallback_intent=definition.fallback_intent,+ intent_field=definition.intent_field,+ )+++def _config_from_definition(+ definition: FlowConversationalDefinition,+) -> ConversationConfig:+ """Build a live ``ConversationConfig`` from its serializable form.++ Used for flows built from a declaration, which have no class-level+ ``conversational_config`` to read.+ """+ return ConversationConfig(+ system_prompt=definition.system_prompt,+ llm=definition.llm,+ router=(+ _router_config_from_definition(definition.router)+ if definition.router is not None+ else None+ ),+ answer_from_history_prompt=definition.answer_from_history_prompt,+ default_intents=definition.default_intents,+ intent_llm=definition.intent_llm,+ answer_from_history_llm=definition.answer_from_history_llm,+ visible_agent_outputs=definition.visible_agent_outputs,+ defer_trace_finalization=definition.defer_trace_finalization,+ )++def _conversation_start_router(func: Callable[..., Any]) -> Any:wrapper = start()(func)_set_flow_method_definition(@@ -135,6 +196,7 @@ class _ConversationalMixin:_pending_intent_llm: str | BaseLLM | None_turn_classified_intent: str | None_assistant_reply_appended: bool+ _resolved_conversation_config: ConversationConfig | Nonedef _clear_or_listeners(self) -> None:pass@@ -587,7 +649,9 @@ class _ConversationalMixin:if router_config is None:if config.default_intents:return None- custom_routes = self._effective_routes(None) - set(self.builtin_routes)+ custom_routes = (+ self._effective_routes(None) - self._effective_builtin_routes()+ )if not custom_routes:return Nonerouter_config = RouterConfig()@@ -779,31 +843,63 @@ class _ConversationalMixin:@propertydef _conversation_config(self) -> ConversationConfig | None:- return getattr(type(self), "conversational_config", None)+ """Resolve the live conversational configuration for this flow.++ The class-level ``conversational_config`` wins when present: it can+ hold live objects — a configured ``LLM``, a custom ``BaseLLM``, a+ ``response_format`` model class — that the serializable definition+ degrades to a config dict or a ``module:qualname`` ref. Reading the+ definition first would silently downgrade every decorated Python flow.++ A flow built from a declaration has no class config, so its+ ``conversational`` block supplies one.+ """+ config: ConversationConfig | None = getattr(+ type(self), "conversational_config", None+ )+ if config is not None:+ return config++ # Cached so the resolved config has stable identity, matching the+ # class-config path. Callers read it many times per turn and a fresh+ # object each time would make `config.llm is llm` false.+ resolved: ConversationConfig | None = getattr(+ self, "_resolved_conversation_config", None+ )+ if resolved is not None:+ return resolved++ definition = self._conversation_definition+ if definition is None or not definition.enabled:+ return None++ resolved = _config_from_definition(definition)+ object.__setattr__(self, "_resolved_conversation_config", resolved)+ return resolved@property- def _conversation_definition(self) -> Any | None:+ def _conversation_definition(self) -> FlowConversationalDefinition | None:return self._conversation_flow_definition().conversational- def _conversation_flow_definition(self) -> Any:+ def _conversation_flow_definition(self) -> FlowDefinition:+ """Return the definition that describes this flow's methods.++ Prefers the instance definition, which is the loaded declaration for a+ flow built with ``from_declaration`` and the class projection+ otherwise. Falls back to the class projection while ``_definition`` is+ still unset — ``_initialize_runtime_extension_attrs`` runs one step+ before it is assigned in ``_flow_post_init``.+ """+ definition: FlowDefinition | None = getattr(self, "_definition", None)+ if definition is not None:+ return definition+flow_definition = getattr(type(self), "flow_definition", None)if not callable(flow_definition):raise AttributeError(f"{type(self).__name__} does not expose flow_definition()")- return flow_definition()-- @classmethod- def _conversational_definition(cls) -> Any | None:- flow_definition = getattr(cls, "flow_definition", None)- if not callable(flow_definition):- return None- return flow_definition().conversational-- @classmethod- def _is_conversational(cls) -> bool:- definition = cls._conversational_definition()- return bool(definition and definition.enabled)+ return cast(FlowDefinition, flow_definition())def _is_conversational_enabled(self) -> bool:definition = self._conversation_definition@@ -824,19 +920,30 @@ class _ConversationalMixin:object.__setattr__(self, "_turn_classified_intent", None)if not hasattr(self, "_assistant_reply_appended"):object.__setattr__(self, "_assistant_reply_appended", False)+ if not hasattr(self, "_resolved_conversation_config"):+ object.__setattr__(self, "_resolved_conversation_config", None)def _create_default_extension_state(self) -> ConversationState | None:+ """Supply ``ConversationState`` only when nothing else declares state.++ A declared ``state:`` block always wins. This hook is consulted before+ ``_create_definition_state``, so returning a state here would discard+ every field the declaration asked for.+ """+ if not self._is_conversational_enabled():+ return None+ if self._conversation_flow_definition().state is not None:+ return Noneinitial_state_t = getattr(self, "_initial_state_t", None)- if type(self)._is_conversational() and (- not hasattr(self, "_initial_state_t")- or isinstance(initial_state_t, TypeVar)+ if not hasattr(self, "_initial_state_t") or isinstance(+ initial_state_t, TypeVar):return ConversationState()return Nonedef _should_apply_pending_kickoff_context(self) -> bool:return (- type(self)._is_conversational() and self._pending_user_message is not None+ self._is_conversational_enabled() and self._pending_user_message is not None)def _apply_pending_kickoff_context(self) -> None:@@ -846,7 +953,7 @@ class _ConversationalMixin:self,start_methods: list[Any],) -> tuple[list[Any], bool]:- if not type(self)._is_conversational():+ if not self._is_conversational_enabled():return start_methods, Falseroute_conversation = "route_conversation"@@ -868,17 +975,23 @@ class _ConversationalMixin:True when either:- ``flow.defer_trace_finalization`` is set on the instance, OR- - the static conversational definition enables deferred finalization.+ - the resolved conversational configuration enables it.Either source enables the deferred-session pattern. The callereventually invokes ``finalize_session_traces()`` to close the batch.++ Read through ``_conversation_config`` rather than the definition so+ deferral follows the same precedence as every other behavior knob. A+ class config and a declaration can disagree on the hybrid+ ``ClassWithConfig.from_declaration(...)`` path, and deferral must not+ be the one setting that follows the other source."""if getattr(self, "defer_trace_finalization", False):return True- definition = self._conversation_definition- return bool(- definition and definition.enabled and definition.defer_trace_finalization- )+ if not self._is_conversational_enabled():+ return False+ config = self._conversation_config+ return bool(config and config.defer_trace_finalization)def _reset_turn_execution_state(self) -> None:"""Clear per-execution tracking so the next turn re-runs the graph."""@@ -1101,24 +1214,35 @@ class _ConversationalMixin:labels.update(_iter_condition_labels(method_definition.listen))return labels+ def _effective_builtin_routes(self) -> set[str]:+ """Route labels the framework handles, from the definition when there is one.++ Shared with ``route_turn`` so both agree on what counts as a custom+ route. Reading the class attribute in one place and the definition in+ the other lets a declaration that customizes ``builtin_routes`` look+ like it declared a custom route, which auto-enables the LLM router.+ """+ definition = self._conversation_definition+ if definition is not None:+ return set(definition.builtin_routes)+ return set(self.builtin_routes)++ def _effective_internal_routes(self) -> set[str]:+ definition = self._conversation_definition+ if definition is not None:+ return set(definition.internal_routes)+ return set(self.internal_routes)+def _effective_routes(self, router_config: RouterConfig | None = None) -> set[str]:custom_routes = set(router_config.routes or ()) if router_config else set()- definition = self._conversation_definition- builtin_routes = (- tuple(definition.builtin_routes)- if definition is not None- else self.builtin_routes- )- internal_routes = (- tuple(definition.internal_routes)- if definition is not None- else self.internal_routes- )+ builtin_routes = self._effective_builtin_routes()if not custom_routes:custom_routes = (- self._valid_route_labels() - set(builtin_routes) - set(internal_routes)+ self._valid_route_labels()+ - builtin_routes+ - self._effective_internal_routes())- return custom_routes | set(builtin_routes)+ return custom_routes | builtin_routesdef _default_conversation_llm(self) -> Any | None:config = self._conversation_configdiff --git a/lib/crewai/tests/test_flow_conversation.py b/lib/crewai/tests/test_flow_conversation.pyindex ce8f1293d..7982eb72f 100644--- a/lib/crewai/tests/test_flow_conversation.py+++ b/lib/crewai/tests/test_flow_conversation.py@@ -2,6 +2,7 @@from __future__ import annotations+import loggingfrom typing import Any, ClassVar, Literalfrom unittest.mock import MagicMock, patchfrom uuid import uuid4@@ -2269,3 +2270,320 @@ class TestHandleTurnGuard:return "ok"assert DecoratedFlow().handle_turn("hi") == "ok"+++_MIXIN = "crewai.experimental.conversational_mixin:_ConversationalMixin"+++class DeclaredChatState(ConversationState):+ """Module-level so ``state.ref`` can import it; a locals-scoped class cannot."""++ ticket_id: str | None = None+++class _ScriptedLLM(BaseLLM):+ """Fake LLM returning queued responses; records the messages it saw."""++ def __init__(self, responses: list[str] | None = None) -> None:+ super().__init__(model="fake")+ object.__setattr__(self, "_responses", list(responses or []))+ object.__setattr__(self, "seen", [])++ def call(self, messages, **kwargs) -> str: # type: ignore[no-untyped-def]+ self.seen.append(messages)+ return self._responses.pop(0) if self._responses else "fallback"++ def supports_function_calling(self) -> bool:+ return False++ def supports_stop_words(self) -> bool:+ return False++ def get_context_window_size(self) -> int:+ return 8192+++def _conversational_declaration(**overrides: Any) -> dict[str, Any]:+ """A declaration naming the built-in methods explicitly.++ Synthesizing these entries from ``conversational.enabled`` is a follow-up;+ until then a declaration has to name them.+ """+ declaration: dict[str, Any] = {+ "schema": "crewai.flow/v1",+ "name": "DeclaredChat",+ "state": {+ "type": "pydantic",+ "ref": "crewai.experimental.conversational:ConversationState",+ },+ "conversational": {},+ "methods": {+ "route_conversation": {+ "do": {"call": "code", "ref": f"{_MIXIN}.route_conversation"},+ "start": True,+ "router": True,+ },+ "converse_turn": {+ "do": {"call": "code", "ref": f"{_MIXIN}.converse_turn"},+ "listen": "converse",+ },+ "end_conversation": {+ "do": {"call": "code", "ref": f"{_MIXIN}.end_conversation"},+ "listen": "end",+ },+ },+ }+ declaration.update(overrides)+ return declaration+++class TestDeclarativeConversationalFlow:+ """A declaration's ``conversational`` block drives the runtime."""++ def test_declaration_enables_conversational_mode(self) -> None:+ flow = Flow.from_declaration(contents=_conversational_declaration())++ assert flow._is_conversational_enabled() is True++ def test_declaration_with_enabled_false_stays_non_conversational(self) -> None:+ flow = Flow.from_declaration(+ contents=_conversational_declaration(conversational={"enabled": False})+ )++ assert flow._is_conversational_enabled() is False++ def test_declared_route_labels_reach_the_router_catalog(self) -> None:+ declaration = _conversational_declaration()+ declaration["methods"]["handle_order"] = {+ "do": {"call": "expression", "expr": "'shipped'"},+ "listen": "order",+ "description": "Order status questions.",+ }++ flow = Flow.from_declaration(contents=declaration)++ assert "order" in flow._valid_route_labels()+ assert "order" in flow._effective_routes()++ def test_declaration_runs_a_turn_and_accumulates_history(self) -> None:+ declaration = _conversational_declaration(+ conversational={"system_prompt": "You are terse."}+ )+ chat = _ScriptedLLM(["Hi there.", "Anything else?"])+ flow = Flow.from_declaration(contents=declaration)+ flow._conversation_config.llm = chat++ assert flow.handle_turn("hello") == "Hi there."+ assert flow.handle_turn("thanks") == "Anything else?"+ assert [(m.role, m.content) for m in flow.state.messages] == [+ ("user", "hello"),+ ("assistant", "Hi there."),+ ("user", "thanks"),+ ("assistant", "Anything else?"),+ ]+ assert chat.seen[-1][0] == {"role": "system", "content": "You are terse."}++ def test_declaration_drives_deferred_trace_finalization(self) -> None:+ deferred = Flow.from_declaration(contents=_conversational_declaration())+ not_deferred = Flow.from_declaration(+ contents=_conversational_declaration(+ conversational={"defer_trace_finalization": False}+ )+ )++ assert deferred._should_defer_trace_finalization() is True+ assert not_deferred._should_defer_trace_finalization() is False++ def test_declaration_orders_the_router_last_and_sequentially(self) -> None:+ flow = Flow.from_declaration(contents=_conversational_declaration())++ ordered, sequential = flow._order_start_methods_for_kickoff(+ ["bootstrap", "route_conversation"]+ )++ assert ordered == ["bootstrap", "route_conversation"]+ assert sequential is True++ def test_router_response_format_ref_is_dropped_with_a_warning(self, caplog) -> None:+ caplog.set_level(+ logging.WARNING, logger="crewai.experimental.conversational_mixin"+ )+ flow = Flow.from_declaration(+ contents=_conversational_declaration(+ conversational={+ "router": {"response_format": {"ref": "some.module:Schema"}}+ }+ )+ )++ assert flow._conversation_config.router.response_format is None+ assert "cannot carry a model class" in caplog.text+++class TestBuiltinRouteResolution:+ """``route_turn`` and ``_effective_routes`` agree on what is built in."""++ @staticmethod+ def _flow(builtin: list[str]) -> Flow[Any]:+ return Flow.from_declaration(+ contents=_conversational_declaration(+ conversational={"builtin_routes": builtin}+ )+ )++ def test_declared_builtin_routes_are_not_mistaken_for_custom_ones(self) -> None:+ """A declaration adding a builtin route must not auto-enable the router.++ ``route_turn`` used to subtract the class attribute while+ ``_effective_routes`` used the declaration, so an added builtin looked+ like a custom route and turned the LLM router on for every turn.+ """+ flow = self._flow(["converse", "end", "greet"])++ assert flow._effective_builtin_routes() == {"converse", "end", "greet"}+ assert flow.route_turn(flow.build_router_context()) is None++ def test_a_real_custom_route_still_auto_enables_the_router(self) -> None:+ declaration = _conversational_declaration(conversational={})+ declaration["methods"]["handle_order"] = {+ "do": {"call": "expression", "expr": "'shipped'"},+ "listen": "order",+ }+ flow = Flow.from_declaration(contents=declaration)+ flow._conversation_config.llm = _ScriptedLLM(['{"intent": "order"}'])++ assert "order" in flow._effective_routes(None) - flow._effective_builtin_routes()+ assert flow.route_turn(flow.build_router_context()) == "order"++ def test_class_based_flow_falls_back_to_its_class_attributes(self) -> None:+ @ConversationConfig()+ class ClassChat(Flow[ConversationState]):+ pass++ flow = ClassChat()++ assert flow._effective_builtin_routes() == set(flow.builtin_routes)+ assert flow._effective_internal_routes() == set(flow.internal_routes)+++class TestConversationalStatePrecedence:+ """A declared ``state:`` block is never replaced by the default."""++ def test_declared_state_survives_on_both_paths(self) -> None:+ class SubclassChat(Flow):+ conversational = True++ declaration = _conversational_declaration(+ state={"type": "pydantic", "ref": f"{__name__}:DeclaredChatState"}+ )++ for cls in (Flow, SubclassChat):+ state = cls.from_declaration(contents=declaration).state++ assert "ticket_id" in type(state).model_fields, cls.__name__+ assert "messages" in type(state).model_fields, cls.__name__++ def test_conversation_state_is_implied_when_none_declared(self) -> None:+ declaration = _conversational_declaration()+ del declaration["state"]++ flow = Flow.from_declaration(contents=declaration)++ assert isinstance(flow.state, ConversationState)++ def test_non_conversational_declaration_keeps_its_state(self) -> None:+ flow = Flow.from_declaration(+ contents={+ "schema": "crewai.flow/v1",+ "name": "Plain",+ "state": {"type": "dict", "default": {"topic": "ai"}},+ "methods": {+ "begin": {+ "do": {"call": "expression", "expr": "state.topic"},+ "start": True,+ }+ },+ }+ )++ assert flow.state["topic"] == "ai"+++class TestClassConfigStillWins:+ """Existing decorated Python flows keep their live objects."""++ def test_live_llm_object_is_not_downgraded_by_the_definition(self) -> None:+ llm = _ScriptedLLM(["from the live object"])++ @ConversationConfig(llm=llm)+ class LiveLLMFlow(ConversationalFlow):+ pass++ flow = LiveLLMFlow()++ assert flow._conversation_config.llm is llm+ assert flow.handle_turn("hello") == "from the live object"++ def test_live_router_response_format_is_not_downgraded(self) -> None:+ class MyRoute(BaseModel):+ intent: str++ @ConversationConfig(router=RouterConfig(response_format=MyRoute))+ class LiveFormatFlow(ConversationalFlow):+ pass++ assert LiveFormatFlow()._conversation_config.router.response_format is MyRoute++ def test_defer_trace_finalization_follows_the_class_config(self) -> None:+ """Deferral is a behavior knob, so it follows the same precedence.++ The class config and the declaration can disagree on the hybrid path;+ every other setting follows the class config, and this must too.+ """++ @ConversationConfig(defer_trace_finalization=False)+ class ConfiguredChat(Flow):+ conversational = True++ flow = ConfiguredChat.from_declaration(+ contents=_conversational_declaration(conversational={})+ )++ assert flow._conversation_definition.defer_trace_finalization is True+ assert flow._conversation_config.defer_trace_finalization is False+ assert flow._should_defer_trace_finalization() is False++ def test_instance_flag_still_forces_deferral(self) -> None:+ @ConversationConfig(defer_trace_finalization=False)+ class ConfiguredChat(Flow):+ conversational = True++ flow = ConfiguredChat()+ assert flow._should_defer_trace_finalization() is False++ flow.defer_trace_finalization = True+ assert flow._should_defer_trace_finalization() is True++ def test_non_conversational_flow_never_defers_from_config(self) -> None:+ class PlainFlow(Flow):+ @start()+ def begin(self) -> str:+ return "begin"++ assert PlainFlow()._should_defer_trace_finalization() is False++ def test_class_config_wins_over_a_declaration_block(self) -> None:+ llm = _ScriptedLLM(["from the class config"])++ @ConversationConfig(llm=llm, system_prompt="From the class.")+ class ConfiguredChat(Flow):+ conversational = True++ flow = ConfiguredChat.from_declaration(+ contents=_conversational_declaration(+ conversational={"system_prompt": "From the declaration."}+ )+ )++ assert flow._conversation_config.llm is llm+ assert flow._conversation_config.system_prompt == "From the class."