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): 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.py
index 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, start
from 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, FlowMethodDefinition
from 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 | None
def _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 None
router_config = RouterConfig()
@@ -779,31 +843,63 @@ class _ConversationalMixin:
@property
def _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 None
initial_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 None
def _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, False
route_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 caller
eventually 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_routes
def _default_conversation_llm(self) -> Any | None:
config = self._conversation_config
diff --git a/lib/crewai/tests/test_flow_conversation.py b/lib/crewai/tests/test_flow_conversation.py
index 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 logging
from typing import Any, ClassVar, Literal
from unittest.mock import MagicMock, patch
from 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."