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 chat flow declare its own state shape (#7061)
João Mouraf68fd9e85038
diff --git a/lib/crewai/src/crewai/experimental/conversational_mixin.py b/lib/crewai/src/crewai/experimental/conversational_mixin.pyindex 35422701c..5cac956d7 100644--- a/lib/crewai/src/crewai/experimental/conversational_mixin.py+++ b/lib/crewai/src/crewai/experimental/conversational_mixin.py@@ -23,9 +23,9 @@ from contextlib import contextmanagerfrom enum import Enumimport jsonimport logging-from typing import TYPE_CHECKING, Any, ClassVar, Literal, TypeVar, cast+from typing import TYPE_CHECKING, Any, ClassVar, Literal, cast-from pydantic import BaseModel, Field, create_model+from pydantic import BaseModel, ConfigDict, Field, create_modelfrom crewai.events.event_bus import crewai_event_busfrom crewai.events.types.flow_events import (@@ -140,6 +140,37 @@ def _config_from_definition()+def _conversation_state_with_defaults(+ defaults: dict[str, Any] | None,+) -> ConversationState:+ """Build the chat state, keeping declared defaults the shape cannot hold.++ A ``dict`` state's defaults are arbitrary keys, and dropping the ones that+ are not conversational fields would break an action reading+ ``state.topic``. They are carried as extras instead.+ """+ if not defaults:+ return ConversationState()++ known = {+ name: value+ for name, value in defaults.items()+ if name in ConversationState.model_fields+ }+ extra = {+ name: value+ for name, value in defaults.items()+ if name not in ConversationState.model_fields+ }+ if not extra:+ return ConversationState(**known)++ class ConversationStateWithDeclaredDefaults(ConversationState):+ model_config = ConfigDict(extra="allow")++ return ConversationStateWithDeclaredDefaults(**known, **extra)++def _builtin_method(handler: Callable[..., Any], **roles: Any) -> FlowMethodDefinition:"""One built-in conversational method, as the code ref the DSL already emits."""return FlowMethodDefinition(do=_method_action(handler), **roles)@@ -997,23 +1028,53 @@ class _ConversationalMixin:update={"methods": {**definition.methods, **missing}})- def _create_default_extension_state(self) -> ConversationState | None:- """Supply ``ConversationState`` only when nothing else declares state.+ def _compose_extension_state_model(+ self, model_class: type[BaseModel]+ ) -> type[BaseModel]:+ """Add the conversational fields to a declared state model.- 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.+ A turn reads ``messages``, ``current_user_message``, ``last_intent``,+ ``ended``, ``events`` and ``agent_threads`` off state, so a declared+ model that lacks them fails on the first turn. Composing rather than+ replacing keeps every field the declaration asked for. A model that+ already extends ``ConversationState`` is returned untouched.+ """+ if not self._is_conversational_enabled():+ return model_class+ if issubclass(model_class, ConversationState):+ return model_class++ class ConversationalState(ConversationState, model_class): # type: ignore[misc, valid-type]+ pass++ return ConversationalState++ def _create_default_extension_state(+ self, *, ignore_declared_state: bool = False+ ) -> ConversationState | None:+ """Supply ``ConversationState`` when the declaration cannot carry it.++ A declared ``pydantic`` or ``json_schema`` state is composed with the+ conversational fields instead (see+ ``_compose_extension_state_model``), so it keeps everything it asked+ for. ``dict`` and ``unknown`` state cannot carry them at all, so this+ supplies the real shape rather than letting the turn die on+ ``state.id`` -- seeded from the declared defaults where they fit."""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 not hasattr(self, "_initial_state_t") or isinstance(- initial_state_t, TypeVar- ):++ state_definition = self._conversation_flow_definition().state+ if state_definition is None:return ConversationState()- return None+ if not ignore_declared_state and state_definition.type in (+ "pydantic",+ "json_schema",+ ):+ # Composed with the declared model instead; see+ # ``_compose_extension_state_model``.+ return None+ return _conversation_state_with_defaults(state_definition.default)def _should_apply_pending_kickoff_context(self) -> bool:return (diff --git a/lib/crewai/src/crewai/flow/runtime/__init__.py b/lib/crewai/src/crewai/flow/runtime/__init__.pyindex 0e95d971d..07e53de19 100644--- a/lib/crewai/src/crewai/flow/runtime/__init__.py+++ b/lib/crewai/src/crewai/flow/runtime/__init__.py@@ -185,6 +185,7 @@ def _condition_satisfied(condition: FlowDefinitionCondition, events: set[str]) -def _build_definition_state_model(state_definition: FlowStateDefinition,+ compose: Callable[[type[BaseModel]], type[BaseModel]] | None = None,) -> BaseModel | None:kwargs = dict(state_definition.default or {})@@ -216,6 +217,9 @@ def _build_definition_state_model(if model_class is None:return None+ if compose is not None:+ model_class = compose(model_class)+if not issubclass(model_class, FlowState):class StateWithId(FlowState, model_class): # type: ignore[misc, valid-type]@@ -458,10 +462,28 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):"""return definition- def _create_default_extension_state(self) -> Any | None:- """Return a default state supplied by an optional runtime extension."""+ def _create_default_extension_state(+ self, *, ignore_declared_state: bool = False+ ) -> Any | None:+ """Return a default state supplied by an optional runtime extension.++ ``ignore_declared_state`` is set when a declared ``state:`` block named+ a model that could not be built, so the extension is asked again as if+ nothing had been declared.+ """return None+ def _compose_extension_state_model(+ self, model_class: type[BaseModel]+ ) -> type[BaseModel]:+ """Let an optional runtime extension add bases to a declared state model.++ Applied to the model built from ``state:`` before the engine wraps it+ for its ``id`` field, so an extension can require its own fields+ alongside whatever the declaration asked for.+ """+ return model_class+def _should_apply_pending_kickoff_context(self) -> bool:"""Whether an optional runtime extension has pending kickoff context."""return False@@ -1721,7 +1743,9 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):if state_definition is None:return {"id": str(uuid4())}if state_definition.type in ("pydantic", "json_schema"):- state = _build_definition_state_model(state_definition)+ state = _build_definition_state_model(+ state_definition, compose=self._compose_extension_state_model+ )if state is not None:return statelogger.error(@@ -1730,6 +1754,11 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):self._definition.name,state_definition.type,)+ extension_state: dict[str, Any] | BaseModel | None = (+ self._create_default_extension_state(ignore_declared_state=True)+ )+ if extension_state is not None:+ return extension_stateelif state_definition.type == "unknown":logger.warning("Flow %r declares state of unknown type; falling back to dict state",diff --git a/lib/crewai/tests/test_flow_conversation.py b/lib/crewai/tests/test_flow_conversation.pyindex 87d0836ac..6841ecade 100644--- a/lib/crewai/tests/test_flow_conversation.py+++ b/lib/crewai/tests/test_flow_conversation.py@@ -2420,6 +2420,140 @@ class TestDeclarativeConversationalFlow:assert "cannot carry a model class" in caplog.text+class DeclaredSchemaChatState(ConversationState):+ """A ConversationState subclass, i.e. the already-supported state shape."""++ ticket_id: str | None = None+++class TestDeclaredConversationalState:+ """Any declared state shape works for a chat flow, keeping its own fields."""++ @staticmethod+ def _flow(state: dict[str, Any] | None) -> Flow[Any]:+ declaration = _conversational_declaration(conversational={})+ if state is None:+ declaration.pop("state", None)+ else:+ declaration["state"] = state+ return Flow.from_declaration(contents=declaration)++ CONVERSATIONAL_FIELDS = (+ "messages",+ "current_user_message",+ "last_intent",+ "ended",+ "events",+ "agent_threads",+ )++ def test_inline_json_schema_state_gains_the_conversational_fields(self) -> None:+ flow = self._flow(+ {+ "type": "json_schema",+ "json_schema": {+ "type": "object",+ "properties": {+ "ticket_id": {"type": "string"},+ "turns": {"type": "integer"},+ },+ },+ "default": {"ticket_id": "T-1"},+ }+ )+ fields = type(flow.state).model_fields++ for name in self.CONVERSATIONAL_FIELDS:+ assert name in fields, name+ assert "ticket_id" in fields and "turns" in fields+ assert flow.state.ticket_id == "T-1"+ assert flow.state.id++ def test_a_pydantic_ref_that_is_not_a_conversation_state_is_composed(self) -> None:+ flow = self._flow({"type": "pydantic", "ref": "crewai.flow:ChatState"})+ fields = type(flow.state).model_fields++ for name in self.CONVERSATIONAL_FIELDS:+ assert name in fields, name+ assert "session_ready" in fields++ def test_a_conversation_state_subclass_is_not_composed_twice(self) -> None:+ flow = self._flow(+ {"type": "pydantic", "ref": f"{__name__}:DeclaredSchemaChatState"}+ )+ mro = [cls.__name__ for cls in type(flow.state).__mro__]++ assert mro.count("ConversationState") == 1+ assert "ticket_id" in type(flow.state).model_fields++ def test_dict_state_is_given_the_real_shape(self) -> None:+ """A dict cannot carry the fields, so supply them rather than die."""+ flow = self._flow({"type": "dict", "default": {"last_intent": "order"}})++ assert isinstance(flow.state, ConversationState)+ assert flow.state.last_intent == "order"++ def test_dict_state_keeps_declared_defaults_it_does_not_own(self) -> None:+ """Dropping them would break an action reading `state.topic`."""+ flow = self._flow({"type": "dict", "default": {"topic": "ai", "limit": 3}})++ assert flow.state.topic == "ai"+ assert flow.state.limit == 3+ assert isinstance(flow.state, ConversationState)++ def test_unknown_state_is_treated_like_dict(self) -> None:+ flow = self._flow({"type": "unknown", "ref": "x:Y", "default": {"topic": "ai"}})++ assert flow.state.topic == "ai"+ assert isinstance(flow.state, ConversationState)++ def test_an_unbuildable_declared_model_still_gets_the_chat_shape(self) -> None:+ """A bad ref fell back to a plain dict, so the turn died on `state.id`."""+ flow = self._flow({"type": "pydantic", "ref": "no.such.module:Nope"})++ assert isinstance(flow.state, ConversationState)+ assert flow.state.id++ def test_declared_state_still_runs_a_turn(self) -> None:+ flow = self._flow(+ {+ "type": "json_schema",+ "json_schema": {+ "type": "object",+ "properties": {"ticket_id": {"type": "string"}},+ },+ }+ )+ flow._conversation_config.llm = _ScriptedLLM(["Hello."])++ assert flow.handle_turn("hi") == "Hello."+ assert [m.role for m in flow.state.messages] == ["user", "assistant"]++ def test_non_conversational_declaration_keeps_its_plain_state(self) -> None:+ flow = Flow.from_declaration(+ contents={+ "schema": "crewai.flow/v1",+ "name": "Plain",+ "state": {+ "type": "json_schema",+ "json_schema": {+ "type": "object",+ "properties": {"topic": {"type": "string"}},+ },+ "default": {"topic": "ai"},+ },+ "methods": {+ "begin": {+ "do": {"call": "expression", "expr": "state.topic"},+ "start": True,+ }+ },+ }+ )++ assert "messages" not in type(flow.state).model_fields+ assert flow.state.topic == "ai"+class TestDeclaredConversationalLLM:"""A conversational block accepts the shapes a crew agent's `llm` accepts."""@@ -2525,7 +2659,6 @@ class TestDeclaredConversationalLLM:assert declared in seenassert [m.role for m in flow.state.messages][0] == "user"-class TestRoutingArtefactLabels:"""A route label echoed by a handler is a routing artefact, not a reply."""