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): add experimental turn and reply identities (OSS-197) (#7909)

Lorenze Jay19d4154b0b96
diff --git a/docs/edge/ar/guides/flows/conversational-flows.mdx b/docs/edge/ar/guides/flows/conversational-flows.mdx
index 0f0d940ce..3b67a1c16 100644
--- a/docs/edge/ar/guides/flows/conversational-flows.mdx
+++ b/docs/edge/ar/guides/flows/conversational-flows.mdx
@@ -691,3 +691,57 @@ async def run_job():
عند إغلاق الجلسة، استدعِ `runner.request_close()` على loop المالك قبل انتظار انتهاء التنفيذ في المقدمة، ثم `await runner.aclose()`. يؤدي ذلك إلى إغلاق قبول العمل والنشر وإرسال إشارة إلى كل worker وتحرير publishers المنتظرين وانتظار tasks المملوكة. يجب أن تستدعي طرق العمل `check_open()` عند حدود المراحل. لا تُجهض عملية provider قيد التنفيذ. يغلق فشل subscriber الـ runner بدل ترك publishers معلقين. لا ينبغي أن يؤدي إيقاف الكلام وحده إلى إغلاق runner.
دورة الحياة الأولية هي `queued → running → completed/failed`. لا تتوفر pause/resume أو الاستبدال أو تسليم الردود تلقائيًا أو الاستعادة الموزعة. يمكن تسلسل السجلات باستخدام إمكانات الحالة الموجودة، لكن استعادتها لا تعيد إنشاء workers نشطين ولا تضمن تنفيذ الآثار الخارجية مرة واحدة بالضبط.
+
+## هويات الأدوار والردود العامة التجريبية
+
+استورد `TurnRecord` و`ReplyRecord` و`TurnState` و`ReplyEvent` و`TurnRunner` صراحةً من `crewai.experimental.flow_turns`. هذه API اختيارية وتجريبية وقد تتغير. تغلّف conversational Flow موجودًا؛ ولا تغيّر `handle_turn()` أو `stream_turn()` المستقرة أو قيم الإرجاع أو عقد jobs التجريبي.
+
+تضيف `TurnState` إلى `ConversationState` مجموعتي `turns` و`replies` القابلتين للتسلسل. يتتبع استدعاء `TurnRunner.stream_turn()` مدخلًا مؤكدًا واحدًا وردّه العام الأساسي. لكل مدخل `turn_id` يستخدم مرة واحدة داخل الجلسة؛ ويأخذ الكلام الجديد أو التصحيح هوية دور جديدة. `input_revision` عدد صحيح موجب، افتراضيًا `1`، وليس استبدالًا تلقائيًا للنص المؤقت. `delivery_id` هو هوية الرد الوحيدة؛ لا توجد هوية `reply_id` ثانية. أنواع الرد هي `acknowledgment` و`answer` و`progress`.
+
+```python
+from crewai.flow import Flow, listen
+from crewai.experimental.flow_turns import TurnRunner, TurnState
+
+class Chat(Flow[TurnState]):
+ conversational = True
+
+ def route_turn(self, context):
+ return "acknowledge"
+
+ @listen("acknowledge")
+ def handle_acknowledge(self):
+ return "Request received."
+
+flow = Chat(suppress_flow_events=True)
+runner = TurnRunner(flow)
+events = runner.stream_turn("Hello", turn_id="turn-1", kind="acknowledgment")
+try:
+ for event in events:
+ if runner.accept_event(event):
+ print(event.model_dump_json())
+finally:
+ events.close()
+
+snapshot = runner.snapshot()
+reply = snapshot["replies"][0]
+runner.interrupt(
+ session_id=reply["session_id"], turn_id=reply["turn_id"],
+ input_revision=reply["input_revision"], delivery_id=reply["delivery_id"],
+)
+```
+
+تستخدم الردود الثابتة وproviders التي تعيد جوابًا نهائيًا فقط عقد `text`/`completed` العام نفسه الذي تستخدمه الردود المتدفقة. يظل Flow الموجود مسؤولًا عن سجل المحادثة الأساسي. ترتب `seq` الأحداث داخل الرد، وتُرقّم `segment_id` أجزاء النص بدءًا من واحد. جزء النص ليس بالضرورة جملة صوتية كاملة. تحمل أحداث اختيار المسار وتوليد الرد الهوية نفسها. تعني `completed` انتهاء توليد النص، **ولا** تعني تشغيل الصوت أو سماعه.
+
+يُسمح بالنص الحي من طرق الرد العام المخصصة فقط (`converse_turn` و`answer_from_history_turn` افتراضيًا)، أو من هويات Agent العامة المختارة صراحةً. اضبط `public_methods` وcallback الخاص بـ `public_agent_ids` بعناية؛ ولا تحدد طريقة تمزج عمل LLM الخاص مع توليد الرد العام. تُستبعد تدفقات router والتفكير وtool-call chunks والاستدعاءات التي تفعّل tools وAgents غير المعنية. لا تتحول نتائج Agent الخاصة إلى ردود. ينشر provider الذي لا يتيح أجزاء النص رسالته الأساسية النهائية دون اختلاق توقيت للـ LLM.
+
+تقبل `runner.accept_event(event)` حدثًا صادرًا عن runner قبل تسليمه للنقل. ترفض الهوية الأجنبية والتسلسل المكرر أو غير المرتب والمخرجات التي أُلغي صلاحيتها بسبب المقاطعة أو الفشل. استدعها بعد أي انتظار أو queue في التطبيق وقبل التسليم مباشرةً. ليست أداة للتحقق من إيصالات تشغيل الصوت غير الموثوقة من العميل. تتطلب المخرجات التي سُلّمت بالفعل حماية الهوية وإيقاف الصوت داخل adapter.
+
+تستهدف `runner.interrupt(session_id=..., turn_id=..., input_revision=..., delivery_id=...)` ردًا واحدًا، وتكون الطلبات الصحيحة المتكررة idempotent. أثناء التوليد تجعل الدور والرد interrupted؛ وبعد التوليد تحفظ النص المكتمل وتحدد مقاطعة الرد دون تغيير نجاح job. يمكن لـ `on_interrupt` إرسال إشارة إلى فحوص الإيقاف التعاوني الموجودة، ويمكن لـ `should_interrupt` مراقبة إشارة التطبيق الحالية. لا تُجهض callbacks هذه استدعاء provider عشوائيًا. يجب انتظار انتهاء stream قبل تنفيذ دور آخر على Flow نفسه. يؤدي إغلاق iterator إلى طلب المقاطعة وانتظار التنفيذ الأصلي، وقد ينتظر عملية provider قيد التنفيذ.
+
+للدمج مع العمل الخلفي، أعلن `class WorkChatState(TurnState, JobState[MyJob]): ...`. احتفظ بـ `JobRunner.state_lock` طوال **كامل** التكرار في المقدمة وكل تعديلات jobs الأب. يحمي TurnRunner سجلاته وأوامر المقاطعة بصورة منفصلة. لا تشغّل واجهات الدور الأصلية بالتوازي مع wrapper. بعد قبول job بنجاح، تربط `runner.associate_job(job)` هويات الجلسة والدور الأصلي وrevision/attempt بالرد النشط؛ ولا تقبل أو تشغّل أو تلغي العمل. لا يبطل دور محادثة جديد البحث المستقل.
+
+تستخدم `elapsed_ms` ساعة server monotonic منذ بدء الدور المتتبع. تمثل `model_first_text_ms`، عند توفرها، الفرق بين **timestamps لأحداث** بدء طلب provider وأول نص عام؛ وتشمل عمل provider وSDK والشبكة ولا تمثل TTFT لمحرك inference وحده. لا تطرح timestamps المتصفح والخادم بعضها من بعض. يظل أول جزء TTS والصوت المخزن وبداية الصوت المسموع فعليًا واكتمال التشغيل من قياسات adapter.
+
+لا يوفر هذا الإصدار queues للردود الخلفية أو جدولة دور الكلام أو إيصالات التشغيل أو محاذاة الكلمات الدقيقة أو speculative generation أو pause/resume للـ jobs. تحتوي snapshots على سجلات لا أقفال أو إشارات إلغاء أو تنفيذ نشط، ولا تستأنف العمل أو تعيد تشغيل الرد. استعد الحالة قبل بدء دور حي متتبع جديد؛ ويرفض wrapper خيار `from_checkpoint` و`restore_from_state_id` عمدًا. تبقى المصالحة المستمرة وحفظ سجلات التتبع النهائية عملًا منفصلًا. استخدم واجهات Flow المستقرة لمسارات checkpoint الموجودة.
+
+أثناء التنفيذ المتتبع، تظل الحالة المستعادة الحالية هي المرجع: يُمنع التحميل التلقائي لحالة الجلسة كي لا تُفقد سجلات turn/reply المقبولة أو تحديثات jobs الخلفية. تحتفظ واجهات Flow الأصلية بسلوك تحميل الحالة المحفوظة المعتاد. لا يؤدي إغلاق iterator بعد حدث نهائي إلى مقاطعة الرد المكتمل. ويظل حدث الفشل إشارة نهائية مقبولة لدورة الحياة إذا وصلت المقاطعة بعد الفشل.
diff --git a/docs/edge/en/guides/flows/conversational-flows.mdx b/docs/edge/en/guides/flows/conversational-flows.mdx
index e716d7369..f7ffabcac 100644
--- a/docs/edge/en/guides/flows/conversational-flows.mdx
+++ b/docs/edge/en/guides/flows/conversational-flows.mdx
@@ -692,3 +692,57 @@ Project relevant job status and outputs through `build_router_context()` and `bu
At session teardown, call `runner.request_close()` on its owning loop before draining foreground execution, then `await runner.aclose()`. This closes admission/publication, signals each worker, releases waiting publishers, and settles owned tasks. Work methods must call `check_open()` at stage boundaries. An in-flight provider operation is not aborted. Subscriber failure closes the runner rather than stranding publishers. Stopping speech alone should not close the runner.
The initial lifecycle is `queued → running → completed/failed`. Pause/resume, replacement, automatic reply delivery, and distributed recovery are not supplied. Records can be serialized with existing state facilities, but restoring them does not recreate live workers or guarantee exactly-once external effects.
+
+## Experimental turn and public reply identities
+
+Import `TurnRecord`, `ReplyRecord`, `TurnState`, `ReplyEvent`, and `TurnRunner` explicitly from `crewai.experimental.flow_turns`. This opt-in API may change. It wraps an existing conversational Flow; the stable `handle_turn()`/`stream_turn()` APIs, return values, and experimental job contract are unchanged.
+
+`TurnState` extends `ConversationState` with serializable `turns` and `replies`. One invocation of `TurnRunner.stream_turn()` tracks one committed input and its primary public reply. Every accepted input has a session-scoped, single-use `turn_id`; a new utterance or correction gets a new turn ID. `input_revision` is a positive integer (default `1`), not automatic provisional transcript replacement. `delivery_id` is the sole reply identity; there is no second `reply_id`. Reply kinds are `acknowledgment`, `answer`, and `progress`.
+
+```python
+from crewai.flow import Flow, listen
+from crewai.experimental.flow_turns import TurnRunner, TurnState
+
+class Chat(Flow[TurnState]):
+ conversational = True
+
+ def route_turn(self, context):
+ return "acknowledge"
+
+ @listen("acknowledge")
+ def handle_acknowledge(self):
+ return "Request received."
+
+flow = Chat(suppress_flow_events=True)
+runner = TurnRunner(flow)
+events = runner.stream_turn("Hello", turn_id="turn-1", kind="acknowledgment")
+try:
+ for event in events:
+ if runner.accept_event(event):
+ print(event.model_dump_json())
+finally:
+ events.close()
+
+snapshot = runner.snapshot()
+reply = snapshot["replies"][0]
+runner.interrupt(
+ session_id=reply["session_id"], turn_id=reply["turn_id"],
+ input_revision=reply["input_revision"], delivery_id=reply["delivery_id"],
+)
+```
+
+Hardcoded replies and final-only providers emit the same public `text`/`completed` contract as streaming responders. The existing Flow remains responsible for canonical history. `seq` orders events within a delivery; `segment_id` numbers text deltas starting at one. A text delta is not necessarily a complete spoken sentence. Route and generation observation events include the same identity. `completed` means text generation finished, **not** that audio was played or heard.
+
+Only dedicated public responder methods (`converse_turn` and `answer_from_history_turn` by default), or explicitly selected public agent IDs, allow live model text. Configure `public_methods` and the `public_agent_ids` callback deliberately; do not designate a method that mixes private model work with public response generation. Router streams, reasoning, tool-call chunks, tool-enabled calls, and unrelated agents are excluded. Private agent results do not become replies. Providers without observable deltas still publish their canonical final message; no model timing is invented.
+
+`runner.accept_event(event)` claims one runner-issued event before transport handoff. It rejects foreign identity, duplicate/out-of-order sequence, and output invalidated by interruption or failure. Invoke it after any application queue/delay, immediately before handoff. It is not a validator for untrusted client playback receipts. Already handed-off output needs adapter-side identity fencing and audio interruption.
+
+`runner.interrupt(session_id=..., turn_id=..., input_revision=..., delivery_id=...)` targets exactly one reply and is idempotent for valid repeated requests. During generation it marks the turn/reply interrupted; after generation it preserves completed text and marks the reply interrupted without changing job success. `on_interrupt` may signal existing cooperative stage checks; `should_interrupt` can observe an application's existing stop signal. These callbacks do not abort arbitrary provider calls. The stream must settle before another tracked turn can execute on the same Flow. Closing the iterator signals interruption and drains native execution; it can wait for an in-flight provider.
+
+To compose with background work, declare `class WorkChatState(TurnState, JobState[MyJob]): ...`. Hold `JobRunner.state_lock` around the **entire** foreground iteration and all parent job mutations. TurnRunner separately protects its records and interruption controls. Do not run native turn APIs concurrently with the wrapper. After successfully admitting a job, `runner.associate_job(job)` links its session/originating turn and revision/attempt to the active reply; it never admits, submits, or cancels work. A new conversational turn does not invalidate independent research.
+
+`elapsed_ms` uses a server monotonic clock from tracked-turn startup. `model_first_text_ms`, when available, is the difference between provider request-start and first public text **event timestamps**; it includes provider/SDK/network work and is not isolated inference-engine TTFT. Never subtract browser and server timestamps. TTS first chunk, cached audio, physical audible onset, and playback completion remain adapter measurements.
+
+This increment does not supply background reply queues, speaking-floor scheduling, playback receipts, exact word alignment, speculative generation, or job pause/resume. Snapshots contain records, not locks, cancellation signals or running executions. They do not resume work or replay delivery. Restore state before creating a new tracked live turn; `from_checkpoint` and `restore_from_state_id` are deliberately rejected by this wrapper. Durable reconciliation and persistence of terminal tracking records remain separate work. Continue using the stable Flow APIs for existing checkpoint workflows.
+
+During tracked execution, the current restored state remains authoritative: automatic session reload is suppressed so it cannot discard admitted turn/reply records or accepted background job updates. Native Flow turn APIs retain their existing persistence reload behavior. Closing after a terminal event does not interrupt the completed reply. Failure remains an acceptable terminal lifecycle signal if interruption arrives after failure.
diff --git a/docs/edge/ko/guides/flows/conversational-flows.mdx b/docs/edge/ko/guides/flows/conversational-flows.mdx
index 42f1ca291..a9ffd3e85 100644
--- a/docs/edge/ko/guides/flows/conversational-flows.mdx
+++ b/docs/edge/ko/guides/flows/conversational-flows.mdx
@@ -687,3 +687,57 @@ async def run_job():
Session 종료 시 foreground 실행을 정리하기 전에 소유 loop에서 `runner.request_close()`를 호출하고 이후 `await runner.aclose()`를 실행합니다. 새 작업 등록과 publication을 닫고 각 worker에 신호를 보내며 대기 중인 publisher를 해제하고 소유 task를 정리합니다. Work method는 단계 경계에서 `check_open()`을 호출해야 합니다. 진행 중인 provider 작업은 강제로 중단되지 않습니다. Subscriber 실패 시 publisher가 무한히 기다리지 않도록 runner가 닫힙니다. 음성 재생만 중지할 때는 runner를 닫지 않습니다.
초기 lifecycle은 `queued → running → completed/failed`입니다. Pause/resume, replacement, 자동 응답 전달과 분산 recovery는 제공하지 않습니다. 기존 state 기능으로 record를 직렬화할 수 있지만, 복원은 live worker를 다시 만들거나 외부 작업의 exactly-once 실행을 보장하지 않습니다.
+
+## 실험적 턴 및 공개 응답 식별자
+
+`TurnRecord`, `ReplyRecord`, `TurnState`, `ReplyEvent`, `TurnRunner`는 `crewai.experimental.flow_turns`에서 명시적으로 가져옵니다. 이 API는 선택적으로 사용하며 변경될 수 있습니다. 기존 conversational Flow를 감싸므로 안정적인 `handle_turn()`/`stream_turn()` API, 반환값, 실험적 job 계약은 바뀌지 않습니다.
+
+`TurnState`는 `ConversationState`에 직렬화 가능한 `turns`와 `replies`를 추가합니다. `TurnRunner.stream_turn()` 호출 하나는 확정된 입력 하나와 기본 공개 응답을 추적합니다. 입력마다 세션 내에서 한 번만 사용하는 `turn_id`가 있으며, 새 발화나 정정에는 새 턴 ID를 사용합니다. `input_revision`은 양의 정수(기본값 `1`)이며 잠정 전사를 자동으로 교체하지 않습니다. `delivery_id`가 유일한 응답 ID이고 별도의 `reply_id`는 없습니다. 응답 종류는 `acknowledgment`, `answer`, `progress`입니다.
+
+```python
+from crewai.flow import Flow, listen
+from crewai.experimental.flow_turns import TurnRunner, TurnState
+
+class Chat(Flow[TurnState]):
+ conversational = True
+
+ def route_turn(self, context):
+ return "acknowledge"
+
+ @listen("acknowledge")
+ def handle_acknowledge(self):
+ return "Request received."
+
+flow = Chat(suppress_flow_events=True)
+runner = TurnRunner(flow)
+events = runner.stream_turn("Hello", turn_id="turn-1", kind="acknowledgment")
+try:
+ for event in events:
+ if runner.accept_event(event):
+ print(event.model_dump_json())
+finally:
+ events.close()
+
+snapshot = runner.snapshot()
+reply = snapshot["replies"][0]
+runner.interrupt(
+ session_id=reply["session_id"], turn_id=reply["turn_id"],
+ input_revision=reply["input_revision"], delivery_id=reply["delivery_id"],
+)
+```
+
+고정 응답과 최종 결과만 반환하는 provider도 스트리밍 응답과 같은 공개 `text`/`completed` 계약을 사용합니다. 기존 Flow가 정식 대화 기록을 관리합니다. `seq`는 delivery 내 이벤트 순서이고 `segment_id`는 1부터 시작하는 텍스트 델타 번호입니다. 델타가 완전한 음성 문장이라는 보장은 없습니다. 라우팅과 생성 관측 이벤트도 같은 ID를 포함합니다. `completed`는 텍스트 생성 완료이며, **오디오 재생이나 청취 완료가 아닙니다**.
+
+전용 공개 응답 메서드(기본값 `converse_turn`, `answer_from_history_turn`) 또는 명시적으로 선택한 공개 Agent ID만 실시간 모델 텍스트를 허용합니다. `public_methods`와 `public_agent_ids` callback을 신중하게 설정하고 비공개 모델 작업과 공개 응답을 섞는 메서드를 선택하지 마세요. router 스트림, 추론, tool-call chunk, tools가 활성화된 호출, 무관한 Agent는 제외합니다. 비공개 Agent 결과는 응답으로 전환되지 않습니다. 관측 가능한 델타가 없는 provider는 정식 최종 메시지만 공개하며 모델 타이밍을 만들어내지 않습니다.
+
+`runner.accept_event(event)`는 전송 직전에 runner가 발행한 이벤트 하나를 승인합니다. 다른 소유자의 ID, 중복되거나 순서가 뒤바뀐 이벤트, 중단 또는 실패로 무효화된 출력을 거부합니다. 애플리케이션 queue나 지연 이후 실제 전달 직전에 호출하세요. 신뢰할 수 없는 클라이언트 재생 receipt를 검증하는 API는 아닙니다. 이미 전달한 출력은 adapter에서 ID를 확인하고 오디오를 중단해야 합니다.
+
+`runner.interrupt(session_id=..., turn_id=..., input_revision=..., delivery_id=...)`는 응답 하나만 대상으로 하며 올바른 반복 요청은 idempotent합니다. 생성 중에는 턴과 응답을 interrupted로 표시합니다. 생성 후에는 완료된 텍스트를 보존하고 job 성공 상태를 바꾸지 않은 채 응답 중단을 표시합니다. `on_interrupt`는 기존 협력적 중단 검사에 신호를 보내고 `should_interrupt`는 애플리케이션의 기존 중단 신호를 관찰할 수 있습니다. callback은 임의의 provider 호출을 강제로 중단하지 않습니다. 같은 Flow에서 다음 턴을 실행하기 전에 stream이 종료되어야 합니다. iterator를 닫으면 중단을 요청하고 기존 실행을 끝까지 기다리므로 진행 중인 provider 작업을 기다릴 수 있습니다.
+
+백그라운드 작업과 조합하려면 `class WorkChatState(TurnState, JobState[MyJob]): ...`를 선언합니다. **전체** foreground 반복과 모든 부모 job 변경 동안 `JobRunner.state_lock`을 유지하세요. TurnRunner는 자체 기록과 중단 제어를 별도로 보호합니다. wrapper와 기본 턴 API를 동시에 실행하지 마세요. job을 성공적으로 등록한 뒤 `runner.associate_job(job)`을 호출하면 세션, 원래 턴, revision/attempt를 활성 응답에 연결합니다. 이 메서드는 작업을 등록, 제출 또는 취소하지 않습니다. 새 대화 턴은 독립적인 연구를 무효화하지 않습니다.
+
+`elapsed_ms`는 추적 턴 시작부터 server monotonic clock을 사용합니다. 관측 가능한 `model_first_text_ms`는 provider 요청 시작과 첫 공개 텍스트의 **이벤트 timestamp 차이**입니다. provider/SDK/네트워크 작업을 포함하며 추론 엔진만의 TTFT가 아닙니다. 브라우저와 서버 timestamp를 서로 빼지 마세요. TTS 첫 chunk, 캐시 오디오, 실제 가청 시작, 재생 완료는 adapter 측정입니다.
+
+이 단계는 백그라운드 응답 queue, 발언권 스케줄링, 재생 receipt, 정확한 단어 정렬, speculative generation, job pause/resume를 제공하지 않습니다. snapshot에는 기록만 있고 lock, 취소 신호, 실행 중인 작업은 없습니다. 작업을 재개하거나 delivery를 다시 재생하지 않습니다. 새 추적 live turn 전에 상태를 복원하세요. wrapper는 `from_checkpoint` 및 `restore_from_state_id`를 의도적으로 거부합니다. 영속적인 조정과 최종 추적 기록 저장은 별도 작업입니다. 기존 checkpoint 워크플로에는 안정적인 Flow API를 계속 사용하세요.
+
+추적 실행 중에는 현재 복원된 상태가 기준이 됩니다. 자동 세션 재로드를 억제하여 등록된 turn/reply 기록이나 승인된 백그라운드 job 업데이트가 사라지지 않도록 합니다. 기본 Flow 턴 API의 기존 영속 상태 재로드 동작은 유지됩니다. 종료 이벤트 이후 iterator를 닫아도 완료된 응답을 중단하지 않습니다. 실패 이후 중단 요청이 도착해도 실패 이벤트는 유효한 종료 수명 주기 신호로 처리됩니다.
diff --git a/docs/edge/pt-BR/guides/flows/conversational-flows.mdx b/docs/edge/pt-BR/guides/flows/conversational-flows.mdx
index 4cedd2aff..e40d31b9e 100644
--- a/docs/edge/pt-BR/guides/flows/conversational-flows.mdx
+++ b/docs/edge/pt-BR/guides/flows/conversational-flows.mdx
@@ -692,3 +692,57 @@ Forneça status e saídas relevantes pelos hooks `build_router_context()` e `bui
Ao encerrar a sessão, chame `runner.request_close()` no loop proprietário antes de aguardar a execução em primeiro plano e, depois, `await runner.aclose()`. Isso fecha a admissão e a publicação, sinaliza cada worker, libera publishers em espera e aguarda as tasks próprias. Os métodos de trabalho devem chamar `check_open()` nos limites das etapas. Uma operação do provider em andamento não é abortada. Uma falha do subscriber fecha o runner para não deixar publishers bloqueados. Interromper apenas a fala não deve fechar o runner.
O ciclo inicial é `queued → running → completed/failed`. Pause/resume, substituição, entrega automática de respostas e recuperação distribuída não são fornecidos. Os registros podem ser serializados com os recursos de estado existentes, mas restaurá-los não recria workers ativos nem garante efeitos externos exatamente uma vez.
+
+## Identidades experimentais de turnos e respostas públicas
+
+Importe `TurnRecord`, `ReplyRecord`, `TurnState`, `ReplyEvent` e `TurnRunner` explicitamente de `crewai.experimental.flow_turns`. Esta API é opcional e pode mudar. Ela envolve um conversational Flow existente; as APIs estáveis `handle_turn()`/`stream_turn()`, seus valores de retorno e o contrato experimental de jobs permanecem inalterados.
+
+`TurnState` estende `ConversationState` com `turns` e `replies` serializáveis. Uma chamada a `TurnRunner.stream_turn()` acompanha uma entrada confirmada e sua resposta pública principal. Cada entrada tem um `turn_id` usado uma única vez na sessão; uma nova fala ou correção recebe um novo ID. `input_revision` é um inteiro positivo (padrão `1`), não uma substituição automática de transcrição provisória. `delivery_id` é a única identidade da resposta; não existe um segundo `reply_id`. Os tipos são `acknowledgment`, `answer` e `progress`.
+
+```python
+from crewai.flow import Flow, listen
+from crewai.experimental.flow_turns import TurnRunner, TurnState
+
+class Chat(Flow[TurnState]):
+ conversational = True
+
+ def route_turn(self, context):
+ return "acknowledge"
+
+ @listen("acknowledge")
+ def handle_acknowledge(self):
+ return "Request received."
+
+flow = Chat(suppress_flow_events=True)
+runner = TurnRunner(flow)
+events = runner.stream_turn("Hello", turn_id="turn-1", kind="acknowledgment")
+try:
+ for event in events:
+ if runner.accept_event(event):
+ print(event.model_dump_json())
+finally:
+ events.close()
+
+snapshot = runner.snapshot()
+reply = snapshot["replies"][0]
+runner.interrupt(
+ session_id=reply["session_id"], turn_id=reply["turn_id"],
+ input_revision=reply["input_revision"], delivery_id=reply["delivery_id"],
+)
+```
+
+Respostas fixas e providers que retornam somente o resultado final usam o mesmo contrato público `text`/`completed` das respostas em streaming. O Flow existente continua responsável pelo histórico canônico. `seq` ordena eventos dentro de uma entrega; `segment_id` numera deltas de texto a partir de um. Um delta não é necessariamente uma frase falada completa. Eventos de rota e observação de geração incluem a mesma identidade. `completed` significa que a geração de texto terminou, **não** que o áudio foi reproduzido ou ouvido.
+
+Somente métodos dedicados à resposta pública (`converse_turn` e `answer_from_history_turn` por padrão), ou IDs de Agent públicos selecionados explicitamente, permitem texto ao vivo do modelo. Configure `public_methods` e o callback `public_agent_ids` com cuidado; não selecione um método que misture trabalho privado do modelo e geração pública. Streams do router, raciocínio, chunks de tool calls, chamadas com tools habilitadas e Agents não relacionados são excluídos. Resultados privados de Agent não viram respostas. Providers sem deltas observáveis publicam sua mensagem canônica final sem inventar métricas do modelo.
+
+`runner.accept_event(event)` aceita um evento emitido pelo runner antes do envio ao transporte. Rejeita identidade estrangeira, sequência duplicada ou fora de ordem e saída invalidada por interrupção ou falha. Chame após qualquer fila/espera da aplicação, imediatamente antes do envio. Não valida recibos de reprodução não confiáveis enviados pelo cliente. Saídas já enviadas precisam de proteção por identidade e interrupção de áudio no adapter.
+
+`runner.interrupt(session_id=..., turn_id=..., input_revision=..., delivery_id=...)` direciona exatamente uma resposta e é idempotente para pedidos válidos repetidos. Durante a geração, marca turno e resposta como interrupted; após a geração, preserva o texto completo e marca a interrupção sem alterar o sucesso do job. `on_interrupt` pode sinalizar verificações cooperativas existentes; `should_interrupt` pode observar o sinal de parada da aplicação. Esses callbacks não abortam chamadas arbitrárias de provider. O stream deve terminar antes de executar outro turno no mesmo Flow. Fechar o iterator sinaliza a interrupção e aguarda a execução nativa, podendo esperar uma operação de provider em andamento.
+
+Para combinar com trabalho em segundo plano, declare `class WorkChatState(TurnState, JobState[MyJob]): ...`. Mantenha `JobRunner.state_lock` durante **toda** a iteração em primeiro plano e todas as alterações de jobs no estado pai. TurnRunner protege seus registros e controles de interrupção separadamente. Não execute APIs nativas de turno simultaneamente com o wrapper. Após admitir um job com sucesso, `runner.associate_job(job)` associa sessão/turno de origem e revision/attempt à resposta ativa; nunca admite, inicia ou cancela trabalho. Um novo turno de conversa não invalida pesquisa independente.
+
+`elapsed_ms` usa um relógio monotônico do servidor a partir do início do turno acompanhado. Quando disponível, `model_first_text_ms` é a diferença entre os **timestamps dos eventos** de início da solicitação ao provider e primeiro texto público; inclui trabalho do provider/SDK/rede e não é TTFT isolado do motor de inferência. Não subtraia timestamps do navegador e do servidor. Primeiro chunk de TTS, áudio em cache, início audível físico e conclusão da reprodução continuam sendo métricas do adapter.
+
+Esta etapa não oferece filas de respostas em segundo plano, agendamento da vez de falar, recibos de reprodução, alinhamento exato de palavras, geração especulativa ou pause/resume de jobs. Snapshots contêm registros, não locks, sinais de cancelamento ou execuções ativas. Não retomam trabalho nem repetem entregas. Restaure o estado antes de criar um novo turno acompanhado; este wrapper rejeita `from_checkpoint` e `restore_from_state_id` deliberadamente. Reconciliação durável e persistência dos registros finais de acompanhamento continuam sendo trabalhos separados. Use as APIs estáveis de Flow para workflows existentes de checkpoint.
+
+Durante a execução acompanhada, o estado atual restaurado permanece como referência: o recarregamento automático da sessão é suprimido para não descartar registros de turn/reply admitidos nem atualizações aceitas de jobs em segundo plano. As APIs nativas de turno do Flow mantêm seu comportamento de recarregamento de persistência. Fechar o iterator após um evento terminal não interrompe a resposta concluída. Uma falha continua sendo um sinal terminal de ciclo de vida aceito se a interrupção chegar após a falha.
diff --git a/lib/crewai/src/crewai/experimental/flow_turns.py b/lib/crewai/src/crewai/experimental/flow_turns.py
new file mode 100644
index 000000000..d0d7089de
--- /dev/null
+++ b/lib/crewai/src/crewai/experimental/flow_turns.py
@@ -0,0 +1,448 @@
+"""Experimental, opt-in public replies over an existing conversational Flow.
+
+This module does not change handle_turn/stream_turn or the job contract. Consume
+TurnRunner.stream_turn in a worker and fully drain it before reusing the Flow.
+Completion means generation finished, never that audio was delivered.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Collection, Iterator
+from threading import RLock
+from time import perf_counter
+from typing import Any, Literal
+from uuid import uuid4
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from crewai.experimental.flow_jobs import JobRecord
+from crewai.flow.conversational import ConversationState
+from crewai.flow.flow import Flow
+from crewai.types.streaming import StreamFrame
+from crewai.utilities.agent_utils import message_content_text
+
+
+class TurnRecord(BaseModel):
+ """One committed input; revisions are explicit, not new user utterances."""
+
+ model_config = ConfigDict(extra="forbid")
+ session_id: str = Field(min_length=1)
+ turn_id: str = Field(min_length=1)
+ input_revision: int = Field(default=1, gt=0, strict=True)
+ status: Literal["running", "completed", "interrupted", "failed"] = "running"
+ route: str | None = None
+ job_ids: list[str] = Field(default_factory=list)
+
+
+class ReplyRecord(BaseModel):
+ """Generated public text, separate from future playback receipt state.
+
+ delivery_id is the canonical reply identity. interrupted fences delivery
+ even when text generation already completed; text remains inspectable.
+ Text deltas are segments, not claims about sentences or audible words.
+ """
+
+ model_config = ConfigDict(extra="forbid")
+ session_id: str = Field(min_length=1)
+ turn_id: str = Field(min_length=1)
+ input_revision: int = Field(gt=0, strict=True)
+ delivery_id: str = Field(default_factory=lambda: str(uuid4()), min_length=1)
+ kind: Literal["acknowledgment", "answer", "progress"] = "answer"
+ status: Literal["generating", "completed", "interrupted", "failed"] = "generating"
+ interrupted: bool = False
+ segments: list[str] = Field(default_factory=list)
+ text: str = ""
+ last_event_seq: int = 0
+ last_accepted_seq: int = 0
+ job_id: str | None = None
+ job_revision: int | None = None
+ job_attempt: int | None = None
+
+
+class TurnState(ConversationState):
+ """Compose with JobState in an application's state if work spans turns."""
+
+ turns: dict[str, TurnRecord] = Field(default_factory=dict)
+ replies: dict[str, ReplyRecord] = Field(default_factory=dict)
+
+
+class ReplyEvent(BaseModel):
+ """Transport-independent public event; no private model/tool payloads.
+
+ seq orders events within a delivery; segment_id orders text deltas. Timings
+ describe server observation, not engine TTFT or physical speaker output.
+ """
+
+ model_config = ConfigDict(extra="forbid")
+ type: Literal[
+ "started",
+ "route_selected",
+ "generation_started",
+ "first_model_text",
+ "text",
+ "completed",
+ "interrupted",
+ "failed",
+ ]
+ session_id: str
+ turn_id: str
+ input_revision: int
+ delivery_id: str
+ kind: Literal["acknowledgment", "answer", "progress"]
+ seq: int
+ elapsed_ms: float
+ clock: Literal["server_monotonic"] = "server_monotonic"
+ segment_id: int | None = None
+ text: str = ""
+ route: str | None = None
+ call_id: str | None = None
+ # Provider-event timestamp delta, only for an observed public text chunk.
+ model_first_text_ms: float | None = None
+ job_id: str | None = None
+ job_revision: int | None = None
+ job_attempt: int | None = None
+
+
+class TurnRunner:
+ """Opt-in public stream adapter with targeted cooperative interruption.
+
+ The existing Flow executes the turn and owns history. Dedicated responder
+ methods/agent IDs explicitly allowlist public model calls; routers, tools,
+ reasoning and unrelated agent streams are excluded. Applications remain
+ responsible for choosing safe public responders and admission policy.
+
+ This runner locks its own records/controls. Hold JobRunner.state_lock around
+ the complete foreground iteration when composing with background jobs.
+ Do not invoke the original Flow turn APIs concurrently with this runner.
+ """
+
+ def __init__(
+ self,
+ flow: Flow[Any],
+ *,
+ public_methods: Collection[str] = ("converse_turn", "answer_from_history_turn"),
+ public_agent_ids: Callable[[], Collection[str]] | None = None,
+ on_interrupt: Callable[[], None] | None = None,
+ should_interrupt: Callable[[], bool] | None = None,
+ ) -> None:
+ if not isinstance(flow.state, TurnState):
+ raise TypeError("TurnRunner requires a Flow with TurnState")
+ if not flow._is_conversational_enabled():
+ raise ValueError("TurnRunner requires a conversational Flow")
+ self.flow = flow
+ self.public_methods = frozenset(public_methods)
+ self.public_agent_ids = public_agent_ids
+ self.on_interrupt = on_interrupt
+ self.should_interrupt = should_interrupt
+ self._lock = RLock()
+ self._active: str | None = None
+
+ @property
+ def state(self) -> TurnState:
+ # Flow restoration can replace the state object; do not retain it.
+ state = self.flow.state
+ if not isinstance(state, TurnState):
+ raise TypeError("Restored state must include TurnState")
+ return state
+
+ def associate_job(self, job: JobRecord) -> bool:
+ """Associate admitted work with the active originating turn/reply.
+
+ This does not register, submit, control or mutate the job. Call through
+ the application's serialized admission path after add_job succeeds.
+ """
+ with self._lock:
+ reply = self.state.replies.get(self._active or "")
+ if (
+ reply is None
+ or reply.interrupted
+ or (job.session_id, job.origin_turn_id)
+ != (reply.session_id, reply.turn_id)
+ ):
+ return False
+ if reply.job_id is not None and reply.job_id != job.job_id:
+ return False
+ reply.job_id = job.job_id
+ reply.job_revision = job.revision
+ reply.job_attempt = job.attempt
+ turn = self.state.turns[reply.turn_id]
+ if job.job_id not in turn.job_ids:
+ turn.job_ids.append(job.job_id)
+ return True
+
+ def interrupt(
+ self,
+ *,
+ session_id: str,
+ turn_id: str,
+ input_revision: int,
+ delivery_id: str,
+ ) -> bool:
+ """Fence exactly this reply; never cancel a job or abort a provider.
+
+ Repeated valid requests are idempotent. Completed generated text is
+ preserved. An active provider still drains before another turn starts.
+ """
+ with self._lock:
+ if type(input_revision) is not int or input_revision < 1:
+ return False
+ reply = self.state.replies.get(delivery_id)
+ if (
+ reply is None
+ or (reply.session_id, reply.turn_id, reply.input_revision)
+ != (
+ session_id,
+ turn_id,
+ input_revision,
+ )
+ or session_id != self.state.id
+ ):
+ return False
+ if reply.interrupted:
+ return True
+ reply.interrupted = True
+ if reply.status == "generating":
+ reply.status = "interrupted"
+ self.state.turns[turn_id].status = "interrupted"
+ if self._active == delivery_id and self.on_interrupt is not None:
+ self.on_interrupt()
+ return True
+
+ def accept_event(self, event: ReplyEvent) -> bool:
+ """Claim one runner-issued event at the transport boundary.
+
+ Call before handing off output, including after any queue/delay. This
+ fences late output after interruption and duplicate/out-of-order events.
+ It is not a validator for arbitrary untrusted client receipts.
+ """
+ with self._lock:
+ reply = self.state.replies.get(event.delivery_id)
+ if (
+ reply is None
+ or (event.session_id, event.turn_id, event.input_revision)
+ != (
+ reply.session_id,
+ reply.turn_id,
+ reply.input_revision,
+ )
+ or event.session_id != self.state.id
+ or not reply.last_accepted_seq < event.seq <= reply.last_event_seq
+ ):
+ return False
+ # Failure is a terminal lifecycle signal, not deliverable text.
+ # Preserve it if interruption arrives after failure was observed.
+ if event.type == "failed":
+ if reply.status != "failed":
+ return False
+ elif reply.interrupted:
+ if event.type != "interrupted":
+ return False
+ elif reply.status == "failed":
+ return False
+ reply.last_accepted_seq = event.seq
+ return True
+
+ def snapshot(self) -> dict[str, Any]:
+ """Copy serializable turn/reply records, never live execution handles."""
+ with self._lock:
+ return {
+ "session_id": self.state.id,
+ "turns": [
+ turn.model_dump(mode="json") for turn in self.state.turns.values()
+ ],
+ "replies": [
+ reply.model_dump(mode="json")
+ for reply in self.state.replies.values()
+ ],
+ }
+
+ def stream_turn(
+ self,
+ message: str,
+ *,
+ turn_id: str | None = None,
+ input_revision: int = 1,
+ kind: Literal["acknowledgment", "answer", "progress"] = "answer",
+ **turn_kwargs: Any,
+ ) -> Iterator[ReplyEvent]:
+ """Stream intentional public output while fully draining native frames.
+
+ IDs are single-use within a session. Provisional transcript replacement,
+ playback scheduling/receipts and background announcements are not
+ implemented here. Closing the iterator interrupts and drains execution.
+ """
+ if not isinstance(message, str) or not message.strip():
+ raise ValueError("A non-empty committed message is required")
+ if {"from_checkpoint", "restore_from_state_id"} & turn_kwargs.keys():
+ raise ValueError("Restore state before starting a tracked live turn")
+ started = perf_counter()
+ with self._lock:
+ if self._active is not None:
+ raise RuntimeError("Drain the active turn before starting another")
+ state = self.state
+ if state.ended:
+ raise ValueError("This conversation has ended")
+ if turn_kwargs.get("session_id", state.id) != state.id:
+ raise ValueError("TurnRunner cannot change the owning session")
+ turn = TurnRecord(
+ session_id=state.id,
+ turn_id=turn_id if turn_id is not None else str(uuid4()),
+ input_revision=input_revision,
+ )
+ if turn.turn_id in state.turns:
+ raise ValueError("Turn identity has already been used")
+ reply = ReplyRecord(
+ session_id=state.id,
+ turn_id=turn.turn_id,
+ input_revision=turn.input_revision,
+ kind=kind,
+ )
+ state.turns[turn.turn_id] = turn
+ state.replies[reply.delivery_id] = reply
+ self._active = reply.delivery_id
+
+ def event(event_type: Any, **details: Any) -> ReplyEvent:
+ with self._lock:
+ reply.last_event_seq += 1
+ return ReplyEvent(
+ type=event_type,
+ session_id=reply.session_id,
+ turn_id=reply.turn_id,
+ input_revision=reply.input_revision,
+ delivery_id=reply.delivery_id,
+ kind=reply.kind,
+ seq=reply.last_event_seq,
+ elapsed_ms=(perf_counter() - started) * 1000,
+ job_id=reply.job_id,
+ job_revision=reply.job_revision,
+ job_attempt=reply.job_attempt,
+ **details,
+ )
+
+ def interrupted() -> bool:
+ if self.should_interrupt is not None and self.should_interrupt():
+ self.interrupt(
+ session_id=reply.session_id,
+ turn_id=reply.turn_id,
+ input_revision=reply.input_revision,
+ delivery_id=reply.delivery_id,
+ )
+ with self._lock:
+ return reply.interrupted
+
+ def text_segment(text: str) -> ReplyEvent:
+ with self._lock:
+ reply.segments.append(text)
+ return event("text", text=text, segment_id=len(reply.segments))
+
+ methods: dict[str, str] = {}
+ public_calls: dict[str, StreamFrame] = {}
+ first_chunks: set[str] = set()
+ stream = None
+ terminal_emitted = False
+ suppression = self.flow.suppress_flow_events
+ skip_restore = self.flow._skip_persistence_restore
+ try:
+ # The current state owns admitted turns and accepted background jobs.
+ # Native session reload would replace it with an older snapshot.
+ self.flow._skip_persistence_restore = True
+ yield event("started")
+ # Native method/message frames are required even for suppressed Flows.
+ self.flow.suppress_flow_events = False
+ stream = self.flow.stream_turn(message, **turn_kwargs)
+ for frame in stream:
+ if interrupted():
+ continue
+ data = frame.data
+ if frame.type == "method_execution_started":
+ methods[frame.id] = data.get("method_name", "")
+ elif frame.type == "conversation_route_selected":
+ with self._lock:
+ turn.route = data.get("route")
+ yield event("route_selected", route=turn.route)
+ elif frame.type == "llm_call_started":
+ method = methods.get(frame.parent_id or "", "")
+ agent = data.get("agent_id")
+ allowed_agents = (
+ self.public_agent_ids() if self.public_agent_ids else ()
+ )
+ if (
+ method in self.public_methods or agent in allowed_agents
+ ) and not data.get("tools"):
+ call_id = data.get("call_id")
+ if isinstance(call_id, str):
+ public_calls[call_id] = frame
+ yield event("generation_started", call_id=call_id)
+ elif frame.type == "llm_stream_chunk":
+ call_id = data.get("call_id")
+ chunk = data.get("chunk")
+ if (
+ call_id in public_calls
+ and isinstance(chunk, str)
+ and chunk
+ and not data.get("tool_call")
+ and data.get("call_type") != "tool_call"
+ ):
+ if call_id not in first_chunks:
+ first_chunks.add(call_id)
+ delta = (
+ frame.timestamp - public_calls[call_id].timestamp
+ ).total_seconds() * 1000
+ yield event(
+ "first_model_text",
+ call_id=call_id,
+ model_first_text_ms=max(0, delta),
+ )
+ if not interrupted():
+ yield text_segment(chunk)
+ elif (
+ frame.type == "conversation_message_added"
+ and data.get("role") == "assistant"
+ ):
+ final = message_content_text(
+ {"role": "assistant", "content": data.get("content")}
+ )
+ with self._lock:
+ reply.text = final
+ # Non-streaming providers and hardcoded replies share this path.
+ if not reply.segments and final and not interrupted():
+ yield text_segment(final)
+ if interrupted():
+ terminal_emitted = True
+ yield event("interrupted")
+ else:
+ with self._lock:
+ if reply.interrupted:
+ terminal = event("interrupted")
+ else:
+ reply.status = "completed"
+ turn.status = "completed"
+ terminal = event("completed", text=reply.text)
+ terminal_emitted = True
+ yield terminal
+ except GeneratorExit:
+ if not terminal_emitted:
+ self.interrupt(
+ session_id=reply.session_id,
+ turn_id=reply.turn_id,
+ input_revision=reply.input_revision,
+ delivery_id=reply.delivery_id,
+ )
+ raise
+ except Exception:
+ with self._lock:
+ if not reply.interrupted:
+ reply.status = "failed"
+ turn.status = "failed"
+ terminal = event("interrupted" if reply.interrupted else "failed")
+ yield terminal
+ raise
+ finally:
+ try:
+ if stream is not None:
+ stream.close() # Joins native execution on consumer abandonment.
+ finally:
+ self.flow.suppress_flow_events = suppression
+ self.flow._skip_persistence_restore = skip_restore
+ with self._lock:
+ self._active = None
diff --git a/lib/crewai/src/crewai/flow/runtime/__init__.py b/lib/crewai/src/crewai/flow/runtime/__init__.py
index bc7812579..9113cbf18 100644
--- a/lib/crewai/src/crewai/flow/runtime/__init__.py
+++ b/lib/crewai/src/crewai/flow/runtime/__init__.py
@@ -816,6 +816,8 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):
_usage_aggregation_handler: Callable[..., Any] | None = PrivateAttr(default=None)
_persist_backends: dict[int, FlowPersistence] = PrivateAttr(default_factory=dict)
_instance_persistence: bool = PrivateAttr(default=False)
+ # Live adapters restore before admission; kickoff must not replace their state.
+ _skip_persistence_restore: bool = PrivateAttr(default=False)
def __class_getitem__(cls: type[Flow[T]], item: type[T]) -> type[Flow[T]]: # type: ignore[override]
class _FlowGeneric(cls): # type: ignore[valid-type,misc]
@@ -2347,6 +2349,7 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):
"id" in inputs
and self.persistence is not None
and not fork_succeeded
+ and not self._skip_persistence_restore
):
restore_uuid = inputs["id"]
stored_state = self.persistence.load_state(restore_uuid)
diff --git a/lib/crewai/tests/test_flow_turns.py b/lib/crewai/tests/test_flow_turns.py
new file mode 100644
index 000000000..1265c53c2
--- /dev/null
+++ b/lib/crewai/tests/test_flow_turns.py
@@ -0,0 +1,427 @@
+"""Public reply behavior over real Flow execution and provider event machinery."""
+
+from __future__ import annotations
+
+import asyncio
+from concurrent.futures import ThreadPoolExecutor
+from threading import Event
+from typing import Any
+
+import pytest
+
+from crewai.experimental.flow_jobs import (
+ JobRecord, JobRunner, JobState, JobWorkFlow, JobWorkState,
+ JobUpdate, add_job, commit_job_update,
+)
+from crewai.experimental.flow_turns import TurnRunner, TurnState
+from crewai.flow import ConversationConfig, ConversationState, Flow, listen, start
+from crewai.llms.base_llm import BaseLLM, llm_call_context
+from crewai.events.types.llm_events import LLMCallType
+
+
+class PublicLLM(BaseLLM):
+ def __init__(self, gate: Event | None = None, failure: bool = False):
+ super().__init__(model="test", stream=False)
+ self.gate = gate
+ self.failure = failure
+
+ def call(self, messages: Any, **kwargs: Any) -> str:
+ with llm_call_context():
+ self._emit_call_started_event(messages=messages)
+ self._emit_thinking_chunk_event("PRIVATE reasoning")
+ self._emit_stream_chunk_event("PRIVATE tool", call_type=LLMCallType.TOOL_CALL)
+ self._emit_stream_chunk_event("Hello ")
+ if self.gate is not None:
+ assert self.gate.wait(5), "Test did not release foreground provider"
+ if self.failure:
+ raise RuntimeError("Provider failed")
+ self._emit_stream_chunk_event("world.")
+ self._emit_call_completed_event(response="Hello world.", call_type=LLMCallType.LLM_CALL)
+ return "Hello world."
+
+
+def chat(llm: PublicLLM | None = None):
+ @ConversationConfig(llm=llm or PublicLLM())
+ class Chat(Flow[TurnState]):
+ def route_turn(self, context):
+ # Even public-looking router tokens must never enter the reply.
+ with llm_call_context():
+ router = PublicLLM()
+ router._emit_call_started_event(messages=[])
+ router._emit_stream_chunk_event("PRIVATE routing")
+ return "converse"
+
+ return Chat(suppress_flow_events=True)
+
+
+def test_generated_reply_is_live_public_correlated_and_has_one_history():
+ gate = Event()
+ flow = chat(PublicLLM(gate))
+ runner = TurnRunner(flow)
+ stream = runner.stream_turn("Hello", turn_id="t1")
+ events = []
+ try:
+ for event in stream:
+ events.append(event)
+ assert runner.accept_event(event)
+ assert not runner.accept_event(event)
+ if event.type == "text":
+ assert event.text == "Hello "
+ assert not gate.is_set()
+ gate.set()
+ events.extend(stream)
+ break
+ finally:
+ gate.set()
+ stream.close()
+ assert "PRIVATE" not in str(events)
+ assert "".join(e.text for e in events if e.type == "text") == "Hello world."
+ assert events[-1].type == "completed"
+ assert events[-1].text == "Hello world."
+ assert {e.delivery_id for e in events} == {events[0].delivery_id}
+ assert {e.turn_id for e in events} == {"t1"}
+ assert [e.seq for e in events] == list(range(1, len(events) + 1))
+ assert [e.segment_id for e in events if e.type == "text"] == [1, 2]
+ assert next(e for e in events if e.type == "first_model_text").model_first_text_ms >= 0
+ assert flow.conversation_messages == [{"role": "user", "content": "Hello"},
+ {"role": "assistant", "content": "Hello world."}]
+ assert flow.suppress_flow_events is True
+ snapshot = runner.snapshot()
+ assert snapshot["turns"][0]["route"] == "converse"
+ assert snapshot["replies"][0]["status"] == "completed"
+ assert TurnState.model_validate_json(flow.state.model_dump_json()).replies
+
+
+def test_hardcoded_reply_uses_same_contract_without_fake_model_timing():
+ class Admission(Flow[TurnState]):
+ conversational = True
+
+ def route_turn(self, context):
+ return "admit"
+
+ @listen("admit")
+ def accept(self):
+ return "Research accepted."
+
+ flow = Admission()
+ runner = TurnRunner(flow)
+ events = list(runner.stream_turn("Research", kind="acknowledgment"))
+ assert [e.text for e in events if e.type == "text"] == ["Research accepted."]
+ assert events[-1].text == "Research accepted."
+ assert all(e.kind == "acknowledgment" for e in events)
+ assert not any(e.type in {"generation_started", "first_model_text"} for e in events)
+ assert len(flow.conversation_messages) == 2
+
+
+def test_interruption_fences_queued_output_and_drains_before_next_turn():
+ gate = Event()
+ flow = chat(PublicLLM(gate))
+ stopped = Event()
+ runner = TurnRunner(flow, on_interrupt=stopped.set)
+ stream = runner.stream_turn("First", turn_id="first")
+ first = next(stream)
+ control = dict(session_id=first.session_id, turn_id="first", input_revision=1,
+ delivery_id=first.delivery_id)
+ events = []
+ try:
+ for event in stream:
+ events.append(event)
+ if event.type == "text":
+ assert not runner.interrupt(**{**control, "session_id": "foreign"})
+ assert not runner.interrupt(**{**control, "input_revision": 2})
+ assert not runner.interrupt(**{**control, "input_revision": True})
+ assert not runner.interrupt(**{**control, "delivery_id": "foreign"})
+ assert runner.interrupt(**control)
+ assert runner.interrupt(**control)
+ assert stopped.is_set()
+ assert not runner.accept_event(event)
+ with pytest.raises(RuntimeError, match="Drain"):
+ next(runner.stream_turn("Overlapping"))
+ gate.set()
+ events.extend(stream)
+ break
+ finally:
+ gate.set()
+ stream.close()
+ assert events[-1].type == "interrupted"
+ assert sum(e.type in {"completed", "interrupted", "failed"} for e in events) == 1
+ assert runner.accept_event(events[-1])
+ assert flow.state.turns["first"].status == "interrupted"
+ # Generation remains inspectable; no physical delivery is inferred.
+ assert flow.conversation_messages[-1]["content"] == "Hello world."
+ later = list(runner.stream_turn("Second", turn_id="second"))
+ assert later[-1].type == "completed"
+ assert later[0].delivery_id != first.delivery_id
+ assert not runner.accept_event(events[0])
+
+
+def test_completed_text_can_be_fenced_without_changing_generation_or_jobs():
+ runner = TurnRunner(chat())
+ events = list(runner.stream_turn("First"))
+ last = events[-1]
+ assert runner.interrupt(session_id=last.session_id, turn_id=last.turn_id,
+ input_revision=last.input_revision, delivery_id=last.delivery_id)
+ reply = runner.state.replies[last.delivery_id]
+ assert reply.status == "completed"
+ assert reply.text == "Hello world."
+ assert not runner.accept_event(last)
+
+
+def test_failed_generation_is_terminal_and_next_turn_is_available():
+ runner = TurnRunner(chat(PublicLLM(failure=True)))
+ events = []
+ with pytest.raises(RuntimeError, match="Provider failed"):
+ events.extend(runner.stream_turn("Fail"))
+ assert events[-1].type == "failed"
+ assert runner.accept_event(events[-1])
+ assert not runner.accept_event(next(e for e in events if e.type == "text"))
+ assert runner.state.turns[events[0].turn_id].status == "failed"
+ assert runner.flow.suppress_flow_events is True
+
+
+def test_closing_stream_signals_control_before_draining_provider():
+ gate = Event()
+ runner = TurnRunner(chat(PublicLLM(gate)), on_interrupt=gate.set)
+ stream = runner.stream_turn("Close")
+ events = []
+ for event in stream:
+ events.append(event)
+ if event.type == "text":
+ stream.close()
+ break
+ assert gate.is_set()
+ assert runner.state.turns[events[0].turn_id].status == "interrupted"
+ assert runner.flow.suppress_flow_events is True
+ assert list(runner.stream_turn("Next"))[-1].type == "completed"
+
+
+def test_input_identity_owner_and_order_are_validated_before_execution():
+ runner = TurnRunner(chat())
+ for kwargs in ({"input_revision": True}, {"input_revision": 0},
+ {"turn_id": ""}, {"session_id": "foreign"}, {"from_checkpoint": "checkpoint"},
+ {"restore_from_state_id": "other-state"}):
+ with pytest.raises(ValueError):
+ list(runner.stream_turn("Hello", **kwargs))
+ assert not runner.state.turns
+ with pytest.raises(ValueError):
+ list(runner.stream_turn(" "))
+ events = list(runner.stream_turn("Hello", turn_id="t1"))
+ with pytest.raises(ValueError, match="already"):
+ list(runner.stream_turn("Again", turn_id="t1"))
+ assert runner.accept_event(events[-1])
+ assert not runner.accept_event(events[-2])
+ foreign = events[-1].model_copy(update={"session_id": "foreign", "seq": events[-1].seq + 1})
+ assert not runner.accept_event(foreign)
+
+
+def test_separate_sessions_do_not_share_reply_identity_or_control():
+ runners = [TurnRunner(chat()), TurnRunner(chat())]
+ with ThreadPoolExecutor(max_workers=2) as pool:
+ results = list(pool.map(lambda r: list(r.stream_turn("Hello", turn_id="same")), runners))
+ assert results[0][0].session_id != results[1][0].session_id
+ assert not runners[1].accept_event(results[0][-1])
+ assert len(runners[1].state.messages) == 2
+
+
+def test_native_turn_and_stream_contracts_are_unchanged():
+ flow = chat()
+ assert flow.handle_turn("Native") == "Hello world."
+ stream = flow.stream_turn("Native stream")
+ frames = list(stream)
+ assert stream.result == "Hello world."
+ assert any(f.type == "llm_stream_chunk" for f in frames)
+ assert flow.state.turns == {}
+ assert flow.state.replies == {}
+ with pytest.raises(TypeError):
+ TurnRunner(Flow[ConversationState]())
+
+
+async def test_independent_job_commits_after_foreground_interruption():
+ class State(TurnState, JobState[JobRecord]):
+ pass
+
+ search_gate = Event()
+ search_started = Event()
+ answer_gate = Event()
+
+ class Work(JobWorkFlow[JobWorkState[JobRecord]]):
+ @start()
+ def research(self):
+ self.publish_update("started")
+ search_started.set()
+ assert search_gate.wait(5)
+ self.publish_update("completed")
+
+ @ConversationConfig(llm=PublicLLM(answer_gate))
+ class Chat(Flow[State]):
+ def route_turn(self, context):
+ return "converse"
+
+ flow = Chat()
+ changes = asyncio.Queue()
+ jobs = JobRunner(flow.state, lambda j, inputs, publish: Work(
+ initial_state=JobWorkState(job=j), publish=publish), on_update=changes.put)
+ replies = TurnRunner(flow)
+ async with jobs.state_lock:
+ job = JobRecord(session_id=flow.state.id, origin_turn_id="research")
+ assert add_job(flow.state, job)
+ jobs.submit(job, {})
+ try:
+ assert await asyncio.to_thread(search_started.wait, 5)
+ def consume():
+ events = []
+ for event in replies.stream_turn("Status", turn_id="status"):
+ events.append(event)
+ if event.type == "text":
+ assert replies.interrupt(session_id=event.session_id, turn_id=event.turn_id,
+ input_revision=event.input_revision, delivery_id=event.delivery_id)
+ search_gate.set()
+ answer_gate.set()
+ return events
+ async with jobs.state_lock:
+ events = await asyncio.to_thread(consume)
+ assert events[-1].type == "interrupted"
+ while (await asyncio.wait_for(changes.get(), 5))["jobs"][0]["status"] != "completed":
+ pass
+ assert job.status == "completed"
+ assert flow.state.turns["status"].status == "interrupted"
+ finally:
+ search_gate.set()
+ answer_gate.set()
+ await jobs.aclose()
+
+
+def test_job_association_validates_owner_and_origin_without_admitting_work():
+ runner = TurnRunner(chat())
+ stream = runner.stream_turn("Research", turn_id="origin")
+ first = next(stream)
+ job = JobRecord(session_id=first.session_id, origin_turn_id="origin", revision=2, attempt=3)
+ assert not runner.associate_job(job.model_copy(update={"session_id": "foreign"}))
+ assert not runner.associate_job(job.model_copy(update={"origin_turn_id": "another"}))
+ assert runner.associate_job(job)
+ assert runner.associate_job(job)
+ assert not runner.associate_job(job.model_copy(update={"job_id": "another"}))
+ rest = list(stream)
+ assert rest[-1].job_id == job.job_id
+ assert rest[-1].job_revision == 2
+ assert rest[-1].job_attempt == 3
+ assert runner.state.turns["origin"].job_ids == [job.job_id]
+ assert job.status == "queued"
+
+
+def test_private_agent_return_does_not_become_public_reply():
+ class PrivateChat(Flow[TurnState]):
+ conversational = True
+
+ def route_turn(self, context):
+ return "private"
+
+ @listen("private")
+ def scratch(self):
+ reply = "PRIVATE scratch result"
+ self.append_agent_result("scratch", reply, visibility="private")
+ return reply
+
+ runner = TurnRunner(PrivateChat())
+ events = list(runner.stream_turn("Hello"))
+ assert not any(e.type == "text" for e in events)
+ assert events[-1].text == ""
+ assert "PRIVATE" not in str(events)
+ assert len(runner.flow.conversation_messages) == 1
+
+
+
[email protected]("failure", [False, True])
+def test_closing_after_terminal_keeps_queued_event_deliverable(failure):
+ stopped = Event()
+ runner = TurnRunner(chat(PublicLLM(failure=failure)), on_interrupt=stopped.set)
+ stream = runner.stream_turn("Finish")
+ for event in stream:
+ if event.type in {"completed", "failed"}:
+ stream.close()
+ reply = runner.state.replies[event.delivery_id]
+ assert reply.status == event.type
+ assert not reply.interrupted
+ assert not stopped.is_set()
+ assert runner.accept_event(event)
+ assert not runner.flow._skip_persistence_restore
+ break
+ else:
+ pytest.fail("Missing terminal event")
+
+
+def test_failure_terminal_remains_acceptable_after_cross_thread_interruption():
+ runner = TurnRunner(chat(PublicLLM(failure=True)))
+ stream = runner.stream_turn("Fail")
+ for event in stream:
+ if event.type == "failed":
+ control = dict(session_id=event.session_id, turn_id=event.turn_id,
+ input_revision=event.input_revision, delivery_id=event.delivery_id)
+ with ThreadPoolExecutor(1) as pool:
+ assert pool.submit(runner.interrupt, **control).result(timeout=5)
+ assert runner.state.replies[event.delivery_id].status == "failed"
+ assert runner.accept_event(event)
+ assert not runner.accept_event(event)
+ with pytest.raises(RuntimeError, match="Provider failed"):
+ next(stream)
+ assert not runner.flow._skip_persistence_restore
+ break
+ else:
+ pytest.fail("Missing failure event")
+
+
+def test_persisted_tracked_turn_keeps_live_records_and_jobs(tmp_path):
+ from crewai.flow.persistence import persist
+ from crewai.flow.persistence.sqlite import SQLiteFlowPersistence
+
+ class State(TurnState, JobState[JobRecord]):
+ pass
+
+ store = SQLiteFlowPersistence(str(tmp_path / "turns.db"))
+
+ @persist(store)
+ class Chat(Flow[State]):
+ conversational = True
+
+ def route_turn(self, context):
+ if runner._active is None:
+ return "ack"
+ assert runner.state.replies[runner._active].turn_id in self.state.turns
+ job = JobRecord(session_id=self.state.id,
+ origin_turn_id=self.state.replies[runner._active].turn_id)
+ assert add_job(self.state, job)
+ assert runner.associate_job(job)
+ return "ack"
+
+ @listen("ack")
+ def reply(self):
+ return "Accepted."
+
+ flow = Chat()
+ # An existing snapshot is deliberately older than current live job state.
+ store.save_state(flow.state.id, "seed", flow.state.model_dump())
+ restored = Chat(initial_state=State.model_validate(store.load_state(flow.state.id)))
+ live = restored.state
+ job = JobRecord(session_id=live.id, origin_turn_id="earlier")
+ assert add_job(live, job)
+ for seq, kind in enumerate(("started", "completed"), 1):
+ assert commit_job_update(live, JobUpdate(session_id=live.id, job_id=job.job_id,
+ revision=1, attempt=1, seq=seq, kind=kind))
+ runner = TurnRunner(restored)
+ first = list(runner.stream_turn("First", turn_id="first"))
+ assert restored.state is live
+ assert runner.accept_event(first[-1])
+ # Persisted snapshots precede terminal tracking; a second reload would regress it.
+ assert list(runner.stream_turn("Second", turn_id="second"))[-1].type == "completed"
+ assert restored.state is live
+ assert live.turns["first"].status == "completed"
+ assert live.jobs[job.job_id].status == "completed"
+ assert len(live.jobs) == 3
+ assert len(runner.snapshot()["replies"]) == 2
+ assert not restored._skip_persistence_restore
+ assert runner.interrupt(session_id=first[0].session_id, turn_id="first",
+ input_revision=1, delivery_id=first[0].delivery_id)
+ # The same Flow's native turn API still reloads persisted state normally.
+ restored.handle_turn("Native")
+ assert restored.state is not live