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): 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.py
index 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 | None
def _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]
continue
handler_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"}
+ )
@staticmethod
def _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.py
index 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_feedback
diff --git a/lib/crewai/src/crewai/flow/runtime/__init__.py b/lib/crewai/src/crewai/flow/runtime/__init__.py
index 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 None
diff --git a/lib/crewai/tests/test_flow_conversation.py b/lib/crewai/tests/test_flow_conversation.py
index 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 llm
assert 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"),
+ ]