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.

[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.mdx
index 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.result
5. **تنفيذ الرسم** — طرق `@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 instantiation
2. يُلحق رسالة المستخدم بـ `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.mdx
index 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.mdx
index 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.result
5. **그래프 실행** — 사용자 정의 `@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.mdx
index 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 su
2. 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.py
index 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, start
from crewai.flow.dsl._utils import _method_action, _set_flow_method_definition
from crewai.flow.flow_definition import FlowDefinition, FlowMethodDefinition
from crewai.project.crew_definition import PythonReferenceDefinition
+from crewai.flow.types import FlowMethodName
from 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
+
@property
def method_outputs(self) -> list[Any]:
pass
@@ -443,6 +447,8 @@ class _ConversationalMixin:
session_id as pending turn state, runs kickoff (which restores from
persist and then applies the pending turn), and promotes the result to
an 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 exc
except 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.py
index 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, persist
from crewai.flow.async_feedback import HumanFeedbackPending, PendingFeedbackContext
from 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.