Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.
[OSS-115] Persist custom conversational replies after fallback append (#7026)
Vidit Ostwal56e0e85a8186
diff --git a/docs/edge/ar/guides/flows/conversational-flows.mdx b/docs/edge/ar/guides/flows/conversational-flows.mdxindex 66934a6d0..273b1b4da 100644--- a/docs/edge/ar/guides/flows/conversational-flows.mdx+++ b/docs/edge/ar/guides/flows/conversational-flows.mdx@@ -121,7 +121,7 @@ result = stream.result5. **تنفيذ الرسم** — طرق `@start` التي يعرّفها المستخدم (إن وجدت) → `route_conversation` (نقطة البدء/الموجّه المدمجة) → معالج `@listen` المختار. تستدعي `route_conversation` أيضاً المساعد القابل للتجاوز `conversation_start()`.6. **نهاية التشغيل** — يُتخطى `flow_finished` لكل جولة وإنهاء التتبع عند تفعيل التأجيل؛ كما لا تغلق استدعاءات `Agent.kickoff()` المتداخلة أو crews دفعة الأب.-ينبغي للمعالجات استدعاء **`append_assistant_message(reply)`** كي تتضمن `conversation_messages` في الجولة التالية نص المساعد. سطر المستخدم محفوظ بالفعل عبر `handle_turn` — لا تُضفه مرة أخرى في المعالجات.+استدعِ **`append_assistant_message(reply)`** عندما لا تطابق الرد الظاهر قيمة الإرجاع، أو عند قصّ التاريخ. تُسجَّل أيضاً سلسلة الإرجاع العامة كمساعد وتُضمَّن في لقطة `@persist`، فتستعيدها نسخة Flow جديدة. سطر المستخدم محفوظ عبر `handle_turn` — لا تُضفه مرة أخرى.## نظرة عامة على الإعداد@@ -428,7 +428,7 @@ def create_video(self) -> str: # rejected at flow instantiation2. يُلحق رسالة المستخدم بـ `state.messages` ويضبط `current_user_message` / `last_user_message`. يُحافَظ على `last_intent` **من الجولة السابقة** كي يستخدمها LLM التوجيه كإشارة.3. يُشغّل طرق `@start` التي يعرّفها المستخدم (إن وجدت)، ثم `route_conversation` كنقطة البدء/الموجّه المدمجة، ثم معالج `@listen` المختار. وتستدعي `route_conversation` المساعد القابل للتجاوز `conversation_start()`.4. يخزّن الموجّه قراره في `state.last_intent` (يكون مرئياً لسياق التوجيه في الجولة التالية).-5. إذا أعاد معالجك سلسلة نصية ولم يستدعِ `append_assistant_message`، فإن `handle_turn` يُلحقها نيابةً عنك.+5. إذا أعاد معالجك سلسلة نصية ولم يستدعِ `append_assistant_message`، فإن `handle_turn` يُلحقها نيابةً عنك ويحفظ `state.messages` المحدَّث حتى تشمل استعادة `@persist` جولة المساعد.استدعِ `handle_turn()` لرسائل الدردشة. استدعاء `kickoff(inputs={"id": ...})` مباشرةً يشغل الرسم بدون غلاف الجولة المحادثية.diff --git a/docs/edge/en/guides/flows/conversational-flows.mdx b/docs/edge/en/guides/flows/conversational-flows.mdxindex 3c6d2e6ad..a602795f6 100644--- a/docs/edge/en/guides/flows/conversational-flows.mdx+++ b/docs/edge/en/guides/flows/conversational-flows.mdx@@ -121,7 +121,7 @@ Each `handle_turn` runs this pipeline:5. **Graph execution** — user-defined `@start` methods (if any) → `route_conversation` (the built-in start/router) → the selected `@listen` handler. `route_conversation` also calls the overridable `conversation_start()` helper.6. **End of run** — per-turn `flow_finished` and trace finalization are **skipped** when deferral is enabled; nested `Agent.kickoff()` / crews do not close the parent batch either.-Handlers should call **`append_assistant_message(reply)`** so the next turn’s `conversation_messages` includes assistant text. The user line is already stored by `handle_turn` — do not append it again in handlers.+Handlers should call **`append_assistant_message(reply)`** when the visible reply is not the return value, or when you trim history. A public string return is also recorded as assistant and included in the `@persist` snapshot, so a fresh Flow instance restores it. The user line is already stored by `handle_turn` — do not append it again in handlers.## Configuration overview@@ -427,7 +427,7 @@ You can override any of these by defining a same-named handler in your subclass.2. Appends the user message to `state.messages`, sets `current_user_message` / `last_user_message`. `last_intent` is **preserved from the prior turn** so the router LLM can use it as a signal.3. Runs user-defined `@start` methods (if any), then `route_conversation` as the built-in start/router, then the chosen `@listen` handler. `route_conversation` invokes the overridable `conversation_start()` helper.4. The router stores its decision in `state.last_intent` (visible to the next turn's router context).-5. If your handler returned a string and didn't already call `append_assistant_message`, `handle_turn` appends it for you.+5. If your handler returned a string and didn't already call `append_assistant_message`, `handle_turn` appends it for you and persists the updated `state.messages` so `@persist` restore includes the assistant turn.Call `handle_turn()` for chat messages. Calling `kickoff(inputs={"id": ...})` directly runs the flow graph without applying the conversational turn wrapper.diff --git a/docs/edge/ko/guides/flows/conversational-flows.mdx b/docs/edge/ko/guides/flows/conversational-flows.mdxindex 17f7509f9..cbbc7d326 100644--- a/docs/edge/ko/guides/flows/conversational-flows.mdx+++ b/docs/edge/ko/guides/flows/conversational-flows.mdx@@ -121,7 +121,7 @@ result = stream.result5. **그래프 실행** — 사용자 정의 `@start` 메서드(있는 경우) → `route_conversation`(내장 start/router) → 선택된 `@listen` 핸들러. `route_conversation`은 재정의 가능한 `conversation_start()` 헬퍼도 호출합니다.6. **실행 종료** — 지연 활성화 시 턴별 `flow_finished` 및 trace 종료 **건너뜀**; 중첩 `Agent.kickoff()` / crew도 부모 batch를 닫지 않음.-핸들러는 **`append_assistant_message(reply)`**를 호출해 다음 턴의 `conversation_messages`에 어시스턴트 응답이 포함되게 하세요. 사용자 입력은 `handle_turn`이 이미 저장합니다 — 핸들러에서 다시 추가하지 마세요.+핸들러는 보이는 응답이 반환값과 다를 때, 또는 히스토리를 자를 때 **`append_assistant_message(reply)`**를 호출하세요. public 문자열 반환값도 assistant로 기록되며 `@persist` 스냅샷에 포함되므로, 새 Flow 인스턴스에서도 복원됩니다. 사용자 입력은 `handle_turn`이 이미 저장합니다 — 핸들러에서 다시 추가하지 마세요.## 설정 개요@@ -424,7 +424,7 @@ Routes:2. 사용자 메시지를 `state.messages`에 추가하고 `current_user_message` / `last_user_message`를 설정합니다. `last_intent`는 **이전 턴 값이 유지**되어 router LLM이 신호로 활용할 수 있습니다.3. 사용자 정의 `@start` 메서드(있는 경우)를 실행한 다음 내장 start/router인 `route_conversation`을 거쳐 선택된 `@listen` 핸들러를 실행합니다. `route_conversation`은 재정의 가능한 `conversation_start()` 헬퍼를 호출합니다.4. router는 결정을 `state.last_intent`에 저장합니다 (다음 턴의 router 컨텍스트에서 보입니다).-5. 핸들러가 문자열을 반환했지만 `append_assistant_message`를 직접 호출하지 않았다면, `handle_turn`이 대신 추가해 줍니다.+5. 핸들러가 문자열을 반환했지만 `append_assistant_message`를 직접 호출하지 않았다면, `handle_turn`이 대신 추가한 뒤 갱신된 `state.messages`를 persist합니다. `@persist` 복원 시 assistant 턴이 포함됩니다.채팅 메시지에는 `handle_turn()`을 호출하세요. `kickoff(inputs={"id": ...})`를 직접 호출하면 대화형 턴 래퍼 없이 flow 그래프가 실행됩니다.diff --git a/docs/edge/pt-BR/guides/flows/conversational-flows.mdx b/docs/edge/pt-BR/guides/flows/conversational-flows.mdxindex 6843d0f47..79fc4373e 100644--- a/docs/edge/pt-BR/guides/flows/conversational-flows.mdx+++ b/docs/edge/pt-BR/guides/flows/conversational-flows.mdx@@ -122,7 +122,7 @@ Cada `handle_turn` executa este pipeline:5. **Execução do grafo** — métodos `@start` definidos pelo usuário (se houver) → `route_conversation` (o start/router embutido) → o handler `@listen` selecionado. `route_conversation` também chama o helper sobrescrevível `conversation_start()`.6. **Fim da execução** — `flow_finished` por turno e finalização de trace são **ignorados** com adiamento; `Agent.kickoff()` / crews aninhados também não fecham o batch pai.-Os handlers devem chamar **`append_assistant_message(reply)`** para que o próximo turno inclua a resposta do assistente. A linha do usuário já é salva por `handle_turn` — não acrescente de novo nos handlers.+Os handlers devem chamar **`append_assistant_message(reply)`** quando a resposta visível não for o valor de retorno, ou ao recortar o histórico. Um retorno de string pública também é gravado como assistente e entra no snapshot `@persist`, então uma nova instância de Flow o restaura. A linha do usuário já é salva por `handle_turn` — não acrescente de novo nos handlers.## Visão geral da configuração@@ -430,7 +430,7 @@ Você pode sobrescrever qualquer uma definindo um handler com o mesmo nome na su2. Anexa a mensagem do usuário em `state.messages`, define `current_user_message` / `last_user_message`. `last_intent` é **preservado do turno anterior** para que o LLM de routing possa usá-lo como sinal.3. Executa métodos `@start` definidos pelo usuário (se houver), depois `route_conversation` como start/router embutido e, por fim, o handler `@listen` escolhido. `route_conversation` invoca o helper sobrescrevível `conversation_start()`.4. O router grava sua decisão em `state.last_intent` (visível para o contexto de routing do próximo turno).-5. Se seu handler retornou uma string e ainda não chamou `append_assistant_message`, `handle_turn` anexa para você.+5. Se seu handler retornou uma string e ainda não chamou `append_assistant_message`, `handle_turn` anexa para você e persiste o `state.messages` atualizado para que a restauração `@persist` inclua o turno do assistente.Chame `handle_turn()` para mensagens de chat. Chamar `kickoff(inputs={"id": ...})` diretamente executa o grafo sem aplicar o wrapper de turno conversacional.diff --git a/lib/crewai/src/crewai/experimental/conversational_mixin.py b/lib/crewai/src/crewai/experimental/conversational_mixin.pyindex 8496ddd70..06f403ca3 100644--- a/lib/crewai/src/crewai/experimental/conversational_mixin.py+++ b/lib/crewai/src/crewai/experimental/conversational_mixin.py@@ -60,6 +60,7 @@ from crewai.flow.dsl import listen, startfrom crewai.flow.dsl._utils import _method_action, _set_flow_method_definitionfrom crewai.flow.flow_definition import FlowDefinition, FlowMethodDefinitionfrom crewai.project.crew_definition import PythonReferenceDefinition+from crewai.flow.types import FlowMethodNamefrom crewai.utilities.types import LLMMessage@@ -294,6 +295,9 @@ class _ConversationalMixin:def kickoff(self, *args: Any, **kwargs: Any) -> Any:pass+ def _persist_method_completion(self, method_name: FlowMethodName) -> None:+ pass+@propertydef method_outputs(self) -> list[Any]:pass@@ -443,6 +447,8 @@ class _ConversationalMixin:session_id as pending turn state, runs kickoff (which restores frompersist and then applies the pending turn), and promotes the result toan assistant message when the handler didn't.+ If that fallback appends, state is snapshotted again so ``@persist``+ restores the assistant reply on a fresh Flow instance.Raises:ValueError: If the flow is not conversational. Without this the@@ -481,12 +487,7 @@ class _ConversationalMixin: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- and not self._assistant_reply_appended- and self._is_public_turn_result(result)- ):- self.append_assistant_message(self._stringify_result(result))+ self._append_public_turn_result_and_persist(result)except Exception as exc:failed_event = ConversationTurnFailedEvent(type="conversation_turn_failed",@@ -571,12 +572,7 @@ class _ConversationalMixin:object.__setattr__(self, "_streaming_conversation_turn", original_streaming_turn)- if (- result is not None- and not self._assistant_reply_appended- and self._is_public_turn_result(result)- ):- self.append_assistant_message(self._stringify_result(result))+ self._append_public_turn_result_and_persist(result)except HumanFeedbackPending as exc:return excexcept Exception as exc:@@ -1449,6 +1445,32 @@ class _ConversationalMixin:return "public"return "private"+ def _append_public_turn_result_and_persist(self, result: Any) -> None:+ """Copy a public handler return into history, then snapshot if needed.++ Built-in routes already call ``append_assistant_message`` inside the+ method, so this is a no-op for them. Custom ``@listen`` handlers that+ only ``return`` a public string hit this path after ``kickoff()``,+ which is after the per-method ``@persist`` snapshot. Persist again so+ a fresh Flow instance restores the assistant reply.+ """+ if (+ result is None+ or self._assistant_reply_appended+ or not self._is_public_turn_result(result)+ ):+ return+ self.append_assistant_message(self._stringify_result(result))+ self._persist_fallback_assistant_reply()++ def _persist_fallback_assistant_reply(self) -> None:+ """Write the current state using the same persist path as kickoff."""+ last = self._method_outputs[-1] if self._method_outputs else None+ method_name = last.get("method") if isinstance(last, dict) else None+ if not isinstance(method_name, str) or not method_name:+ return+ self._persist_method_completion(FlowMethodName(method_name))+def _is_public_turn_result(self, result: Any) -> bool:"""Whether a handler's return value should become the assistant reply.diff --git a/lib/crewai/tests/test_flow_conversation.py b/lib/crewai/tests/test_flow_conversation.pyindex ca90d3b96..439a4ff03 100644--- a/lib/crewai/tests/test_flow_conversation.py+++ b/lib/crewai/tests/test_flow_conversation.py@@ -34,6 +34,7 @@ from crewai.experimental import (RouterConfig,)from crewai.flow import Flow, ChatState, listen, start+from crewai.flow.persistence import SQLiteFlowPersistence, persistfrom crewai.flow.async_feedback import HumanFeedbackPending, PendingFeedbackContextfrom crewai.flow.flow_context import (current_flow_defer_trace_finalization,@@ -1599,6 +1600,121 @@ class TestHandleTurnReplyFallback:assert assistant_messages == ["computed reply"]+class TestPersistCustomListenReplies:+ """Custom ``@listen`` returns must land in ``@persist`` snapshots.++ The fallback appends after ``kickoff()``, so the per-method snapshot is+ user-only unless we persist again. Fresh Flow instances restore the+ latest row; without that second snapshot the assistant turn disappears.+ """++ SESSION = "persist-custom-listen-session"++ @staticmethod+ def _roles(messages: Any) -> list[tuple[Any, Any]]:+ rows: list[tuple[Any, Any]] = []+ for message in messages:+ if hasattr(message, "role"):+ rows.append((message.role, message.content))+ else:+ rows.append((message["role"], message["content"]))+ return rows++ def test_custom_listen_return_persists_across_fresh_instances(+ self, tmp_path: Any+ ) -> None:+ store = SQLiteFlowPersistence(str(tmp_path / "custom-listen.db"))++ @persist(store)+ class ResearchBot(ConversationalFlow):+ def route_turn(self, context: dict[str, Any]) -> str | None:+ return "research"++ @listen("research")+ def run_research(self) -> str:+ return f"researched: {self.state.current_user_message}"++ bot_a = ResearchBot()+ bot_a.handle_turn("what is CrewAI?", session_id=self.SESSION)++ saved = store.load_state(self.SESSION)+ assert saved is not None+ assert self._roles(saved["messages"]) == [+ ("user", "what is CrewAI?"),+ ("assistant", "researched: what is CrewAI?"),+ ]++ bot_b = ResearchBot()+ bot_b.handle_turn("tell me more", session_id=self.SESSION)++ assert self._roles(bot_b.state.messages) == [+ ("user", "what is CrewAI?"),+ ("assistant", "researched: what is CrewAI?"),+ ("user", "tell me more"),+ ("assistant", "researched: tell me more"),+ ]++ def test_builtin_converse_does_not_double_append_with_persist(+ self, tmp_path: Any+ ) -> None:+ store = SQLiteFlowPersistence(str(tmp_path / "converse.db"))+ chat_llm = MagicMock()+ chat_llm.call.return_value = "hello back"++ @ConversationConfig(llm=chat_llm)+ @persist(store)+ class ChatBot(ConversationalFlow):+ def route_turn(self, context: dict[str, Any]) -> str | None:+ return None++ bot_a = ChatBot()+ bot_a.handle_turn("hi", session_id=self.SESSION)++ assert self._roles(bot_a.state.messages) == [+ ("user", "hi"),+ ("assistant", "hello back"),+ ]++ bot_b = ChatBot()+ bot_b.handle_turn("again", session_id=self.SESSION)++ assert self._roles(bot_b.state.messages) == [+ ("user", "hi"),+ ("assistant", "hello back"),+ ("user", "again"),+ ("assistant", "hello back"),+ ]++ def test_custom_listen_return_emits_one_user_and_one_assistant_message_event(+ self, tmp_path: Any+ ) -> None:+ store = SQLiteFlowPersistence(str(tmp_path / "trace.db"))++ @persist(store)+ class ResearchBot(ConversationalFlow):+ def route_turn(self, context: dict[str, Any]) -> str | None:+ return "research"++ @listen("research")+ def run_research(self) -> str:+ return "researched"++ events: list[ConversationMessageAddedEvent] = []+ with crewai_event_bus.scoped_handlers():++ @crewai_event_bus.on(ConversationMessageAddedEvent)+ def capture(_: Any, event: ConversationMessageAddedEvent) -> None:+ events.append(event)++ ResearchBot().handle_turn("hello", session_id=self.SESSION)+ crewai_event_bus.flush()++ assert [(event.role, event.content) for event in events] == [+ ("user", "hello"),+ ("assistant", "researched"),+ ]++class TestFalsyRouteTurnFallback:"""A falsy ``route_turn()`` must never replay a previous turn's intent.