Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.
feat(flow): synthesize the built-in conversational methods for declarations (#7033)
João Moura01a156d73817
diff --git a/lib/crewai/src/crewai/experimental/conversational_mixin.py b/lib/crewai/src/crewai/experimental/conversational_mixin.pyindex 17bbbd9f2..aaef4146b 100644--- a/lib/crewai/src/crewai/experimental/conversational_mixin.py+++ b/lib/crewai/src/crewai/experimental/conversational_mixin.py@@ -140,6 +140,35 @@ def _config_from_definition()+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)+++def _builtin_methods() -> dict[str, FlowMethodDefinition]:+ """The built-in methods a conversational flow needs to run a turn.++ A Python flow inherits these methods; a declaration has nothing to inherit+ from, so without them ``conversational: {}`` loads clean and then runs zero+ methods and returns ``None``.+ """+ return {+ "route_conversation": _builtin_method(+ _ConversationalMixin.route_conversation, start=True, router=True+ ),+ "converse_turn": _builtin_method(+ _ConversationalMixin.converse_turn, listen="converse"+ ),+ "end_conversation": _builtin_method(+ _ConversationalMixin.end_conversation, listen="end"+ ),+ "answer_from_history_turn": _builtin_method(+ _ConversationalMixin.answer_from_history_turn,+ listen="answer_from_history",+ ),+ }++def _conversation_start_router(func: Callable[..., Any]) -> Any:wrapper = start()(func)_set_flow_method_definition(@@ -196,6 +225,7 @@ class _ConversationalMixin:_pending_intent_llm: str | BaseLLM | None_turn_classified_intent: str | None_assistant_reply_appended: bool+ _turn_recorded_results: list[Any]_resolved_conversation_config: ConversationConfig | Nonedef _clear_or_listeners(self) -> None:@@ -396,6 +426,7 @@ class _ConversationalMixin:self._reset_turn_execution_state()object.__setattr__(self, "_assistant_reply_appended", False)+ object.__setattr__(self, "_turn_recorded_results", [])result = self.kickoff(inputs={"id": sid}, **kickoff_kwargs)if (result is not None@@ -473,6 +504,7 @@ class _ConversationalMixin:self._reset_turn_execution_state()object.__setattr__(self, "_assistant_reply_appended", False)+ object.__setattr__(self, "_turn_recorded_results", [])original_stream = bool(getattr(self, "stream", False))original_streaming_turn = getattr(self, "_streaming_conversation_turn", False@@ -700,6 +732,11 @@ class _ConversationalMixin:state.agent_threads.setdefault(agent_name, []).append(AgentMessage(content=content, metadata=metadata or {}))+ # Remember the object itself so the end-of-turn fallback does not+ # re-publish a result the handler deliberately kept private. Identity,+ # not content: a handler that records scratch work privately and then+ # returns a user-facing summary still gets that summary promoted.+ self._turn_recorded_results.append(result)if event_visibility == "public":self.append_assistant_message(content)@@ -920,9 +957,42 @@ 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 isinstance(getattr(self, "_turn_recorded_results", None), list):+ object.__setattr__(self, "_turn_recorded_results", [])if not hasattr(self, "_resolved_conversation_config"):object.__setattr__(self, "_resolved_conversation_config", None)+ def _extend_definition(self, definition: FlowDefinition) -> FlowDefinition:+ """Add the built-in conversational methods a declaration cannot inherit.++ An entry the author supplied under the same name always wins, and a+ Python flow already carries all four from the MRO walk, so this only+ fills gaps.+ """+ conversational = definition.conversational+ if conversational is None or not conversational.enabled:+ return definition++ # A declaration enables chat without the ``conversational = True``+ # class attribute, so mark the instance. Callers outside this package+ # capability-check that attribute, and it should agree with+ # ``_is_conversational_enabled()``. Instance-only on purpose: the DSL+ # projection reads it off the *class* to decide whether to emit a+ # conversational block, and setting it there would make every later+ # subclass look conversational.+ object.__setattr__(self, "conversational", True)++ missing = {+ name: method+ for name, method in _builtin_methods().items()+ if name not in definition.methods+ }+ if not missing:+ return definition+ return definition.model_copy(+ update={"methods": {**definition.methods, **missing}}+ )+def _create_default_extension_state(self) -> ConversationState | None:"""Supply ``ConversationState`` only when nothing else declares state.@@ -1174,16 +1244,38 @@ class _ConversationalMixin:catalog[route_label] = self.builtin_route_descriptions[route_label]continuehandler_name = label_to_method.get(route_label)- description = ""- if handler_name:- method = getattr(type(self), handler_name, None)- doc = getattr(method, "__doc__", None)- if doc:- description = doc.strip().split("\n", 1)[0].strip()- catalog[route_label] = description+ catalog[route_label] = (+ self._route_description(flow_definition, handler_name)+ if handler_name+ else ""+ )return catalog+ def _route_description(+ self,+ flow_definition: FlowDefinition,+ handler_name: str,+ ) -> str:+ """Describe a route for the router LLM's catalog.++ The declared ``description`` comes first so a declaration can say what+ a route is for; the handler docstring backs it for Python flows whose+ definition predates the DSL filling that field.+ """+ declared = flow_definition.methods[handler_name].description+ if declared:+ return declared.strip().split("\n", 1)[0].strip()++ method = getattr(type(self), handler_name, None)+ if method is None:+ # A declarative flow has no class attribute to read, and+ # ``None.__doc__`` is NoneType's own docstring — which would be+ # handed to the router LLM as the route description.+ return ""+ doc = getattr(method, "__doc__", None)+ return doc.strip().split("\n", 1)[0].strip() if doc else ""+def _extract_router_intent(self, response: Any, intent_field: str) -> str | None:if isinstance(response, BaseModel):value = getattr(response, intent_field, None)@@ -1270,17 +1362,42 @@ class _ConversationalMixin:return "private"def _is_public_turn_result(self, result: Any) -> bool:- if not isinstance(result, str):+ """Whether a handler's return value should become the assistant reply.++ Declarative ``agent`` and ``crew`` actions return ``LiteAgentOutput`` /+ ``CrewOutput`` rather than a string, so the text lives on ``.raw``.+ Without unwrapping it here their reply never reaches the transcript.+ """+ if any(result is recorded for recorded in self._turn_recorded_results):+ # Already routed by ``append_agent_result``, which honours+ # ``visible_agent_outputs``. Promoting it here would publish a+ # result the handler asked to keep private.return False- if result in {- "conversation",- "converse",- "end",- "answer_from_history",- "route_to_flow",- }:++ text = result+ raw = getattr(result, "raw", None)+ if not isinstance(text, str) and isinstance(raw, str):+ text = raw+ if not isinstance(text, str):return False- return result != cast(ConversationState, self.state).last_intent+ if text in self._routing_artefact_labels():+ return False+ return text != cast(ConversationState, self.state).last_intent++ def _routing_artefact_labels(self) -> set[str]:+ """Strings that are a routing decision rather than something to say.++ Derived from the effective routes so a declaration that customizes+ ``builtin_routes`` is covered too; a literal list here would miss the+ added labels. ``conversation`` and ``route_to_flow`` are not routes:+ the first is a legacy label and the second is an outcome of the+ answer-from-history check.+ """+ return (+ self._effective_builtin_routes()+ | self._effective_internal_routes()+ | {"conversation", "route_to_flow"}+ )@staticmethoddef _coerce_user_message_text(user_message: str | dict[str, Any] | Any) -> str:diff --git a/lib/crewai/src/crewai/flow/dsl/_utils.py b/lib/crewai/src/crewai/flow/dsl/_utils.pyindex 5373199c2..feb4ad605 100644--- a/lib/crewai/src/crewai/flow/dsl/_utils.py+++ b/lib/crewai/src/crewai/flow/dsl/_utils.py@@ -370,6 +370,14 @@ def _build_method_definition(deep=True, update={"do": _method_action(method)})+ if method_definition.description is None:+ # The router catalog describes a route from its handler's docstring.+ # Projecting it makes that description survive serialization, so a+ # declaration can carry one too.+ docstring = getattr(method, "__doc__", None)+ if docstring and docstring.strip():+ method_definition.description = docstring.strip().split("\n", 1)[0].strip()+human_feedback = _build_human_feedback_definition(method, f"{path}.human_feedback")if human_feedback is not None:method_definition.human_feedback = human_feedbackdiff --git a/lib/crewai/src/crewai/flow/runtime/__init__.py b/lib/crewai/src/crewai/flow/runtime/__init__.pyindex 8e5580280..eefbd75b6 100644--- a/lib/crewai/src/crewai/flow/runtime/__init__.py+++ b/lib/crewai/src/crewai/flow/runtime/__init__.py@@ -450,6 +450,14 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):def _initialize_runtime_extension_attrs(self) -> None:"""Initialize optional runtime-extension attributes."""+ def _extend_definition(self, definition: FlowDefinition) -> FlowDefinition:+ """Let an optional runtime extension complete the definition.++ Runs once ``_definition`` is resolved and before methods are bound, so+ an extension can contribute the methods it owns.+ """+ return definition+def _create_default_extension_state(self) -> Any | None:"""Return a default state supplied by an optional runtime extension."""return None@@ -784,6 +792,7 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):self._definition = definition or type(self).flow_definition()if self.name and self.name != self._definition.name:self._definition = self._definition.model_copy(update={"name": self.name})+ self._definition = self._extend_definition(self._definition)methods = (self._action_bound_methods()if definition is not Nonediff --git a/lib/crewai/tests/test_flow_conversation.py b/lib/crewai/tests/test_flow_conversation.pyindex 7982eb72f..29fb57b72 100644--- a/lib/crewai/tests/test_flow_conversation.py+++ b/lib/crewai/tests/test_flow_conversation.py@@ -2420,6 +2420,99 @@ class TestDeclarativeConversationalFlow:assert "cannot carry a model class" in caplog.text+class TestRoutingArtefactLabels:+ """A route label echoed by a handler is a routing artefact, not a reply."""++ def test_class_based_set_matches_the_framework_labels(self) -> None:+ @ConversationConfig()+ class ClassChat(Flow[ConversationState]):+ pass++ assert ClassChat()._routing_artefact_labels() == {+ "conversation",+ "converse",+ "end",+ "answer_from_history",+ "route_to_flow",+ }++ def test_a_declared_extra_builtin_route_is_covered(self) -> None:+ """A literal list would miss it; deriving from the routes does not."""+ flow = Flow.from_declaration(+ contents=_conversational_declaration(+ conversational={"builtin_routes": ["converse", "end", "greet"]}+ )+ )++ assert "greet" in flow._routing_artefact_labels()+ assert flow._is_public_turn_result("greet") is False++ def test_ordinary_text_is_still_a_reply(self) -> None:+ flow = Flow.from_declaration(contents=_conversational_declaration())++ assert flow._is_public_turn_result("Your order shipped.") is True+++class TestConversationalCapabilityAttribute:+ """A declarative chat flow reports itself conversational to outside callers.++ Consumers outside this package capability-check the ``conversational``+ attribute, so it must agree with ``_is_conversational_enabled()``.+ """++ def test_declaration_marks_the_instance_conversational(self) -> None:+ flow = Flow.from_declaration(contents=_conversational_declaration())++ assert getattr(flow, "conversational") is True+ assert flow._is_conversational_enabled() is True+ assert callable(getattr(flow, "stream_turn", None))++ def test_the_flag_does_not_leak_onto_the_class(self) -> None:+ """The DSL projection reads it off the class to decide what to emit."""+ Flow.from_declaration(contents=_conversational_declaration())++ assert Flow.conversational is False++ class LaterPlainFlow(Flow):+ @start()+ def begin(self) -> str:+ return "begin"++ assert LaterPlainFlow.conversational is False+ assert LaterPlainFlow.flow_definition().conversational is None++ def test_disabled_declaration_is_not_marked(self) -> None:+ flow = Flow.from_declaration(+ contents=_conversational_declaration(conversational={"enabled": False})+ )++ assert getattr(flow, "conversational") is False++ def test_non_conversational_declaration_is_not_marked(self) -> None:+ flow = Flow.from_declaration(+ contents={+ "schema": "crewai.flow/v1",+ "name": "Plain",+ "methods": {+ "begin": {+ "do": {"call": "expression", "expr": "'x'"},+ "start": True,+ }+ },+ }+ )++ assert getattr(flow, "conversational") is False++ def test_class_based_flow_keeps_its_own_flag(self) -> None:+ @ConversationConfig()+ class ClassChat(Flow[ConversationState]):+ pass++ assert ClassChat.conversational is True+ assert getattr(ClassChat(), "conversational") is True++class TestBuiltinRouteResolution:"""``route_turn`` and ``_effective_routes`` agree on what is built in."""@@ -2587,3 +2680,499 @@ class TestClassConfigStillWins:assert flow._conversation_config.llm is llmassert flow._conversation_config.system_prompt == "From the class."+++class TestMinimalDeclarativeChat:+ """A declaration only has to name its own routes."""++ @staticmethod+ def _declaration(**overrides: Any) -> dict[str, Any]:+ declaration: dict[str, Any] = {+ "schema": "crewai.flow/v1",+ "name": "MinimalChat",+ "conversational": {},+ "methods": {+ "handle_order": {+ "do": {"call": "expression", "expr": "'Your order shipped.'"},+ "listen": "order",+ "description": "Order status questions.",+ }+ },+ }+ declaration.update(overrides)+ return declaration++ def test_minimal_declaration_runs_a_conversational_turn(self) -> None:+ # No custom routes, so the router does not auto-enable and the turn+ # goes straight to the built-in converse handler.+ declaration = self._declaration(methods={})+ flow = Flow.from_declaration(contents=declaration)+ flow._conversation_config.llm = _ScriptedLLM(["Hello there."])++ assert flow.handle_turn("hi") == "Hello there."+ assert [(m.role, m.content) for m in flow.state.messages] == [+ ("user", "hi"),+ ("assistant", "Hello there."),+ ]++ def test_minimal_declaration_implies_conversation_state(self) -> None:+ flow = Flow.from_declaration(contents=self._declaration())++ assert isinstance(flow.state, ConversationState)++ def test_minimal_declaration_routes_to_a_declared_handler(self) -> None:+ flow = Flow.from_declaration(contents=self._declaration())+ flow._conversation_config.router = RouterConfig(+ llm=_ScriptedLLM(['{"intent": "order"}'])+ )++ assert flow.handle_turn("where is my order?") == "Your order shipped."+ assert flow.state.last_intent == "order"++ def test_method_description_reaches_the_router_catalog(self) -> None:+ flow = Flow.from_declaration(contents=self._declaration())++ catalog = flow._build_route_catalog(RouterConfig(routes=["order"]))++ assert catalog["order"] == "Order status questions."+++class TestBuiltinMethodSynthesis:+ """A declaration does not have to name the built-in methods."""++ BUILTIN_METHODS = {+ "route_conversation",+ "converse_turn",+ "end_conversation",+ "answer_from_history_turn",+ }++ @staticmethod+ def _declaration(**overrides: Any) -> dict[str, Any]:+ declaration: dict[str, Any] = {+ "schema": "crewai.flow/v1",+ "name": "SynthChat",+ "conversational": {},+ "methods": {+ "handle_order": {+ "do": {"call": "expression", "expr": "'shipped'"},+ "listen": "order",+ }+ },+ }+ declaration.update(overrides)+ return declaration++ def test_builtin_methods_are_synthesized_with_their_roles(self) -> None:+ flow = Flow.from_declaration(contents=self._declaration())+ methods = flow._definition.methods++ assert self.BUILTIN_METHODS <= set(methods)+ assert methods["route_conversation"].start is True+ assert methods["route_conversation"].router is True+ assert methods["converse_turn"].listen == "converse"+ assert methods["end_conversation"].listen == "end"+ assert methods["answer_from_history_turn"].listen == "answer_from_history"++ def test_synthesized_refs_match_the_python_projection(self) -> None:+ class ProjectedChat(Flow):+ conversational = True++ projected = ProjectedChat.flow_definition().methods+ synthesized = Flow.from_declaration(+ contents=self._declaration()+ )._definition.methods++ for name in self.BUILTIN_METHODS:+ assert synthesized[name].do == projected[name].do++ def test_author_supplied_entry_is_not_overridden(self) -> None:+ declaration = self._declaration()+ declaration["methods"]["converse_turn"] = {+ "do": {"call": "expression", "expr": "'mine'"},+ "listen": "converse",+ }++ flow = Flow.from_declaration(contents=declaration)++ assert flow._definition.methods["converse_turn"].do.expr == "'mine'"++ def test_disabled_block_synthesizes_nothing(self) -> None:+ flow = Flow.from_declaration(+ contents=self._declaration(conversational={"enabled": False})+ )++ assert set(flow._definition.methods) == {"handle_order"}++ def test_non_conversational_flow_synthesizes_nothing(self) -> None:+ flow = Flow.from_declaration(+ contents={+ "schema": "crewai.flow/v1",+ "name": "Plain",+ "methods": {+ "begin": {+ "do": {"call": "expression", "expr": "'x'"},+ "start": True,+ }+ },+ }+ )++ assert set(flow._definition.methods) == {"begin"}++ def test_the_loaded_definition_itself_is_left_alone(self) -> None:+ """Synthesis is a runtime concern; the contract stays as authored."""+ from crewai.flow.flow_definition import FlowDefinition++ definition = FlowDefinition.from_declaration(contents=self._declaration())++ assert set(definition.methods) == {"handle_order"}+++class TestRouteDescriptions:+ """Route descriptions survive into a declaration."""++ def test_python_handler_docstring_is_projected(self) -> None:+ class DocumentedChat(Flow):+ conversational = True++ @listen("research")+ def handle_research(self) -> str:+ """Fresh web research and current news."""+ return "researched"++ definition = DocumentedChat.flow_definition()++ assert (+ definition.methods["handle_research"].description+ == "Fresh web research and current news."+ )++ def test_declared_description_reaches_the_catalog(self) -> None:+ flow = Flow.from_declaration(+ contents={+ "schema": "crewai.flow/v1",+ "name": "DescribedChat",+ "conversational": {},+ "methods": {+ "handle_order": {+ "do": {"call": "expression", "expr": "'shipped'"},+ "listen": "order",+ "description": "Order status questions.",+ }+ },+ }+ )++ catalog = flow._build_route_catalog(RouterConfig(routes=["order"]))++ assert catalog["order"] == "Order status questions."++ def test_missing_description_is_empty_not_nonetype_docstring(self) -> None:+ flow = Flow.from_declaration(+ contents={+ "schema": "crewai.flow/v1",+ "name": "UndescribedChat",+ "conversational": {},+ "methods": {+ "handle_order": {+ "do": {"call": "expression", "expr": "'shipped'"},+ "listen": "order",+ }+ },+ }+ )++ catalog = flow._build_route_catalog(RouterConfig(routes=["order"]))++ assert catalog["order"] == ""++ def test_python_docstring_still_describes_the_route(self) -> None:+ class DocumentedChat(Flow):+ conversational = True++ @listen("research")+ def handle_research(self) -> str:+ """Fresh web research and current news."""+ return "researched"++ catalog = DocumentedChat()._build_route_catalog(+ RouterConfig(routes=["research"])+ )++ assert catalog["research"] == "Fresh web research and current news."+++class TestDeclarativeTurnMatrix:+ """A declaration-built flow across the turn entry points."""++ @staticmethod+ def _flow(reply: str = "Declared reply.") -> Flow[Any]:+ flow = Flow.from_declaration(+ contents={+ "schema": "crewai.flow/v1",+ "name": "MatrixChat",+ "conversational": {},+ "methods": {},+ }+ )+ flow._conversation_config.llm = _ScriptedLLM([reply])+ return flow++ def test_sync_turn(self) -> None:+ assert self._flow().handle_turn("hi") == "Declared reply."++ def test_stream_turn_frames_match_the_class_based_path(self) -> None:+ """A chat UI must see the same frame sequence either way."""++ @ConversationConfig(llm=_ScriptedLLM(["streamed reply"]))+ class ClassChat(Flow[ConversationState]):+ pass++ class_frames = [f.type for f in ClassChat().stream_turn("hi").events]++ flow = self._flow("streamed reply")+ stream = flow.stream_turn("hi", session_id="session-1")+ declared_frames = [f.type for f in stream.events]++ assert declared_frames == class_frames+ assert declared_frames[0] == "conversation_turn_started"+ assert declared_frames[-1] == "conversation_turn_completed"+ assert "conversation_message_added" in declared_frames+ assert stream.result == "streamed reply"+ assert flow.state.messages[-1].content == "streamed reply"++ def test_turn_inside_a_running_event_loop(self) -> None:+ """``kickoff`` takes its thread-pool path when a loop is already running."""+ import asyncio++ flow = self._flow("reply from the loop")++ async def run() -> Any:+ return flow.handle_turn("hi")++ assert asyncio.run(run()) == "reply from the loop"+ assert flow.state.messages[-1].content == "reply from the loop"++ def test_follow_up_turn_keeps_history(self) -> None:+ flow = self._flow()+ flow._conversation_config.llm = _ScriptedLLM(["first", "second"])++ flow.handle_turn("one")+ flow.handle_turn("two")++ assert [(m.role, m.content) for m in flow.state.messages] == [+ ("user", "one"),+ ("assistant", "first"),+ ("user", "two"),+ ("assistant", "second"),+ ]++ def test_chat_repl_drives_declared_turns(self) -> None:+ flow = self._flow()+ flow._conversation_config.llm = _ScriptedLLM(["hello", "goodbye"])+ prompts: list[str] = []+ outputs: list[str] = []++ replies = iter(["hi", "bye", "exit"])++ def input_fn(prompt: str) -> str:+ prompts.append(prompt)+ return next(replies)++ flow.chat(input_fn=input_fn, output_fn=outputs.append)++ assert [m.content for m in flow.state.messages if m.role == "user"] == [+ "hi",+ "bye",+ ]+ assert len(outputs) == 2+++class TestPrivateAgentResultsStayPrivate:+ """Unwrapping ``.raw`` must not defeat ``visible_agent_outputs``."""++ class _Out:+ """Shape of ``LiteAgentOutput`` / ``CrewOutput``."""++ def __init__(self, raw: str) -> None:+ self.raw = raw++ def test_privately_recorded_result_is_not_republished(self) -> None:+ """A handler that records privately and hands the object back.++ ``append_agent_result`` defaults to private and does not set the+ reply flag, so before this guard the end-of-turn fallback promoted the+ very object the handler had just asked to keep out of the transcript.+ """+ recorded = self._Out("SECRET scratch work")++ @ConversationConfig()+ class PrivateChat(Flow[ConversationState]):+ @listen("converse")+ def converse_turn(self) -> Any:+ self.append_agent_result("researcher", recorded)+ return recorded++ flow = PrivateChat()+ flow.handle_turn("look something up")++ assert [m.role for m in flow.state.messages] == ["user"]+ assert flow.state.agent_threads["researcher"][0].content == (+ "SECRET scratch work"+ )++ def test_a_summary_returned_alongside_a_private_result_is_published(self) -> None:+ """Identity, not content: a different return value is still promoted."""++ @ConversationConfig()+ class SummarisingChat(Flow[ConversationState]):+ @listen("converse")+ def converse_turn(self) -> Any:+ self.append_agent_result(+ "researcher", TestPrivateAgentResultsStayPrivate._Out("SECRET")+ )+ return "Here is the summary."++ flow = SummarisingChat()+ flow.handle_turn("look something up")++ assert flow.state.messages[-1].content == "Here is the summary."++ def test_visible_agent_outputs_still_publishes(self) -> None:+ result = self._Out("PUBLIC RESULT")++ @ConversationConfig(visible_agent_outputs="all")+ class VisibleChat(Flow[ConversationState]):+ @listen("converse")+ def converse_turn(self) -> Any:+ self.append_agent_result("researcher", result)+ return result++ flow = VisibleChat()+ flow.handle_turn("go")++ assert flow.state.messages[-1].content == "PUBLIC RESULT"+ assert [m.role for m in flow.state.messages].count("assistant") == 1++ def test_explicit_public_visibility_still_publishes(self) -> None:+ result = self._Out("PUBLIC RESULT")++ @ConversationConfig()+ class PublicChat(Flow[ConversationState]):+ @listen("converse")+ def converse_turn(self) -> Any:+ self.append_agent_result("researcher", result, visibility="public")+ return result++ flow = PublicChat()+ flow.handle_turn("go")++ assert flow.state.messages[-1].content == "PUBLIC RESULT"+ assert [m.role for m in flow.state.messages].count("assistant") == 1++ def test_recorded_results_do_not_leak_across_turns(self) -> None:+ """The per-turn list resets, so turn 2 is judged on its own."""+ shared = self._Out("reply text")++ @ConversationConfig()+ class TwoTurnChat(Flow[ConversationState]):+ @listen("converse")+ def converse_turn(self) -> Any:+ return shared++ flow = TwoTurnChat()+ flow.handle_turn("one")+ flow.handle_turn("two")++ assert [m.content for m in flow.state.messages if m.role == "assistant"] == [+ "reply text",+ "reply text",+ ]+++class TestHandlerReplyPromotion:+ """An agent or crew handler's reply reaches the transcript."""++ class _AgentOutput:+ """Shape of ``LiteAgentOutput`` / ``CrewOutput``: text lives on ``.raw``."""++ def __init__(self, raw: str) -> None:+ self.raw = raw++ def __str__(self) -> str:+ return f"<output {self.raw!r}>"++ @staticmethod+ def _chat(handler_result: Any) -> Flow[Any]:+ @ConversationConfig()+ class HandlerChat(Flow[ConversationState]):+ @listen("converse")+ def converse_turn(self) -> Any:+ return handler_result++ return HandlerChat()++ def test_output_object_reply_reaches_history(self) -> None:+ flow = self._chat(self._AgentOutput("Your order shipped Tuesday."))++ flow.handle_turn("where is my order?")++ assert [(m.role, m.content) for m in flow.state.messages] == [+ ("user", "where is my order?"),+ ("assistant", "Your order shipped Tuesday."),+ ]++ def test_string_reply_still_reaches_history(self) -> None:+ flow = self._chat("A plain string reply.")++ flow.handle_turn("hi")++ assert flow.state.messages[-1].content == "A plain string reply."++ def test_route_label_output_is_not_promoted(self) -> None:+ flow = self._chat(self._AgentOutput("converse"))++ flow.handle_turn("hi")++ assert [m.role for m in flow.state.messages] == ["user"]++ def test_output_matching_this_turns_intent_is_not_promoted(self) -> None:+ @ConversationConfig()+ class RoutedChat(Flow[ConversationState]):+ def route_turn(self, context: dict[str, Any]) -> str:+ return "order"++ @listen("order")+ def handle_order(self) -> Any:+ # Echoing the route label is a routing artefact, not a reply.+ return TestHandlerReplyPromotion._AgentOutput("order")++ flow = RoutedChat()+ flow.handle_turn("where is my order?")++ assert flow.state.last_intent == "order"+ assert [m.role for m in flow.state.messages] == ["user"]++ def test_non_text_output_is_not_promoted(self) -> None:+ flow = self._chat(self._AgentOutput(raw=None)) # type: ignore[arg-type]++ flow.handle_turn("hi")++ assert [m.role for m in flow.state.messages] == ["user"]++ def test_handler_that_already_replied_is_not_double_promoted(self) -> None:+ @ConversationConfig()+ class ExplicitReplyChat(Flow[ConversationState]):+ @listen("converse")+ def converse_turn(self) -> Any:+ self.append_assistant_message("explicit")+ return TestHandlerReplyPromotion._AgentOutput("returned")++ flow = ExplicitReplyChat()+ flow.handle_turn("hi")++ assert [(m.role, m.content) for m in flow.state.messages] == [+ ("user", "hi"),+ ("assistant", "explicit"),+ ]