Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.
decouple convo logic from runtime and added a conversational_definition (#6091)
Lorenze Jayf214ff4b7bf4
diff --git a/lib/crewai/src/crewai/experimental/conversational_mixin.py b/lib/crewai/src/crewai/experimental/conversational_mixin.pyindex 862706a88..46e83134b 100644--- a/lib/crewai/src/crewai/experimental/conversational_mixin.py+++ b/lib/crewai/src/crewai/experimental/conversational_mixin.py@@ -1,15 +1,17 @@-"""Conversational graph + helpers as a mixin for ``Flow`` (experimental).+"""Conversational graph + helpers as an experimental Flow extension.-The experimental conversational chat surface lives here as a mixin so that-``crewai.flow.runtime`` stays focused on the execution engine. ``Flow``-inherits from ``_ConversationalMixin``; the methods only register on-subclasses that opt in via ``conversational = True`` (enforced by the-``_conversational_only`` marker + ``FlowMeta`` gating in-``crewai.flow.runtime``).+The conversational chat surface remains experimental and may change before the+v2 graduation path. It lives here so ``crewai.flow.runtime`` can stay focused+on the execution engine. ``crewai.flow.flow`` composes this mixin onto the+public ``Flow`` class for backwards compatibility.++The built-in conversational graph only registers for subclasses that opt in+with ``conversational = True``. Static conversational metadata is projected+into ``FlowDefinition.conversational`` via the Python DSL builder.Import surface:- - :class:`_ConversationalMixin` — internal; ``Flow`` mixes it in. Users- don't import it directly.+ - :class:`_ConversationalMixin` — internal; the public ``Flow`` class+ composes it in. Users don't import it directly.- The data types this mixin uses live in:mod:`crewai.experimental.conversational`."""@@ -20,7 +22,7 @@ from collections.abc import Callable, Mapping, Sequencefrom enum import Enumimport jsonimport logging-from typing import TYPE_CHECKING, Any, ClassVar, Literal, cast+from typing import TYPE_CHECKING, Any, ClassVar, Literal, TypeVar, castfrom pydantic import BaseModel, Field, create_model@@ -49,21 +51,56 @@ from crewai.utilities.types import LLMMessageif TYPE_CHECKING:- from crewai.flow.runtime import Flowfrom crewai.llms.base_llm import BaseLLMlogger = logging.getLogger(__name__)+def _iter_condition_labels(condition: Any) -> set[str]:+ if isinstance(condition, str):+ return {condition}+ if isinstance(condition, dict):+ labels: set[str] = set()+ for value in condition.values():+ if isinstance(value, list):+ for item in value:+ labels.update(_iter_condition_labels(item))+ else:+ labels.update(_iter_condition_labels(value))+ return labels+ return set()++class _ConversationalMixin:- """Built-in conversational graph for ``Flow`` (gated on ``conversational``).+ """Experimental conversational graph for ``Flow``.- Mixed into ``Flow`` so its execution engine (``runtime.py``) stays focused- on running graphs. The methods here only register on subclasses that set- ``conversational = True``; non-chat flows see them as inert attributes.+ This mixin owns chat behavior and runtime hooks. Non-chat flows see these+ methods as inert attributes unless they opt in with ``conversational = True``."""+ # === EXPERIMENTAL: conversational mode ===+ # When ``conversational = True`` on a Flow subclass, this mixin's built-in+ # graph registers and ``handle_turn`` / ``chat`` become chat entry points.+ conversational: ClassVar[bool] = False+ conversational_config: ClassVar[ConversationConfig | None] = None+ builtin_routes: ClassVar[tuple[str, ...]] = ("converse", "end")+ internal_routes: ClassVar[tuple[str, ...]] = (+ "answer_from_history",+ "conversation_start",+ )+ builtin_route_descriptions: ClassVar[dict[str, str]] = {+ "converse": (+ "Ordinary chat, follow-ups, summaries, clarifications, and "+ "questions answerable from prior conversation history."+ ),+ "end": ("User signals the conversation is finished (goodbye, exit, done)."),+ "answer_from_history": (+ "Answer directly from prior conversation history without invoking "+ "tools, agents, or custom routes."+ ),+ }+# The metaclass + state attributes referenced below live on ``Flow`` —# this mixin is never instantiated standalone. These type-only# declarations exist so static analyzers don't flag attribute access.@@ -71,14 +108,6 @@ class _ConversationalMixin:# (otherwise mypy flags "Cannot override instance variable with class# variable" when Flow declares them as ``ClassVar``).if TYPE_CHECKING:- conversational: ClassVar[bool]- conversational_config: ClassVar[ConversationConfig | None]- builtin_routes: ClassVar[tuple[str, ...]]- internal_routes: ClassVar[tuple[str, ...]]- builtin_route_descriptions: ClassVar[dict[str, str]]- # Registry ClassVars populated by ``FlowMeta`` at class creation.- _listeners: ClassVar[dict[Any, Any]]-# Instance attrs from ``Flow``.state: Anyname: str | None@@ -87,6 +116,7 @@ class _ConversationalMixin:_pending_events: dict[Any, Any]_method_call_counts: dict[Any, int]_is_execution_resuming: bool+ _conversation_messages: list[LLMMessage]_pending_user_message: str | dict[str, Any] | None_pending_intents: Sequence[str] | None_pending_intent_llm: str | BaseLLM | None@@ -97,8 +127,8 @@ class _ConversationalMixin:def _collapse_to_outcome(self,feedback: str,- outcomes: tuple[str, ...],- llm: str | BaseLLM | Any,+ outcomes: Sequence[str],+ llm: str | BaseLLM,) -> str:pass@@ -238,8 +268,8 @@ class _ConversationalMixin:state = cast(ConversationState, self.state)sid = session_id or state.id- # Stash the pending turn so ``_apply_pending_conversational_turn``- # picks it up AFTER persist restore.+ # Stash the pending turn so the kickoff extension hook picks it up+ # after persist restore.self._pending_user_message = messageself._pending_intents = list(intents) if intents else Noneself._pending_intent_llm = intent_llm@@ -286,7 +316,7 @@ class _ConversationalMixin:callers can customize prompts or exercise the loop without patchingbuiltins."""- if not getattr(type(self), "conversational", False):+ if not self._is_conversational_enabled():raise ValueError("Flow.chat() is only available on conversational flows")exit_set = {command.lower() for command in exit_commands}@@ -491,14 +521,14 @@ class _ConversationalMixin:**extra: Any,) -> None:"""Append a message to conversation history (legacy ChatState path)."""- _append_conversation_message(cast("Flow[Any]", self), role, content, **extra)+ _append_conversation_message(cast(Any, self), role, content, **extra)@propertydef conversation_messages(self) -> list[LLMMessage]:"""Message history from state, coerced to LLM-shaped dicts."""return [message_to_llm_dict(message)- for message in get_conversation_messages(cast("Flow[Any]", self))+ for message in get_conversation_messages(cast(Any, self))]def receive_user_message(@@ -514,7 +544,7 @@ class _ConversationalMixin:``state.messages`` and preserve ``last_intent`` across turns.Non-conversational flows fall through to the legacy helper."""- if self.conversational:+ if self._is_conversational_enabled():state = cast(ConversationState, self.state)state.messages.append(ConversationMessage(role="user", content=text))self._emit_conversation_message_added(@@ -535,9 +565,7 @@ class _ConversationalMixin:return intentreturn text- return _receive_user_message(- cast("Flow[Any]", self), text, outcomes=outcomes, llm=llm- )+ return _receive_user_message(cast(Any, self), text, outcomes=outcomes, llm=llm)def classify_intent(self,@@ -561,21 +589,98 @@ class _ConversationalMixin:def _conversation_config(self) -> ConversationConfig | None:return getattr(type(self), "conversational_config", None)+ @property+ def _conversation_definition(self) -> Any | None:+ return self._conversation_flow_definition().conversational++ def _conversation_flow_definition(self) -> Any:+ 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)++ def _is_conversational_enabled(self) -> bool:+ definition = self._conversation_definition+ return bool(definition and definition.enabled)++ def _initialize_runtime_extension_attrs(self) -> None:+ if not isinstance(getattr(self, "_conversation_messages", None), list):+ object.__setattr__(self, "_conversation_messages", [])+ if not hasattr(self, "_pending_user_message"):+ object.__setattr__(self, "_pending_user_message", None)+ if not hasattr(self, "_pending_intents"):+ object.__setattr__(self, "_pending_intents", None)+ if not hasattr(self, "_pending_intent_llm"):+ object.__setattr__(self, "_pending_intent_llm", None)++ def _create_default_extension_state(self) -> ConversationState | 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)+ ):+ 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+ )++ def _apply_pending_kickoff_context(self) -> None:+ self._apply_pending_conversational_turn()++ def _order_start_methods_for_kickoff(+ self,+ start_methods: list[Any],+ ) -> tuple[list[Any], bool]:+ if not type(self)._is_conversational():+ return start_methods, False++ conversation_start = "conversation_start"+ if conversation_start not in {str(method) for method in start_methods}:+ return start_methods, False++ ordered_starts = [+ method for method in start_methods if str(method) != conversation_start+ ]+ ordered_starts.append(+ next(+ method for method in start_methods if str(method) == conversation_start+ )+ )+ return ordered_starts, True+def _should_defer_trace_finalization(self) -> bool:"""Whether per-turn ``FlowFinished`` + ``finalize_batch`` should be skipped.True when either:- ``flow.defer_trace_finalization`` is set on the instance, OR- - the class-level ``ConversationConfig.defer_trace_finalization``- on a conversational subclass is True.+ - the static conversational definition enables deferred finalization.Either source enables the deferred-session pattern. The callereventually invokes ``finalize_session_traces()`` to close the batch."""if getattr(self, "defer_trace_finalization", False):return True- config = self._conversation_config- return bool(config and config.defer_trace_finalization)+ definition = self._conversation_definition+ return bool(+ definition and definition.enabled and definition.defer_trace_finalization+ )def _reset_turn_execution_state(self) -> None:"""Clear per-execution tracking so the next turn re-runs the graph."""@@ -733,11 +838,12 @@ class _ConversationalMixin:router_config: RouterConfig | None,) -> dict[str, str]:label_to_method: dict[str, str] = {}- for listener_name, condition in self._listeners.items():- if isinstance(condition, tuple):- _, trigger_labels = condition- for trigger_label in trigger_labels:- label_to_method.setdefault(str(trigger_label), str(listener_name))+ flow_definition = self._conversation_flow_definition()+ for listener_name, method_definition in flow_definition.methods.items():+ if method_definition.listen is None or method_definition.router:+ continue+ for trigger_label in _iter_condition_labels(method_definition.listen):+ label_to_method.setdefault(trigger_label, listener_name)routes = self._effective_routes(router_config)overrides = (@@ -788,21 +894,31 @@ class _ConversationalMixin:def _valid_route_labels(self) -> set[str]:labels: set[str] = set()- for condition in self._listeners.values():- if isinstance(condition, tuple):- _, methods = condition- labels.update(str(method) for method in methods)+ flow_definition = self._conversation_flow_definition()+ for method_definition in flow_definition.methods.values():+ if method_definition.listen is None or method_definition.router:+ continue+ labels.update(_iter_condition_labels(method_definition.listen))return labelsdef _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+ )if not custom_routes:custom_routes = (- self._valid_route_labels()- - set(self.builtin_routes)- - set(self.internal_routes)+ self._valid_route_labels() - set(builtin_routes) - set(internal_routes))- return custom_routes | set(self.builtin_routes)+ return custom_routes | set(builtin_routes)def _default_conversation_llm(self) -> Any | None:config = self._conversation_configdiff --git a/lib/crewai/src/crewai/flow/conversational_definition.py b/lib/crewai/src/crewai/flow/conversational_definition.pynew file mode 100644index 000000000..8673bbb3a--- /dev/null+++ b/lib/crewai/src/crewai/flow/conversational_definition.py@@ -0,0 +1,50 @@+"""Static conversational Flow definition models.++This module is part of the serializable Flow Definition contract. It should+only contain static data shapes. Experimental conversational runtime behavior+continues to live in ``crewai.experimental.conversational_mixin``.+"""++from __future__ import annotations++from typing import Any, Literal++from pydantic import BaseModel, Field+++class FlowConversationalRouterDefinition(BaseModel):+ """Static conversational router configuration."""++ prompt: str | None = None+ response_format: Any = None+ llm: Any = None+ routes: list[str] | None = None+ route_descriptions: dict[str, str] | None = None+ default_intent: str | None = "converse"+ fallback_intent: str | None = "converse"+ intent_field: str = "intent"+++class FlowConversationalDefinition(BaseModel):+ """Static conversational Flow configuration."""++ enabled: bool = False+ system_prompt: str | None = None+ llm: Any = None+ router: FlowConversationalRouterDefinition | None = None+ answer_from_history_prompt: str | None = None+ default_intents: list[str] | None = None+ intent_llm: Any = None+ answer_from_history_llm: Any = None+ visible_agent_outputs: list[str] | Literal["all"] | None = None+ defer_trace_finalization: bool = True+ builtin_routes: list[str] = Field(default_factory=lambda: ["converse", "end"])+ internal_routes: list[str] = Field(+ default_factory=lambda: ["answer_from_history", "conversation_start"]+ )+++__all__ = [+ "FlowConversationalDefinition",+ "FlowConversationalRouterDefinition",+]diff --git a/lib/crewai/src/crewai/flow/dsl/_utils.py b/lib/crewai/src/crewai/flow/dsl/_utils.pyindex 21b9b4477..c4b9a4c92 100644--- a/lib/crewai/src/crewai/flow/dsl/_utils.py+++ b/lib/crewai/src/crewai/flow/dsl/_utils.py@@ -9,6 +9,8 @@ from typing_extensions import TypeIsfrom crewai.flow.flow_definition import (FlowConfigDefinition,+ FlowConversationalDefinition,+ FlowConversationalRouterDefinition,FlowDefinition,FlowDefinitionDiagnostic,FlowHumanFeedbackDefinition,@@ -27,6 +29,13 @@ R = TypeVar("R")logger = logging.getLogger(__name__)_FLOW_METHOD_DEFINITION_ATTR = "__flow_method_definition__"+_FLOW_METHOD_METADATA_ATTRS = [+ "__conversational_only__",+ "__flow_method_definition__",+ "__flow_persistence_config__",+ "__human_feedback_config__",+ "_human_feedback_llm",+]def is_flow_method(obj: Any) -> TypeIs[FlowMethod[Any, Any]]:@@ -42,6 +51,39 @@ def _should_include_flow_method(flow_class: type, method: Any) -> bool:return True+def _is_conversational_flow(flow_class: type) -> bool:+ return bool(getattr(flow_class, "conversational", False))+++def _get_inherited_conversational_method(+ flow_class: type,+ attr_name: str,+) -> Any | None:+ if not _is_conversational_flow(flow_class):+ return None++ for base in flow_class.__mro__[1:]:+ inherited = base.__dict__.get(attr_name)+ if inherited is None:+ continue+ if getattr(inherited, "__conversational_only__", False) and is_flow_method(+ inherited+ ):+ return inherited+ return None+++def _stamp_inherited_conversational_metadata(+ method: Any,+ inherited: Any,+) -> Any:+ for attr in _FLOW_METHOD_METADATA_ATTRS:+ if hasattr(inherited, attr):+ setattr(method, attr, getattr(inherited, attr))+ method.__is_flow_method__ = True+ return method++def _set_flow_method_definition(wrapper: FlowMethod[P, R],definition: FlowMethodDefinition,@@ -135,6 +177,8 @@ def _build_state_definition(from pydantic import BaseModel as PydanticBaseModelstate_value = getattr(flow_class, "_initial_state_t", None)+ if isinstance(state_value, TypeVar):+ state_value = Noneinitial_state = getattr(flow_class, "initial_state", None)if initial_state is not None:state_value = initial_state@@ -230,6 +274,98 @@ def _build_persistence_definition()+def _build_conversational_router_definition(+ router_config: Any,+ diagnostics: list[FlowDefinitionDiagnostic],+ path: str,+) -> FlowConversationalRouterDefinition | None:+ if router_config is None:+ return None++ routes = getattr(router_config, "routes", None)+ return FlowConversationalRouterDefinition(+ prompt=getattr(router_config, "prompt", None),+ response_format=_serialize_static_value(+ getattr(router_config, "response_format", None),+ diagnostics,+ f"{path}.response_format",+ ),+ llm=_serialize_static_value(+ getattr(router_config, "llm", None), diagnostics, f"{path}.llm"+ ),+ routes=[str(route) for route in routes] if routes is not None else None,+ route_descriptions=getattr(router_config, "route_descriptions", None),+ default_intent=getattr(router_config, "default_intent", "converse"),+ fallback_intent=getattr(router_config, "fallback_intent", "converse"),+ intent_field=str(getattr(router_config, "intent_field", "intent")),+ )+++def _build_conversational_definition(+ flow_class: type,+ diagnostics: list[FlowDefinitionDiagnostic],+) -> FlowConversationalDefinition | None:+ if not _is_conversational_flow(flow_class):+ return None++ config = getattr(flow_class, "conversational_config", None)+ builtin_routes = getattr(flow_class, "builtin_routes", ("converse", "end"))+ internal_routes = getattr(+ flow_class,+ "internal_routes",+ ("answer_from_history", "conversation_start"),+ )+ if config is None:+ return FlowConversationalDefinition(+ enabled=True,+ builtin_routes=[str(route) for route in builtin_routes],+ internal_routes=[str(route) for route in internal_routes],+ )++ default_intents = getattr(config, "default_intents", None)+ visible_agent_outputs = getattr(config, "visible_agent_outputs", None)+ return FlowConversationalDefinition(+ enabled=True,+ system_prompt=getattr(config, "system_prompt", None),+ llm=_serialize_static_value(+ getattr(config, "llm", None), diagnostics, "conversational.llm"+ ),+ router=_build_conversational_router_definition(+ getattr(config, "router", None),+ diagnostics,+ "conversational.router",+ ),+ answer_from_history_prompt=getattr(config, "answer_from_history_prompt", None),+ default_intents=(+ [str(intent) for intent in default_intents]+ if default_intents is not None+ else None+ ),+ intent_llm=_serialize_static_value(+ getattr(config, "intent_llm", None),+ diagnostics,+ "conversational.intent_llm",+ ),+ answer_from_history_llm=_serialize_static_value(+ getattr(config, "answer_from_history_llm", None),+ diagnostics,+ "conversational.answer_from_history_llm",+ ),+ visible_agent_outputs=(+ "all"+ if visible_agent_outputs == "all"+ else [str(output) for output in visible_agent_outputs]+ if visible_agent_outputs is not None+ else None+ ),+ defer_trace_finalization=bool(+ getattr(config, "defer_trace_finalization", True)+ ),+ builtin_routes=[str(route) for route in builtin_routes],+ internal_routes=[str(route) for route in internal_routes],+ )++def _build_method_definition(method: Any,diagnostics: list[FlowDefinitionDiagnostic],@@ -270,6 +406,29 @@ def _iter_flow_methods(flow_class: type) -> dict[str, Any]:flow_class, attr_value):methods[attr_name] = attr_value+ continue++ inherited = _get_inherited_conversational_method(flow_class, attr_name)+ if inherited is not None and callable(attr_value):+ methods[attr_name] = _stamp_inherited_conversational_metadata(+ attr_value, inherited+ )++ if _is_conversational_flow(flow_class):+ for base in reversed(flow_class.__mro__[1:]):+ for attr_name, raw_value in base.__dict__.items():+ if attr_name.startswith("_") or attr_name in methods:+ continue+ if not getattr(raw_value, "__conversational_only__", False):+ continue+ try:+ attr_value = getattr(flow_class, attr_name)+ except AttributeError:+ continue+ if is_flow_method(attr_value) and _should_include_flow_method(+ flow_class, attr_value+ ):+ methods[attr_name] = attr_value# A wrapped method whose name collides with a base Flow model field# (e.g. ``checkpoint``) is absorbed by Pydantic as a field; the underlying@@ -314,6 +473,7 @@ def _build_flow_definition_from_class(state=_build_state_definition(flow_class, diagnostics),config=_build_config_definition(flow_class, diagnostics),persist=_build_persistence_definition(flow_class, diagnostics, "persist"),+ conversational=_build_conversational_definition(flow_class, diagnostics),methods=methods,diagnostics=diagnostics,)diff --git a/lib/crewai/src/crewai/flow/flow.py b/lib/crewai/src/crewai/flow/flow.pyindex 353f0ba9c..19c161ffb 100644--- a/lib/crewai/src/crewai/flow/flow.py+++ b/lib/crewai/src/crewai/flow/flow.py@@ -6,15 +6,22 @@ The implementation now lives in three modules, split by concern:``@router``, ``or_`` / ``and_``) and Python Flow class projection- ``crewai.flow.flow_definition`` -- the serializable Flow Definition contract- ``crewai.flow.runtime`` -- the Flow execution engine and state+- ``crewai.experimental.conversational_mixin`` -- experimental conversational+ runtime extension composed onto the public ``Flow`` classPrefer importing from those modules in new code; this module preserves thehistorical ``crewai.flow.flow`` import path."""+from typing import Any, TypeVar++from pydantic import BaseModel++from crewai.experimental.conversational_mixin import _ConversationalMixinfrom crewai.flow.dsl import and_, listen, or_, router, startfrom crewai.flow.runtime import (_INITIAL_STATE_CLASS_MARKER,- Flow,+ Flow as RuntimeFlow,FlowMeta,FlowState,LockedDictProxy,@@ -23,6 +30,13 @@ from crewai.flow.runtime import ()+T = TypeVar("T", bound=dict[str, Any] | BaseModel)+++class Flow(_ConversationalMixin, RuntimeFlow[T]):+ """Public Flow class with experimental conversational extension behavior."""++__all__ = ["_INITIAL_STATE_CLASS_MARKER","Flow",diff --git a/lib/crewai/src/crewai/flow/flow_definition.py b/lib/crewai/src/crewai/flow/flow_definition.pyindex 1c05a51a9..0830f7a65 100644--- a/lib/crewai/src/crewai/flow/flow_definition.py+++ b/lib/crewai/src/crewai/flow/flow_definition.py@@ -16,6 +16,11 @@ from typing import Any, Literal as TypingLiteralfrom pydantic import BaseModel, ConfigDict, Fieldimport yaml+from crewai.flow.conversational_definition import (+ FlowConversationalDefinition,+ FlowConversationalRouterDefinition,+)+logger = logging.getLogger(__name__)@@ -23,6 +28,8 @@ FlowDefinitionCondition = str | dict[str, Any]__all__ = ["FlowConfigDefinition",+ "FlowConversationalDefinition",+ "FlowConversationalRouterDefinition","FlowDefinition","FlowDefinitionCondition","FlowDefinitionDiagnostic",@@ -115,6 +122,7 @@ class FlowDefinition(BaseModel):state: FlowStateDefinition | None = Noneconfig: FlowConfigDefinition = Field(default_factory=FlowConfigDefinition)persist: FlowPersistenceDefinition | None = None+ conversational: FlowConversationalDefinition | None = Nonemethods: dict[str, FlowMethodDefinition] = Field(default_factory=dict)diagnostics: list[FlowDefinitionDiagnostic] = Field(default_factory=list)diff --git a/lib/crewai/src/crewai/flow/runtime.py b/lib/crewai/src/crewai/flow/runtime.pyindex 4be128c6f..874972a61 100644--- a/lib/crewai/src/crewai/flow/runtime.py+++ b/lib/crewai/src/crewai/flow/runtime.py@@ -84,11 +84,6 @@ from crewai.events.types.flow_events import (MethodExecutionPausedEvent,MethodExecutionStartedEvent,)-from crewai.experimental.conversational import (- ConversationConfig,- ConversationState,-)-from crewai.experimental.conversational_mixin import _ConversationalMixinfrom crewai.flow.dsl._utils import build_flow_definitionfrom crewai.flow.flow_context import current_flow_id, current_flow_request_idfrom crewai.flow.flow_definition import (@@ -139,7 +134,6 @@ from crewai.utilities.streaming import (signal_end,signal_error,)-from crewai.utilities.types import LLMMessage# Runtime alias so Pydantic can resolve the ``execution_context`` field's@@ -645,7 +639,7 @@ class FlowMeta(ModelMetaclass):return super().__new__(mcs, name, bases, namespace)-class Flow(_ConversationalMixin, BaseModel, Generic[T], metaclass=FlowMeta):+class Flow(BaseModel, Generic[T], metaclass=FlowMeta):"""Base class for all flows.type parameter T must be either dict[str, Any] or a subclass of BaseModel."""@@ -659,41 +653,33 @@ class Flow(_ConversationalMixin, BaseModel, Generic[T], metaclass=FlowMeta):_flow_definition: ClassVar[FlowDefinition | None] = None- # === EXPERIMENTAL: conversational mode ===- # When ``conversational = True`` on a subclass, the built-in conversational- # graph (``conversation_start`` -> ``route_conversation`` -> ``converse_turn``- # / ``end_conversation`` / ``answer_from_history_turn``) registers and- # ``handle_turn`` / ``chat`` become the chat entry points. When ``False``- # (default), the methods exist as inert attributes and never register or- # fire — non-chat flows pay no runtime cost.- #- # ⚠ EXPERIMENTAL FEATURE. The whole conversational surface- # (``conversational`` ClassVar, ``handle_turn``, ``chat``,- # ``ConversationConfig``, ``RouterConfig``, ``ConversationState``, the- # built-in graph + helpers) lives under ``crewai.experimental`` and may- # change shape before graduating. Pin your CrewAI version if you depend on- # specific behavior, and watch the changelog for breaking updates.- conversational: ClassVar[bool] = False- conversational_config: ClassVar[ConversationConfig | None] = None- builtin_routes: ClassVar[tuple[str, ...]] = ("converse", "end")- internal_routes: ClassVar[tuple[str, ...]] = (- "answer_from_history",- "conversation_start",- )- builtin_route_descriptions: ClassVar[dict[str, str]] = {- "converse": (- "Ordinary chat, follow-ups, summaries, clarifications, and "- "questions answerable from prior conversation history."- ),- "end": ("User signals the conversation is finished (goodbye, exit, done)."),- "answer_from_history": (- "Answer directly from prior conversation history without invoking "- "tools, agents, or custom routes."- ),- }-entity_type: Literal["flow"] = "flow"+ def _initialize_runtime_extension_attrs(self) -> None:+ """Initialize optional runtime-extension attributes."""++ def _create_default_extension_state(self) -> Any | None:+ """Return a default state supplied by an optional runtime extension."""+ return None++ def _should_apply_pending_kickoff_context(self) -> bool:+ """Whether an optional runtime extension has pending kickoff context."""+ return False++ def _apply_pending_kickoff_context(self) -> None:+ """Apply optional runtime-extension kickoff context."""++ def _order_start_methods_for_kickoff(+ self,+ start_methods: list[FlowMethodName],+ ) -> tuple[list[FlowMethodName], bool]:+ """Allow an optional runtime extension to order kickoff start methods."""+ return start_methods, False++ def _should_defer_trace_finalization(self) -> bool:+ """Whether this kickoff should defer final flow trace finalization."""+ return bool(getattr(self, "defer_trace_finalization", False))+@classmethoddef flow_definition(cls) -> FlowDefinition:"""Return the static Flow Definition built from this Flow class."""@@ -911,10 +897,6 @@ class Flow(_ConversationalMixin, BaseModel, Generic[T], metaclass=FlowMeta):_human_feedback_method_outputs: dict[str, Any] = PrivateAttr(default_factory=dict)_input_history: list[InputHistoryEntry] = PrivateAttr(default_factory=list)_state: Any = PrivateAttr(default=None)- _conversation_messages: list[LLMMessage] = PrivateAttr(default_factory=list)- _pending_user_message: str | dict[str, Any] | None = PrivateAttr(default=None)- _pending_intents: Sequence[str] | None = PrivateAttr(default=None)- _pending_intent_llm: str | "BaseLLM" | None = PrivateAttr(default=None)_deferred_flow_started_event_id: str | None = PrivateAttr(default=None)def __class_getitem__(cls: type[Flow[T]], item: type[T]) -> type[Flow[T]]: # type: ignore[override]@@ -940,6 +922,7 @@ class Flow(_ConversationalMixin, BaseModel, Generic[T], metaclass=FlowMeta):if getattr(self, "_flow_post_init_done", False):returnobject.__setattr__(self, "_flow_post_init_done", True)+ self._initialize_runtime_extension_attrs()if self._state is None:self._state = self._create_initial_state()@@ -1569,20 +1552,15 @@ class Flow(_ConversationalMixin, BaseModel, Generic[T], metaclass=FlowMeta):"""init_state = self.initial_state- # Conversational subclasses default to ``ConversationState`` if the- # user didn't supply an explicit type parameter (``Flow[...]``) or an- # ``initial_state``. This makes ``class MyChat(Flow): conversational- # = True`` work without forcing every user to import and parameterize- # ``ConversationState`` themselves.- if (- init_state is None- and getattr(type(self), "conversational", False)- and not hasattr(self, "_initial_state_t")- ):- return cast(T, ConversationState())+ if init_state is None:+ extension_state = self._create_default_extension_state()+ if extension_state is not None:+ return cast(T, extension_state)if init_state is None and hasattr(self, "_initial_state_t"):state_type = self._initial_state_t+ if isinstance(state_type, TypeVar):+ state_type = Noneif isinstance(state_type, type):if issubclass(state_type, FlowState):instance = state_type()@@ -2152,9 +2130,8 @@ class Flow(_ConversationalMixin, BaseModel, Generic[T], metaclass=FlowMeta):if should_emit_flow_started:# In normal flows, each kickoff owns its own flow lifecycle.- # Deferred conversational sessions are different: the first- # turn opens the flow scope and later turns reuse it until- # ``finalize_session_traces()`` emits the single finish event.+ # Deferred sessions reuse the first flow scope until an+ # explicit finalization call closes the batch.started_event = FlowStartedEvent(type="flow_started",flow_name=self.name or self.__class__.__name__,@@ -2184,16 +2161,8 @@ class Flow(_ConversationalMixin, BaseModel, Generic[T], metaclass=FlowMeta):# with implicit "crew" execution_type.get_env_context()- # Conversational hook: apply the pending user message AFTER state- # restore and AFTER flow scope initialization, so transcript events- # are parented under the current conversation trace.- # ``handle_turn`` stashes the message on ``self._pending_user_message``- # before calling ``kickoff``; this drains it.- if (- getattr(type(self), "conversational", False)- and self._pending_user_message is not None- ):- self._apply_pending_conversational_turn()+ if self._should_apply_pending_kickoff_context():+ self._apply_pending_kickoff_context()if inputs is not None and "id" not in inputs:self._initialize_state(inputs)@@ -2216,11 +2185,18 @@ class Flow(_ConversationalMixin, BaseModel, Generic[T], metaclass=FlowMeta):starts_to_execute = (unconditional_starts if unconditional_starts else start_methods)- tasks = [- self._execute_start_method(start_method)- for start_method in starts_to_execute- ]- await asyncio.gather(*tasks)+ starts_to_execute, run_starts_sequentially = (+ self._order_start_methods_for_kickoff(starts_to_execute)+ )+ if run_starts_sequentially:+ for start_method in starts_to_execute:+ await self._execute_start_method(start_method)+ else:+ tasks = [+ self._execute_start_method(start_method)+ for start_method in starts_to_execute+ ]+ await asyncio.gather(*tasks)except Exception as e:# Check if flow was paused for human feedbackfrom crewai.flow.async_feedback.types import HumanFeedbackPending@@ -2292,10 +2268,9 @@ class Flow(_ConversationalMixin, BaseModel, Generic[T], metaclass=FlowMeta):# When ``defer_trace_finalization`` is set, skip both per-turn# ``FlowFinishedEvent`` AND trace-batch finalization. The caller- # invokes ``finalize_session_traces()`` once at session end to- # close out the whole conversation as one trace. The flag is- # read from EITHER the instance attribute (set by user code) OR- # the class-level ``ConversationConfig.defer_trace_finalization``.+ # invokes the matching finalization hook once at session end. The+ # flag is read from either the instance attribute or an extension+ # definition.if not self._should_defer_trace_finalization():future = crewai_event_bus.emit(self,@@ -2919,7 +2894,7 @@ class Flow(_ConversationalMixin, BaseModel, Generic[T], metaclass=FlowMeta):return self.input_providerif flow_config.input_provider is not None:return flow_config.input_provider- return ConsoleProvider()+ return cast(InputProvider, ConsoleProvider())def _checkpoint_state_for_ask(self) -> None:"""Auto-checkpoint flow state before waiting for user input.@@ -3038,7 +3013,7 @@ class Flow(_ConversationalMixin, BaseModel, Generic[T], metaclass=FlowMeta):executor = ThreadPoolExecutor(max_workers=1)ctx = contextvars.copy_context()future = executor.submit(- ctx.run, provider.request_input, message, self, metadata+ ctx.run, provider.request_input, message, cast(Any, self), metadata)try:raw = future.result(timeout=timeout)@@ -3051,7 +3026,9 @@ class Flow(_ConversationalMixin, BaseModel, Generic[T], metaclass=FlowMeta):# cancel_futures=True cleans up any queued-but-not-started tasks.executor.shutdown(wait=False, cancel_futures=True)else:- raw = provider.request_input(message, self, metadata=metadata)+ raw = provider.request_input(+ message, cast(Any, self), metadata=metadata+ )except KeyboardInterrupt:raiseexcept Exception:@@ -3329,7 +3306,7 @@ class Flow(_ConversationalMixin, BaseModel, Generic[T], metaclass=FlowMeta):flow_name=self.name or self.__class__.__name__,),)- structure = build_flow_structure(self)+ structure = build_flow_structure(cast(Any, self))return render_interactive(structure, filename=filename, show=show)@staticmethoddiff --git a/lib/crewai/src/crewai/memory/recall_flow.py b/lib/crewai/src/crewai/memory/recall_flow.pyindex e09278983..562768c18 100644--- a/lib/crewai/src/crewai/memory/recall_flow.py+++ b/lib/crewai/src/crewai/memory/recall_flow.py@@ -259,8 +259,9 @@ class RecallFlow(Flow[RecallState]):candidates = []if not candidates:candidates = [scope_prefix]- self.state.candidate_scopes = candidates[:20]- return self.state.candidate_scopes+ selected_scopes = candidates[:20]+ self.state.candidate_scopes = selected_scopes+ return selected_scopes@listen(filter_and_chunk)def search_chunks(self) -> list[Any]:@@ -368,9 +369,10 @@ class RecallFlow(Flow[RecallState]):))matches.sort(key=lambda m: m.score, reverse=True)- self.state.final_results = matches[: self.state.limit]+ final_results = matches[: self.state.limit]+ self.state.final_results = final_resultsif self.state.evidence_gaps and self.state.final_results:self.state.final_results[0].evidence_gaps = list(self.state.evidence_gaps)- return self.state.final_results+ return final_resultsdiff --git a/lib/crewai/tests/test_flow_conversation.py b/lib/crewai/tests/test_flow_conversation.pyindex 03f95080f..122ad0009 100644--- a/lib/crewai/tests/test_flow_conversation.py+++ b/lib/crewai/tests/test_flow_conversation.py@@ -169,9 +169,6 @@ class TestConversationalFlow:)- @pytest.mark.skip(- reason="Experimental conversational registry behavior is out of scope for the definition-first start migration."- )def test_handle_turn_routes_to_listener_and_records_public_result(self) -> None:@ConversationConfig(default_intents=["research"], intent_llm="gpt-4o-mini")class ResearchFlow(ConversationalFlow):@@ -595,9 +592,6 @@ class TestConversationalFlow:assert result == "legacy-searched"assert flow.state.last_intent == "search"- @pytest.mark.skip(- reason="Experimental conversational sequential-start behavior is out of scope for the definition-first start migration."- )def test_user_start_methods_run_sequentially_before_router_in_conversational_mode(self,) -> None:@@ -649,9 +643,6 @@ class TestConversationalFlow:assert "attach_bus" in order # still fires every turnassert "route_turn" in order- @pytest.mark.skip(- reason="Experimental inherited conversational start registration is out of scope for the definition-first start migration."- )def test_subclass_can_override_conversation_start_without_redecorating(self,) -> None:@@ -1342,6 +1333,12 @@ class TestFlowTracingWhenSuppressed:class TestDeferTraceFinalization:+ def test_bare_conversational_flow_defers_by_default(self) -> None:+ class BareChat(ConversationalFlow):+ pass++ assert BareChat()._should_defer_trace_finalization() is True+def test_conversation_config_drives_defer_flag(self) -> None:"""``ConversationConfig(defer_trace_finalization=...)`` controls whethera conversational subclass defers per-turn trace finalization."""diff --git a/lib/crewai/tests/test_flow_definition.py b/lib/crewai/tests/test_flow_definition.pyindex bda29e7eb..da7908798 100644--- a/lib/crewai/tests/test_flow_definition.py+++ b/lib/crewai/tests/test_flow_definition.py@@ -13,6 +13,7 @@ from pydantic import BaseModelimport crewai.flow.dsl as flow_dslimport crewai.flow.flow_definition as flow_definitionimport crewai.flow.visualization.builder as visualization_builder+from crewai.experimental import ConversationConfig, RouterConfigfrom crewai.flow import Flow, and_, human_feedback, listen, or_, persist, router, start@@ -36,6 +37,8 @@ def test_flow_public_exports_are_explicit():}assert set(flow_definition.__all__) == {"FlowConfigDefinition",+ "FlowConversationalDefinition",+ "FlowConversationalRouterDefinition","FlowDefinition","FlowDefinitionCondition","FlowDefinitionDiagnostic",@@ -169,6 +172,7 @@ def test_flow_definition_maps_dsl_to_static_contract():assert definition.state.ref and "ContractState" in definition.state.refassert definition.config.stream is Trueassert definition.config.max_method_calls == 7+ assert definition.conversational is Noneassert definition.methods["begin"].start is Trueassert definition.methods["process"].listen == "begin"@@ -201,27 +205,74 @@ def test_flow_definition_excludes_conversational_builtins_for_regular_flows():methods = RegularFlow.flow_definition().methods+ assert RegularFlow.flow_definition().conversational is Noneassert set(methods) == {"begin"}assert "conversation_start" not in methodsassert "route_conversation" not in methodsassert "converse_turn" not in methods- reason="Experimental conversational inherited built-ins are out of scope for the definition-first start migration."-)def test_flow_definition_includes_conversational_builtins_when_enabled():class ChatFlow(Flow):conversational = True- methods = ChatFlow.flow_definition().methods+ definition = ChatFlow.flow_definition()+ methods = definition.methods+ assert definition.conversational is not None+ assert definition.conversational.enabled is True+ assert definition.conversational.defer_trace_finalization is True+ assert definition.conversational.builtin_routes == ["converse", "end"]assert "conversation_start" in methodsassert "route_conversation" in methodsassert "converse_turn" in methodsassert methods["conversation_start"].start is True+def test_flow_definition_serializes_conversational_config():+ @ConversationConfig(+ system_prompt="Be concise.",+ llm="gpt-4o-mini",+ router=RouterConfig(+ prompt="Pick a route.",+ routes=["research"],+ default_intent="converse",+ fallback_intent="end",+ ),+ default_intents=["research"],+ visible_agent_outputs=["researcher"],+ defer_trace_finalization=False,+ )+ class ChatFlow(Flow):+ conversational = True++ conversational = ChatFlow.flow_definition().conversational++ assert conversational is not None+ assert conversational.system_prompt == "Be concise."+ assert conversational.llm == "gpt-4o-mini"+ assert conversational.default_intents == ["research"]+ assert conversational.visible_agent_outputs == ["researcher"]+ assert conversational.defer_trace_finalization is False+ assert conversational.router is not None+ assert conversational.router.prompt == "Pick a route."+ assert conversational.router.routes == ["research"]+ assert conversational.router.fallback_intent == "end"+++def test_flow_definition_preserves_undecorated_conversational_override():+ class ChatFlow(Flow):+ conversational = True++ def conversation_start(self) -> str | None:+ return "custom"++ methods = ChatFlow.flow_definition().methods++ assert methods["conversation_start"].start is True+ assert "route_conversation" in methods++def test_flow_definition_serializes_human_feedback_metadata():marker = object()