docs: update otel images (#6103)

* docs: udpate docs to reflect new state of OpenTelemetry collector

* docs: add OTel collector and Datadog screenshots

These images are referenced by the capture_telemetry_logs guides but were
missing from the tree, which broke the link checker across all locales.

* docs: address PR review on OTel collector guide

- Clarify that OpenTelemetry Traces and Logs are separate integrations
  sharing the same fields (resolves Traces/Logs wording inconsistency)
- List regional Datadog OTLP hosts (US1/US3/US5/EU1/AP1) so users outside
  US5 can copy the right domain

docs/ar/enterprise/guides/capture_telemetry_logs.mdx

@@ -24,15 +24,39 @@ mode: "wide"
 
 1. في CrewAI AMP، انتقل إلى **Settings** > **OpenTelemetry Collectors**.
 2. انقر على **Add Collector**.
-3. اختر نوع التكامل — **OpenTelemetry Traces** أو **OpenTelemetry Logs**.
-4. هيّئ الاتصال:
-   - **Endpoint** — نقطة نهاية OTLP لمجمّعك (مثل `https://otel-collector.example.com:4317`).
-   - **Service Name** — اسم لتعريف هذه الخدمة في منصة المراقبة.
-   - **Custom Headers** *(اختياري)* — أضف رؤوس المصادقة أو التوجيه كأزواج مفتاح-قيمة.
-   - **Certificate** *(اختياري)* — قدم شهادة TLS إذا كان مجمّعك يتطلبها.
-5. انقر على **Save**.
+3. اختر تكاملاً:
+   - **OpenTelemetry Traces** و**OpenTelemetry Logs** — صدّر إلى أي مجمّع أو واجهة خلفية متوافقة مع OTLP.
+   - **Datadog** — أرسل التتبعات مباشرة إلى استقبال OTLP الخاص بـ Datadog، دون الحاجة إلى مجمّع منفصل أو Datadog Agent.
+4. هيّئ الاتصال. تعتمد الحقول على التكامل الذي اخترته:
 
-<Frame>![تهيئة مجمّع OpenTelemetry](/images/crewai-otel-collector-config.png)</Frame>
+<Tabs>
+  <Tab title="OpenTelemetry Traces / Logs">
+    إن **OpenTelemetry Traces** و**OpenTelemetry Logs** تكاملان منفصلان يتشاركان نفس الحقول — اختر التكامل المطابق للإشارة التي تريد تصديرها.
+
+    - **Endpoint** — نقطة نهاية OTLP لمجمّعك (مثل `https://otel-collector.example.com:4317`).
+    - **Service Name** — اسم لتعريف هذه الخدمة في منصة المراقبة.
+    - **Custom Headers** *(اختياري)* — أضف رؤوس المصادقة أو التوجيه كأزواج مفتاح-قيمة.
+    - **Certificate** *(اختياري)* — قدم شهادة TLS إذا كان مجمّعك يتطلبها.
+
+    <Frame>![تهيئة مجمّع OpenTelemetry](/images/crewai-otel-collector-opentelemetry.png)</Frame>
+  </Tab>
+  <Tab title="Datadog">
+    - **Datadog Site Domain** — مضيف OTLP لموقع Datadog الخاص بك فقط، دون بروتوكول أو مسار. يقوم CrewAI ببناء نقطة نهاية HTTPS OTLP الكاملة نيابةً عنك. استخدم المضيف المطابق لـ [موقع Datadog](https://docs.datadoghq.com/getting_started/site/) الخاص بك:
+      - `otlp.datadoghq.com` (US1)
+      - `otlp.us3.datadoghq.com` (US3)
+      - `otlp.us5.datadoghq.com` (US5)
+      - `otlp.datadoghq.eu` (EU1)
+      - `otlp.ap1.datadoghq.com` (AP1)
+    - **API Key** — مفتاح واجهة برمجة تطبيقات Datadog الخاص بك. راجع [كيفية إنشاء واحد](https://docs.datadoghq.com/account_management/api-app-keys/#api-keys).
+
+    يصدّر تكامل Datadog **التتبعات**.
+
+    <Frame>![تهيئة مجمّع Datadog](/images/crewai-otel-collector-datadog.png)</Frame>
+  </Tab>
+</Tabs>
+
+5. *(اختياري)* انقر على **Test Connection** للتحقق من قدرة CrewAI على الوصول إلى نقطة النهاية باستخدام بيانات الاعتماد التي قدمتها.
+6. انقر على **Save**.
 
 <Tip>
   يمكنك إضافة مجمّعات متعددة — على سبيل المثال، واحد للتتبعات وآخر للسجلات، أو الإرسال إلى واجهات خلفية مختلفة لأغراض مختلفة.

docs/en/enterprise/guides/capture_telemetry_logs.mdx

@@ -24,15 +24,39 @@ Telemetry data follows the [OpenTelemetry GenAI semantic conventions](https://op
 
 1. In CrewAI AMP, go to **Settings** > **OpenTelemetry Collectors**.
 2. Click **Add Collector**.
-3. Select an integration type — **OpenTelemetry Traces** or **OpenTelemetry Logs**.
-4. Configure the connection:
-   - **Endpoint** — Your collector's OTLP endpoint (e.g., `https://otel-collector.example.com:4317`).
-   - **Service Name** — A name to identify this service in your observability platform.
-   - **Custom Headers** *(optional)* — Add authentication or routing headers as key-value pairs.
-   - **Certificate** *(optional)* — Provide a TLS certificate if your collector requires one.
-5. Click **Save**.
+3. Select an integration:
+   - **OpenTelemetry Traces** and **OpenTelemetry Logs** — export to any OTLP-compatible collector or backend.
+   - **Datadog** — send traces straight to Datadog's OTLP intake, no separate collector or Datadog Agent required.
+4. Configure the connection. The fields depend on the integration you selected:
 
-<Frame>![OpenTelemetry Collector Configuration](/images/crewai-otel-collector-config.png)</Frame>
+<Tabs>
+  <Tab title="OpenTelemetry Traces / Logs">
+    **OpenTelemetry Traces** and **OpenTelemetry Logs** are separate integrations that share the same fields — pick the one matching the signal you want to export.
+
+    - **Endpoint** — Your collector's OTLP endpoint (e.g., `https://otel-collector.example.com:4317`).
+    - **Service Name** — A name to identify this service in your observability platform.
+    - **Custom Headers** *(optional)* — Add authentication or routing headers as key-value pairs.
+    - **Certificate** *(optional)* — Provide a TLS certificate if your collector requires one.
+
+    <Frame>![OpenTelemetry collector configuration](/images/crewai-otel-collector-opentelemetry.png)</Frame>
+  </Tab>
+  <Tab title="Datadog">
+    - **Datadog Site Domain** — Your Datadog site's OTLP host only, with no protocol or path. CrewAI builds the full HTTPS OTLP endpoint for you. Use the host that matches your [Datadog site](https://docs.datadoghq.com/getting_started/site/):
+      - `otlp.datadoghq.com` (US1)
+      - `otlp.us3.datadoghq.com` (US3)
+      - `otlp.us5.datadoghq.com` (US5)
+      - `otlp.datadoghq.eu` (EU1)
+      - `otlp.ap1.datadoghq.com` (AP1)
+    - **API Key** — Your Datadog API key. See [how to create one](https://docs.datadoghq.com/account_management/api-app-keys/#api-keys).
+
+    The Datadog integration exports **traces**.
+
+    <Frame>![Datadog collector configuration](/images/crewai-otel-collector-datadog.png)</Frame>
+  </Tab>
+</Tabs>
+
+5. *(optional)* Click **Test Connection** to verify CrewAI can reach the endpoint with the credentials you provided.
+6. Click **Save**.
 
 <Tip>
   You can add multiple collectors — for example, one for traces and another for logs, or send to different backends for different purposes.

docs/ko/enterprise/guides/capture_telemetry_logs.mdx

@@ -24,15 +24,39 @@ CrewAI AMP는 배포에서 OpenTelemetry **트레이스**와 **로그**를 자
 
 1. CrewAI AMP에서 **Settings** > **OpenTelemetry Collectors**로 이동합니다.
 2. **Add Collector**를 클릭합니다.
-3. 통합 유형을 선택합니다 — **OpenTelemetry Traces** 또는 **OpenTelemetry Logs**.
-4. 연결을 구성합니다:
-   - **Endpoint** — 수집기의 OTLP 엔드포인트 (예: `https://otel-collector.example.com:4317`).
-   - **Service Name** — 관측 가능성 플랫폼에서 이 서비스를 식별하기 위한 이름.
-   - **Custom Headers** *(선택 사항)* — 인증 또는 라우팅 헤더를 키-값 쌍으로 추가합니다.
-   - **Certificate** *(선택 사항)* — 수집기에서 TLS 인증서가 필요한 경우 제공합니다.
-5. **Save**를 클릭합니다.
+3. 통합을 선택합니다:
+   - **OpenTelemetry Traces** 및 **OpenTelemetry Logs** — OTLP 호환 수집기 또는 백엔드로 내보냅니다.
+   - **Datadog** — 별도의 수집기나 Datadog Agent 없이 트레이스를 Datadog의 OTLP 인테이크로 직접 전송합니다.
+4. 연결을 구성합니다. 필드는 선택한 통합에 따라 달라집니다:
 
-<Frame>![OpenTelemetry 수집기 구성](/images/crewai-otel-collector-config.png)</Frame>
+<Tabs>
+  <Tab title="OpenTelemetry Traces / Logs">
+    **OpenTelemetry Traces**와 **OpenTelemetry Logs**는 동일한 필드를 공유하는 별개의 통합입니다 — 내보내려는 신호에 맞는 것을 선택하세요.
+
+    - **Endpoint** — 수집기의 OTLP 엔드포인트 (예: `https://otel-collector.example.com:4317`).
+    - **Service Name** — 관측 가능성 플랫폼에서 이 서비스를 식별하기 위한 이름.
+    - **Custom Headers** *(선택 사항)* — 인증 또는 라우팅 헤더를 키-값 쌍으로 추가합니다.
+    - **Certificate** *(선택 사항)* — 수집기에서 TLS 인증서가 필요한 경우 제공합니다.
+
+    <Frame>![OpenTelemetry 수집기 구성](/images/crewai-otel-collector-opentelemetry.png)</Frame>
+  </Tab>
+  <Tab title="Datadog">
+    - **Datadog Site Domain** — Datadog 사이트의 OTLP 호스트만 입력합니다 (프로토콜이나 경로 제외). CrewAI가 전체 HTTPS OTLP 엔드포인트를 자동으로 구성합니다. [Datadog 사이트](https://docs.datadoghq.com/getting_started/site/)에 맞는 호스트를 사용하세요:
+      - `otlp.datadoghq.com` (US1)
+      - `otlp.us3.datadoghq.com` (US3)
+      - `otlp.us5.datadoghq.com` (US5)
+      - `otlp.datadoghq.eu` (EU1)
+      - `otlp.ap1.datadoghq.com` (AP1)
+    - **API Key** — Datadog API 키입니다. [키 생성 방법](https://docs.datadoghq.com/account_management/api-app-keys/#api-keys)을 참고하세요.
+
+    Datadog 통합은 **트레이스**를 내보냅니다.
+
+    <Frame>![Datadog 수집기 구성](/images/crewai-otel-collector-datadog.png)</Frame>
+  </Tab>
+</Tabs>
+
+5. *(선택 사항)* **Test Connection**을 클릭하여 제공한 자격 증명으로 CrewAI가 엔드포인트에 연결할 수 있는지 확인합니다.
+6. **Save**를 클릭합니다.
 
 <Tip>
   여러 수집기를 추가할 수 있습니다 — 예를 들어, 트레이스용 하나와 로그용 하나를 추가하거나, 다른 목적을 위해 다른 백엔드로 전송할 수 있습니다.

docs/pt-BR/enterprise/guides/capture_telemetry_logs.mdx

@@ -24,15 +24,39 @@ Os dados de telemetria seguem as [convenções semânticas GenAI do OpenTelemetr
 
 1. No CrewAI AMP, vá para **Settings** > **OpenTelemetry Collectors**.
 2. Clique em **Add Collector**.
-3. Selecione um tipo de integração — **OpenTelemetry Traces** ou **OpenTelemetry Logs**.
-4. Configure a conexão:
-   - **Endpoint** — O endpoint OTLP do seu coletor (por exemplo, `https://otel-collector.example.com:4317`).
-   - **Service Name** — Um nome para identificar este serviço na sua plataforma de observabilidade.
-   - **Custom Headers** *(opcional)* — Adicione headers de autenticação ou roteamento como pares chave-valor.
-   - **Certificate** *(opcional)* — Forneça um certificado TLS se o seu coletor exigir um.
-5. Clique em **Save**.
+3. Selecione uma integração:
+   - **OpenTelemetry Traces** e **OpenTelemetry Logs** — exporte para qualquer coletor ou backend compatível com OTLP.
+   - **Datadog** — envie traces diretamente para a ingestão OTLP do Datadog, sem precisar de um coletor separado ou do Datadog Agent.
+4. Configure a conexão. Os campos dependem da integração selecionada:
 
-<Frame>![Configuração do Coletor OpenTelemetry](/images/crewai-otel-collector-config.png)</Frame>
+<Tabs>
+  <Tab title="OpenTelemetry Traces / Logs">
+    **OpenTelemetry Traces** e **OpenTelemetry Logs** são integrações separadas que compartilham os mesmos campos — escolha a que corresponde ao sinal que você quer exportar.
+
+    - **Endpoint** — O endpoint OTLP do seu coletor (por exemplo, `https://otel-collector.example.com:4317`).
+    - **Service Name** — Um nome para identificar este serviço na sua plataforma de observabilidade.
+    - **Custom Headers** *(opcional)* — Adicione headers de autenticação ou roteamento como pares chave-valor.
+    - **Certificate** *(opcional)* — Forneça um certificado TLS se o seu coletor exigir um.
+
+    <Frame>![Configuração do coletor OpenTelemetry](/images/crewai-otel-collector-opentelemetry.png)</Frame>
+  </Tab>
+  <Tab title="Datadog">
+    - **Datadog Site Domain** — Apenas o host OTLP do seu site Datadog, sem protocolo ou caminho. O CrewAI monta o endpoint HTTPS OTLP completo para você. Use o host correspondente ao seu [site Datadog](https://docs.datadoghq.com/getting_started/site/):
+      - `otlp.datadoghq.com` (US1)
+      - `otlp.us3.datadoghq.com` (US3)
+      - `otlp.us5.datadoghq.com` (US5)
+      - `otlp.datadoghq.eu` (EU1)
+      - `otlp.ap1.datadoghq.com` (AP1)
+    - **API Key** — Sua chave de API do Datadog. Veja [como criar uma](https://docs.datadoghq.com/account_management/api-app-keys/#api-keys).
+
+    A integração com o Datadog exporta **traces**.
+
+    <Frame>![Configuração do coletor Datadog](/images/crewai-otel-collector-datadog.png)</Frame>
+  </Tab>
+</Tabs>
+
+5. *(opcional)* Clique em **Test Connection** para verificar se o CrewAI consegue acessar o endpoint com as credenciais fornecidas.
+6. Clique em **Save**.
 
 <Tip>
   Você pode adicionar múltiplos coletores — por exemplo, um para traces e outro para logs, ou enviar para diferentes backends para diferentes propósitos.

lib/crewai/src/crewai/experimental/conversational_mixin.py

@@ -1,15 +1,17 @@
-"""Conversational graph + helpers as a mixin for ``Flow`` (experimental).
+"""Conversational graph + helpers as an experimental Flow extension.
 
-The experimental conversational chat surface lives here as a mixin so that
-``crewai.flow.runtime`` stays focused on the execution engine. ``Flow``
-inherits from ``_ConversationalMixin``; the methods only register on
-subclasses that opt in via ``conversational = True`` (enforced by the
-``_conversational_only`` marker + ``FlowMeta`` gating in
-``crewai.flow.runtime``).
+The conversational chat surface remains experimental and may change before the
+v2 graduation path. It lives here so ``crewai.flow.runtime`` can stay focused
+on the execution engine. ``crewai.flow.flow`` composes this mixin onto the
+public ``Flow`` class for backwards compatibility.
+
+The built-in conversational graph only registers for subclasses that opt in
+with ``conversational = True``. Static conversational metadata is projected
+into ``FlowDefinition.conversational`` via the Python DSL builder.
 
 Import surface:
-    - :class:`_ConversationalMixin` — internal; ``Flow`` mixes it in. Users
-      don't import it directly.
+    - :class:`_ConversationalMixin` — internal; the public ``Flow`` class
+      composes it in. Users don't import it directly.
     - The data types this mixin uses live in
       :mod:`crewai.experimental.conversational`.
 """
@@ -20,7 +22,7 @@ from collections.abc import Callable, Mapping, Sequence
 from enum import Enum
 import json
 import logging
-from typing import TYPE_CHECKING, Any, ClassVar, Literal, cast
+from typing import TYPE_CHECKING, Any, ClassVar, Literal, TypeVar, cast
 
 from pydantic import BaseModel, Field, create_model
 
@@ -49,21 +51,56 @@ from crewai.utilities.types import LLMMessage
 
 
 if TYPE_CHECKING:
-    from crewai.flow.runtime import Flow
     from crewai.llms.base_llm import BaseLLM
 
 
 logger = logging.getLogger(__name__)
 
 
-class _ConversationalMixin:
-    """Built-in conversational graph for ``Flow`` (gated on ``conversational``).
+def _iter_condition_labels(condition: Any) -> set[str]:
+    if isinstance(condition, str):
+        return {condition}
+    if isinstance(condition, dict):
+        labels: set[str] = set()
+        for value in condition.values():
+            if isinstance(value, list):
+                for item in value:
+                    labels.update(_iter_condition_labels(item))
+            else:
+                labels.update(_iter_condition_labels(value))
+        return labels
+    return set()
 
-    Mixed into ``Flow`` so its execution engine (``runtime.py``) stays focused
-    on running graphs. The methods here only register on subclasses that set
-    ``conversational = True``; non-chat flows see them as inert attributes.
+
+class _ConversationalMixin:
+    """Experimental conversational graph for ``Flow``.
+
+    This mixin owns chat behavior and runtime hooks. Non-chat flows see these
+    methods as inert attributes unless they opt in with ``conversational = True``.
     """
 
+    # === EXPERIMENTAL: conversational mode ===
+    # When ``conversational = True`` on a Flow subclass, this mixin's built-in
+    # graph registers and ``handle_turn`` / ``chat`` become chat entry points.
+    conversational: ClassVar[bool] = False
+    conversational_config: ClassVar[ConversationConfig | None] = None
+    builtin_routes: ClassVar[tuple[str, ...]] = ("converse", "end")
+    internal_routes: ClassVar[tuple[str, ...]] = (
+        "answer_from_history",
+        "conversation_start",
+    )
+    builtin_route_descriptions: ClassVar[dict[str, str]] = {
+        "converse": (
+            "Ordinary chat, follow-ups, summaries, clarifications, and "
+            "questions answerable from prior conversation history."
+        ),
+        "end": ("User signals the conversation is finished (goodbye, exit, done)."),
+        "answer_from_history": (
+            "Answer directly from prior conversation history without invoking "
+            "tools, agents, or custom routes."
+        ),
+    }
+
     # The metaclass + state attributes referenced below live on ``Flow`` —
     # this mixin is never instantiated standalone. These type-only
     # declarations exist so static analyzers don't flag attribute access.
@@ -71,22 +108,15 @@ class _ConversationalMixin:
     # (otherwise mypy flags "Cannot override instance variable with class
     # variable" when Flow declares them as ``ClassVar``).
     if TYPE_CHECKING:
-        conversational: ClassVar[bool]
-        conversational_config: ClassVar[ConversationConfig | None]
-        builtin_routes: ClassVar[tuple[str, ...]]
-        internal_routes: ClassVar[tuple[str, ...]]
-        builtin_route_descriptions: ClassVar[dict[str, str]]
-        # Registry ClassVars populated by ``FlowMeta`` at class creation.
-        _listeners: ClassVar[dict[Any, Any]]
-
         # Instance attrs from ``Flow``.
         state: Any
         name: str | None
         _completed_methods: set[Any]
         _method_outputs: list[Any]
-        _pending_and_listeners: dict[Any, Any]
+        _pending_events: dict[Any, Any]
         _method_call_counts: dict[Any, int]
         _is_execution_resuming: bool
+        _conversation_messages: list[LLMMessage]
         _pending_user_message: str | dict[str, Any] | None
         _pending_intents: Sequence[str] | None
         _pending_intent_llm: str | BaseLLM | None
@@ -97,8 +127,8 @@ class _ConversationalMixin:
         def _collapse_to_outcome(
             self,
             feedback: str,
-            outcomes: tuple[str, ...],
-            llm: str | BaseLLM | Any,
+            outcomes: Sequence[str],
+            llm: str | BaseLLM,
         ) -> str:
             pass
 
@@ -238,8 +268,8 @@ class _ConversationalMixin:
         state = cast(ConversationState, self.state)
         sid = session_id or state.id
 
-        # Stash the pending turn so ``_apply_pending_conversational_turn``
-        # picks it up AFTER persist restore.
+        # Stash the pending turn so the kickoff extension hook picks it up
+        # after persist restore.
         self._pending_user_message = message
         self._pending_intents = list(intents) if intents else None
         self._pending_intent_llm = intent_llm
@@ -286,7 +316,7 @@ class _ConversationalMixin:
         callers can customize prompts or exercise the loop without patching
         builtins.
         """
-        if not getattr(type(self), "conversational", False):
+        if not self._is_conversational_enabled():
             raise ValueError("Flow.chat() is only available on conversational flows")
 
         exit_set = {command.lower() for command in exit_commands}
@@ -491,14 +521,14 @@ class _ConversationalMixin:
         **extra: Any,
     ) -> None:
         """Append a message to conversation history (legacy ChatState path)."""
-        _append_conversation_message(cast("Flow[Any]", self), role, content, **extra)
+        _append_conversation_message(cast(Any, self), role, content, **extra)
 
     @property
     def conversation_messages(self) -> list[LLMMessage]:
         """Message history from state, coerced to LLM-shaped dicts."""
         return [
             message_to_llm_dict(message)
-            for message in get_conversation_messages(cast("Flow[Any]", self))
+            for message in get_conversation_messages(cast(Any, self))
         ]
 
     def receive_user_message(
@@ -514,7 +544,7 @@ class _ConversationalMixin:
         ``state.messages`` and preserve ``last_intent`` across turns.
         Non-conversational flows fall through to the legacy helper.
         """
-        if self.conversational:
+        if self._is_conversational_enabled():
             state = cast(ConversationState, self.state)
             state.messages.append(ConversationMessage(role="user", content=text))
             self._emit_conversation_message_added(
@@ -535,9 +565,7 @@ class _ConversationalMixin:
                 return intent
             return text
 
-        return _receive_user_message(
-            cast("Flow[Any]", self), text, outcomes=outcomes, llm=llm
-        )
+        return _receive_user_message(cast(Any, self), text, outcomes=outcomes, llm=llm)
 
     def classify_intent(
         self,
@@ -561,27 +589,104 @@ class _ConversationalMixin:
     def _conversation_config(self) -> ConversationConfig | None:
         return getattr(type(self), "conversational_config", None)
 
+    @property
+    def _conversation_definition(self) -> Any | None:
+        return self._conversation_flow_definition().conversational
+
+    def _conversation_flow_definition(self) -> Any:
+        flow_definition = getattr(type(self), "flow_definition", None)
+        if not callable(flow_definition):
+            raise AttributeError(
+                f"{type(self).__name__} does not expose flow_definition()"
+            )
+        return flow_definition()
+
+    @classmethod
+    def _conversational_definition(cls) -> Any | None:
+        flow_definition = getattr(cls, "flow_definition", None)
+        if not callable(flow_definition):
+            return None
+        return flow_definition().conversational
+
+    @classmethod
+    def _is_conversational(cls) -> bool:
+        definition = cls._conversational_definition()
+        return bool(definition and definition.enabled)
+
+    def _is_conversational_enabled(self) -> bool:
+        definition = self._conversation_definition
+        return bool(definition and definition.enabled)
+
+    def _initialize_runtime_extension_attrs(self) -> None:
+        if not isinstance(getattr(self, "_conversation_messages", None), list):
+            object.__setattr__(self, "_conversation_messages", [])
+        if not hasattr(self, "_pending_user_message"):
+            object.__setattr__(self, "_pending_user_message", None)
+        if not hasattr(self, "_pending_intents"):
+            object.__setattr__(self, "_pending_intents", None)
+        if not hasattr(self, "_pending_intent_llm"):
+            object.__setattr__(self, "_pending_intent_llm", None)
+
+    def _create_default_extension_state(self) -> ConversationState | None:
+        initial_state_t = getattr(self, "_initial_state_t", None)
+        if type(self)._is_conversational() and (
+            not hasattr(self, "_initial_state_t")
+            or isinstance(initial_state_t, TypeVar)
+        ):
+            return ConversationState()
+        return None
+
+    def _should_apply_pending_kickoff_context(self) -> bool:
+        return (
+            type(self)._is_conversational() and self._pending_user_message is not None
+        )
+
+    def _apply_pending_kickoff_context(self) -> None:
+        self._apply_pending_conversational_turn()
+
+    def _order_start_methods_for_kickoff(
+        self,
+        start_methods: list[Any],
+    ) -> tuple[list[Any], bool]:
+        if not type(self)._is_conversational():
+            return start_methods, False
+
+        conversation_start = "conversation_start"
+        if conversation_start not in {str(method) for method in start_methods}:
+            return start_methods, False
+
+        ordered_starts = [
+            method for method in start_methods if str(method) != conversation_start
+        ]
+        ordered_starts.append(
+            next(
+                method for method in start_methods if str(method) == conversation_start
+            )
+        )
+        return ordered_starts, True
+
     def _should_defer_trace_finalization(self) -> bool:
         """Whether per-turn ``FlowFinished`` + ``finalize_batch`` should be skipped.
 
         True when either:
           - ``flow.defer_trace_finalization`` is set on the instance, OR
-          - the class-level ``ConversationConfig.defer_trace_finalization``
-            on a conversational subclass is True.
+          - the static conversational definition enables deferred finalization.
 
         Either source enables the deferred-session pattern. The caller
         eventually invokes ``finalize_session_traces()`` to close the batch.
         """
         if getattr(self, "defer_trace_finalization", False):
             return True
-        config = self._conversation_config
-        return bool(config and config.defer_trace_finalization)
+        definition = self._conversation_definition
+        return bool(
+            definition and definition.enabled and definition.defer_trace_finalization
+        )
 
     def _reset_turn_execution_state(self) -> None:
         """Clear per-execution tracking so the next turn re-runs the graph."""
         self._completed_methods.clear()
         self._method_outputs.clear()
-        self._pending_and_listeners.clear()
+        self._pending_events.clear()
         self._method_call_counts.clear()
         self._clear_or_listeners()
         self._is_execution_resuming = False
@@ -733,11 +838,12 @@ class _ConversationalMixin:
         router_config: RouterConfig | None,
     ) -> dict[str, str]:
         label_to_method: dict[str, str] = {}
-        for listener_name, condition in self._listeners.items():
-            if isinstance(condition, tuple):
-                _, trigger_labels = condition
-                for trigger_label in trigger_labels:
-                    label_to_method.setdefault(str(trigger_label), str(listener_name))
+        flow_definition = self._conversation_flow_definition()
+        for listener_name, method_definition in flow_definition.methods.items():
+            if method_definition.listen is None or method_definition.router:
+                continue
+            for trigger_label in _iter_condition_labels(method_definition.listen):
+                label_to_method.setdefault(trigger_label, listener_name)
 
         routes = self._effective_routes(router_config)
         overrides = (
@@ -788,21 +894,31 @@ class _ConversationalMixin:
 
     def _valid_route_labels(self) -> set[str]:
         labels: set[str] = set()
-        for condition in self._listeners.values():
-            if isinstance(condition, tuple):
-                _, methods = condition
-                labels.update(str(method) for method in methods)
+        flow_definition = self._conversation_flow_definition()
+        for method_definition in flow_definition.methods.values():
+            if method_definition.listen is None or method_definition.router:
+                continue
+            labels.update(_iter_condition_labels(method_definition.listen))
         return labels
 
     def _effective_routes(self, router_config: RouterConfig | None = None) -> set[str]:
         custom_routes = set(router_config.routes or ()) if router_config else set()
+        definition = self._conversation_definition
+        builtin_routes = (
+            tuple(definition.builtin_routes)
+            if definition is not None
+            else self.builtin_routes
+        )
+        internal_routes = (
+            tuple(definition.internal_routes)
+            if definition is not None
+            else self.internal_routes
+        )
         if not custom_routes:
             custom_routes = (
-                self._valid_route_labels()
-                - set(self.builtin_routes)
-                - set(self.internal_routes)
+                self._valid_route_labels() - set(builtin_routes) - set(internal_routes)
             )
-        return custom_routes | set(self.builtin_routes)
+        return custom_routes | set(builtin_routes)
 
     def _default_conversation_llm(self) -> Any | None:
         config = self._conversation_config

lib/crewai/src/crewai/flow/conversational_definition.py

@@ -0,0 +1,50 @@
+"""Static conversational Flow definition models.
+
+This module is part of the serializable Flow Definition contract. It should
+only contain static data shapes. Experimental conversational runtime behavior
+continues to live in ``crewai.experimental.conversational_mixin``.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+
+class FlowConversationalRouterDefinition(BaseModel):
+    """Static conversational router configuration."""
+
+    prompt: str | None = None
+    response_format: Any = None
+    llm: Any = None
+    routes: list[str] | None = None
+    route_descriptions: dict[str, str] | None = None
+    default_intent: str | None = "converse"
+    fallback_intent: str | None = "converse"
+    intent_field: str = "intent"
+
+
+class FlowConversationalDefinition(BaseModel):
+    """Static conversational Flow configuration."""
+
+    enabled: bool = False
+    system_prompt: str | None = None
+    llm: Any = None
+    router: FlowConversationalRouterDefinition | None = None
+    answer_from_history_prompt: str | None = None
+    default_intents: list[str] | None = None
+    intent_llm: Any = None
+    answer_from_history_llm: Any = None
+    visible_agent_outputs: list[str] | Literal["all"] | None = None
+    defer_trace_finalization: bool = True
+    builtin_routes: list[str] = Field(default_factory=lambda: ["converse", "end"])
+    internal_routes: list[str] = Field(
+        default_factory=lambda: ["answer_from_history", "conversation_start"]
+    )
+
+
+__all__ = [
+    "FlowConversationalDefinition",
+    "FlowConversationalRouterDefinition",
+]

lib/crewai/src/crewai/flow/dsl/_utils.py

@@ -9,6 +9,8 @@ from typing_extensions import TypeIs
 
 from crewai.flow.flow_definition import (
     FlowConfigDefinition,
+    FlowConversationalDefinition,
+    FlowConversationalRouterDefinition,
     FlowDefinition,
     FlowDefinitionDiagnostic,
     FlowHumanFeedbackDefinition,
@@ -27,6 +29,13 @@ R = TypeVar("R")
 logger = logging.getLogger(__name__)
 
 _FLOW_METHOD_DEFINITION_ATTR = "__flow_method_definition__"
+_FLOW_METHOD_METADATA_ATTRS = [
+    "__conversational_only__",
+    "__flow_method_definition__",
+    "__flow_persistence_config__",
+    "__human_feedback_config__",
+    "_human_feedback_llm",
+]
 
 
 def is_flow_method(obj: Any) -> TypeIs[FlowMethod[Any, Any]]:
@@ -42,6 +51,39 @@ def _should_include_flow_method(flow_class: type, method: Any) -> bool:
     return True
 
 
+def _is_conversational_flow(flow_class: type) -> bool:
+    return bool(getattr(flow_class, "conversational", False))
+
+
+def _get_inherited_conversational_method(
+    flow_class: type,
+    attr_name: str,
+) -> Any | None:
+    if not _is_conversational_flow(flow_class):
+        return None
+
+    for base in flow_class.__mro__[1:]:
+        inherited = base.__dict__.get(attr_name)
+        if inherited is None:
+            continue
+        if getattr(inherited, "__conversational_only__", False) and is_flow_method(
+            inherited
+        ):
+            return inherited
+    return None
+
+
+def _stamp_inherited_conversational_metadata(
+    method: Any,
+    inherited: Any,
+) -> Any:
+    for attr in _FLOW_METHOD_METADATA_ATTRS:
+        if hasattr(inherited, attr):
+            setattr(method, attr, getattr(inherited, attr))
+    method.__is_flow_method__ = True
+    return method
+
+
 def _set_flow_method_definition(
     wrapper: FlowMethod[P, R],
     definition: FlowMethodDefinition,
@@ -135,6 +177,8 @@ def _build_state_definition(
     from pydantic import BaseModel as PydanticBaseModel
 
     state_value = getattr(flow_class, "_initial_state_t", None)
+    if isinstance(state_value, TypeVar):
+        state_value = None
     initial_state = getattr(flow_class, "initial_state", None)
     if initial_state is not None:
         state_value = initial_state
@@ -230,6 +274,98 @@ def _build_persistence_definition(
     )
 
 
+def _build_conversational_router_definition(
+    router_config: Any,
+    diagnostics: list[FlowDefinitionDiagnostic],
+    path: str,
+) -> FlowConversationalRouterDefinition | None:
+    if router_config is None:
+        return None
+
+    routes = getattr(router_config, "routes", None)
+    return FlowConversationalRouterDefinition(
+        prompt=getattr(router_config, "prompt", None),
+        response_format=_serialize_static_value(
+            getattr(router_config, "response_format", None),
+            diagnostics,
+            f"{path}.response_format",
+        ),
+        llm=_serialize_static_value(
+            getattr(router_config, "llm", None), diagnostics, f"{path}.llm"
+        ),
+        routes=[str(route) for route in routes] if routes is not None else None,
+        route_descriptions=getattr(router_config, "route_descriptions", None),
+        default_intent=getattr(router_config, "default_intent", "converse"),
+        fallback_intent=getattr(router_config, "fallback_intent", "converse"),
+        intent_field=str(getattr(router_config, "intent_field", "intent")),
+    )
+
+
+def _build_conversational_definition(
+    flow_class: type,
+    diagnostics: list[FlowDefinitionDiagnostic],
+) -> FlowConversationalDefinition | None:
+    if not _is_conversational_flow(flow_class):
+        return None
+
+    config = getattr(flow_class, "conversational_config", None)
+    builtin_routes = getattr(flow_class, "builtin_routes", ("converse", "end"))
+    internal_routes = getattr(
+        flow_class,
+        "internal_routes",
+        ("answer_from_history", "conversation_start"),
+    )
+    if config is None:
+        return FlowConversationalDefinition(
+            enabled=True,
+            builtin_routes=[str(route) for route in builtin_routes],
+            internal_routes=[str(route) for route in internal_routes],
+        )
+
+    default_intents = getattr(config, "default_intents", None)
+    visible_agent_outputs = getattr(config, "visible_agent_outputs", None)
+    return FlowConversationalDefinition(
+        enabled=True,
+        system_prompt=getattr(config, "system_prompt", None),
+        llm=_serialize_static_value(
+            getattr(config, "llm", None), diagnostics, "conversational.llm"
+        ),
+        router=_build_conversational_router_definition(
+            getattr(config, "router", None),
+            diagnostics,
+            "conversational.router",
+        ),
+        answer_from_history_prompt=getattr(config, "answer_from_history_prompt", None),
+        default_intents=(
+            [str(intent) for intent in default_intents]
+            if default_intents is not None
+            else None
+        ),
+        intent_llm=_serialize_static_value(
+            getattr(config, "intent_llm", None),
+            diagnostics,
+            "conversational.intent_llm",
+        ),
+        answer_from_history_llm=_serialize_static_value(
+            getattr(config, "answer_from_history_llm", None),
+            diagnostics,
+            "conversational.answer_from_history_llm",
+        ),
+        visible_agent_outputs=(
+            "all"
+            if visible_agent_outputs == "all"
+            else [str(output) for output in visible_agent_outputs]
+            if visible_agent_outputs is not None
+            else None
+        ),
+        defer_trace_finalization=bool(
+            getattr(config, "defer_trace_finalization", True)
+        ),
+        builtin_routes=[str(route) for route in builtin_routes],
+        internal_routes=[str(route) for route in internal_routes],
+    )
+
+
 def _build_method_definition(
     method: Any,
     diagnostics: list[FlowDefinitionDiagnostic],
@@ -270,6 +406,29 @@ def _iter_flow_methods(flow_class: type) -> dict[str, Any]:
             flow_class, attr_value
         ):
             methods[attr_name] = attr_value
+            continue
+
+        inherited = _get_inherited_conversational_method(flow_class, attr_name)
+        if inherited is not None and callable(attr_value):
+            methods[attr_name] = _stamp_inherited_conversational_metadata(
+                attr_value, inherited
+            )
+
+    if _is_conversational_flow(flow_class):
+        for base in reversed(flow_class.__mro__[1:]):
+            for attr_name, raw_value in base.__dict__.items():
+                if attr_name.startswith("_") or attr_name in methods:
+                    continue
+                if not getattr(raw_value, "__conversational_only__", False):
+                    continue
+                try:
+                    attr_value = getattr(flow_class, attr_name)
+                except AttributeError:
+                    continue
+                if is_flow_method(attr_value) and _should_include_flow_method(
+                    flow_class, attr_value
+                ):
+                    methods[attr_name] = attr_value
 
     # A wrapped method whose name collides with a base Flow model field
     # (e.g. ``checkpoint``) is absorbed by Pydantic as a field; the underlying
@@ -314,6 +473,7 @@ def _build_flow_definition_from_class(
         state=_build_state_definition(flow_class, diagnostics),
         config=_build_config_definition(flow_class, diagnostics),
         persist=_build_persistence_definition(flow_class, diagnostics, "persist"),
+        conversational=_build_conversational_definition(flow_class, diagnostics),
         methods=methods,
         diagnostics=diagnostics,
     )

lib/crewai/src/crewai/flow/flow.py

@@ -6,15 +6,22 @@ The implementation now lives in three modules, split by concern:
   ``@router``, ``or_`` / ``and_``) and Python Flow class projection
 - ``crewai.flow.flow_definition`` -- the serializable Flow Definition contract
 - ``crewai.flow.runtime`` -- the Flow execution engine and state
+- ``crewai.experimental.conversational_mixin`` -- experimental conversational
+  runtime extension composed onto the public ``Flow`` class
 
 Prefer importing from those modules in new code; this module preserves the
 historical ``crewai.flow.flow`` import path.
 """
 
+from typing import Any, TypeVar
+
+from pydantic import BaseModel
+
+from crewai.experimental.conversational_mixin import _ConversationalMixin
 from crewai.flow.dsl import and_, listen, or_, router, start
 from crewai.flow.runtime import (
     _INITIAL_STATE_CLASS_MARKER,
-    Flow,
+    Flow as RuntimeFlow,
     FlowMeta,
     FlowState,
     LockedDictProxy,
@@ -23,6 +30,13 @@ from crewai.flow.runtime import (
 )
 
 
+T = TypeVar("T", bound=dict[str, Any] | BaseModel)
+
+
+class Flow(_ConversationalMixin, RuntimeFlow[T]):
+    """Public Flow class with experimental conversational extension behavior."""
+
+
 __all__ = [
     "_INITIAL_STATE_CLASS_MARKER",
     "Flow",

lib/crewai/src/crewai/flow/flow_definition.py

@@ -16,6 +16,11 @@ from typing import Any, Literal as TypingLiteral
 from pydantic import BaseModel, ConfigDict, Field
 import yaml
 
+from crewai.flow.conversational_definition import (
+    FlowConversationalDefinition,
+    FlowConversationalRouterDefinition,
+)
+
 
 logger = logging.getLogger(__name__)
 
@@ -23,6 +28,8 @@ FlowDefinitionCondition = str | dict[str, Any]
 
 __all__ = [
     "FlowConfigDefinition",
+    "FlowConversationalDefinition",
+    "FlowConversationalRouterDefinition",
     "FlowDefinition",
     "FlowDefinitionCondition",
     "FlowDefinitionDiagnostic",
@@ -115,6 +122,7 @@ class FlowDefinition(BaseModel):
     state: FlowStateDefinition | None = None
     config: FlowConfigDefinition = Field(default_factory=FlowConfigDefinition)
     persist: FlowPersistenceDefinition | None = None
+    conversational: FlowConversationalDefinition | None = None
     methods: dict[str, FlowMethodDefinition] = Field(default_factory=dict)
     diagnostics: list[FlowDefinitionDiagnostic] = Field(default_factory=list)
 

lib/crewai/src/crewai/flow/runtime.py

@@ -84,11 +84,6 @@ from crewai.events.types.flow_events import (
     MethodExecutionPausedEvent,
     MethodExecutionStartedEvent,
 )
-from crewai.experimental.conversational import (
-    ConversationConfig,
-    ConversationState,
-)
-from crewai.experimental.conversational_mixin import _ConversationalMixin
 from crewai.flow.dsl._utils import build_flow_definition
 from crewai.flow.flow_context import current_flow_id, current_flow_request_id
 from crewai.flow.flow_definition import (
@@ -139,7 +134,6 @@ from crewai.utilities.streaming import (
     signal_end,
     signal_error,
 )
-from crewai.utilities.types import LLMMessage
 
 
 # Runtime alias so Pydantic can resolve the ``execution_context`` field's
@@ -154,14 +148,42 @@ ExecutionContext = Any  # type: ignore[assignment,misc]
 logger = logging.getLogger(__name__)
 
 
+def _condition_branches(
+    condition: dict[str, Any],
+) -> tuple[Literal["and", "or"], list[FlowDefinitionCondition]]:
+    if "and" in condition:
+        return "and", condition["and"]
+    return "or", condition["or"]
+
+
+def _condition_satisfied(condition: FlowDefinitionCondition, events: set[str]) -> bool:
+    if isinstance(condition, str):
+        return condition in events
+    operator, branches = _condition_branches(condition)
+    combine = all if operator == "and" else any
+    return combine(_condition_satisfied(branch, events) for branch in branches)
+
+
 def _iter_condition_events(condition: FlowDefinitionCondition) -> Iterator[str]:
     if isinstance(condition, str):
         yield condition
         return
 
-    sub_conditions = condition["and"] if "and" in condition else condition["or"]
-    for sub_condition in sub_conditions:
-        yield from _iter_condition_events(sub_condition)
+    _, branches = _condition_branches(condition)
+    for branch in branches:
+        yield from _iter_condition_events(branch)
+
+
+def _or_alternative_events(condition: FlowDefinitionCondition) -> Iterator[str]:
+    if isinstance(condition, str):
+        yield condition
+        return
+
+    operator, branches = _condition_branches(condition)
+    if operator != "or":
+        return
+    for branch in branches:
+        yield from _or_alternative_events(branch)
 
 
 def _is_multi_event_or(
@@ -170,7 +192,8 @@ def _is_multi_event_or(
     if isinstance(condition, str):
         return False
 
-    return "or" in condition and len(condition["or"]) > 1
+    operator, branches = _condition_branches(condition)
+    return operator == "or" and len(branches) > 1
 
 
 def _resolve_persistence(value: Any) -> Any:
@@ -616,7 +639,7 @@ class FlowMeta(ModelMetaclass):
         return super().__new__(mcs, name, bases, namespace)
 
 
-class Flow(_ConversationalMixin, BaseModel, Generic[T], metaclass=FlowMeta):
+class Flow(BaseModel, Generic[T], metaclass=FlowMeta):
     """Base class for all flows.
 
     type parameter T must be either dict[str, Any] or a subclass of BaseModel."""
@@ -630,41 +653,33 @@ class Flow(_ConversationalMixin, BaseModel, Generic[T], metaclass=FlowMeta):
 
     _flow_definition: ClassVar[FlowDefinition | None] = None
 
-    # === EXPERIMENTAL: conversational mode ===
-    # When ``conversational = True`` on a subclass, the built-in conversational
-    # graph (``conversation_start`` -> ``route_conversation`` -> ``converse_turn``
-    # / ``end_conversation`` / ``answer_from_history_turn``) registers and
-    # ``handle_turn`` / ``chat`` become the chat entry points. When ``False``
-    # (default), the methods exist as inert attributes and never register or
-    # fire — non-chat flows pay no runtime cost.
-    #
-    # ⚠ EXPERIMENTAL FEATURE. The whole conversational surface
-    # (``conversational`` ClassVar, ``handle_turn``, ``chat``,
-    # ``ConversationConfig``, ``RouterConfig``, ``ConversationState``, the
-    # built-in graph + helpers) lives under ``crewai.experimental`` and may
-    # change shape before graduating. Pin your CrewAI version if you depend on
-    # specific behavior, and watch the changelog for breaking updates.
-    conversational: ClassVar[bool] = False
-    conversational_config: ClassVar[ConversationConfig | None] = None
-    builtin_routes: ClassVar[tuple[str, ...]] = ("converse", "end")
-    internal_routes: ClassVar[tuple[str, ...]] = (
-        "answer_from_history",
-        "conversation_start",
-    )
-    builtin_route_descriptions: ClassVar[dict[str, str]] = {
-        "converse": (
-            "Ordinary chat, follow-ups, summaries, clarifications, and "
-            "questions answerable from prior conversation history."
-        ),
-        "end": ("User signals the conversation is finished (goodbye, exit, done)."),
-        "answer_from_history": (
-            "Answer directly from prior conversation history without invoking "
-            "tools, agents, or custom routes."
-        ),
-    }
-
     entity_type: Literal["flow"] = "flow"
 
+    def _initialize_runtime_extension_attrs(self) -> None:
+        """Initialize optional runtime-extension attributes."""
+
+    def _create_default_extension_state(self) -> Any | None:
+        """Return a default state supplied by an optional runtime extension."""
+        return None
+
+    def _should_apply_pending_kickoff_context(self) -> bool:
+        """Whether an optional runtime extension has pending kickoff context."""
+        return False
+
+    def _apply_pending_kickoff_context(self) -> None:
+        """Apply optional runtime-extension kickoff context."""
+
+    def _order_start_methods_for_kickoff(
+        self,
+        start_methods: list[FlowMethodName],
+    ) -> tuple[list[FlowMethodName], bool]:
+        """Allow an optional runtime extension to order kickoff start methods."""
+        return start_methods, False
+
+    def _should_defer_trace_finalization(self) -> bool:
+        """Whether this kickoff should defer final flow trace finalization."""
+        return bool(getattr(self, "defer_trace_finalization", False))
+
     @classmethod
     def flow_definition(cls) -> FlowDefinition:
         """Return the static Flow Definition built from this Flow class."""
@@ -864,7 +879,7 @@ class Flow(_ConversationalMixin, BaseModel, Generic[T], metaclass=FlowMeta):
     _method_execution_counts: dict[FlowMethodName, int] = PrivateAttr(
         default_factory=dict
     )
-    _pending_and_listeners: dict[PendingListenerKey, set[int]] = PrivateAttr(
+    _pending_events: dict[PendingListenerKey, set[str]] = PrivateAttr(
         default_factory=dict
     )
     _fired_or_listeners: set[FlowMethodName] = PrivateAttr(default_factory=set)
@@ -882,10 +897,6 @@ class Flow(_ConversationalMixin, BaseModel, Generic[T], metaclass=FlowMeta):
     _human_feedback_method_outputs: dict[str, Any] = PrivateAttr(default_factory=dict)
     _input_history: list[InputHistoryEntry] = PrivateAttr(default_factory=list)
     _state: Any = PrivateAttr(default=None)
-    _conversation_messages: list[LLMMessage] = PrivateAttr(default_factory=list)
-    _pending_user_message: str | dict[str, Any] | None = PrivateAttr(default=None)
-    _pending_intents: Sequence[str] | None = PrivateAttr(default=None)
-    _pending_intent_llm: str | "BaseLLM" | None = PrivateAttr(default=None)
     _deferred_flow_started_event_id: str | None = PrivateAttr(default=None)
 
     def __class_getitem__(cls: type[Flow[T]], item: type[T]) -> type[Flow[T]]:  # type: ignore[override]
@@ -911,6 +922,7 @@ class Flow(_ConversationalMixin, BaseModel, Generic[T], metaclass=FlowMeta):
         if getattr(self, "_flow_post_init_done", False):
             return
         object.__setattr__(self, "_flow_post_init_done", True)
+        self._initialize_runtime_extension_attrs()
 
         if self._state is None:
             self._state = self._create_initial_state()
@@ -1027,11 +1039,8 @@ class Flow(_ConversationalMixin, BaseModel, Generic[T], metaclass=FlowMeta):
         condition = type(self)._start_condition(method_name)
         if condition is None:
             return False
-        return self._evaluate_condition(
-            condition,
-            trigger,
-            method_name,
-            pending_key_prefix=f"start:{method_name}",
+        return self._condition_met(
+            condition, trigger, PendingListenerKey(f"start:{method_name}")
         )
 
     def _rearm_or_listeners_for_trigger(
@@ -1071,6 +1080,9 @@ class Flow(_ConversationalMixin, BaseModel, Generic[T], metaclass=FlowMeta):
         # Only events that EXCLUSIVELY feed one OR listener race; an event that
         # also feeds another listener (e.g. an AND) is left alone when a sibling
         # wins. e.g. @listen(or_(a, b)) on handler -> {frozenset({a, b}): handler}.
+        # Events nested under an and_() branch (e.g. or_(and_(a, b), c)) are not
+        # alternatives and never race -- cancelling one would make the AND
+        # unsatisfiable.
         racing_groups: dict[frozenset[FlowMethodName], FlowMethodName] = {}
         listener_conditions: dict[FlowMethodName, FlowDefinitionCondition] = {
             listener_name: condition
@@ -1093,14 +1105,14 @@ class Flow(_ConversationalMixin, BaseModel, Generic[T], metaclass=FlowMeta):
         for listener_name, condition in listener_conditions.items():
             if not isinstance(condition, dict):
                 continue
-            events = events_by_listener[listener_name]
-            if "or" not in condition or len(events) <= 1:
+            alternatives = set(_or_alternative_events(condition))
+            if len(alternatives) <= 1:
                 continue
 
             exclusive_events = {
                 event
-                for event in events
-                if listeners_by_event.get(event, set()) == {listener_name}
+                for event in alternatives
+                if listeners_by_event[event] == {listener_name}
             }
             if len(exclusive_events) > 1:
                 # Racing only applies to method-completion events: each member is
@@ -1540,20 +1552,15 @@ class Flow(_ConversationalMixin, BaseModel, Generic[T], metaclass=FlowMeta):
         """
         init_state = self.initial_state
 
-        # Conversational subclasses default to ``ConversationState`` if the
-        # user didn't supply an explicit type parameter (``Flow[...]``) or an
-        # ``initial_state``. This makes ``class MyChat(Flow): conversational
-        # = True`` work without forcing every user to import and parameterize
-        # ``ConversationState`` themselves.
-        if (
-            init_state is None
-            and getattr(type(self), "conversational", False)
-            and not hasattr(self, "_initial_state_t")
-        ):
-            return cast(T, ConversationState())
+        if init_state is None:
+            extension_state = self._create_default_extension_state()
+            if extension_state is not None:
+                return cast(T, extension_state)
 
         if init_state is None and hasattr(self, "_initial_state_t"):
             state_type = self._initial_state_t
+            if isinstance(state_type, TypeVar):
+                state_type = None
             if isinstance(state_type, type):
                 if issubclass(state_type, FlowState):
                     instance = state_type()
@@ -2028,7 +2035,7 @@ class Flow(_ConversationalMixin, BaseModel, Generic[T], metaclass=FlowMeta):
                 # Clear completed methods and outputs for a fresh start
                 self._completed_methods.clear()
                 self._method_outputs.clear()
-                self._pending_and_listeners.clear()
+                self._pending_events.clear()
                 self._clear_or_listeners()
                 self._method_call_counts.clear()
             else:
@@ -2123,9 +2130,8 @@ class Flow(_ConversationalMixin, BaseModel, Generic[T], metaclass=FlowMeta):
 
             if should_emit_flow_started:
                 # In normal flows, each kickoff owns its own flow lifecycle.
-                # Deferred conversational sessions are different: the first
-                # turn opens the flow scope and later turns reuse it until
-                # ``finalize_session_traces()`` emits the single finish event.
+                # Deferred sessions reuse the first flow scope until an
+                # explicit finalization call closes the batch.
                 started_event = FlowStartedEvent(
                     type="flow_started",
                     flow_name=self.name or self.__class__.__name__,
@@ -2155,16 +2161,8 @@ class Flow(_ConversationalMixin, BaseModel, Generic[T], metaclass=FlowMeta):
             # with implicit "crew" execution_type.
             get_env_context()
 
-            # Conversational hook: apply the pending user message AFTER state
-            # restore and AFTER flow scope initialization, so transcript events
-            # are parented under the current conversation trace.
-            # ``handle_turn`` stashes the message on ``self._pending_user_message``
-            # before calling ``kickoff``; this drains it.
-            if (
-                getattr(type(self), "conversational", False)
-                and self._pending_user_message is not None
-            ):
-                self._apply_pending_conversational_turn()
+            if self._should_apply_pending_kickoff_context():
+                self._apply_pending_kickoff_context()
 
             if inputs is not None and "id" not in inputs:
                 self._initialize_state(inputs)
@@ -2187,11 +2185,18 @@ class Flow(_ConversationalMixin, BaseModel, Generic[T], metaclass=FlowMeta):
                 starts_to_execute = (
                     unconditional_starts if unconditional_starts else start_methods
                 )
-                tasks = [
-                    self._execute_start_method(start_method)
-                    for start_method in starts_to_execute
-                ]
-                await asyncio.gather(*tasks)
+                starts_to_execute, run_starts_sequentially = (
+                    self._order_start_methods_for_kickoff(starts_to_execute)
+                )
+                if run_starts_sequentially:
+                    for start_method in starts_to_execute:
+                        await self._execute_start_method(start_method)
+                else:
+                    tasks = [
+                        self._execute_start_method(start_method)
+                        for start_method in starts_to_execute
+                    ]
+                    await asyncio.gather(*tasks)
             except Exception as e:
                 # Check if flow was paused for human feedback
                 from crewai.flow.async_feedback.types import HumanFeedbackPending
@@ -2263,10 +2268,9 @@ class Flow(_ConversationalMixin, BaseModel, Generic[T], metaclass=FlowMeta):
 
             # When ``defer_trace_finalization`` is set, skip both per-turn
             # ``FlowFinishedEvent`` AND trace-batch finalization. The caller
-            # invokes ``finalize_session_traces()`` once at session end to
-            # close out the whole conversation as one trace. The flag is
-            # read from EITHER the instance attribute (set by user code) OR
-            # the class-level ``ConversationConfig.defer_trace_finalization``.
+            # invokes the matching finalization hook once at session end. The
+            # flag is read from either the instance attribute or an extension
+            # definition.
             if not self._should_defer_trace_finalization():
                 future = crewai_event_bus.emit(
                     self,
@@ -2725,63 +2729,18 @@ class Flow(_ConversationalMixin, BaseModel, Generic[T], metaclass=FlowMeta):
                             else:
                                 await self._execute_start_method(method_name)
 
-    def _evaluate_condition(
+    def _condition_met(
         self,
         condition: FlowDefinitionCondition,
         trigger_method: FlowMethodName,
-        listener_name: FlowMethodName,
-        pending_key_prefix: str | None = None,
+        subscription_key: PendingListenerKey,
     ) -> bool:
-        if isinstance(condition, str):
-            return condition == str(trigger_method)
-
-        def _sub_prefix(index: int) -> str | None:
-            if pending_key_prefix is None:
-                return None
-            return f"{pending_key_prefix}:{index}"
-
-        if "or" in condition:
-            # Evaluate every sub-condition (no short-circuit): a nested and_()
-            # branch needs the chance to clear its pending state in
-            # _pending_and_listeners even when an earlier branch already matched.
-            any_matched = False
-            for index, sub_condition in enumerate(condition["or"]):
-                if self._evaluate_condition(
-                    sub_condition,
-                    trigger_method,
-                    listener_name,
-                    pending_key_prefix=_sub_prefix(index),
-                ):
-                    any_matched = True
-            return any_matched
-
-        sub_conditions = condition["and"]
-        pending_key = PendingListenerKey(
-            pending_key_prefix
-            if pending_key_prefix is not None
-            else f"{listener_name}:{id(condition)}"
-        )
-
-        if pending_key not in self._pending_and_listeners:
-            self._pending_and_listeners[pending_key] = set(range(len(sub_conditions)))
-
-        pending_conditions = self._pending_and_listeners[pending_key]
-        for index, sub_condition in enumerate(sub_conditions):
-            if index not in pending_conditions:
-                continue
-            if self._evaluate_condition(
-                sub_condition,
-                trigger_method,
-                listener_name,
-                pending_key_prefix=_sub_prefix(index),
-            ):
-                pending_conditions.discard(index)
-
-        if not pending_conditions:
-            self._pending_and_listeners.pop(pending_key, None)
-            return True
-
-        return False
+        seen = self._pending_events.setdefault(subscription_key, set())
+        seen.add(str(trigger_method))
+        if not _condition_satisfied(condition, seen):
+            return False
+        del self._pending_events[subscription_key]
+        return True
 
     def _find_triggered_methods(
         self, trigger_method: FlowMethodName, router_only: bool
@@ -2799,10 +2758,8 @@ class Flow(_ConversationalMixin, BaseModel, Generic[T], metaclass=FlowMeta):
             if should_check_fired and listener_name in self._fired_or_listeners:
                 continue
 
-            if self._evaluate_condition(
-                condition,
-                trigger_method,
-                listener_name,
+            if self._condition_met(
+                condition, trigger_method, PendingListenerKey(str(listener_name))
             ):
                 triggered.append(listener_name)
                 if should_check_fired:
@@ -2937,7 +2894,7 @@ class Flow(_ConversationalMixin, BaseModel, Generic[T], metaclass=FlowMeta):
             return self.input_provider
         if flow_config.input_provider is not None:
             return flow_config.input_provider
-        return ConsoleProvider()
+        return cast(InputProvider, ConsoleProvider())
 
     def _checkpoint_state_for_ask(self) -> None:
         """Auto-checkpoint flow state before waiting for user input.
@@ -3056,7 +3013,7 @@ class Flow(_ConversationalMixin, BaseModel, Generic[T], metaclass=FlowMeta):
                 executor = ThreadPoolExecutor(max_workers=1)
                 ctx = contextvars.copy_context()
                 future = executor.submit(
-                    ctx.run, provider.request_input, message, self, metadata
+                    ctx.run, provider.request_input, message, cast(Any, self), metadata
                 )
                 try:
                     raw = future.result(timeout=timeout)
@@ -3069,7 +3026,9 @@ class Flow(_ConversationalMixin, BaseModel, Generic[T], metaclass=FlowMeta):
                     # cancel_futures=True cleans up any queued-but-not-started tasks.
                     executor.shutdown(wait=False, cancel_futures=True)
             else:
-                raw = provider.request_input(message, self, metadata=metadata)
+                raw = provider.request_input(
+                    message, cast(Any, self), metadata=metadata
+                )
         except KeyboardInterrupt:
             raise
         except Exception:
@@ -3347,7 +3306,7 @@ class Flow(_ConversationalMixin, BaseModel, Generic[T], metaclass=FlowMeta):
                 flow_name=self.name or self.__class__.__name__,
             ),
         )
-        structure = build_flow_structure(self)
+        structure = build_flow_structure(cast(Any, self))
         return render_interactive(structure, filename=filename, show=show)
 
     @staticmethod

lib/crewai/src/crewai/flow/types.py

@@ -16,7 +16,7 @@ R = TypeVar("R", covariant=True)
 FlowMethodName = NewType("FlowMethodName", str)
 PendingListenerKey = NewType(
     "PendingListenerKey",
-    Annotated[str, "nested flow conditions use 'listener_name:object_id'"],
+    Annotated[str, "listener method name, or 'start:<method>' for conditional starts"],
 )
 
 

lib/crewai/src/crewai/memory/recall_flow.py

@@ -259,8 +259,9 @@ class RecallFlow(Flow[RecallState]):
                 candidates = []
         if not candidates:
             candidates = [scope_prefix]
-        self.state.candidate_scopes = candidates[:20]
-        return self.state.candidate_scopes
+        selected_scopes = candidates[:20]
+        self.state.candidate_scopes = selected_scopes
+        return selected_scopes
 
     @listen(filter_and_chunk)
     def search_chunks(self) -> list[Any]:
@@ -368,9 +369,10 @@ class RecallFlow(Flow[RecallState]):
                         )
                     )
         matches.sort(key=lambda m: m.score, reverse=True)
-        self.state.final_results = matches[: self.state.limit]
+        final_results = matches[: self.state.limit]
+        self.state.final_results = final_results
 
         if self.state.evidence_gaps and self.state.final_results:
             self.state.final_results[0].evidence_gaps = list(self.state.evidence_gaps)
 
-        return self.state.final_results
+        return final_results

lib/crewai/tests/agents/test_agent_executor.py

@@ -32,7 +32,7 @@ def _build_executor(**kwargs: Any) -> AgentExecutor:
     executor._method_outputs = []
     executor._completed_methods = set()
     executor._fired_or_listeners = set()
-    executor._pending_and_listeners = {}
+    executor._pending_events = {}
     executor._method_execution_counts = {}
     executor._method_call_counts = {}
     executor._event_futures = []

lib/crewai/tests/test_flow.py

@@ -1542,40 +1542,63 @@ def test_deeply_nested_conditions():
 
 
 def test_or_branch_does_not_leave_stale_and_state():
-    """or_() over nested and_() branches must not leave stale pending AND state.
-
-    Regression: evaluating an or_() condition stopped at the first branch that was
-    satisfied, so a later and_() branch that the *same* trigger would have completed
-    never cleared its pending state. On the next cycle that trigger alone then
-    spuriously re-satisfied the whole condition. Both branches share the final
-    event ``x`` here, so the shared trigger that completes branch ``(a AND x)`` also
-    completes branch ``(c AND x)`` and both must be cleared together.
-    """
+    fired = []
 
     class StaleStateFlow(Flow):
         @start()
         def begin(self):
             pass
 
-        @listen(or_(and_("a", "x"), and_("c", "x")))
-        def joined(self):
+        @listen(begin)
+        def a(self):
             pass
 
-    flow = StaleStateFlow()
-    condition = type(flow)._listen_condition("joined")
+        @listen(begin)
+        def c(self):
+            pass
 
-    def fires(trigger):
-        return flow._evaluate_condition(condition, trigger, "joined")
+        @listen(and_(a, c))
+        def x(self):
+            pass
 
-    # First cycle: "a" then "c" arrive, then the shared "x" completes (a AND x).
-    assert fires("a") is False
-    assert fires("c") is False
-    assert fires("x") is True
+        @listen(or_(and_("a", "x"), and_("c", "y")))
+        def joined(self):
+            fired.append("joined")
 
-    # Next cycle: "x" alone must NOT re-satisfy the condition. The "c" from the
-    # previous cycle was consumed when "joined" fired, so neither branch is half
-    # complete and "x" by itself is insufficient.
-    assert fires("x") is False
+        @router(joined)
+        def emit_y(self):
+            return "y"
+
+    StaleStateFlow().kickoff()
+
+    assert fired == ["joined"]
+
+
+def test_and_branch_inside_or_does_not_race():
+    execution_order = []
+
+    class DiamondWithFallbackFlow(Flow):
+        @start()
+        def go(self):
+            execution_order.append("go")
+
+        @listen(go)
+        def a(self):
+            execution_order.append("a")
+
+        @listen(go)
+        def b(self):
+            execution_order.append("b")
+
+        @listen(or_(and_(a, b), "fallback"))
+        def done(self):
+            execution_order.append("done")
+
+    DiamondWithFallbackFlow().kickoff()
+
+    assert "done" in execution_order
+    assert execution_order.index("done") > execution_order.index("a")
+    assert execution_order.index("done") > execution_order.index("b")
 
 
 def test_mixed_sync_async_execution_order():

lib/crewai/tests/test_flow_conversation.py

@@ -169,9 +169,6 @@ class TestConversationalFlow:
         )
 
 
-    @pytest.mark.skip(
-        reason="Experimental conversational registry behavior is out of scope for the definition-first start migration."
-    )
     def test_handle_turn_routes_to_listener_and_records_public_result(self) -> None:
         @ConversationConfig(default_intents=["research"], intent_llm="gpt-4o-mini")
         class ResearchFlow(ConversationalFlow):
@@ -595,9 +592,6 @@ class TestConversationalFlow:
         assert result == "legacy-searched"
         assert flow.state.last_intent == "search"
 
-    @pytest.mark.skip(
-        reason="Experimental conversational sequential-start behavior is out of scope for the definition-first start migration."
-    )
     def test_user_start_methods_run_sequentially_before_router_in_conversational_mode(
         self,
     ) -> None:
@@ -649,9 +643,6 @@ class TestConversationalFlow:
         assert "attach_bus" in order  # still fires every turn
         assert "route_turn" in order
 
-    @pytest.mark.skip(
-        reason="Experimental inherited conversational start registration is out of scope for the definition-first start migration."
-    )
     def test_subclass_can_override_conversation_start_without_redecorating(
         self,
     ) -> None:
@@ -1342,6 +1333,12 @@ class TestFlowTracingWhenSuppressed:
 
 
 class TestDeferTraceFinalization:
+    def test_bare_conversational_flow_defers_by_default(self) -> None:
+        class BareChat(ConversationalFlow):
+            pass
+
+        assert BareChat()._should_defer_trace_finalization() is True
+
     def test_conversation_config_drives_defer_flag(self) -> None:
         """``ConversationConfig(defer_trace_finalization=...)`` controls whether
         a conversational subclass defers per-turn trace finalization."""

lib/crewai/tests/test_flow_definition.py

@@ -13,6 +13,7 @@ from pydantic import BaseModel
 import crewai.flow.dsl as flow_dsl
 import crewai.flow.flow_definition as flow_definition
 import crewai.flow.visualization.builder as visualization_builder
+from crewai.experimental import ConversationConfig, RouterConfig
 from crewai.flow import Flow, and_, human_feedback, listen, or_, persist, router, start
 
 
@@ -36,6 +37,8 @@ def test_flow_public_exports_are_explicit():
     }
     assert set(flow_definition.__all__) == {
         "FlowConfigDefinition",
+        "FlowConversationalDefinition",
+        "FlowConversationalRouterDefinition",
         "FlowDefinition",
         "FlowDefinitionCondition",
         "FlowDefinitionDiagnostic",
@@ -169,6 +172,7 @@ def test_flow_definition_maps_dsl_to_static_contract():
     assert definition.state.ref and "ContractState" in definition.state.ref
     assert definition.config.stream is True
     assert definition.config.max_method_calls == 7
+    assert definition.conversational is None
 
     assert definition.methods["begin"].start is True
     assert definition.methods["process"].listen == "begin"
@@ -201,27 +205,74 @@ def test_flow_definition_excludes_conversational_builtins_for_regular_flows():
 
     methods = RegularFlow.flow_definition().methods
 
+    assert RegularFlow.flow_definition().conversational is None
     assert set(methods) == {"begin"}
     assert "conversation_start" not in methods
     assert "route_conversation" not in methods
     assert "converse_turn" not in methods
 
 
-@pytest.mark.skip(
-    reason="Experimental conversational inherited built-ins are out of scope for the definition-first start migration."
-)
 def test_flow_definition_includes_conversational_builtins_when_enabled():
     class ChatFlow(Flow):
         conversational = True
 
-    methods = ChatFlow.flow_definition().methods
+    definition = ChatFlow.flow_definition()
+    methods = definition.methods
 
+    assert definition.conversational is not None
+    assert definition.conversational.enabled is True
+    assert definition.conversational.defer_trace_finalization is True
+    assert definition.conversational.builtin_routes == ["converse", "end"]
     assert "conversation_start" in methods
     assert "route_conversation" in methods
     assert "converse_turn" in methods
     assert methods["conversation_start"].start is True
 
 
+def test_flow_definition_serializes_conversational_config():
+    @ConversationConfig(
+        system_prompt="Be concise.",
+        llm="gpt-4o-mini",
+        router=RouterConfig(
+            prompt="Pick a route.",
+            routes=["research"],
+            default_intent="converse",
+            fallback_intent="end",
+        ),
+        default_intents=["research"],
+        visible_agent_outputs=["researcher"],
+        defer_trace_finalization=False,
+    )
+    class ChatFlow(Flow):
+        conversational = True
+
+    conversational = ChatFlow.flow_definition().conversational
+
+    assert conversational is not None
+    assert conversational.system_prompt == "Be concise."
+    assert conversational.llm == "gpt-4o-mini"
+    assert conversational.default_intents == ["research"]
+    assert conversational.visible_agent_outputs == ["researcher"]
+    assert conversational.defer_trace_finalization is False
+    assert conversational.router is not None
+    assert conversational.router.prompt == "Pick a route."
+    assert conversational.router.routes == ["research"]
+    assert conversational.router.fallback_intent == "end"
+
+
+def test_flow_definition_preserves_undecorated_conversational_override():
+    class ChatFlow(Flow):
+        conversational = True
+
+        def conversation_start(self) -> str | None:
+            return "custom"
+
+    methods = ChatFlow.flow_definition().methods
+
+    assert methods["conversation_start"].start is True
+    assert "route_conversation" in methods
+
+
 def test_flow_definition_serializes_human_feedback_metadata():
     marker = object()