Merge branch 'main' into worktree-ssrf-redirect-fix

lib/cli/pyproject.toml

@@ -8,7 +8,7 @@ authors = [
 ]
 requires-python = ">=3.10, <3.14"
 dependencies = [
-    "crewai-core==1.14.6",
+    "crewai-core==1.14.7a2",
     "click>=8.1.7,<9",
     "pydantic>=2.11.9,<2.13",
     "pydantic-settings~=2.10.1",

lib/cli/src/crewai_cli/__init__.py

@@ -1 +1 @@
-__version__ = "1.14.6"
+__version__ = "1.14.7a2"

lib/cli/src/crewai_cli/templates/crew/pyproject.toml

@@ -5,7 +5,7 @@ description = "{{name}} using crewAI"
 authors = [{ name = "Your Name", email = "you@example.com" }]
 requires-python = ">=3.10,<3.14"
 dependencies = [
-    "crewai[tools]==1.14.6"
+    "crewai[tools]==1.14.7a2"
 ]
 
 [project.scripts]

lib/cli/src/crewai_cli/templates/flow/pyproject.toml

@@ -5,7 +5,7 @@ description = "{{name}} using crewAI"
 authors = [{ name = "Your Name", email = "you@example.com" }]
 requires-python = ">=3.10,<3.14"
 dependencies = [
-    "crewai[tools]==1.14.6"
+    "crewai[tools]==1.14.7a2"
 ]
 
 [project.scripts]

lib/cli/src/crewai_cli/templates/tool/pyproject.toml

@@ -5,7 +5,7 @@ description = "Power up your crews with {{folder_name}}"
 readme = "README.md"
 requires-python = ">=3.10,<3.14"
 dependencies = [
-    "crewai[tools]==1.14.6"
+    "crewai[tools]==1.14.7a2"
 ]
 
 [tool.crewai]

lib/crewai-core/src/crewai_core/__init__.py

@@ -1 +1 @@
-__version__ = "1.14.6"
+__version__ = "1.14.7a2"

lib/crewai-core/src/crewai_core/lock_store.py

@@ -1,14 +1,18 @@
 """Centralised lock factory.
 
-If ``REDIS_URL`` is set and the ``redis`` package is installed, locks are
-distributed via ``portalocker.RedisLock``. Otherwise, falls back to the
-standard file-based ``portalocker.Lock`` in the system temp dir.
+By default, if ``REDIS_URL`` is set and the ``redis`` package is installed,
+locks are distributed via ``portalocker.RedisLock``. Otherwise, falls back to
+the standard file-based ``portalocker.Lock`` in the system temp dir.
+
+The backend can be replaced via :func:`set_lock_backend` to plug in a custom
+locking strategy (e.g. a different distributed lock service, or an in-process
+lock for tests).
 """
 
 from __future__ import annotations
 
-from collections.abc import Iterator
-from contextlib import contextmanager
+from collections.abc import Callable, Iterator
+from contextlib import AbstractContextManager, contextmanager
 from functools import lru_cache
 from hashlib import md5
 import logging
@@ -30,6 +34,25 @@ _REDIS_URL: str | None = os.environ.get("REDIS_URL")
 
 _DEFAULT_TIMEOUT: Final[int] = 120
 
+# A backend is called as ``backend(name, timeout=...)`` and returns a context
+# manager that holds the lock while the ``with`` block runs.
+LockBackend = Callable[..., AbstractContextManager[None]]
+
+# ``None`` means use the built-in Redis/file selection.
+_backend: LockBackend | None = None
+
+
+def set_lock_backend(backend: LockBackend | None) -> None:
+    """Replace the process-wide locking backend used by :func:`lock`.
+
+    Intended for one-time setup at startup. Pass ``None`` to restore the
+    built-in Redis/file default. In-flight :func:`lock` calls keep the backend
+    they started with, but swapping backends while other threads acquire locks
+    is otherwise unsynchronised.
+    """
+    global _backend
+    _backend = backend
+
 
 def _redis_available() -> bool:
     """Return True if redis is installed and REDIS_URL is set."""
@@ -58,10 +81,19 @@ def lock(name: str, *, timeout: float = _DEFAULT_TIMEOUT) -> Iterator[None]:
     """Acquire a named lock, yielding while it is held.
 
     Args:
-        name: A human-readable lock name (e.g. ``"chromadb_init"``).
-              Automatically namespaced to avoid collisions.
+        name: A human-readable lock name (e.g. ``"chromadb_init"``). The
+              built-in default namespaces it to avoid collisions; a custom
+              backend receives it verbatim.
         timeout: Maximum seconds to wait for the lock before raising.
     """
+    # Snapshot the global once: a concurrent set_lock_backend() must not turn
+    # the check-then-call into calling ``None``.
+    backend = _backend
+    if backend is not None:
+        with backend(name, timeout=timeout):
+            yield
+        return
+
     channel = f"crewai:{md5(name.encode(), usedforsecurity=False).hexdigest()}"
 
     if _redis_available():

lib/crewai-files/src/crewai_files/__init__.py

@@ -152,4 +152,4 @@ __all__ = [
     "wrap_file_source",
 ]
 
-__version__ = "1.14.6"
+__version__ = "1.14.7a2"

lib/crewai-tools/pyproject.toml

@@ -10,7 +10,7 @@ requires-python = ">=3.10, <3.14"
 dependencies = [
     "pytube~=15.0.0",
     "requests>=2.33.0,<3",
-    "crewai==1.14.6",
+    "crewai==1.14.7a2",
     "tiktoken>=0.8.0,<0.13",
     "beautifulsoup4~=4.13.4",
     "python-docx~=1.2.0",

lib/crewai-tools/src/crewai_tools/__init__.py

@@ -330,4 +330,4 @@ __all__ = [
     "ZapierActionTools",
 ]
 
-__version__ = "1.14.6"
+__version__ = "1.14.7a2"

lib/crewai/pyproject.toml

@@ -8,8 +8,8 @@ authors = [
 ]
 requires-python = ">=3.10, <3.14"
 dependencies = [
-    "crewai-core==1.14.6",
-    "crewai-cli==1.14.6",
+    "crewai-core==1.14.7a2",
+    "crewai-cli==1.14.7a2",
     # Core Dependencies
     "pydantic>=2.11.9,<2.13",
     "openai>=2.30.0,<3",
@@ -54,7 +54,7 @@ Repository = "https://github.com/crewAIInc/crewAI"
 
 [project.optional-dependencies]
 tools = [
-    "crewai-tools==1.14.6",
+    "crewai-tools==1.14.7a2",
 ]
 embeddings = [
     "tiktoken>=0.8.0,<0.13"
@@ -138,6 +138,9 @@ torchvision = [
 crewai-files = { workspace = true }
 
 
+[project.scripts]
+crewai = "crewai_cli.cli:crewai"
+
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"

lib/crewai/src/crewai/__init__.py

@@ -48,7 +48,7 @@ def _suppress_pydantic_deprecation_warnings() -> None:
 
 _suppress_pydantic_deprecation_warnings()
 
-__version__ = "1.14.6"
+__version__ = "1.14.7a2"
 
 _LAZY_IMPORTS: dict[str, tuple[str, str]] = {
     "Memory": ("crewai.memory.unified_memory", "Memory"),

lib/crewai/src/crewai/events/__init__.py

@@ -61,6 +61,8 @@ if TYPE_CHECKING:
         CrewTrainStartedEvent,
     )
     from crewai.events.types.flow_events import (
+        ConversationMessageAddedEvent,
+        ConversationRouteSelectedEvent,
         FlowCreatedEvent,
         FlowEvent,
         FlowFinishedEvent,
@@ -176,6 +178,8 @@ _LAZY_EVENT_MAPPING: dict[str, str] = {
     "CrewTrainCompletedEvent": "crewai.events.types.crew_events",
     "CrewTrainFailedEvent": "crewai.events.types.crew_events",
     "CrewTrainStartedEvent": "crewai.events.types.crew_events",
+    "ConversationMessageAddedEvent": "crewai.events.types.flow_events",
+    "ConversationRouteSelectedEvent": "crewai.events.types.flow_events",
     "FlowCreatedEvent": "crewai.events.types.flow_events",
     "FlowEvent": "crewai.events.types.flow_events",
     "FlowFinishedEvent": "crewai.events.types.flow_events",
@@ -291,6 +295,8 @@ __all__ = [
     "CheckpointRestoreStartedEvent",
     "CheckpointStartedEvent",
     "CircularDependencyError",
+    "ConversationMessageAddedEvent",
+    "ConversationRouteSelectedEvent",
     "CrewKickoffCompletedEvent",
     "CrewKickoffFailedEvent",
     "CrewKickoffStartedEvent",

lib/crewai/src/crewai/events/event_listener.py

@@ -306,20 +306,24 @@ class EventListener(BaseEventListener):
             self._telemetry.flow_execution_span(
                 event.flow_name, list(source._methods.keys())
             )
-            self.formatter.handle_flow_created(event.flow_name, str(source.flow_id))
-            self.formatter.handle_flow_started(event.flow_name, str(source.flow_id))
+            if not getattr(source, "suppress_flow_events", False):
+                self.formatter.handle_flow_created(event.flow_name, str(source.flow_id))
+                self.formatter.handle_flow_started(event.flow_name, str(source.flow_id))
 
         @crewai_event_bus.on(FlowFinishedEvent)
         def on_flow_finished(source: Any, event: FlowFinishedEvent) -> None:
-            self.formatter.handle_flow_status(
-                event.flow_name,
-                source.flow_id,
-            )
+            if not getattr(source, "suppress_flow_events", False):
+                self.formatter.handle_flow_status(
+                    event.flow_name,
+                    source.flow_id,
+                )
 
         @crewai_event_bus.on(MethodExecutionStartedEvent)
         def on_method_execution_started(
-            _: Any, event: MethodExecutionStartedEvent
+            source: Any, event: MethodExecutionStartedEvent
         ) -> None:
+            if getattr(source, "suppress_flow_events", False):
+                return
             self.formatter.handle_method_status(
                 event.method_name,
                 "running",
@@ -327,8 +331,10 @@ class EventListener(BaseEventListener):
 
         @crewai_event_bus.on(MethodExecutionFinishedEvent)
         def on_method_execution_finished(
-            _: Any, event: MethodExecutionFinishedEvent
+            source: Any, event: MethodExecutionFinishedEvent
         ) -> None:
+            if getattr(source, "suppress_flow_events", False):
+                return
             self.formatter.handle_method_status(
                 event.method_name,
                 "completed",

lib/crewai/src/crewai/events/event_types.py

@@ -53,6 +53,8 @@ from crewai.events.types.crew_events import (
     CrewTrainStartedEvent,
 )
 from crewai.events.types.flow_events import (
+    ConversationMessageAddedEvent,
+    ConversationRouteSelectedEvent,
     FlowFinishedEvent,
     FlowStartedEvent,
     MethodExecutionFailedEvent,
@@ -154,6 +156,8 @@ EventTypes = (
     | TaskStartedEvent
     | TaskCompletedEvent
     | TaskFailedEvent
+    | ConversationMessageAddedEvent
+    | ConversationRouteSelectedEvent
     | FlowStartedEvent
     | FlowFinishedEvent
     | MethodExecutionStartedEvent

lib/crewai/src/crewai/events/listeners/tracing/first_time_trace_handler.py

@@ -222,6 +222,8 @@ To enable tracing later, do any one of these:
             return
         self.batch_manager.batch_owner_type = None
         self.batch_manager.batch_owner_id = None
+        self.batch_manager.defer_session_finalization = False
+        self.batch_manager._batch_finalized = False
         self.batch_manager.current_batch = None
         self.batch_manager.event_buffer.clear()
         self.batch_manager.trace_batch_id = None

lib/crewai/src/crewai/events/listeners/tracing/trace_batch_manager.py

@@ -62,6 +62,7 @@ class TraceBatchManager:
         self._pending_events_lock = Lock()
         self._pending_events_cv = Condition(self._pending_events_lock)
         self._pending_events_count = 0
+        self._finalize_lock = Lock()
 
         self.is_current_batch_ephemeral = False
         self.trace_batch_id: str | None = None
@@ -70,6 +71,8 @@ class TraceBatchManager:
         self.execution_start_times: dict[str, datetime] = {}
         self.batch_owner_type: str | None = None
         self.batch_owner_id: str | None = None
+        self.defer_session_finalization: bool = False
+        self._batch_finalized: bool = False
         self.backend_initialized: bool = False
         self.ephemeral_trace_url: str | None = None
         try:
@@ -101,6 +104,7 @@ class TraceBatchManager:
                 user_context=user_context, execution_metadata=execution_metadata
             )
             self.is_current_batch_ephemeral = use_ephemeral
+            self._batch_finalized = False
 
             self.record_start_time("execution")
 
@@ -312,6 +316,9 @@ class TraceBatchManager:
     def finalize_batch(self) -> TraceBatch | None:
         """Finalize batch and return it for sending"""
 
+        if self._batch_finalized:
+            return None
+
         if not self.current_batch or not is_tracing_enabled_in_context():
             return None
 
@@ -340,16 +347,15 @@ class TraceBatchManager:
         self.current_batch.events = sorted_events
         events_sent_count = len(sorted_events)
         if sorted_events:
-            original_buffer = self.event_buffer
             self.event_buffer = sorted_events
             events_sent_to_backend_status = self._send_events_to_backend()
-            self.event_buffer = original_buffer
             if events_sent_to_backend_status == 500 and self.trace_batch_id:
                 self._mark_batch_as_failed(
                     self.trace_batch_id, "Error sending events to backend"
                 )
                 return None
-        self._finalize_backend_batch(events_sent_count)
+        if not self._finalize_backend_batch(events_sent_count):
+            return None
 
         finalized_batch = self.current_batch
 
@@ -360,80 +366,87 @@ class TraceBatchManager:
         self.event_buffer.clear()
         self.trace_batch_id = None
         self.is_current_batch_ephemeral = False
+        self._batch_finalized = True
 
         self._cleanup_batch_data()
 
         return finalized_batch
 
-    def _finalize_backend_batch(self, events_count: int = 0) -> None:
+    def _finalize_backend_batch(self, events_count: int = 0) -> bool:
         """Send batch finalization to backend
 
         Args:
             events_count: Number of events that were successfully sent
         """
-        if not self.plus_api or not self.trace_batch_id:
-            return
+        with self._finalize_lock:
+            batch_id = self.trace_batch_id
+            is_ephemeral = self.is_current_batch_ephemeral
+            if self._batch_finalized or not self.plus_api or not batch_id:
+                return True
 
-        try:
-            payload: TraceFinalizePayload = {
-                "status": "completed",
-                "duration_ms": self.calculate_duration("execution"),
-                "final_event_count": events_count,
-            }
+            try:
+                payload: TraceFinalizePayload = {
+                    "status": "completed",
+                    "duration_ms": self.calculate_duration("execution"),
+                    "final_event_count": events_count,
+                }
 
-            response = (
-                self.plus_api.finalize_ephemeral_trace_batch(
-                    self.trace_batch_id, payload
-                )
-                if self.is_current_batch_ephemeral
-                else self.plus_api.finalize_trace_batch(self.trace_batch_id, payload)
-            )
-
-            if response.status_code == 200:
-                access_code = response.json().get("access_code", None)
-                console = Console()
-                settings = Settings()
-                base_url = settings.enterprise_base_url or DEFAULT_CREWAI_ENTERPRISE_URL
-                return_link = (
-                    f"{base_url}/crewai_plus/trace_batches/{self.trace_batch_id}"
-                    if not self.is_current_batch_ephemeral and access_code is None
-                    else f"{base_url}/crewai_plus/ephemeral_trace_batches/{self.trace_batch_id}?access_code={access_code}"
+                response = (
+                    self.plus_api.finalize_ephemeral_trace_batch(batch_id, payload)
+                    if is_ephemeral
+                    else self.plus_api.finalize_trace_batch(batch_id, payload)
                 )
 
-                if self.is_current_batch_ephemeral:
-                    self.ephemeral_trace_url = return_link
+                if response.status_code == 200:
+                    self._batch_finalized = True
+                    access_code = response.json().get("access_code", None)
+                    console = Console()
+                    settings = Settings()
+                    base_url = (
+                        settings.enterprise_base_url or DEFAULT_CREWAI_ENTERPRISE_URL
+                    )
+                    return_link = (
+                        f"{base_url}/crewai_plus/trace_batches/{batch_id}"
+                        if not is_ephemeral and access_code is None
+                        else f"{base_url}/crewai_plus/ephemeral_trace_batches/{batch_id}?access_code={access_code}"
+                    )
 
-                message_parts = [
-                    f"✅ Trace batch finalized with session ID: {self.trace_batch_id}",
-                    "",
-                    f"🔗 View here: {return_link}",
-                ]
+                    if is_ephemeral:
+                        self.ephemeral_trace_url = return_link
 
-                if access_code:
-                    message_parts.append(f"🔑 Access Code: {access_code}")
+                    message_parts = [
+                        f"✅ Trace batch finalized with session ID: {batch_id}",
+                        "",
+                        f"🔗 View here: {return_link}",
+                    ]
 
-                panel = Panel(
-                    "\n".join(message_parts),
-                    title="Trace Batch Finalization",
-                    border_style="green",
-                )
-                if not should_auto_collect_first_time_traces():
-                    console.print(panel)
+                    if access_code:
+                        message_parts.append(f"🔑 Access Code: {access_code}")
+
+                    panel = Panel(
+                        "\n".join(message_parts),
+                        title="Trace Batch Finalization",
+                        border_style="green",
+                    )
+                    if not should_auto_collect_first_time_traces():
+                        console.print(panel)
+                    return True
 
-            else:
                 logger.error(
                     f"❌ Failed to finalize trace batch: {response.status_code} - {response.text}"
                 )
-                self._mark_batch_as_failed(self.trace_batch_id, response.text)
+                self._mark_batch_as_failed(batch_id, response.text)
+                return False
 
-        except Exception as e:
-            logger.error(f"❌ Error finalizing trace batch: {e}")
-            try:
-                self._mark_batch_as_failed(self.trace_batch_id, str(e))
-            except Exception:
-                logger.debug(
-                    "Could not mark trace batch as failed (network unavailable)"
-                )
+            except Exception as e:
+                logger.error(f"❌ Error finalizing trace batch: {e}")
+                try:
+                    self._mark_batch_as_failed(batch_id, str(e))
+                except Exception:
+                    logger.debug(
+                        "Could not mark trace batch as failed (network unavailable)"
+                    )
+                return False
 
     def _cleanup_batch_data(self) -> None:
         """Clean up batch data after successful finalization to free memory"""

lib/crewai/src/crewai/events/listeners/tracing/trace_listener.py

@@ -1,5 +1,6 @@
 """Trace collection listener for orchestrating trace collection."""
 
+from datetime import datetime, timezone
 import os
 from typing import Any, ClassVar
 import uuid
@@ -61,6 +62,8 @@ from crewai.events.types.crew_events import (
     CrewKickoffStartedEvent,
 )
 from crewai.events.types.flow_events import (
+    ConversationMessageAddedEvent,
+    ConversationRouteSelectedEvent,
     FlowCreatedEvent,
     FlowFinishedEvent,
     FlowPlotEvent,
@@ -230,11 +233,14 @@ class TraceCollectionListener(BaseEventListener):
 
         @event_bus.on(FlowStartedEvent)
         def on_flow_started(source: Any, event: FlowStartedEvent) -> None:
-            # Always call _initialize_flow_batch to claim ownership.
-            # If batch was already initialized by a concurrent action event
-            # (race condition), initialize_batch() returns early but
-            # batch_owner_type is still correctly set to "flow".
-            self._initialize_flow_batch(source, event)
+            # Only the first execution to open the session batch owns it. A flow
+            # that starts while a batch already exists is nested -- inside a crew
+            # (e.g. an agent's Flow-based executor), a conversational Flow, or a
+            # parent flow -- and must NOT re-claim ownership. Re-claiming would
+            # mark batch_owner_type="flow" and cause the nested flow to finalize
+            # the parent's batch prematurely when it completes.
+            if not self.batch_manager.is_batch_initialized():
+                self._initialize_flow_batch(source, event)
             self._handle_trace_event("flow_started", source, event)
 
         @event_bus.on(MethodExecutionStartedEvent)
@@ -251,6 +257,18 @@ class TraceCollectionListener(BaseEventListener):
         def on_method_failed(source: Any, event: MethodExecutionFailedEvent) -> None:
             self._handle_trace_event("method_execution_failed", source, event)
 
+        @event_bus.on(ConversationMessageAddedEvent)
+        def on_conversation_message_added(
+            source: Any, event: ConversationMessageAddedEvent
+        ) -> None:
+            self._handle_action_event("conversation_message_added", source, event)
+
+        @event_bus.on(ConversationRouteSelectedEvent)
+        def on_conversation_route_selected(
+            source: Any, event: ConversationRouteSelectedEvent
+        ) -> None:
+            self._handle_action_event("conversation_route_selected", source, event)
+
         @event_bus.on(FlowFinishedEvent)
         def on_flow_finished(source: Any, event: FlowFinishedEvent) -> None:
             self._handle_trace_event("flow_finished", source, event)
@@ -264,18 +282,20 @@ class TraceCollectionListener(BaseEventListener):
 
         @event_bus.on(CrewKickoffStartedEvent)
         def on_crew_started(source: Any, event: CrewKickoffStartedEvent) -> None:
-            if self.batch_manager.batch_owner_type != "flow":
-                # Always call _initialize_crew_batch to claim ownership.
-                # If batch was already initialized by a concurrent action event
-                # (e.g. LLM/tool before crew_kickoff_started), initialize_batch()
-                # returns early but batch_owner_type is still correctly set to "crew".
-                # Skip only when a parent flow already owns the batch.
+            # Nested crew inside Flow.kickoff: never claim an existing flow session batch.
+            if not self._nested_in_flow_execution() and (
+                not self.batch_manager.is_batch_initialized()
+            ):
                 self._initialize_crew_batch(source, event)
             self._handle_trace_event("crew_kickoff_started", source, event)
 
         @event_bus.on(CrewKickoffCompletedEvent)
         def on_crew_completed(source: Any, event: CrewKickoffCompletedEvent) -> None:
             self._handle_trace_event("crew_kickoff_completed", source, event)
+            if self.batch_manager.defer_session_finalization:
+                return
+            if self._nested_in_flow_execution():
+                return
             if self.batch_manager.batch_owner_type == "crew":
                 if self.first_time_handler.is_first_time:
                     self.first_time_handler.mark_events_collected()
@@ -286,10 +306,14 @@ class TraceCollectionListener(BaseEventListener):
         @event_bus.on(CrewKickoffFailedEvent)
         def on_crew_failed(source: Any, event: CrewKickoffFailedEvent) -> None:
             self._handle_trace_event("crew_kickoff_failed", source, event)
+            if self.batch_manager.defer_session_finalization:
+                return
+            if self._nested_in_flow_execution():
+                return
             if self.first_time_handler.is_first_time:
                 self.first_time_handler.mark_events_collected()
                 self.first_time_handler.handle_execution_completion()
-            else:
+            elif self.batch_manager.batch_owner_type == "crew":
                 self.batch_manager.finalize_batch()
 
         @event_bus.on(TaskStartedEvent)
@@ -707,8 +731,32 @@ class TraceCollectionListener(BaseEventListener):
         @on_signal
         def handle_signal(source: Any, event: SignalEvent) -> None:
             """Flush trace batch on system signals to prevent data loss."""
-            if self.batch_manager.is_batch_initialized():
-                self.batch_manager.finalize_batch()
+            if not self.batch_manager.is_batch_initialized():
+                return
+            # Multi-turn flows defer batch finalization to finalize_session_traces().
+            if self.batch_manager.defer_session_finalization:
+                return
+            self.batch_manager.finalize_batch()
+
+    @staticmethod
+    def _is_inside_active_flow_context() -> bool:
+        """True when ``kickoff_async`` has set ``current_flow_id`` (nested crew)."""
+        from crewai.flow.flow_context import current_flow_id
+
+        return current_flow_id.get() is not None
+
+    def _flow_owns_trace_batch(self) -> bool:
+        """True when an in-flight conversational flow already owns the trace batch."""
+        if self.batch_manager.batch_owner_type == "flow":
+            return True
+        batch = self.batch_manager.current_batch
+        if batch is not None:
+            return batch.execution_metadata.get("execution_type") == "flow"
+        return False
+
+    def _nested_in_flow_execution(self) -> bool:
+        """True when a crew runs inside a flow session (context or batch ownership)."""
+        return self._is_inside_active_flow_context() or self._flow_owns_trace_batch()
 
     def _initialize_crew_batch(self, source: Any, event: BaseEvent) -> None:
         """Initialize trace batch.
@@ -729,6 +777,33 @@ class TraceCollectionListener(BaseEventListener):
 
         self._initialize_batch(user_context, execution_metadata)
 
+    def _try_initialize_flow_batch_from_context(self, event: Any) -> bool:
+        """Claim a flow trace batch when an action event fires inside kickoff.
+
+        When ``suppress_flow_events=True``, console panels are hidden but
+        ``FlowStartedEvent`` and method lifecycle events still emit; if no
+        batch exists yet, LLM/tool events must not fall back to implicit crew
+        batches.
+        """
+        from crewai.flow.flow_context import current_flow_id, current_flow_name
+
+        flow_id = current_flow_id.get()
+        if flow_id is None:
+            return False
+
+        started_at = getattr(event, "timestamp", None) or datetime.now(timezone.utc)
+        user_context = self._get_user_context()
+        execution_metadata = {
+            "flow_name": current_flow_name.get() or "Unknown Flow",
+            "execution_start": started_at,
+            "crewai_version": get_crewai_version(),
+            "execution_type": "flow",
+        }
+        self.batch_manager.batch_owner_type = "flow"
+        self.batch_manager.batch_owner_id = flow_id
+        self._initialize_batch(user_context, execution_metadata)
+        return True
+
     def _initialize_flow_batch(self, source: Any, event: BaseEvent) -> None:
         """Initialize trace batch for Flow execution.
 
@@ -793,12 +868,19 @@ class TraceCollectionListener(BaseEventListener):
             event: Event object.
         """
         if not self.batch_manager.is_batch_initialized():
-            user_context = self._get_user_context()
-            execution_metadata = {
-                "crew_name": getattr(source, "name", "Unknown Crew"),
-                "crewai_version": get_crewai_version(),
-            }
-            self._initialize_batch(user_context, execution_metadata)
+            if self._try_initialize_flow_batch_from_context(event):
+                pass
+            elif not self._nested_in_flow_execution():
+                user_context = self._get_user_context()
+                execution_metadata = {
+                    "crew_name": getattr(source, "name", "Unknown Crew"),
+                    "crewai_version": get_crewai_version(),
+                }
+                self.batch_manager.batch_owner_type = "crew"
+                self.batch_manager.batch_owner_id = getattr(
+                    source, "id", str(uuid.uuid4())
+                )
+                self._initialize_batch(user_context, execution_metadata)
 
         self.batch_manager.begin_event_processing()
         try:

lib/crewai/src/crewai/events/types/flow_events.py

@@ -166,6 +166,31 @@ class FlowInputReceivedEvent(FlowEvent):
     type: Literal["flow_input_received"] = "flow_input_received"
 
 
+class ConversationMessageAddedEvent(FlowEvent):
+    """Event emitted when a conversational Flow records a message.
+
+    This gives trace consumers a first-class transcript signal instead of
+    requiring them to inspect the full method state payload.
+    """
+
+    session_id: str
+    role: Literal["user", "assistant", "system", "tool"]
+    content: Any
+    message_index: int
+    type: Literal["conversation_message_added"] = "conversation_message_added"
+
+
+class ConversationRouteSelectedEvent(FlowEvent):
+    """Event emitted when a conversational Flow selects a route for a turn."""
+
+    session_id: str
+    route: str
+    user_message: str | None = None
+    message_index: int | None = None
+    previous_intent: str | None = None
+    type: Literal["conversation_route_selected"] = "conversation_route_selected"
+
+
 class HumanFeedbackRequestedEvent(FlowEvent):
     """Event emitted when human feedback is requested.
 

lib/crewai/src/crewai/events/types/llm_events.py

@@ -1,7 +1,7 @@
 from enum import Enum
 from typing import Any, Literal
 
-from pydantic import BaseModel
+from pydantic import BaseModel, field_validator
 
 from crewai.events.base_events import BaseEvent
 
@@ -48,6 +48,43 @@ class LLMCallStartedEvent(LLMEventBase):
     tools: list[dict[str, Any]] | None = None
     callbacks: list[Any] | None = None
     available_functions: dict[str, Any] | None = None
+    # Sampling/request parameters forwarded for OTel GenAI compliance.
+    # All optional so legacy emitters keep working unchanged.
+    temperature: float | None = None
+    top_p: float | None = None
+    max_tokens: int | float | None = None
+    stream: bool | None = None
+    seed: int | None = None
+    stop_sequences: list[str] | None = None
+    frequency_penalty: float | None = None
+    presence_penalty: float | None = None
+    n: int | None = None
+
+    @field_validator("stop_sequences", mode="before")
+    @classmethod
+    def _coerce_stop_sequences_to_str_list(cls, value: Any) -> list[str] | None:
+        """Normalize stop_sequences to ``list[str] | None``.
+
+        Some providers store stop sequences in non-Python-list containers —
+        e.g. a Vertex AI / Gemini code path can hand back a
+        ``google.protobuf.struct_pb2.ListValue`` or a ``RepeatedScalarContainer``.
+        Without coercion the OTel SDK falls back to ``str(value)`` when
+        ``gen_ai.request.stop_sequences`` is set, producing the protobuf
+        textproto repr (``values { string_value: \"...\" }``) instead of a
+        proper ``Sequence[str]``.
+
+        A bare string is treated as a single stop sequence. Anything that
+        can't be iterated cleanly falls back to ``None`` rather than crashing
+        event construction.
+        """
+        if value is None:
+            return None
+        if isinstance(value, str):
+            return [value]
+        try:
+            return [item if isinstance(item, str) else str(item) for item in value]
+        except TypeError:
+            return None
 
 
 class LLMCallCompletedEvent(LLMEventBase):
@@ -58,6 +95,23 @@ class LLMCallCompletedEvent(LLMEventBase):
     response: Any
     call_type: LLMCallType
     usage: dict[str, Any] | None = None
+    finish_reason: str | None = None
+    response_id: str | None = None
+
+    @field_validator("finish_reason", "response_id", mode="before")
+    @classmethod
+    def _coerce_non_string_to_none(cls, value: Any) -> str | None:
+        """Drop non-string values so test mocks and exotic provider types
+        (MagicMock, protobuf enums, etc.) never crash event construction.
+
+        Provider helpers are best-effort: when extraction returns something
+        non-string (e.g. a ``MagicMock`` in unit tests), we treat it as
+        "no value" rather than raising. Downstream telemetry already
+        handles the missing-attribute case.
+        """
+        if value is None or isinstance(value, str):
+            return value
+        return None
 
 
 class LLMCallFailedEvent(LLMEventBase):

lib/crewai/src/crewai/experimental/__init__.py

@@ -1,31 +1,32 @@
-from crewai.experimental.agent_executor import AgentExecutor, CrewAgentExecutorFlow
-from crewai.experimental.evaluation import (
-    AgentEvaluationResult,
-    AgentEvaluator,
-    BaseEvaluator,
-    EvaluationScore,
-    EvaluationTraceCallback,
-    ExperimentResult,
-    ExperimentResults,
-    ExperimentRunner,
-    GoalAlignmentEvaluator,
-    MetricCategory,
-    ParameterExtractionEvaluator,
-    ReasoningEfficiencyEvaluator,
-    SemanticQualityEvaluator,
-    ToolInvocationEvaluator,
-    ToolSelectionEvaluator,
-    create_default_evaluator,
-    create_evaluation_callbacks,
+"""Experimental CrewAI surface — APIs here may change without major-version bumps."""
+
+from __future__ import annotations
+
+from typing import Any
+
+# ``crewai.experimental.conversational`` is pure data shapes — no Flow or Task
+# imports — so it's safe to eager-import. Everything else is resolved lazily
+# below; otherwise the chain
+#     crewai → Flow → experimental.conversational → experimental.__init__
+#                  → experimental.agent_executor / experimental.evaluation
+#                  → Flow / Task (mid-load)
+# would deadlock with "partially initialized module" ImportErrors.
+from crewai.experimental.conversational import (
+    AgentMessage,
+    ConversationConfig,
+    ConversationEvent,
+    ConversationMessage,
+    ConversationState,
+    RouterConfig,
 )
 
 
-__all__ = [
+_LAZY_FROM_AGENT_EXECUTOR = {"AgentExecutor", "CrewAgentExecutorFlow"}
+
+_LAZY_FROM_EVALUATION = {
     "AgentEvaluationResult",
     "AgentEvaluator",
-    "AgentExecutor",
     "BaseEvaluator",
-    "CrewAgentExecutorFlow",  # Deprecated alias for AgentExecutor
     "EvaluationScore",
     "EvaluationTraceCallback",
     "ExperimentResult",
@@ -40,4 +41,62 @@ __all__ = [
     "ToolSelectionEvaluator",
     "create_default_evaluator",
     "create_evaluation_callbacks",
+}
+
+
+def __getattr__(name: str) -> Any:
+    """Lazily resolve symbols whose modules import ``Flow`` or ``Task``.
+
+    Eager re-exports would deadlock when ``Flow`` itself is the consumer that
+    triggered ``crewai.experimental.__init__`` (``Flow`` imports types from
+    :mod:`crewai.experimental.conversational`). Callers like
+    ``from crewai.experimental import AgentExecutor`` still work — the
+    real import just runs lazily, after the original loader finishes.
+    """
+    if name in _LAZY_FROM_AGENT_EXECUTOR:
+        from crewai.experimental.agent_executor import (
+            AgentExecutor,
+            CrewAgentExecutorFlow,
+        )
+
+        globals()["AgentExecutor"] = AgentExecutor
+        globals()["CrewAgentExecutorFlow"] = CrewAgentExecutorFlow
+        return globals()[name]
+
+    if name in _LAZY_FROM_EVALUATION:
+        from crewai.experimental import evaluation as _evaluation_mod
+
+        for attr in _LAZY_FROM_EVALUATION:
+            globals()[attr] = getattr(_evaluation_mod, attr)
+        return globals()[name]
+
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = [
+    "AgentEvaluationResult",
+    "AgentEvaluator",
+    "AgentExecutor",
+    "AgentMessage",
+    "BaseEvaluator",
+    "ConversationConfig",
+    "ConversationEvent",
+    "ConversationMessage",
+    "ConversationState",
+    "CrewAgentExecutorFlow",  # Deprecated alias for AgentExecutor
+    "EvaluationScore",
+    "EvaluationTraceCallback",
+    "ExperimentResult",
+    "ExperimentResults",
+    "ExperimentRunner",
+    "GoalAlignmentEvaluator",
+    "MetricCategory",
+    "ParameterExtractionEvaluator",
+    "ReasoningEfficiencyEvaluator",
+    "RouterConfig",
+    "SemanticQualityEvaluator",
+    "ToolInvocationEvaluator",
+    "ToolSelectionEvaluator",
+    "create_default_evaluator",
+    "create_evaluation_callbacks",
 ]

lib/crewai/src/crewai/experimental/conversational.py

@@ -0,0 +1,184 @@
+"""Conversational types and helpers shared by ``Flow`` (experimental).
+
+The conversational chat surface (``Flow`` with ``conversational = True``) is
+EXPERIMENTAL. APIs in this module and the conversational methods on ``Flow``
+may change without a major-version bump until the feature graduates.
+
+This module hosts the **data shapes** — ``ConversationConfig``,
+``RouterConfig``, ``ConversationState`` and its message types — plus the
+``_conversational_only`` decorator used to gate built-in conversational
+methods on the base ``Flow`` class. The methods themselves live on ``Flow``
+directly.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from typing import Any, Literal, TypeVar, cast
+from uuid import uuid4
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from crewai.utilities.types import LLMMessage
+
+
+ConversationMessageRole = Literal["user", "assistant", "system", "tool"]
+ConversationEventVisibility = Literal["private", "public"]
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def _conversational_only(func: F) -> F:
+    """Mark a method as part of the conversational built-in graph.
+
+    Methods carrying this marker only register on a ``Flow`` subclass when
+    ``conversational = True``. Subclasses that don't opt in see them as
+    inert attributes — they don't fire and don't pollute the listener graph.
+    """
+    func.__conversational_only__ = True  # type: ignore[attr-defined]
+    return func
+
+
+@dataclass
+class RouterConfig:
+    """LLM router configuration for the experimental conversational ``Flow``.
+
+    .. warning::
+
+       **EXPERIMENTAL.** Part of the conversational ``Flow`` surface. Fields
+       and defaults may change before the feature graduates from
+       ``crewai.experimental``. Pin your CrewAI version if you depend on
+       a specific shape.
+
+    ``route_descriptions`` overrides the per-route descriptions used to build
+    the router LLM's "available routes" catalog. Routes without an entry fall
+    back to the handler's docstring first line (or, for built-in routes, the
+    framework's canned description). ``prompt`` is reserved for domain
+    policy/voice, not the route catalog — that's auto-built.
+    """
+
+    prompt: str | None = None
+    response_format: type[BaseModel] | None = None
+    llm: Any | None = None
+    routes: Sequence[str] | None = None
+    route_descriptions: dict[str, str] | None = None
+    default_intent: str | None = "converse"
+    fallback_intent: str | None = "converse"
+    intent_field: str = "intent"
+
+
+@dataclass
+class ConversationConfig:
+    """Class-level configuration for the experimental conversational ``Flow``.
+
+    .. warning::
+
+       **EXPERIMENTAL.** Part of the conversational ``Flow`` surface. Fields
+       and defaults may change before the feature graduates from
+       ``crewai.experimental``. Pin your CrewAI version if you depend on
+       a specific shape.
+
+    ``system_prompt`` defaults to the ``slices.conversational_system_prompt``
+    translation when left as ``None``. Pass an empty string to opt out of any
+    system prompt for ``converse_turn``. ``answer_from_history_prompt`` falls
+    back to ``slices.conversational_answer_from_history_prompt`` when ``None``.
+    """
+
+    system_prompt: str | None = None
+    llm: Any | None = None
+    router: RouterConfig | None = None
+    answer_from_history_prompt: str | None = None
+    default_intents: Sequence[str] | None = None
+    intent_llm: Any | None = None
+    answer_from_history_llm: Any | None = None
+    visible_agent_outputs: Sequence[str] | Literal["all"] | None = None
+    defer_trace_finalization: bool = True
+
+    def __call__(self, flow_cls: type[Any]) -> type[Any]:
+        """Use this config as a class decorator."""
+        flow_cls.conversational_config = self
+        return flow_cls
+
+
+class ConversationMessage(BaseModel):
+    """Canonical user-facing message shared across conversational turns."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    role: ConversationMessageRole
+    content: str | list[dict[str, Any]] | None
+    name: str | None = None
+    tool_call_id: str | None = None
+    tool_calls: list[dict[str, Any]] | None = None
+    files: dict[str, Any] | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class AgentMessage(BaseModel):
+    """Private per-agent message or scratch result."""
+
+    role: ConversationMessageRole | str = "assistant"
+    content: Any
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class ConversationEvent(BaseModel):
+    """Structured trace/event that is separate from user-visible messages."""
+
+    type: str
+    payload: dict[str, Any] = Field(default_factory=dict)
+    agent_name: str | None = None
+    visibility: ConversationEventVisibility = "private"
+
+
+class ConversationState(BaseModel):
+    """Structured state for the experimental conversational ``Flow``.
+
+    .. warning::
+
+       **EXPERIMENTAL.** Field shape and defaults may change before the
+       conversational ``Flow`` graduates from ``crewai.experimental``.
+
+    ``messages`` is the canonical user-facing history. Agent/tool scratch work
+    belongs in ``events`` or ``agent_threads`` unless explicitly made public.
+    """
+
+    id: str = Field(default_factory=lambda: str(uuid4()))
+    messages: list[ConversationMessage] = Field(default_factory=list)
+    current_user_message: str | None = None
+    last_user_message: str | None = None
+    last_intent: str | None = None
+    ended: bool = False
+    events: list[ConversationEvent] = Field(default_factory=list)
+    agent_threads: dict[str, list[AgentMessage]] = Field(default_factory=dict)
+    session_ready: bool = False
+
+
+def message_to_llm_dict(message: Any) -> LLMMessage:
+    """Coerce a stored ``ConversationMessage`` (or dict) into an ``LLMMessage``."""
+    if isinstance(message, BaseModel):
+        data = message.model_dump(exclude_none=True)
+    elif isinstance(message, dict):
+        data = dict(message)
+    else:
+        data = {"role": "user", "content": str(message)}
+
+    return cast(
+        LLMMessage,
+        {key: value for key, value in data.items() if key != "metadata"},
+    )
+
+
+__all__ = [
+    "AgentMessage",
+    "ConversationConfig",
+    "ConversationEvent",
+    "ConversationEventVisibility",
+    "ConversationMessage",
+    "ConversationMessageRole",
+    "ConversationState",
+    "RouterConfig",
+    "_conversational_only",
+    "message_to_llm_dict",
+]

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

@@ -0,0 +1,942 @@
+"""Conversational graph + helpers as a mixin for ``Flow`` (experimental).
+
+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``).
+
+Import surface:
+    - :class:`_ConversationalMixin` — internal; ``Flow`` mixes it in. Users
+      don't import it directly.
+    - The data types this mixin uses live in
+      :mod:`crewai.experimental.conversational`.
+"""
+
+from __future__ import annotations
+
+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 pydantic import BaseModel, Field, create_model
+
+from crewai.events.event_bus import crewai_event_bus
+from crewai.events.types.flow_events import (
+    ConversationMessageAddedEvent,
+    ConversationRouteSelectedEvent,
+)
+from crewai.experimental.conversational import (
+    AgentMessage,
+    ConversationConfig,
+    ConversationEvent,
+    ConversationMessage,
+    ConversationState,
+    RouterConfig,
+    _conversational_only,
+    message_to_llm_dict,
+)
+from crewai.flow.conversation import (
+    append_message as _append_conversation_message,
+    get_conversation_messages,
+    receive_user_message as _receive_user_message,
+)
+from crewai.flow.dsl import listen, router, start
+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``).
+
+    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.
+    """
+
+    # 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.
+    # Class-level slots use ``ClassVar`` to match Flow's actual declarations
+    # (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]
+        _method_call_counts: dict[Any, int]
+        _is_execution_resuming: bool
+        _pending_user_message: str | dict[str, Any] | None
+        _pending_intents: Sequence[str] | None
+        _pending_intent_llm: str | BaseLLM | None
+
+        def _clear_or_listeners(self) -> None:
+            pass
+
+        def _collapse_to_outcome(
+            self,
+            feedback: str,
+            outcomes: tuple[str, ...],
+            llm: str | BaseLLM | Any,
+        ) -> str:
+            pass
+
+        def _copy_and_serialize_state(self) -> dict[str, Any]:
+            pass
+
+        def kickoff(self, *args: Any, **kwargs: Any) -> Any:
+            pass
+
+    @start()
+    @_conversational_only
+    def conversation_start(self) -> str | None:
+        """Internal Flow entrypoint that hands the user message to the router.
+
+        In conversational mode, ``Flow.kickoff_async`` runs all ``@start``
+        methods sequentially and this one is registered last, so any user
+        ``@start`` methods (e.g. permission loading) have already finished
+        before the returned value triggers ``route_conversation``.
+        """
+        state = cast(ConversationState, self.state)
+        return state.current_user_message
+
+    @router(conversation_start)
+    @_conversational_only
+    def route_conversation(self) -> str:
+        """Route the current turn to a listener label."""
+        state = cast(ConversationState, self.state)
+        context = self.build_router_context()
+        previous_intent = state.last_intent
+        configured_route = self.route_turn(context)
+        if configured_route:
+            state.last_intent = configured_route
+            self._emit_conversation_route_selected(
+                configured_route,
+                previous_intent=previous_intent,
+            )
+            return configured_route
+
+        if state.last_intent:
+            self._emit_conversation_route_selected(
+                state.last_intent,
+                previous_intent=previous_intent,
+            )
+            return state.last_intent
+
+        if self.can_answer_from_history(context):
+            state.last_intent = "answer_from_history"
+            self._emit_conversation_route_selected(
+                "answer_from_history",
+                previous_intent=previous_intent,
+            )
+            return "answer_from_history"
+
+        state.last_intent = "converse"
+        self._emit_conversation_route_selected(
+            "converse",
+            previous_intent=previous_intent,
+        )
+        return "converse"
+
+    @listen("converse")
+    @_conversational_only
+    def converse_turn(self) -> str:
+        """Built-in chat handler over canonical conversation history."""
+        llm = self._default_conversation_llm()
+        if llm is None:
+            content = "I can continue the conversation once an LLM is configured."
+            self.append_assistant_message(content)
+            return content
+
+        messages: list[LLMMessage] = []
+        system_prompt = self._resolve_system_prompt()
+        if system_prompt:
+            messages.append({"role": "system", "content": system_prompt})
+        messages.extend(self.conversation_messages)
+
+        response = self._coerce_llm(llm).call(messages=messages)
+        content = self._stringify_result(response)
+        self.append_assistant_message(content)
+        return content
+
+    @listen("end")
+    @_conversational_only
+    def end_conversation(self) -> str:
+        """Built-in conversation terminator."""
+        cast(ConversationState, self.state).ended = True
+        content = "Conversation ended."
+        self.append_assistant_message(content)
+        return content
+
+    @listen("answer_from_history")
+    @_conversational_only
+    def answer_from_history_turn(self) -> str | None:
+        """Answer directly from canonical conversation history when configured."""
+        config = self._conversation_config
+        if config is None:
+            return None
+        llm = config.answer_from_history_llm
+        if llm is None:
+            return None
+
+        llm_instance = self._coerce_llm(llm)
+        messages: list[LLMMessage] = [
+            {
+                "role": "system",
+                "content": self._resolve_answer_from_history_prompt(),
+            },
+            *self.build_agent_context("answer_from_history"),
+        ]
+        response = llm_instance.call(messages=messages)
+        content = self._stringify_result(response)
+        self.append_assistant_message(content)
+        return content
+
+    def handle_turn(
+        self,
+        message: str,
+        *,
+        session_id: str | None = None,
+        intents: Sequence[str] | None = None,
+        intent_llm: str | BaseLLM | None = None,
+        **kickoff_kwargs: Any,
+    ) -> Any:
+        """Append a user message, run one conversational turn, and return output.
+
+        .. warning::
+
+           **EXPERIMENTAL.** This is the public entry point for the
+           conversational ``Flow``. Signature and semantics may change before
+           the feature graduates from ``crewai.experimental``.
+
+        Available only when ``conversational = True`` is set on the subclass.
+        Stashes the message + session_id as pending turn state, runs kickoff
+        (which restores from persist and then applies the pending turn), and
+        promotes the result to an assistant message when the handler didn't.
+        """
+        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.
+        self._pending_user_message = message
+        self._pending_intents = list(intents) if intents else None
+        self._pending_intent_llm = intent_llm
+
+        # Each turn is a fresh execution; clear graph tracking so the second
+        # turn re-runs instead of being treated as a checkpoint restore.
+        if "from_checkpoint" not in kickoff_kwargs:
+            self._reset_turn_execution_state()
+
+        assistant_count = self._assistant_message_count()
+        try:
+            result = self.kickoff(inputs={"id": sid}, **kickoff_kwargs)
+        finally:
+            self._pending_user_message = None
+            self._pending_intents = None
+            self._pending_intent_llm = None
+
+        if (
+            result is not None
+            and self._assistant_message_count() == assistant_count
+            and self._is_public_turn_result(result)
+        ):
+            self.append_assistant_message(self._stringify_result(result))
+        return result
+
+    def chat(
+        self,
+        *,
+        session_id: str | None = None,
+        prompt: str = "\nYou: ",
+        assistant_prefix: str = "\nAssistant: ",
+        exit_commands: Sequence[str] = ("exit", "quit"),
+        input_fn: Callable[[str], str] = input,
+        output_fn: Callable[[str], None] = print,
+        skip_empty: bool = True,
+        defer_trace_finalization: bool = True,
+        **handle_turn_kwargs: Any,
+    ) -> None:
+        """Run an interactive terminal chat loop for a conversational Flow.
+
+        ``chat()`` is a convenience wrapper around ``handle_turn()`` for local
+        REPLs. For web apps, tests, and custom transports, call
+        ``handle_turn()`` directly. The input/output callables are injectable so
+        callers can customize prompts or exercise the loop without patching
+        builtins.
+        """
+        if not getattr(type(self), "conversational", False):
+            raise ValueError("Flow.chat() is only available on conversational flows")
+
+        exit_set = {command.lower() for command in exit_commands}
+        previous_defer = getattr(self, "defer_trace_finalization", False)
+        if defer_trace_finalization:
+            self.defer_trace_finalization = True
+
+        try:
+            while True:
+                try:
+                    message = input_fn(prompt).strip()
+                except (EOFError, KeyboardInterrupt):
+                    output_fn("")
+                    break
+
+                if message.lower() in exit_set:
+                    break
+                if skip_empty and not message:
+                    continue
+
+                result = self.handle_turn(
+                    message,
+                    session_id=session_id,
+                    **handle_turn_kwargs,
+                )
+                output_fn(f"{assistant_prefix}{self._stringify_result(result)}")
+        finally:
+            self.finalize_session_traces()
+            if defer_trace_finalization:
+                self.defer_trace_finalization = previous_defer
+
+    def build_router_context(self) -> dict[str, Any]:
+        """Build context used by the routing policy for the current turn."""
+        state = cast(ConversationState, self.state)
+        return {
+            "system_prompt": self._resolve_system_prompt(),
+            "current_user_message": state.current_user_message,
+            "message_history": self.conversation_messages,
+            "events": [event.model_dump() for event in state.events],
+            "last_intent": state.last_intent,
+        }
+
+    def build_agent_context(self, agent_name: str) -> list[LLMMessage]:
+        """Build canonical message context for an agent or direct LLM call."""
+        state = cast(ConversationState, self.state)
+        messages = list(self.conversation_messages)
+        thread = state.agent_threads.get(agent_name, [])
+        messages.extend(
+            cast(
+                LLMMessage,
+                {
+                    "role": msg.role,
+                    "content": self._stringify_result(msg.content),
+                },
+            )
+            for msg in thread
+        )
+        return messages
+
+    def route_turn(self, context: dict[str, Any]) -> str | None:
+        """Route the current turn via the LLM router.
+
+        When ``ConversationConfig.router`` is omitted, the router is
+        auto-enabled with default settings as long as the flow declares
+        custom ``@listen`` handlers (anything beyond the built-in
+        ``converse`` / ``end`` routes). ``@ConversationConfig(llm=ROUTER_LLM)``
+        is enough to dispatch to your custom handlers — no explicit
+        ``RouterConfig()`` needed.
+
+        Pass an explicit ``RouterConfig`` only to override the routing prompt,
+        supply per-route descriptions, or change the default/fallback intent.
+        Override this method to bypass the LLM router entirely (e.g.,
+        permission gates before the LLM decision).
+        """
+        config = self._conversation_config
+        if config is None:
+            return None
+
+        router_config = config.router
+        if router_config is None:
+            if config.default_intents:
+                return None
+            custom_routes = self._effective_routes(None) - set(self.builtin_routes)
+            if not custom_routes:
+                return None
+            router_config = RouterConfig()
+
+        return self._route_with_config(router_config, context)
+
+    def can_answer_from_history(self, context: dict[str, Any]) -> bool:
+        """Return whether this turn can be answered from message history."""
+        config = self._conversation_config
+        if config is None or config.answer_from_history_llm is None:
+            return False
+        if len(self.conversation_messages) < 2:
+            return False
+
+        feedback = (
+            f"{self._resolve_answer_from_history_prompt()}\n\n"
+            f"Current user message: {context.get('current_user_message')}\n\n"
+            f"Message history:\n{self._format_messages(self.conversation_messages)}"
+        )
+        outcome = self._collapse_to_outcome(
+            feedback,
+            ("answer_from_history", "route_to_flow"),
+            config.answer_from_history_llm,
+        )
+        return outcome == "answer_from_history"
+
+    def append_agent_result(
+        self,
+        agent_name: str,
+        result: Any,
+        *,
+        visibility: Literal["private", "public"] = "private",
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        """Record an agent result, optionally making it visible to the user."""
+        content = self._stringify_result(result)
+        event_visibility = self._resolve_visibility(agent_name, visibility)
+        event = ConversationEvent(
+            type="agent_result",
+            agent_name=agent_name,
+            visibility=event_visibility,
+            payload={"content": content, **(metadata or {})},
+        )
+        state = cast(ConversationState, self.state)
+        state.events.append(event)
+        state.agent_threads.setdefault(agent_name, []).append(
+            AgentMessage(content=content, metadata=metadata or {})
+        )
+        if event_visibility == "public":
+            self.append_assistant_message(content)
+
+    def append_assistant_message(
+        self,
+        content: str,
+        *,
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        """Append a final user-visible assistant message."""
+        state = cast(ConversationState, self.state)
+        state.messages.append(
+            ConversationMessage(
+                role="assistant",
+                content=content,
+                metadata=metadata or {},
+            )
+        )
+        self._emit_conversation_message_added(
+            role="assistant",
+            content=content,
+            message_index=len(state.messages) - 1,
+        )
+
+    def _emit_conversation_message_added(
+        self,
+        *,
+        role: Literal["user", "assistant", "system", "tool"],
+        content: Any,
+        message_index: int,
+    ) -> None:
+        """Emit a compact transcript event for conversational trace views."""
+        state = cast(ConversationState, self.state)
+        crewai_event_bus.emit(
+            self,
+            ConversationMessageAddedEvent(
+                type="conversation_message_added",
+                flow_name=self.name or self.__class__.__name__,
+                session_id=state.id,
+                role=role,
+                content=content,
+                message_index=message_index,
+            ),
+        )
+
+    def _emit_conversation_route_selected(
+        self,
+        route: str,
+        *,
+        previous_intent: str | None = None,
+    ) -> None:
+        """Emit the conversational routing decision for the current turn."""
+        state = cast(ConversationState, self.state)
+        crewai_event_bus.emit(
+            self,
+            ConversationRouteSelectedEvent(
+                type="conversation_route_selected",
+                flow_name=self.name or self.__class__.__name__,
+                session_id=state.id,
+                route=route,
+                user_message=state.current_user_message,
+                message_index=(len(state.messages) - 1) if state.messages else None,
+                previous_intent=previous_intent,
+            ),
+        )
+
+    def append_message(
+        self,
+        role: Literal["user", "assistant", "system", "tool"],
+        content: str,
+        **extra: Any,
+    ) -> None:
+        """Append a message to conversation history (legacy ChatState path)."""
+        _append_conversation_message(cast("Flow[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))
+        ]
+
+    def receive_user_message(
+        self,
+        text: str,
+        *,
+        outcomes: Sequence[str] | None = None,
+        llm: str | BaseLLM | None = None,
+    ) -> str:
+        """Append a user message and optionally classify intent.
+
+        Conversational flows push a ``ConversationMessage`` onto
+        ``state.messages`` and preserve ``last_intent`` across turns.
+        Non-conversational flows fall through to the legacy helper.
+        """
+        if self.conversational:
+            state = cast(ConversationState, self.state)
+            state.messages.append(ConversationMessage(role="user", content=text))
+            self._emit_conversation_message_added(
+                role="user",
+                content=text,
+                message_index=len(state.messages) - 1,
+            )
+            state.current_user_message = text
+            state.last_user_message = text
+            if outcomes and llm is not None:
+                intent = self.classify_intent(
+                    text,
+                    outcomes,
+                    llm=llm,
+                    context=self.conversation_messages,
+                )
+                state.last_intent = intent
+                return intent
+            return text
+
+        return _receive_user_message(
+            cast("Flow[Any]", self), text, outcomes=outcomes, llm=llm
+        )
+
+    def classify_intent(
+        self,
+        text: str,
+        outcomes: Sequence[str],
+        *,
+        llm: str | BaseLLM,
+        context: Sequence[Mapping[str, Any]] | None = None,
+    ) -> str:
+        """Map user text to one of the given outcomes using an LLM."""
+        if context:
+            context_blob = "\n".join(
+                f"{m.get('role', 'user')}: {m.get('content', '')}" for m in context
+            )
+            feedback = f"{context_blob}\n\nLatest user message: {text}"
+        else:
+            feedback = text
+        return self._collapse_to_outcome(feedback, tuple(outcomes), llm)
+
+    @property
+    def _conversation_config(self) -> ConversationConfig | None:
+        return getattr(type(self), "conversational_config", None)
+
+    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.
+
+        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)
+
+    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._method_call_counts.clear()
+        self._clear_or_listeners()
+        self._is_execution_resuming = False
+
+    def _apply_pending_conversational_turn(self) -> None:
+        """Drain the stashed user message + classify if intents configured.
+
+        Called from ``Flow.kickoff_async`` AFTER persist state restore so
+        the appended message survives ``self.persistence.load_state(...)``.
+        """
+        if self._pending_user_message is None:
+            return
+
+        text = self._coerce_user_message_text(self._pending_user_message)
+        if not text.strip():
+            return
+
+        cfg = self._conversation_config
+        outcomes = self._pending_intents
+        if outcomes is None and cfg is not None:
+            outcomes = cfg.default_intents
+        llm = self._pending_intent_llm
+        if llm is None and cfg is not None:
+            llm = cfg.intent_llm
+
+        if outcomes:
+            if llm is None:
+                raise ValueError("intent_llm is required when intents are provided")
+            self.receive_user_message(text, outcomes=outcomes, llm=llm)
+        else:
+            self.receive_user_message(text)
+
+    def _resolve_system_prompt(self) -> str | None:
+        """Return the effective conversational system prompt."""
+        from crewai.utilities.i18n import I18N_DEFAULT
+
+        config = self._conversation_config
+        if config is None or config.system_prompt is None:
+            return I18N_DEFAULT.slice("conversational_system_prompt")
+        return config.system_prompt or None
+
+    def _resolve_answer_from_history_prompt(self) -> str:
+        """Return the effective ``answer_from_history`` prompt."""
+        from crewai.utilities.i18n import I18N_DEFAULT
+
+        config = self._conversation_config
+        if config is None or not config.answer_from_history_prompt:
+            return I18N_DEFAULT.slice("conversational_answer_from_history_prompt")
+        return config.answer_from_history_prompt
+
+    def _route_with_config(
+        self,
+        router_config: RouterConfig,
+        context: dict[str, Any],
+    ) -> str | None:
+        router_llm = self._default_router_llm(router_config)
+        if router_llm is None:
+            return router_config.default_intent
+
+        try:
+            llm = self._coerce_llm(router_llm)
+            response = self._call_router_llm(
+                llm,
+                messages=self._build_router_messages(router_config, context),
+                response_format=self._router_response_format(router_config),
+            )
+            intent = self._extract_router_intent(response, router_config.intent_field)
+        except Exception:
+            return router_config.fallback_intent or router_config.default_intent
+
+        if intent is None:
+            return router_config.fallback_intent or router_config.default_intent
+
+        valid_labels = self._effective_routes(router_config)
+        if valid_labels and intent not in valid_labels:
+            return router_config.fallback_intent or router_config.default_intent
+
+        return intent
+
+    def _default_router_llm(self, router_config: RouterConfig) -> Any | None:
+        config = self._conversation_config
+        return (
+            router_config.llm
+            or (config.intent_llm if config else None)
+            or (config.llm if config else None)
+        )
+
+    def _router_response_format(
+        self,
+        router_config: RouterConfig,
+    ) -> type[BaseModel]:
+        if router_config.response_format is not None:
+            return router_config.response_format
+
+        routes = sorted(self._effective_routes(router_config))
+        field_definitions: dict[str, Any] = {
+            router_config.intent_field: (
+                str,
+                Field(description=f"One of: {', '.join(routes)}"),
+            )
+        }
+        return cast(
+            type[BaseModel],
+            create_model("ConversationRoute", **field_definitions),
+        )
+
+    def _call_router_llm(
+        self,
+        llm: Any,
+        *,
+        messages: list[LLMMessage],
+        response_format: type[BaseModel],
+    ) -> Any:
+        try:
+            return llm.call(messages=messages, response_format=response_format)
+        except TypeError as exc:
+            if "response_format" not in str(exc):
+                raise
+            return llm.call(messages=messages, response_model=response_format)
+
+    def _build_router_messages(
+        self,
+        router_config: RouterConfig,
+        context: dict[str, Any],
+    ) -> list[LLMMessage]:
+        catalog = self._build_route_catalog(router_config)
+        context = {**context, "available_routes": sorted(catalog.keys())}
+        domain_prompt = f"{router_config.prompt}\n\n" if router_config.prompt else ""
+        routes_section = "Routes:\n" + "\n".join(
+            f"- {label}: {description}" if description else f"- {label}"
+            for label, description in sorted(catalog.items())
+        )
+        routing_prompt = (
+            domain_prompt
+            + routes_section
+            + "\n\nChoose exactly one route from the list above. Prefer "
+            "'converse' for follow-ups, summaries, and clarifications about "
+            "prior turns — even if they touch on a topic the user previously "
+            "invoked a custom route for. Use a custom route only when the user "
+            "is making a fresh request for that tool or workflow."
+        )
+        return [
+            {"role": "system", "content": routing_prompt},
+            {"role": "user", "content": json.dumps(context, default=str)},
+        ]
+
+    def _build_route_catalog(
+        self,
+        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))
+
+        routes = self._effective_routes(router_config)
+        overrides = (
+            router_config.route_descriptions
+            if router_config and router_config.route_descriptions
+            else {}
+        )
+
+        catalog: dict[str, str] = {}
+        for route_label in routes:
+            if route_label in overrides:
+                catalog[route_label] = overrides[route_label]
+                continue
+            if route_label in self.builtin_route_descriptions:
+                catalog[route_label] = self.builtin_route_descriptions[route_label]
+                continue
+            handler_name = label_to_method.get(route_label)
+            description = ""
+            if handler_name:
+                method = getattr(type(self), handler_name, None)
+                doc = getattr(method, "__doc__", None)
+                if doc:
+                    description = doc.strip().split("\n", 1)[0].strip()
+            catalog[route_label] = description
+
+        return catalog
+
+    def _extract_router_intent(self, response: Any, intent_field: str) -> str | None:
+        if isinstance(response, BaseModel):
+            value = getattr(response, intent_field, None)
+        elif isinstance(response, dict):
+            value = response.get(intent_field)
+        elif isinstance(response, str):
+            try:
+                parsed = json.loads(response)
+            except json.JSONDecodeError:
+                value = response.strip()
+            else:
+                value = parsed.get(intent_field)
+        else:
+            value = getattr(response, intent_field, None)
+
+        if value is None:
+            return None
+        if isinstance(value, Enum):
+            return str(value.value)
+        return str(value)
+
+    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)
+        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()
+        if not custom_routes:
+            custom_routes = (
+                self._valid_route_labels()
+                - set(self.builtin_routes)
+                - set(self.internal_routes)
+            )
+        return custom_routes | set(self.builtin_routes)
+
+    def _default_conversation_llm(self) -> Any | None:
+        config = self._conversation_config
+        if config is None:
+            return None
+        if config.llm is not None:
+            return config.llm
+        if config.answer_from_history_llm is not None:
+            return config.answer_from_history_llm
+        if config.router is not None:
+            return config.router.llm
+        return config.intent_llm
+
+    def _resolve_visibility(
+        self,
+        agent_name: str,
+        visibility: Literal["private", "public"],
+    ) -> Literal["private", "public"]:
+        if visibility == "public":
+            return "public"
+        config = self._conversation_config
+        visible = config.visible_agent_outputs if config else None
+        if visible == "all" or (visible is not None and agent_name in visible):
+            return "public"
+        return "private"
+
+    def _assistant_message_count(self) -> int:
+        state = cast(ConversationState, self.state)
+        return sum(1 for message in state.messages if message.role == "assistant")
+
+    def _is_public_turn_result(self, result: Any) -> bool:
+        if not isinstance(result, str):
+            return False
+        if result in {
+            "conversation",
+            "converse",
+            "end",
+            "answer_from_history",
+            "route_to_flow",
+        }:
+            return False
+        return result != cast(ConversationState, self.state).last_intent
+
+    @staticmethod
+    def _coerce_user_message_text(user_message: str | dict[str, Any] | Any) -> str:
+        if isinstance(user_message, str):
+            return user_message
+        if isinstance(user_message, dict) and user_message.get("content") is not None:
+            return str(user_message["content"])
+        return str(user_message)
+
+    @staticmethod
+    def _stringify_result(result: Any) -> str:
+        if hasattr(result, "raw"):
+            return str(result.raw)
+        if isinstance(result, BaseModel):
+            return result.model_dump_json()
+        return str(result)
+
+    @staticmethod
+    def _format_messages(messages: Sequence[Mapping[str, Any]]) -> str:
+        return "\n".join(
+            f"{message.get('role', 'user')}: {message.get('content', '')}"
+            for message in messages
+        )
+
+    @staticmethod
+    def _coerce_llm(llm: str | BaseLLM | Any) -> Any:
+        from crewai.llm import LLM
+        from crewai.llms.base_llm import BaseLLM as BaseLLMClass
+
+        if isinstance(llm, str):
+            return LLM(model=llm)
+        if isinstance(llm, BaseLLMClass) or callable(getattr(llm, "call", None)):
+            return llm
+        raise ValueError(f"Invalid llm type: {type(llm)}. Expected str or BaseLLM.")
+
+    def finalize_session_traces(self) -> None:
+        """Emit a final ``FlowFinishedEvent`` and finalize the trace batch.
+
+        Pairs with ``flow.defer_trace_finalization = True`` (or
+        ``ConversationConfig(defer_trace_finalization=True)``): per-turn
+        ``handle_turn()`` skips the close, then a single call here at
+        session end emits one ``FlowFinishedEvent`` + ``finalize_batch()``
+        so the whole conversation lands as one trace.
+
+        Safe to call when not deferring — it's a no-op if the trace batch
+        was already finalized per-turn or never started.
+        """
+        from crewai.events.event_bus import crewai_event_bus
+        from crewai.events.event_context import restore_event_scope
+        from crewai.events.listeners.tracing.trace_listener import (
+            TraceCollectionListener,
+        )
+        from crewai.events.types.flow_events import FlowFinishedEvent
+
+        # Only emit the session-end event when a deferred flow_started is
+        # actually pending. ``_deferred_flow_started_event_id`` is set only by
+        # deferred kickoffs; when finalization was not deferred, each per-turn
+        # kickoff already emitted its own flow_finished, so emitting here would
+        # duplicate the session-end event and confuse tracing. Restoring the
+        # stashed scope also pairs this flow_finished with its opener instead
+        # of warning about an empty scope stack.
+        started_id = getattr(self, "_deferred_flow_started_event_id", None)
+        if started_id:
+            last_output = self._method_outputs[-1] if self._method_outputs else None
+            restore_event_scope(((started_id, "flow_started"),))
+            try:
+                crewai_event_bus.emit(
+                    self,
+                    FlowFinishedEvent(
+                        type="flow_finished",
+                        flow_name=self.name or self.__class__.__name__,
+                        result=last_output,
+                        state=self._copy_and_serialize_state(),
+                    ),
+                )
+            except Exception:
+                logger.warning(
+                    "FlowFinishedEvent emission failed during finalize_session_traces",
+                    exc_info=True,
+                )
+            finally:
+                restore_event_scope(())
+                object.__setattr__(self, "_deferred_flow_started_event_id", None)
+
+        trace_listener = TraceCollectionListener()
+        batch_manager = trace_listener.batch_manager
+        if batch_manager.batch_owner_type == "flow":
+            if trace_listener.first_time_handler.is_first_time:
+                trace_listener.first_time_handler.mark_events_collected()
+                trace_listener.first_time_handler.handle_execution_completion()
+            else:
+                batch_manager.finalize_batch()
+
+
+__all__ = ["_ConversationalMixin"]

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

@@ -4,10 +4,14 @@ from crewai.flow.async_feedback import (
     HumanFeedbackProvider,
     PendingFeedbackContext,
 )
+from crewai.flow.conversation import (
+    ChatState,
+    ConversationalConfig,
+    ConversationalInputs,
+)
+from crewai.flow.dsl import HumanFeedbackResult, human_feedback
 from crewai.flow.flow import Flow, and_, listen, or_, router, start
 from crewai.flow.flow_config import flow_config
-from crewai.flow.flow_serializer import flow_structure
-from crewai.flow.human_feedback import HumanFeedbackResult, human_feedback
 from crewai.flow.input_provider import InputProvider, InputResponse
 from crewai.flow.persistence import persist
 from crewai.flow.visualization import (
@@ -18,7 +22,10 @@ from crewai.flow.visualization import (
 
 
 __all__ = [
+    "ChatState",
     "ConsoleProvider",
+    "ConversationalConfig",
+    "ConversationalInputs",
     "Flow",
     "FlowStructure",
     "HumanFeedbackPending",
@@ -30,7 +37,6 @@ __all__ = [
     "and_",
     "build_flow_structure",
     "flow_config",
-    "flow_structure",
     "human_feedback",
     "listen",
     "or_",

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

@@ -0,0 +1,246 @@
+"""Conversational turn helpers for CrewAI Flows.
+
+Provides message history utilities, kickoff input normalization, and optional
+class-level defaults via ``ConversationalConfig``. Session identity is ``state.id``
+(``inputs["id"]`` / ``kickoff(session_id=...)``), not a separate Flow field.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Literal, TypedDict, cast
+from uuid import uuid4
+
+from pydantic import BaseModel, Field
+
+from crewai.utilities.types import LLMMessage
+
+
+if TYPE_CHECKING:
+    from crewai.flow.flow import Flow
+    from crewai.llms.base_llm import BaseLLM
+
+
+_EXIT_COMMANDS_DEFAULT: tuple[str, ...] = ("exit", "quit")
+
+
+class ConversationalInputs(TypedDict, total=False):
+    """Conventional ``kickoff(inputs=...)`` keys for chat turns."""
+
+    id: str
+    user_message: str | dict[str, Any]
+    last_intent: str
+
+
+@dataclass
+class ConversationalConfig:
+    """Optional class-level defaults for conversational flows.
+
+    Override per kickoff via ``user_message``, ``session_id``, ``intents``, etc.
+    """
+
+    default_intents: Sequence[str] | None = None
+    intent_llm: str | None = None
+    interactive_prompt: str = "You: "
+    interactive_timeout: float | None = None
+    exit_commands: Sequence[str] = field(default_factory=lambda: _EXIT_COMMANDS_DEFAULT)
+    defer_trace_finalization: bool = True
+
+
+class ChatState(BaseModel):
+    """Recommended persisted state shape for multi-turn flows."""
+
+    id: str = Field(default_factory=lambda: str(uuid4()))
+    messages: list[LLMMessage] = Field(default_factory=list)
+    last_user_message: str | None = None
+    last_intent: str | None = None
+    session_ready: bool = False
+
+
+def _coerce_user_message_text(user_message: str | dict[str, Any] | Any) -> str:
+    if isinstance(user_message, str):
+        return user_message
+    if isinstance(user_message, dict):
+        content = user_message.get("content")
+        if content is not None:
+            return str(content)
+    return str(user_message)
+
+
+def normalize_kickoff_inputs(
+    inputs: dict[str, Any] | None,
+    *,
+    user_message: str | dict[str, Any] | None = None,
+    session_id: str | None = None,
+) -> dict[str, Any] | None:
+    """Merge conversational kickoff kwargs into the inputs dict.
+
+    Returns ``None`` when the caller passed no inputs and no conversational
+    kwargs — so ``FlowStartedEvent.inputs`` stays ``None`` for stateless flows
+    instead of being materialized as an empty dict.
+    """
+    if inputs is None and user_message is None and session_id is None:
+        return None
+
+    merged: dict[str, Any] = dict(inputs or {})
+
+    if session_id is not None:
+        merged["id"] = session_id
+
+    if user_message is not None:
+        merged["user_message"] = user_message
+
+    return merged
+
+
+def get_conversation_messages(flow: Flow[Any]) -> list[LLMMessage]:
+    """Read message history from flow state or the internal fallback buffer."""
+    buffer: list[LLMMessage] = getattr(flow, "_conversation_messages", [])
+    state = getattr(flow, "_state", None)
+    if state is None:
+        return list(buffer)
+
+    if isinstance(state, dict):
+        messages = state.get("messages")
+        if isinstance(messages, list):
+            return cast(list[LLMMessage], messages)
+    elif isinstance(state, BaseModel) and hasattr(state, "messages"):
+        messages = getattr(state, "messages", None)
+        if isinstance(messages, list):
+            return cast(list[LLMMessage], messages)
+
+    return list(buffer)
+
+
+def append_message(
+    flow: Flow[Any],
+    role: Literal["user", "assistant", "system", "tool"],
+    content: str,
+    **extra: Any,
+) -> None:
+    """Append a message to ``state.messages`` or the flow fallback buffer."""
+    message: LLMMessage = {"role": role, "content": content}
+    for key, value in extra.items():
+        if key in ("tool_call_id", "name", "tool_calls", "files"):
+            message[key] = value  # type: ignore[literal-required]
+
+    state = getattr(flow, "_state", None)
+    if state is not None:
+        if isinstance(state, dict):
+            messages = state.get("messages")
+            if isinstance(messages, list):
+                messages.append(message)
+                return
+        elif isinstance(state, BaseModel) and hasattr(state, "messages"):
+            messages = getattr(state, "messages", None)
+            if messages is None:
+                object.__setattr__(state, "messages", [])
+                messages = state.messages
+            if isinstance(messages, list):
+                messages.append(message)
+                return
+
+    if not hasattr(flow, "_conversation_messages"):
+        object.__setattr__(flow, "_conversation_messages", [])
+    flow._conversation_messages.append(message)
+
+
+def set_state_field(flow: Flow[Any], name: str, value: Any) -> None:
+    """Set a field on structured or dict flow state when present."""
+    state = getattr(flow, "_state", None)
+    if state is None:
+        return
+    if isinstance(state, dict):
+        state[name] = value
+    elif isinstance(state, BaseModel) and hasattr(state, name):
+        object.__setattr__(state, name, value)
+
+
+def receive_user_message(
+    flow: Flow[Any],
+    text: str,
+    *,
+    outcomes: Sequence[str] | None = None,
+    llm: str | BaseLLM | None = None,
+) -> str:
+    """Record a user turn: append message and optionally classify intent."""
+    append_message(flow, "user", text)
+    set_state_field(flow, "last_user_message", text)
+
+    if outcomes and llm is not None:
+        intent = flow.classify_intent(
+            text,
+            outcomes,
+            llm=llm,
+            context=get_conversation_messages(flow),
+        )
+        set_state_field(flow, "last_intent", intent)
+        return intent
+
+    return text
+
+
+def prepare_conversational_turn(
+    flow: Flow[Any],
+    *,
+    user_message: str | dict[str, Any] | None = None,
+    intents: Sequence[str] | None = None,
+    intent_llm: str | BaseLLM | None = None,
+    config: ConversationalConfig | None = None,
+) -> None:
+    """Hydrate conversation state after inputs are merged into flow state."""
+    if user_message is None:
+        state = getattr(flow, "_state", None)
+        if isinstance(state, dict) and "user_message" in state:
+            user_message = state["user_message"]
+        elif isinstance(state, BaseModel) and hasattr(state, "user_message"):
+            user_message = getattr(state, "user_message", None)
+
+    if user_message is None:
+        return
+
+    text = _coerce_user_message_text(user_message)
+    if not text.strip():
+        return
+
+    # Fresh classification each turn (do not reuse prior turn's route label).
+    set_state_field(flow, "last_intent", None)
+
+    resolved_intents = intents
+    if resolved_intents is None and config is not None:
+        resolved_intents = config.default_intents
+
+    resolved_llm = intent_llm
+    if resolved_llm is None and config is not None:
+        resolved_llm = config.intent_llm
+
+    if resolved_intents:
+        if resolved_llm is None:
+            raise ValueError("intent_llm is required when intents are provided")
+        receive_user_message(
+            flow,
+            text,
+            outcomes=resolved_intents,
+            llm=resolved_llm,
+        )
+    else:
+        receive_user_message(flow, text)
+
+
+def input_history_to_messages(entries: Sequence[Any]) -> list[LLMMessage]:
+    """Convert ``Flow.input_history`` entries to LLM message format."""
+    messages: list[LLMMessage] = []
+    for entry in entries:
+        prompt = entry.get("message") if isinstance(entry, dict) else None
+        response = entry.get("response") if isinstance(entry, dict) else None
+        if prompt:
+            messages.append({"role": "assistant", "content": str(prompt)})
+        if response:
+            messages.append({"role": "user", "content": str(response)})
+    return messages
+
+
+def get_conversational_config(flow: Flow[Any]) -> ConversationalConfig | None:
+    """Return class-level ``conversational_config`` if defined."""
+    return getattr(type(flow), "conversational_config", None)

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

@@ -1,320 +0,0 @@
-"""Flow authoring DSL: the ``@start`` / ``@listen`` / ``@router`` decorators
-plus the ``or_`` / ``and_`` condition combinators.
-
-These decorators wrap user methods into the typed wrappers defined in
-``flow_wrappers`` and record their trigger conditions. The structural model
-those conditions feed is built in ``flow_definition``; execution happens in
-``runtime``.
-"""
-
-from __future__ import annotations
-
-from collections.abc import Callable
-from typing import Any, ParamSpec, TypeVar
-
-from crewai.flow.constants import AND_CONDITION, OR_CONDITION
-from crewai.flow.flow_definition import (
-    _extract_all_methods,
-    is_flow_condition_dict,
-    is_flow_method_callable,
-    is_flow_method_name,
-)
-from crewai.flow.flow_wrappers import (
-    FlowCondition,
-    FlowConditions,
-    ListenMethod,
-    RouterMethod,
-    StartMethod,
-)
-
-
-P = ParamSpec("P")
-R = TypeVar("R")
-
-
-def start(
-    condition: str | FlowCondition | Callable[..., Any] | None = None,
-) -> Callable[[Callable[P, R]], StartMethod[P, R]]:
-    """Marks a method as a flow's starting point.
-
-    This decorator designates a method as an entry point for the flow execution.
-    It can optionally specify conditions that trigger the start based on other
-    method executions.
-
-    Args:
-        condition: Defines when the start method should execute. Can be:
-            - str: Name of a method that triggers this start
-            - FlowCondition: Result from or_() or and_(), including nested conditions
-            - Callable[..., Any]: A method reference that triggers this start
-            Default is None, meaning unconditional start.
-
-    Returns:
-        A decorator function that wraps the method as a flow start point and preserves its signature.
-
-    Raises:
-        ValueError: If the condition format is invalid.
-
-    Examples:
-        >>> @start()  # Unconditional start
-        >>> def begin_flow(self):
-        ...     pass
-
-        >>> @start("method_name")  # Start after specific method
-        >>> def conditional_start(self):
-        ...     pass
-
-        >>> @start(and_("method1", "method2"))  # Start after multiple methods
-        >>> def complex_start(self):
-        ...     pass
-    """
-
-    def decorator(func: Callable[P, R]) -> StartMethod[P, R]:
-        """Decorator that wraps a function as a start method.
-
-        Args:
-            func: The function to wrap as a start method.
-
-        Returns:
-            A StartMethod wrapper around the function.
-        """
-        wrapper = StartMethod(func)
-
-        if condition is not None:
-            if is_flow_method_name(condition):
-                wrapper.__trigger_methods__ = [condition]
-                wrapper.__condition_type__ = OR_CONDITION
-            elif is_flow_condition_dict(condition):
-                if "conditions" in condition:
-                    wrapper.__trigger_condition__ = condition
-                    wrapper.__trigger_methods__ = _extract_all_methods(condition)
-                    wrapper.__condition_type__ = condition["type"]
-                elif "methods" in condition:
-                    wrapper.__trigger_methods__ = condition["methods"]
-                    wrapper.__condition_type__ = condition["type"]
-                else:
-                    raise ValueError(
-                        "Condition dict must contain 'conditions' or 'methods'"
-                    )
-            elif is_flow_method_callable(condition):
-                wrapper.__trigger_methods__ = [condition.__name__]
-                wrapper.__condition_type__ = OR_CONDITION
-            else:
-                raise ValueError(
-                    "Condition must be a method, string, or a result of or_() or and_()"
-                )
-        return wrapper
-
-    return decorator
-
-
-def listen(
-    condition: str | FlowCondition | Callable[..., Any],
-) -> Callable[[Callable[P, R]], ListenMethod[P, R]]:
-    """Creates a listener that executes when specified conditions are met.
-
-    This decorator sets up a method to execute in response to other method
-    executions in the flow. It supports both simple and complex triggering
-    conditions.
-
-    Args:
-        condition: Specifies when the listener should execute.
-
-    Returns:
-        A decorator function that wraps the method as a flow listener and preserves its signature.
-
-    Raises:
-        ValueError: If the condition format is invalid.
-
-    Examples:
-        >>> @listen("process_data")
-        >>> def handle_processed_data(self):
-        ...     pass
-
-        >>> @listen("method_name")
-        >>> def handle_completion(self):
-        ...     pass
-    """
-
-    def decorator(func: Callable[P, R]) -> ListenMethod[P, R]:
-        """Decorator that wraps a function as a listener method.
-
-        Args:
-            func: The function to wrap as a listener method.
-
-        Returns:
-            A ListenMethod wrapper around the function.
-        """
-        wrapper = ListenMethod(func)
-
-        if is_flow_method_name(condition):
-            wrapper.__trigger_methods__ = [condition]
-            wrapper.__condition_type__ = OR_CONDITION
-        elif is_flow_condition_dict(condition):
-            if "conditions" in condition:
-                wrapper.__trigger_condition__ = condition
-                wrapper.__trigger_methods__ = _extract_all_methods(condition)
-                wrapper.__condition_type__ = condition["type"]
-            elif "methods" in condition:
-                wrapper.__trigger_methods__ = condition["methods"]
-                wrapper.__condition_type__ = condition["type"]
-            else:
-                raise ValueError(
-                    "Condition dict must contain 'conditions' or 'methods'"
-                )
-        elif is_flow_method_callable(condition):
-            wrapper.__trigger_methods__ = [condition.__name__]
-            wrapper.__condition_type__ = OR_CONDITION
-        else:
-            raise ValueError(
-                "Condition must be a method, string, or a result of or_() or and_()"
-            )
-        return wrapper
-
-    return decorator
-
-
-def router(
-    condition: str | FlowCondition | Callable[..., Any],
-) -> Callable[[Callable[P, R]], RouterMethod[P, R]]:
-    """Creates a routing method that directs flow execution based on conditions.
-
-    This decorator marks a method as a router, which can dynamically determine
-    the next steps in the flow based on its return value. Routers are triggered
-    by specified conditions and can return constants that determine which path
-    the flow should take.
-
-    Args:
-        condition: Specifies when the router should execute. Can be:
-            - str: Name of a method that triggers this router
-            - FlowCondition: Result from or_() or and_(), including nested conditions
-            - Callable[..., Any]: A method reference that triggers this router
-
-    Returns:
-        A decorator function that wraps the method as a router and preserves its signature.
-
-    Raises:
-        ValueError: If the condition format is invalid.
-
-    Examples:
-        >>> @router("check_status")
-        >>> def route_based_on_status(self):
-        ...     if self.state.status == "success":
-        ...         return "SUCCESS"
-        ...     return "FAILURE"
-
-        >>> @router(and_("validate", "process"))
-        >>> def complex_routing(self):
-        ...     if all([self.state.valid, self.state.processed]):
-        ...         return "CONTINUE"
-        ...     return "STOP"
-    """
-
-    def decorator(func: Callable[P, R]) -> RouterMethod[P, R]:
-        """Decorator that wraps a function as a router method.
-
-        Args:
-            func: The function to wrap as a router method.
-
-        Returns:
-            A RouterMethod wrapper around the function.
-        """
-        wrapper = RouterMethod(func)
-
-        if is_flow_method_name(condition):
-            wrapper.__trigger_methods__ = [condition]
-            wrapper.__condition_type__ = OR_CONDITION
-        elif is_flow_condition_dict(condition):
-            if "conditions" in condition:
-                wrapper.__trigger_condition__ = condition
-                wrapper.__trigger_methods__ = _extract_all_methods(condition)
-                wrapper.__condition_type__ = condition["type"]
-            elif "methods" in condition:
-                wrapper.__trigger_methods__ = condition["methods"]
-                wrapper.__condition_type__ = condition["type"]
-            else:
-                raise ValueError(
-                    "Condition dict must contain 'conditions' or 'methods'"
-                )
-        elif is_flow_method_callable(condition):
-            wrapper.__trigger_methods__ = [condition.__name__]
-            wrapper.__condition_type__ = OR_CONDITION
-        else:
-            raise ValueError(
-                "Condition must be a method, string, or a result of or_() or and_()"
-            )
-        return wrapper
-
-    return decorator
-
-
-def or_(*conditions: str | FlowCondition | Callable[..., Any]) -> FlowCondition:
-    """Combines multiple conditions with OR logic for flow control.
-
-    Creates a condition that is satisfied when any of the specified conditions
-    are met. This is used with @start, @listen, or @router decorators to create
-    complex triggering conditions.
-
-    Args:
-        conditions: Variable number of conditions that can be method names, existing condition dictionaries, or method references.
-
-    Returns:
-        A condition dictionary with format {"type": "OR", "conditions": list_of_conditions} where each condition can be a string (method name) or a nested dict
-
-    Raises:
-        ValueError: If condition format is invalid.
-
-    Examples:
-        >>> @listen(or_("success", "timeout"))
-        >>> def handle_completion(self):
-        ...     pass
-
-        >>> @listen(or_(and_("step1", "step2"), "step3"))
-        >>> def handle_nested(self):
-        ...     pass
-    """
-    processed_conditions: FlowConditions = []
-    for condition in conditions:
-        if is_flow_condition_dict(condition) or is_flow_method_name(condition):
-            processed_conditions.append(condition)
-        elif is_flow_method_callable(condition):
-            processed_conditions.append(condition.__name__)
-        else:
-            raise ValueError("Invalid condition in or_()")
-    return {"type": OR_CONDITION, "conditions": processed_conditions}
-
-
-def and_(*conditions: str | FlowCondition | Callable[..., Any]) -> FlowCondition:
-    """Combines multiple conditions with AND logic for flow control.
-
-    Creates a condition that is satisfied only when all specified conditions
-    are met. This is used with @start, @listen, or @router decorators to create
-    complex triggering conditions.
-
-    Args:
-        *conditions: Variable number of conditions that can be method names, existing condition dictionaries, or method references.
-
-    Returns:
-        A condition dictionary with format {"type": "AND", "conditions": list_of_conditions}
-        where each condition can be a string (method name) or a nested dict
-
-    Raises:
-        ValueError: If any condition is invalid.
-
-    Examples:
-        >>> @listen(and_("validated", "processed"))
-        >>> def handle_complete_data(self):
-        ...     pass
-
-        >>> @listen(and_(or_("step1", "step2"), "step3"))
-        >>> def handle_nested(self):
-        ...     pass
-    """
-    processed_conditions: FlowConditions = []
-    for condition in conditions:
-        if is_flow_condition_dict(condition) or is_flow_method_name(condition):
-            processed_conditions.append(condition)
-        elif is_flow_method_callable(condition):
-            processed_conditions.append(condition.__name__)
-        else:
-            raise ValueError("Invalid condition in and_()")
-    return {"type": AND_CONDITION, "conditions": processed_conditions}

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

@@ -0,0 +1,32 @@
+"""Flow DSL: the Python authoring layer for Flows.
+
+Provides the ``@start`` / ``@listen`` / ``@router`` decorators and the
+``or_`` / ``and_`` condition combinators used to write Flow classes in
+Python. The DSL is one way to produce a Flow Structure: this package
+extracts a :class:`~crewai.flow.flow_definition.FlowDefinition` from a
+Python Flow class. Execution is handled by ``runtime``.
+"""
+
+from crewai.flow.dsl._conditions import and_, or_
+from crewai.flow.dsl._human_feedback import (
+    HumanFeedbackResult,
+    human_feedback,
+)
+from crewai.flow.dsl._listen import listen
+from crewai.flow.dsl._router import router
+from crewai.flow.dsl._start import start
+from crewai.flow.dsl._utils import (
+    build_flow_definition as build_flow_definition,
+    extract_flow_definition as extract_flow_definition,
+)
+
+
+__all__ = [
+    "HumanFeedbackResult",
+    "and_",
+    "human_feedback",
+    "listen",
+    "or_",
+    "router",
+    "start",
+]

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

@@ -0,0 +1,287 @@
+"""Flow DSL condition primitives.
+
+Type guards, the public ``or_`` / ``and_`` combinators, and the conversions
+between runtime conditions, normalized conditions, and the
+``FlowDefinitionCondition`` shape stored on a :class:`FlowDefinition`. These are
+the lower layer of the DSL: the decorators and the definition builder
+(``_utils``) build on top of them, so this module imports nothing from its
+siblings.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+
+from typing_extensions import TypeIs
+
+from crewai.flow.constants import AND_CONDITION, OR_CONDITION
+from crewai.flow.dsl._types import FlowTrigger
+from crewai.flow.flow_definition import FlowDefinitionCondition
+from crewai.flow.flow_wrappers import (
+    FlowCondition,
+    FlowConditions,
+    SimpleFlowCondition,
+)
+from crewai.flow.types import FlowMethodName
+
+
+def _is_non_string_sequence(value: Any) -> bool:
+    return isinstance(value, Sequence) and not isinstance(value, (str, bytes))
+
+
+def is_simple_flow_condition(obj: Any) -> TypeIs[SimpleFlowCondition]:
+    """Check if the object is a ``(condition_type, methods)`` tuple."""
+    return (
+        isinstance(obj, tuple)
+        and len(obj) == 2
+        and isinstance(obj[0], str)
+        and isinstance(obj[1], list)
+    )
+
+
+def is_flow_condition_dict(obj: Any) -> TypeIs[FlowCondition]:
+    """Check if the object matches the FlowCondition structure."""
+    if not isinstance(obj, dict):
+        return False
+
+    type_value = obj.get("type")
+    if type_value not in ("AND", "OR"):
+        return False
+
+    if "conditions" in obj:
+        conditions = obj["conditions"]
+        if not _is_non_string_sequence(conditions):
+            return False
+        for cond in conditions:
+            if not (
+                isinstance(cond, str)
+                or (isinstance(cond, dict) and is_flow_condition_dict(cond))
+            ):
+                return False
+
+    if "methods" in obj:
+        methods = obj["methods"]
+        if not (
+            _is_non_string_sequence(methods)
+            and all(isinstance(m, str) for m in methods)
+        ):
+            return False
+
+    allowed_keys = {"type", "conditions", "methods"}
+    if not set(obj).issubset(allowed_keys):
+        return False
+
+    return True
+
+
+def _method_reference_name(value: Any) -> FlowMethodName | None:
+    name = getattr(value, "__name__", None)
+    if callable(value) and isinstance(name, str):
+        return FlowMethodName(name)
+    return None
+
+
+def _normalize_condition(
+    condition: FlowConditions | FlowCondition | str,
+) -> FlowCondition:
+    if isinstance(condition, str):
+        return {"type": OR_CONDITION, "conditions": [FlowMethodName(condition)]}
+    if is_flow_condition_dict(condition):
+        if "conditions" in condition:
+            return condition
+        if "methods" in condition:
+            normalized_methods: list[str | FlowMethodName | FlowCondition] = list(
+                condition["methods"]
+            )
+            return {"type": condition["type"], "conditions": normalized_methods}
+        return condition
+    if _is_non_string_sequence(condition) and all(
+        isinstance(item, str) or is_flow_condition_dict(item) for item in condition
+    ):
+        return {"type": OR_CONDITION, "conditions": condition}
+
+    raise ValueError(f"Cannot normalize condition: {condition}")
+
+
+def _extract_all_methods_recursive(
+    condition: str | FlowCondition | dict[str, Any] | list[Any],
+    flow: Any | None = None,
+) -> list[FlowMethodName]:
+    if isinstance(condition, str):
+        if flow is not None:
+            if condition in flow._methods:
+                return [FlowMethodName(condition)]
+            return []
+        return [FlowMethodName(condition)]
+    if is_flow_condition_dict(condition):
+        normalized = _normalize_condition(condition)
+        methods = []
+        for sub_cond in normalized.get("conditions", []):
+            methods.extend(_extract_all_methods_recursive(sub_cond, flow))
+        return methods
+    if isinstance(condition, list):
+        methods = []
+        for item in condition:
+            methods.extend(_extract_all_methods_recursive(item, flow))
+        return methods
+    return []
+
+
+def _extract_all_methods(
+    condition: str | FlowCondition | dict[str, Any] | list[Any],
+) -> list[FlowMethodName]:
+    if isinstance(condition, str):
+        return [FlowMethodName(condition)]
+    if is_flow_condition_dict(condition):
+        normalized = _normalize_condition(condition)
+        cond_type = normalized.get("type", OR_CONDITION)
+
+        if cond_type == AND_CONDITION:
+            return [
+                FlowMethodName(sub_cond)
+                for sub_cond in normalized.get("conditions", [])
+                if isinstance(sub_cond, str)
+            ]
+        return []
+    if isinstance(condition, list):
+        methods = []
+        for item in condition:
+            methods.extend(_extract_all_methods(item))
+        return methods
+    return []
+
+
+def _condition_trigger(condition: FlowTrigger) -> FlowMethodName | FlowCondition:
+    if isinstance(condition, str):
+        return FlowMethodName(condition)
+    if is_flow_condition_dict(condition):
+        return condition
+    method_name = _method_reference_name(condition)
+    if method_name is not None:
+        return method_name
+    raise ValueError("Invalid condition")
+
+
+def _condition_triggers(
+    conditions: Sequence[FlowTrigger],
+    error_message: str,
+) -> FlowConditions:
+    try:
+        return [_condition_trigger(condition) for condition in conditions]
+    except ValueError as exc:
+        raise ValueError(error_message) from exc
+
+
+def _definition_condition_from_runtime(condition: Any) -> FlowDefinitionCondition:
+    if isinstance(condition, str):
+        return str(condition)
+    method_name = _method_reference_name(condition)
+    if method_name is not None:
+        return str(method_name)
+    if is_flow_condition_dict(condition):
+        normalized = _normalize_condition(condition)
+        key = "and" if normalized.get("type") == AND_CONDITION else "or"
+        return {
+            key: [
+                _definition_condition_from_runtime(sub_condition)
+                for sub_condition in normalized.get("conditions", [])
+            ]
+        }
+    if isinstance(condition, list):
+        return {"or": [_definition_condition_from_runtime(item) for item in condition]}
+    return str(condition)
+
+
+def or_(*triggers: FlowTrigger) -> FlowCondition:
+    """Combine multiple triggers with OR logic for flow control.
+
+    Creates a condition that is satisfied when any of the specified triggers
+    are met. This is used with @start, @listen, or @router decorators to create
+    complex triggering conditions.
+
+    Args:
+        triggers: Route labels, method references, or existing conditions
+            returned by or_() / and_().
+
+    Returns:
+        A condition dictionary with format {"type": "OR", "conditions": list_of_triggers}.
+
+    Raises:
+        ValueError: If a trigger format is invalid.
+
+    Examples:
+        >>> @listen(or_("success", "timeout"))
+        >>> def handle_completion(self):
+        ...     pass
+
+        >>> @listen(or_(and_("step1", "step2"), "step3"))
+        >>> def handle_nested(self):
+        ...     pass
+    """
+    processed_triggers = _condition_triggers(triggers, "Invalid trigger in or_()")
+    return {"type": OR_CONDITION, "conditions": processed_triggers}
+
+
+def and_(*triggers: FlowTrigger) -> FlowCondition:
+    """Combine multiple triggers with AND logic for flow control.
+
+    Creates a condition that is satisfied only when all specified triggers
+    are met. This is used with @start, @listen, or @router decorators to create
+    complex triggering conditions.
+
+    Args:
+        triggers: Route labels, method references, or existing conditions
+            returned by or_() / and_().
+
+    Returns:
+        A condition dictionary with format {"type": "AND", "conditions": list_of_conditions}
+        where each condition can be a route label, method name, or nested condition.
+
+    Raises:
+        ValueError: If any trigger is invalid.
+
+    Examples:
+        >>> @listen(and_("validated", "processed"))
+        >>> def handle_complete_data(self):
+        ...     pass
+
+        >>> @listen(and_(or_("step1", "step2"), "step3"))
+        >>> def handle_nested(self):
+        ...     pass
+    """
+    processed_triggers = _condition_triggers(triggers, "Invalid trigger in and_()")
+    return {"type": AND_CONDITION, "conditions": processed_triggers}
+
+
+def _runtime_condition_from_definition(
+    condition: FlowDefinitionCondition,
+) -> FlowMethodName | FlowCondition:
+    if isinstance(condition, str):
+        return FlowMethodName(condition)
+    if is_flow_condition_dict(condition):
+        return condition
+
+    if "and" in condition:
+        return {
+            "type": AND_CONDITION,
+            "conditions": [
+                _runtime_condition_from_definition(item)
+                for item in condition.get("and", [])
+            ],
+        }
+    return {
+        "type": OR_CONDITION,
+        "conditions": [
+            _runtime_condition_from_definition(item) for item in condition.get("or", [])
+        ],
+    }
+
+
+def _runtime_listener_condition_from_definition(
+    condition: FlowDefinitionCondition,
+) -> SimpleFlowCondition | FlowCondition:
+    runtime_condition = _runtime_condition_from_definition(condition)
+    if isinstance(runtime_condition, str):
+        return (OR_CONDITION, [FlowMethodName(str(runtime_condition))])
+    return runtime_condition

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

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from typing import TYPE_CHECKING, Any, TypeVar
+
+from crewai.flow.flow_definition import FlowMethodDefinition
+from crewai.flow.human_feedback import (
+    HumanFeedbackConfig,
+    HumanFeedbackResult,
+    _build_human_feedback_runtime_decorator,
+)
+
+
+if TYPE_CHECKING:
+    from crewai.flow.async_feedback.types import HumanFeedbackProvider
+    from crewai.llms.base_llm import BaseLLM
+
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+__all__ = ["HumanFeedbackResult", "human_feedback"]
+
+
+def _stamp_human_feedback_metadata(
+    wrapper: Any,
+    func: Callable[..., Any],
+    config: HumanFeedbackConfig,
+) -> None:
+    for attr in [
+        "__is_start_method__",
+        "__trigger_methods__",
+        "__condition_type__",
+        "__trigger_condition__",
+        "__is_flow_method__",
+        "__flow_persistence_config__",
+        "__is_router__",
+        "__router_emit__",
+        "__flow_method_definition__",
+    ]:
+        if hasattr(func, attr):
+            setattr(wrapper, attr, getattr(func, attr))
+
+    wrapper.__human_feedback_config__ = config
+    wrapper.__is_flow_method__ = True
+
+    if config.emit:
+        wrapper.__is_router__ = True
+        wrapper.__router_emit__ = list(config.emit)
+        fragment = getattr(wrapper, "__flow_method_definition__", None)
+        if isinstance(fragment, FlowMethodDefinition):
+            wrapper.__flow_method_definition__ = fragment.model_copy(
+                update={"router": True, "emit": list(config.emit)}
+            )
+
+    wrapper._human_feedback_llm = config.llm
+
+
+def human_feedback(
+    message: str,
+    emit: Sequence[str] | None = None,
+    llm: str | BaseLLM | None = "gpt-4o-mini",
+    default_outcome: str | None = None,
+    metadata: dict[str, Any] | None = None,
+    provider: HumanFeedbackProvider | None = None,
+    learn: bool = False,
+    learn_source: str = "hitl",
+    learn_strict: bool = False,
+) -> Callable[[F], F]:
+    """Decorator for Flow methods that require human feedback."""
+    runtime_decorator = _build_human_feedback_runtime_decorator(
+        message=message,
+        emit=emit,
+        llm=llm,
+        default_outcome=default_outcome,
+        metadata=metadata,
+        provider=provider,
+        learn=learn,
+        learn_source=learn_source,
+        learn_strict=learn_strict,
+    )
+    config = HumanFeedbackConfig(
+        message=message,
+        emit=emit,
+        llm=llm,
+        default_outcome=default_outcome,
+        metadata=metadata,
+        provider=provider,
+        learn=learn,
+        learn_source=learn_source,
+        learn_strict=learn_strict,
+    )
+
+    def decorator(func: F) -> F:
+        wrapper = runtime_decorator(func)
+        _stamp_human_feedback_metadata(wrapper, func, config)
+        return wrapper
+
+    return decorator

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

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import cast
+
+from crewai.flow.dsl._conditions import _definition_condition_from_runtime
+from crewai.flow.dsl._types import FlowMethodDecorator, FlowTrigger
+from crewai.flow.dsl._utils import (
+    P,
+    R,
+    _set_flow_method_definition,
+    _set_trigger_metadata,
+)
+from crewai.flow.flow_definition import FlowMethodDefinition
+from crewai.flow.flow_wrappers import ListenMethod
+
+
+def listen(condition: FlowTrigger) -> FlowMethodDecorator:
+    """Creates a listener that executes when specified conditions are met.
+
+    This decorator sets up a method to execute in response to other method
+    executions in the flow. It supports both simple and complex triggering
+    conditions.
+
+    Args:
+        condition: Route label, method reference, or condition returned by
+            or_() / and_() that triggers the listener.
+
+    Returns:
+        A flow method decorator that preserves the decorated method's static signature.
+
+    Raises:
+        ValueError: If the condition format is invalid.
+
+    Examples:
+        >>> @listen("process_data")
+        >>> def handle_processed_data(self):
+        ...     pass
+
+        >>> @listen("method_name")
+        >>> def handle_completion(self):
+        ...     pass
+    """
+
+    def decorator(func: Callable[P, R]) -> ListenMethod[P, R]:
+        wrapper = ListenMethod(func)
+
+        _set_flow_method_definition(
+            wrapper,
+            FlowMethodDefinition(listen=_definition_condition_from_runtime(condition)),
+        )
+        _set_trigger_metadata(wrapper, condition)
+        return wrapper
+
+    return cast(FlowMethodDecorator, decorator)

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

@@ -0,0 +1,166 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from enum import Enum
+import inspect
+from types import UnionType
+from typing import (
+    Any,
+    Literal,
+    Union,
+    cast,
+    get_args,
+    get_origin,
+    get_type_hints,
+)
+
+from crewai.flow.dsl._conditions import _definition_condition_from_runtime
+from crewai.flow.dsl._types import FlowMethodDecorator, FlowTrigger
+from crewai.flow.dsl._utils import (
+    P,
+    R,
+    _set_flow_method_definition,
+    _set_trigger_metadata,
+)
+from crewai.flow.flow_definition import FlowMethodDefinition
+from crewai.flow.flow_wrappers import RouterMethod
+
+
+def _unwrap_function(function: Any) -> Any:
+    if hasattr(function, "__func__"):
+        function = function.__func__
+
+    if hasattr(function, "__wrapped__"):
+        wrapped = function.__wrapped__
+        if hasattr(wrapped, "unwrap"):
+            return wrapped.unwrap()
+        return wrapped
+
+    if hasattr(function, "unwrap"):
+        return function.unwrap()
+
+    return function
+
+
+def _string_values_from_annotation(annotation: Any) -> list[str]:
+    if annotation is inspect.Signature.empty or isinstance(annotation, str):
+        return []
+    if isinstance(annotation, type) and issubclass(annotation, Enum):
+        return [member.value for member in annotation if isinstance(member.value, str)]
+
+    origin = get_origin(annotation)
+    if origin is None:
+        return []
+
+    args = get_args(annotation)
+    if origin is Literal or getattr(origin, "__name__", "") == "Literal":
+        return [arg for arg in args if isinstance(arg, str)]
+
+    if not (
+        origin is Union
+        or origin is UnionType
+        or getattr(origin, "__name__", "") == "Annotated"
+    ):
+        return []
+
+    values: list[str] = []
+    for arg in args:
+        values.extend(_string_values_from_annotation(arg))
+    return values
+
+
+def _return_annotation(function: Any) -> Any:
+    unwrapped = _unwrap_function(function)
+
+    try:
+        return get_type_hints(unwrapped, include_extras=True).get(
+            "return", inspect.Signature.empty
+        )
+    except (NameError, TypeError, ValueError):
+        try:
+            return inspect.signature(unwrapped).return_annotation
+        except (TypeError, ValueError):
+            return inspect.Signature.empty
+
+
+def _get_router_return_events(function: Any) -> list[str] | None:
+    values = _string_values_from_annotation(_return_annotation(function))
+    return list(dict.fromkeys(values)) if values else None
+
+
+def _normalize_router_emit(value: Sequence[Any] | str) -> list[str]:
+    if isinstance(value, str):
+        return [str(value)]
+    return list(dict.fromkeys(str(item) for item in value))
+
+
+def router(
+    condition: FlowTrigger,
+    *,
+    emit: Sequence[str] | str | None = None,
+) -> FlowMethodDecorator:
+    """Creates a routing method that directs flow execution based on conditions.
+
+    This decorator marks a method as a router, which can dynamically determine
+    the next steps in the flow based on its return value. Routers are triggered
+    by specified conditions and can return constants that emit downstream events.
+
+    Args:
+        condition: Specifies when the router should execute. Can be:
+            - str: Route label or method name that triggers this router
+            - FlowCondition: Result from or_() or and_(), including nested conditions
+            - Flow method reference: A method whose completion triggers this router
+        emit: Optional explicit router output events for static FlowDefinition
+            and visualization. If omitted, Literal/Enum return annotations are
+            used when available.
+
+    Returns:
+        A flow method decorator that preserves the decorated method's static signature.
+
+    Raises:
+        ValueError: If the condition format is invalid.
+
+    Examples:
+        >>> @router("check_status")
+        >>> def route_based_on_status(self):
+        ...     if self.state.status == "success":
+        ...         return "SUCCESS"
+        ...     return "FAILURE"
+
+        >>> @router(and_("validate", "process"))
+        >>> def complex_routing(self):
+        ...     if all([self.state.valid, self.state.processed]):
+        ...         return "CONTINUE"
+        ...     return "STOP"
+
+        >>> @router("check_status", emit=["SUCCESS", "FAILURE"])
+        >>> def explicit_routing(self):
+        ...     return "SUCCESS"
+    """
+
+    def decorator(func: Callable[P, R]) -> RouterMethod[P, R]:
+        wrapper = RouterMethod(func)
+
+        if emit is not None:
+            router_events = _normalize_router_emit(emit)
+        else:
+            router_events = _get_router_return_events(func) or []
+
+        _set_flow_method_definition(
+            wrapper,
+            FlowMethodDefinition(
+                listen=_definition_condition_from_runtime(condition),
+                router=True,
+                emit=router_events or None,
+            ),
+        )
+
+        _set_trigger_metadata(wrapper, condition)
+
+        if emit is not None:
+            wrapper.__router_emit__ = router_events
+        elif router_events:
+            wrapper.__router_emit__ = router_events
+        return wrapper
+
+    return cast(FlowMethodDecorator, decorator)

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

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import cast
+
+from crewai.flow.dsl._conditions import _definition_condition_from_runtime
+from crewai.flow.dsl._types import FlowMethodDecorator, FlowTrigger
+from crewai.flow.dsl._utils import (
+    P,
+    R,
+    _set_flow_method_definition,
+    _set_trigger_metadata,
+)
+from crewai.flow.flow_definition import FlowMethodDefinition
+from crewai.flow.flow_wrappers import StartMethod
+
+
+def start(
+    condition: FlowTrigger | None = None,
+) -> FlowMethodDecorator:
+    """Marks a method as a flow's starting point.
+
+    This decorator designates a method as an entry point for the flow execution.
+    It can optionally specify conditions that trigger the start based on other
+    method executions.
+
+    Args:
+        condition: Defines when the start method should execute. Can be:
+            - str: Route label or method name that triggers this start
+            - FlowCondition: Result from or_() or and_(), including nested conditions
+            - Flow method reference: A method whose completion triggers this start
+            Default is None, meaning unconditional start.
+
+    Returns:
+        A flow method decorator that preserves the decorated method's static signature.
+
+    Raises:
+        ValueError: If the condition format is invalid.
+
+    Examples:
+        >>> @start()  # Unconditional start
+        >>> def begin_flow(self):
+        ...     pass
+
+        >>> @start("method_name")  # Start after specific method
+        >>> def conditional_start(self):
+        ...     pass
+
+        >>> @start(and_("method1", "method2"))  # Start after multiple methods
+        >>> def complex_start(self):
+        ...     pass
+    """
+
+    def decorator(func: Callable[P, R]) -> StartMethod[P, R]:
+        wrapper = StartMethod(func)
+
+        if condition is not None:
+            _set_flow_method_definition(
+                wrapper,
+                FlowMethodDefinition(
+                    start=_definition_condition_from_runtime(condition)
+                ),
+            )
+            _set_trigger_metadata(wrapper, condition)
+        else:
+            _set_flow_method_definition(wrapper, FlowMethodDefinition(start=True))
+        return wrapper
+
+    return cast(FlowMethodDecorator, decorator)

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

@@ -0,0 +1,27 @@
+"""Private typing helpers for the Python Flow DSL."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any, Protocol, TypeAlias, TypeVar
+
+from crewai.flow.flow_wrappers import FlowCondition
+from crewai.flow.types import FlowMethodCallable
+
+
+__all__ = ["FlowMethodDecorator", "FlowTrigger"]
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+FlowTrigger: TypeAlias = str | FlowMethodCallable[..., Any] | FlowCondition
+
+
+class FlowMethodDecorator(Protocol):
+    """Decorator returned by Flow DSL authoring helpers.
+
+    The runtime wraps methods in FlowMethod subclasses, but the authoring
+    contract preserves the decorated method's static callable type.
+    """
+
+    def __call__(self, func: F) -> F:
+        raise NotImplementedError

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

@@ -0,0 +1,529 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+import json
+import logging
+from typing import Any, ParamSpec, TypeVar
+
+from pydantic import BaseModel
+from typing_extensions import TypeIs
+
+from crewai.flow.constants import AND_CONDITION, OR_CONDITION
+from crewai.flow.dsl._conditions import (
+    _definition_condition_from_runtime,
+    _extract_all_methods,
+    _method_reference_name,
+    _runtime_listener_condition_from_definition,
+    is_flow_condition_dict,
+)
+from crewai.flow.dsl._types import FlowTrigger
+from crewai.flow.flow_definition import (
+    FlowConfigDefinition,
+    FlowDefinition,
+    FlowDefinitionCondition,
+    FlowDefinitionDiagnostic,
+    FlowHumanFeedbackDefinition,
+    FlowMethodDefinition,
+    FlowPersistenceDefinition,
+    FlowStateDefinition,
+)
+from crewai.flow.flow_wrappers import (
+    FlowMethod,
+    ListenMethod,
+    RouterMethod,
+    StartMethod,
+)
+from crewai.flow.types import FlowMethodName
+
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+logger = logging.getLogger(__name__)
+
+_FLOW_METHOD_DEFINITION_ATTR = "__flow_method_definition__"
+
+
+def is_flow_method(obj: Any) -> TypeIs[FlowMethod[Any, Any]]:
+    """Check if the object carries Flow method wrapper metadata."""
+    return (
+        hasattr(obj, "__is_flow_method__")
+        or hasattr(obj, "__is_start_method__")
+        or hasattr(obj, "__trigger_methods__")
+        or hasattr(obj, "__is_router__")
+        or hasattr(obj, _FLOW_METHOD_DEFINITION_ATTR)
+    )
+
+
+def _should_include_flow_method(flow_class: type, method: Any) -> bool:
+    if getattr(method, "__conversational_only__", False):
+        return bool(getattr(flow_class, "conversational", False))
+    return True
+
+
+def _flow_method_names(values: Sequence[Any]) -> list[FlowMethodName]:
+    return [FlowMethodName(str(value)) for value in values]
+
+
+def _set_trigger_metadata(
+    wrapper: StartMethod[P, R] | ListenMethod[P, R] | RouterMethod[P, R],
+    condition: FlowTrigger,
+) -> None:
+    if isinstance(condition, str):
+        wrapper.__trigger_methods__ = [FlowMethodName(condition)]
+        wrapper.__condition_type__ = OR_CONDITION
+        return
+
+    if is_flow_condition_dict(condition):
+        if "conditions" in condition:
+            wrapper.__trigger_condition__ = condition
+            wrapper.__trigger_methods__ = _extract_all_methods(condition)
+            wrapper.__condition_type__ = condition["type"]
+            return
+        if "methods" in condition:
+            wrapper.__trigger_methods__ = _flow_method_names(condition["methods"])
+            wrapper.__condition_type__ = condition["type"]
+            return
+        raise ValueError("Condition dict must contain 'conditions' or 'methods'")
+
+    method_name = _method_reference_name(condition)
+    if method_name is not None:
+        wrapper.__trigger_methods__ = [method_name]
+        wrapper.__condition_type__ = OR_CONDITION
+        return
+
+    raise ValueError(
+        "Condition must be a method, string, or a result of or_() or and_()"
+    )
+
+
+def _set_flow_method_definition(
+    wrapper: StartMethod[P, R] | ListenMethod[P, R] | RouterMethod[P, R],
+    definition: FlowMethodDefinition,
+) -> None:
+    setattr(wrapper, _FLOW_METHOD_DEFINITION_ATTR, definition)
+
+
+def _get_flow_method_definition(method: Any) -> FlowMethodDefinition | None:
+    definition = getattr(method, _FLOW_METHOD_DEFINITION_ATTR, None)
+    if isinstance(definition, FlowMethodDefinition):
+        return definition
+    if definition is not None:
+        return FlowMethodDefinition.model_validate(definition)
+    return None
+
+
+def _object_ref(value: Any) -> str:
+    target = value if isinstance(value, type) else type(value)
+    module = getattr(target, "__module__", "")
+    qualname = getattr(target, "__qualname__", getattr(target, "__name__", ""))
+    return f"{module}:{qualname}" if module and qualname else repr(value)
+
+
+def _is_json_serializable(value: Any) -> bool:
+    try:
+        json.dumps(value)
+    except (TypeError, ValueError):
+        return False
+    return True
+
+
+def _serialize_static_value(
+    value: Any,
+    diagnostics: list[FlowDefinitionDiagnostic],
+    path: str,
+) -> Any:
+    if value is None or _is_json_serializable(value):
+        return value
+
+    to_config = getattr(value, "to_config_dict", None)
+    if callable(to_config):
+        try:
+            config = to_config()
+            if _is_json_serializable(config):
+                return config
+        except Exception:
+            logger.debug(
+                "Failed to serialize %s via to_config_dict().",
+                path,
+                exc_info=True,
+            )
+
+    if isinstance(value, BaseModel):
+        try:
+            data = value.model_dump(mode="json")
+            if _is_json_serializable(data):
+                return data
+        except Exception:
+            logger.debug(
+                "Failed to serialize %s via Pydantic model_dump().",
+                path,
+                exc_info=True,
+            )
+
+    ref = _object_ref(value)
+    diagnostics.append(
+        FlowDefinitionDiagnostic(
+            code="non_serializable_value",
+            path=path,
+            message=f"value is not fully serializable; preserved import reference {ref}",
+        )
+    )
+    return {"ref": ref}
+
+
+def _state_ref(value: Any) -> str | None:
+    if value is None:
+        return None
+    target = value if isinstance(value, type) else type(value)
+    module = getattr(target, "__module__", None)
+    qualname = getattr(target, "__qualname__", None)
+    if module and qualname:
+        return f"{module}:{qualname}"
+    return None
+
+
+def _build_state_definition(
+    flow_class: type,
+    diagnostics: list[FlowDefinitionDiagnostic],
+) -> FlowStateDefinition | None:
+    from pydantic import BaseModel as PydanticBaseModel
+
+    state_value = getattr(flow_class, "_initial_state_t", None)
+    initial_state = getattr(flow_class, "initial_state", None)
+    if initial_state is not None:
+        state_value = initial_state
+
+    if state_value is None:
+        return None
+    if state_value is dict or isinstance(state_value, dict):
+        default = None
+        if isinstance(state_value, dict):
+            default = _serialize_static_value(state_value, diagnostics, "state.default")
+        return FlowStateDefinition(type="dict", default=default)
+    if isinstance(state_value, type) and issubclass(state_value, PydanticBaseModel):
+        return FlowStateDefinition(type="pydantic", ref=_state_ref(state_value))
+    if isinstance(state_value, PydanticBaseModel):
+        return FlowStateDefinition(
+            type="pydantic",
+            ref=_state_ref(state_value),
+            default=_serialize_static_value(state_value, diagnostics, "state.default"),
+        )
+    diagnostics.append(
+        FlowDefinitionDiagnostic(
+            code="unknown_state_type",
+            path="state",
+            message=f"could not serialize state type {_object_ref(state_value)}",
+        )
+    )
+    return FlowStateDefinition(type="unknown", ref=_state_ref(state_value))
+
+
+def _build_config_definition(
+    flow_class: type,
+    diagnostics: list[FlowDefinitionDiagnostic],
+) -> FlowConfigDefinition:
+    config_field_names = set(FlowConfigDefinition.model_fields)
+    field_defaults = {
+        name: field.default
+        for name, field in getattr(flow_class, "model_fields", {}).items()
+        if name in config_field_names
+    }
+    values: dict[str, Any] = {}
+    for field_name, default in field_defaults.items():
+        value = getattr(flow_class, field_name, default)
+        values[field_name] = _serialize_static_value(
+            value, diagnostics, f"config.{field_name}"
+        )
+    return FlowConfigDefinition(**values)
+
+
+def _condition_from_method_metadata(method: Any) -> FlowDefinitionCondition | None:
+    trigger_condition = getattr(method, "__trigger_condition__", None)
+    if trigger_condition is not None:
+        return _definition_condition_from_runtime(trigger_condition)
+
+    trigger_methods = getattr(method, "__trigger_methods__", None)
+    if trigger_methods is None:
+        return None
+    condition_type = getattr(method, "__condition_type__", OR_CONDITION)
+    method_names = [str(method_name) for method_name in trigger_methods]
+    if condition_type == AND_CONDITION:
+        return {"and": method_names}
+    if len(method_names) == 1:
+        return method_names[0]
+    return {"or": method_names}
+
+
+def _flow_method_definition_from_legacy_metadata(method: Any) -> FlowMethodDefinition:
+    is_start = bool(getattr(method, "__is_start_method__", False))
+    is_router = bool(getattr(method, "__is_router__", False))
+    condition = _condition_from_method_metadata(method)
+
+    if not is_start:
+        start_value: bool | FlowDefinitionCondition | None = None
+    elif condition is not None:
+        start_value = condition
+    else:
+        start_value = True
+
+    definition = FlowMethodDefinition(
+        start=start_value,
+        listen=condition if not is_start else None,
+        router=is_router,
+    )
+
+    router_emit = getattr(method, "__router_emit__", None)
+    if router_emit:
+        definition.emit = [str(value) for value in router_emit]
+    return definition
+
+
+def _definition_trigger_condition(
+    method_definition: FlowMethodDefinition,
+) -> FlowDefinitionCondition | None:
+    if method_definition.listen is not None:
+        return method_definition.listen
+    if isinstance(method_definition.start, (str, dict)):
+        return method_definition.start
+    return None
+
+
+def _build_human_feedback_definition(
+    method: Any,
+    diagnostics: list[FlowDefinitionDiagnostic],
+    path: str,
+) -> FlowHumanFeedbackDefinition | None:
+    config = getattr(method, "__human_feedback_config__", None)
+    if config is None:
+        return None
+    emit = getattr(config, "emit", None)
+    return FlowHumanFeedbackDefinition(
+        message=str(config.message),
+        emit=[str(value) for value in emit] if emit is not None else None,
+        llm=_serialize_static_value(
+            getattr(config, "llm", None), diagnostics, f"{path}.llm"
+        ),
+        default_outcome=getattr(config, "default_outcome", None),
+        metadata=_serialize_static_value(
+            getattr(config, "metadata", None), diagnostics, f"{path}.metadata"
+        ),
+        provider=_serialize_static_value(
+            getattr(config, "provider", None), diagnostics, f"{path}.provider"
+        ),
+        learn=bool(getattr(config, "learn", False)),
+        learn_source=str(getattr(config, "learn_source", "hitl")),
+        learn_strict=bool(getattr(config, "learn_strict", False)),
+    )
+
+
+def _build_persistence_definition(
+    value: Any,
+    diagnostics: list[FlowDefinitionDiagnostic],
+    path: str,
+) -> FlowPersistenceDefinition | None:
+    config = getattr(value, "__flow_persistence_config__", None)
+    if config is None:
+        return None
+    persistence = getattr(config, "persistence", None)
+    verbose = bool(getattr(config, "verbose", False))
+    return FlowPersistenceDefinition(
+        enabled=True,
+        verbose=verbose,
+        persistence=_serialize_static_value(
+            persistence, diagnostics, f"{path}.persistence"
+        ),
+    )
+
+
+def _build_method_definition(
+    method: Any,
+    diagnostics: list[FlowDefinitionDiagnostic],
+    path: str,
+) -> FlowMethodDefinition:
+    fragment = _get_flow_method_definition(method)
+    if fragment is None:
+        method_definition = _flow_method_definition_from_legacy_metadata(method)
+    else:
+        method_definition = fragment.model_copy(deep=True)
+
+    if bool(getattr(method, "__is_router__", False)):
+        method_definition.router = True
+
+    human_feedback = _build_human_feedback_definition(
+        method, diagnostics, f"{path}.human_feedback"
+    )
+    if human_feedback is not None:
+        method_definition.human_feedback = human_feedback
+        if human_feedback.emit:
+            method_definition.router = True
+            method_definition.emit = None
+
+    method_definition.persist = _build_persistence_definition(
+        method, diagnostics, f"{path}.persist"
+    )
+
+    router_emit = getattr(method, "__router_emit__", None)
+    if router_emit and not (human_feedback and human_feedback.emit):
+        if not method_definition.emit:
+            method_definition.emit = [str(value) for value in router_emit]
+
+    return method_definition
+
+
+def _iter_flow_methods(flow_class: type) -> dict[str, Any]:
+    methods: dict[str, Any] = {}
+    for attr_name in dir(flow_class):
+        if attr_name.startswith("_"):
+            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
+    # function is preserved as the field default. Recover those so the
+    # definition still reflects every method once the class is built.
+    for field_name, field in getattr(flow_class, "model_fields", {}).items():
+        if field_name in methods or field_name.startswith("_"):
+            continue
+        default = getattr(field, "default", None)
+        if is_flow_method(default) and _should_include_flow_method(flow_class, default):
+            methods[field_name] = default
+    return methods
+
+
+def _build_flow_definition_from_class(
+    flow_class: type,
+    namespace: dict[str, Any] | None = None,
+) -> FlowDefinition:
+    diagnostics: list[FlowDefinitionDiagnostic] = []
+    methods: dict[str, FlowMethodDefinition] = {}
+    flow_methods = _iter_flow_methods(flow_class)
+    if namespace is not None:
+        for attr_name, attr_value in namespace.items():
+            if is_flow_method(attr_value) and _should_include_flow_method(
+                flow_class, attr_value
+            ):
+                flow_methods[attr_name] = attr_value
+
+    for method_name, method in flow_methods.items():
+        methods[method_name] = _build_method_definition(
+            method, diagnostics, f"methods.{method_name}"
+        )
+
+    description = None
+    docstring = flow_class.__doc__
+    if docstring:
+        description = docstring.strip()
+
+    definition = FlowDefinition(
+        name=getattr(flow_class, "__name__", "Flow"),
+        description=description,
+        state=_build_state_definition(flow_class, diagnostics),
+        config=_build_config_definition(flow_class, diagnostics),
+        persist=_build_persistence_definition(flow_class, diagnostics, "persist"),
+        methods=methods,
+        diagnostics=diagnostics,
+    )
+    definition.diagnostics.extend(definition.validate_contract())
+    definition.log_diagnostics()
+    return definition
+
+
+def build_flow_definition(
+    flow_class: type,
+    namespace: dict[str, Any] | None = None,
+) -> FlowDefinition:
+    """Build a FlowDefinition from a Python Flow class."""
+    return _build_flow_definition_from_class(flow_class, namespace)
+
+
+def extract_flow_definition(
+    namespace: dict[str, Any],
+) -> tuple[list[str], dict[str, Any], set[str], dict[str, Any]]:
+    """Extract the structural flow registries from a Python class namespace."""
+    start_methods = []
+    listeners = {}
+    router_emit = {}
+    routers = set()
+
+    for attr_name, attr_value in namespace.items():
+        if is_flow_method(attr_value):
+            method_definition = _get_flow_method_definition(attr_value)
+            if method_definition is not None:
+                if method_definition.is_start:
+                    start_methods.append(attr_name)
+
+                condition = _definition_trigger_condition(method_definition)
+                if condition is not None:
+                    listeners[attr_name] = _runtime_listener_condition_from_definition(
+                        condition
+                    )
+
+                is_router = method_definition.router or bool(
+                    getattr(attr_value, "__is_router__", False)
+                )
+                if is_router:
+                    routers.add(attr_name)
+                    if method_definition.emit:
+                        router_emit[attr_name] = [
+                            str(value) for value in method_definition.emit
+                        ]
+                    elif (
+                        hasattr(attr_value, "__router_emit__")
+                        and attr_value.__router_emit__
+                    ):
+                        router_emit[attr_name] = attr_value.__router_emit__
+                    else:
+                        router_emit[attr_name] = []
+                continue
+
+            if hasattr(attr_value, "__is_start_method__"):
+                start_methods.append(attr_name)
+
+            if (
+                hasattr(attr_value, "__trigger_methods__")
+                and attr_value.__trigger_methods__ is not None
+            ):
+                methods = attr_value.__trigger_methods__
+                condition_type = getattr(attr_value, "__condition_type__", OR_CONDITION)
+
+                if (
+                    hasattr(attr_value, "__trigger_condition__")
+                    and attr_value.__trigger_condition__ is not None
+                ):
+                    listeners[attr_name] = attr_value.__trigger_condition__
+                else:
+                    listeners[attr_name] = (condition_type, methods)
+
+                if hasattr(attr_value, "__is_router__") and attr_value.__is_router__:
+                    routers.add(attr_name)
+                    if (
+                        hasattr(attr_value, "__router_emit__")
+                        and attr_value.__router_emit__
+                    ):
+                        router_emit[attr_name] = attr_value.__router_emit__
+                    else:
+                        router_emit[attr_name] = []
+
+            if (
+                hasattr(attr_value, "__is_start_method__")
+                and hasattr(attr_value, "__is_router__")
+                and attr_value.__is_router__
+            ):
+                routers.add(attr_name)
+                if (
+                    hasattr(attr_value, "__router_emit__")
+                    and attr_value.__router_emit__
+                ):
+                    router_emit[attr_name] = attr_value.__router_emit__
+                else:
+                    router_emit[attr_name] = []
+
+    return start_methods, listeners, routers, router_emit

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

@@ -3,8 +3,8 @@
 The implementation now lives in three modules, split by concern:
 
 - ``crewai.flow.dsl`` -- authoring decorators (``@start`` / ``@listen`` /
-  ``@router``, ``or_`` / ``and_``)
-- ``crewai.flow.flow_definition`` -- the structural model extracted from the DSL
+  ``@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
 
 Prefer importing from those modules in new code; this module preserves the

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

@@ -18,3 +18,7 @@ current_flow_id: contextvars.ContextVar[str | None] = contextvars.ContextVar(
 current_flow_method_name: contextvars.ContextVar[str] = contextvars.ContextVar(
     "flow_method_name", default="unknown"
 )
+
+current_flow_name: contextvars.ContextVar[str | None] = contextvars.ContextVar(
+    "flow_name", default=None
+)

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

@@ -1,592 +0,0 @@
-"""Flow structure serializer for introspecting Flow classes.
-
-This module provides the flow_structure() function that analyzes a Flow class
-and returns a JSON-serializable dictionary describing its graph structure.
-This is used by Studio UI to render a visual flow graph.
-
-Example:
-    >>> from crewai.flow import Flow, start, listen
-    >>> from crewai.flow.flow_serializer import flow_structure
-    >>>
-    >>> class MyFlow(Flow):
-    ...     @start()
-    ...     def begin(self):
-    ...         return "started"
-    ...
-    ...     @listen(begin)
-    ...     def process(self):
-    ...         return "done"
-    >>>
-    >>> structure = flow_structure(MyFlow)
-    >>> print(structure["name"])
-    'MyFlow'
-"""
-
-from __future__ import annotations
-
-import inspect
-import logging
-import re
-import textwrap
-from typing import Any, TypedDict, get_args, get_origin
-
-from pydantic import BaseModel
-from pydantic_core import PydanticUndefined
-
-from crewai.flow.flow_wrappers import (
-    FlowCondition,
-    FlowMethod,
-    ListenMethod,
-    RouterMethod,
-    StartMethod,
-)
-
-
-logger = logging.getLogger(__name__)
-
-
-class MethodInfo(TypedDict, total=False):
-    """Information about a single flow method.
-
-    Attributes:
-        name: The method name.
-        type: Method type - start, listen, router, or start_router.
-        trigger_methods: List of method names that trigger this method.
-        condition_type: 'AND' or 'OR' for composite conditions, null otherwise.
-        router_paths: For routers, the possible route names returned.
-        has_human_feedback: Whether the method has @human_feedback decorator.
-        has_crew: Whether the method body references a Crew.
-    """
-
-    name: str
-    type: str
-    trigger_methods: list[str]
-    condition_type: str | None
-    router_paths: list[str]
-    has_human_feedback: bool
-    has_crew: bool
-
-
-class EdgeInfo(TypedDict, total=False):
-    """Information about an edge between flow methods.
-
-    Attributes:
-        from_method: Source method name.
-        to_method: Target method name.
-        edge_type: Type of edge - 'listen' or 'route'.
-        condition: Route name for router edges, null for listen edges.
-    """
-
-    from_method: str
-    to_method: str
-    edge_type: str
-    condition: str | None
-
-
-class StateFieldInfo(TypedDict, total=False):
-    """Information about a state field.
-
-    Attributes:
-        name: Field name.
-        type: Field type as string.
-        default: Default value if any.
-    """
-
-    name: str
-    type: str
-    default: Any
-
-
-class StateSchemaInfo(TypedDict, total=False):
-    """Information about the flow's state schema.
-
-    Attributes:
-        fields: List of field information.
-    """
-
-    fields: list[StateFieldInfo]
-
-
-class FlowStructureInfo(TypedDict, total=False):
-    """Complete flow structure information.
-
-    Attributes:
-        name: Flow class name.
-        description: Flow docstring if available.
-        methods: List of method information.
-        edges: List of edge information.
-        state_schema: State schema if typed, null otherwise.
-        inputs: Detected flow inputs if available.
-    """
-
-    name: str
-    description: str | None
-    methods: list[MethodInfo]
-    edges: list[EdgeInfo]
-    state_schema: StateSchemaInfo | None
-    inputs: list[str]
-
-
-def _get_method_type(
-    method_name: str,
-    method: Any,
-    start_methods: list[str],
-    routers: set[str],
-) -> str:
-    """Determine the type of a flow method.
-
-    Args:
-        method_name: Name of the method.
-        method: The method object.
-        start_methods: List of start method names.
-        routers: Set of router method names.
-
-    Returns:
-        One of: 'start', 'listen', 'router', or 'start_router'.
-    """
-    is_start = method_name in start_methods or getattr(
-        method, "__is_start_method__", False
-    )
-    is_router = method_name in routers or getattr(method, "__is_router__", False)
-
-    if is_start and is_router:
-        return "start_router"
-    if is_start:
-        return "start"
-    if is_router:
-        return "router"
-    return "listen"
-
-
-def _has_human_feedback(method: Any) -> bool:
-    """Check if a method has the @human_feedback decorator.
-
-    Args:
-        method: The method object to check.
-
-    Returns:
-        True if the method has __human_feedback_config__ attribute.
-    """
-    return hasattr(method, "__human_feedback_config__")
-
-
-def _detect_crew_reference(method: Any) -> bool:
-    """Detect if a method body references a Crew.
-
-    Checks for patterns like:
-    - .crew() method calls
-    - Crew( instantiation
-    - References to Crew class in type hints
-
-    Note:
-        This is a **best-effort heuristic for UI hints**, not a guarantee.
-        Uses inspect.getsource + regex which can false-positive on comments
-        or string literals, and may fail on dynamically generated methods
-        or lambdas. Do not rely on this for correctness-critical logic.
-
-    Args:
-        method: The method object to inspect.
-
-    Returns:
-        True if crew reference detected, False otherwise.
-    """
-    try:
-        func = method
-        if hasattr(method, "_meth"):
-            func = method._meth
-        elif hasattr(method, "__wrapped__"):
-            func = method.__wrapped__
-
-        source = inspect.getsource(func)
-        source = textwrap.dedent(source)
-
-        crew_patterns = [
-            r"\.crew\(\)",  # .crew() method call
-            r"Crew\s*\(",  # Crew( instantiation
-            r":\s*Crew\b",  # Type hint with Crew
-            r"->.*Crew",  # Return type hint with Crew
-        ]
-
-        for pattern in crew_patterns:
-            if re.search(pattern, source):
-                return True
-
-        return False
-    except (OSError, TypeError):
-        return False
-
-
-def _extract_trigger_methods(method: Any) -> tuple[list[str], str | None]:
-    """Extract trigger methods and condition type from a method.
-
-    Args:
-        method: The method object to inspect.
-
-    Returns:
-        Tuple of (trigger_methods list, condition_type or None).
-    """
-    trigger_methods: list[str] = []
-    condition_type: str | None = None
-
-    if hasattr(method, "__trigger_methods__") and method.__trigger_methods__:
-        trigger_methods = [str(m) for m in method.__trigger_methods__]
-
-    # For complex conditions (or_/and_ combinators), extract from __trigger_condition__
-    if (
-        not trigger_methods
-        and hasattr(method, "__trigger_condition__")
-        and method.__trigger_condition__
-    ):
-        trigger_condition = method.__trigger_condition__
-        trigger_methods = _extract_all_methods_from_condition(trigger_condition)
-
-    if hasattr(method, "__condition_type__") and method.__condition_type__:
-        condition_type = str(method.__condition_type__)
-
-    return trigger_methods, condition_type
-
-
-def _extract_router_paths(
-    method: Any, router_paths_registry: dict[str, list[str]]
-) -> list[str]:
-    """Extract router paths for a router method.
-
-    Args:
-        method: The method object.
-        router_paths_registry: The class-level _router_paths dict.
-
-    Returns:
-        List of possible route names.
-    """
-    method_name = getattr(method, "__name__", "")
-
-    if hasattr(method, "__router_paths__") and method.__router_paths__:
-        return [str(p) for p in method.__router_paths__]
-
-    if method_name in router_paths_registry:
-        return [str(p) for p in router_paths_registry[method_name]]
-
-    return []
-
-
-def _extract_all_methods_from_condition(
-    condition: str | FlowCondition | dict[str, Any] | list[Any],
-) -> list[str]:
-    """Extract all method names from a condition tree recursively.
-
-    Args:
-        condition: Can be a string, FlowCondition tuple, dict, or list.
-
-    Returns:
-        List of all method names found in the condition.
-    """
-    if isinstance(condition, str):
-        return [condition]
-    if isinstance(condition, tuple) and len(condition) == 2:
-        # FlowCondition: (condition_type, methods_list)
-        _, methods = condition
-        if isinstance(methods, list):
-            result: list[str] = []
-            for m in methods:
-                result.extend(_extract_all_methods_from_condition(m))
-            return result
-        return []
-    if isinstance(condition, dict):
-        conditions_list = condition.get("conditions", [])
-        dict_methods: list[str] = []
-        for sub_cond in conditions_list:
-            dict_methods.extend(_extract_all_methods_from_condition(sub_cond))
-        return dict_methods
-    if isinstance(condition, list):
-        list_methods: list[str] = []
-        for item in condition:
-            list_methods.extend(_extract_all_methods_from_condition(item))
-        return list_methods
-    return []
-
-
-def _generate_edges(
-    listeners: dict[str, tuple[str, list[str]] | FlowCondition],
-    routers: set[str],
-    router_paths: dict[str, list[str]],
-    all_methods: set[str],
-) -> list[EdgeInfo]:
-    """Generate edges from listeners and routers.
-
-    Args:
-        listeners: Map of listener_name -> (condition_type, trigger_methods) or FlowCondition.
-        routers: Set of router method names.
-        router_paths: Map of router_name -> possible return values.
-        all_methods: Set of all method names in the flow.
-
-    Returns:
-        List of EdgeInfo dictionaries.
-    """
-    edges: list[EdgeInfo] = []
-
-    for listener_name, condition_data in listeners.items():
-        trigger_methods: list[str] = []
-
-        if isinstance(condition_data, tuple) and len(condition_data) == 2:
-            _condition_type, methods = condition_data
-            trigger_methods = [str(m) for m in methods]
-        elif isinstance(condition_data, dict):
-            trigger_methods = _extract_all_methods_from_condition(condition_data)
-
-        edges.extend(
-            EdgeInfo(
-                from_method=trigger,
-                to_method=listener_name,
-                edge_type="listen",
-                condition=None,
-            )
-            for trigger in trigger_methods
-            if trigger in all_methods
-        )
-
-    for router_name, paths in router_paths.items():
-        for path in paths:
-            for listener_name, condition_data in listeners.items():
-                path_triggers: list[str] = []
-
-                if isinstance(condition_data, tuple) and len(condition_data) == 2:
-                    _, methods = condition_data
-                    path_triggers = [str(m) for m in methods]
-                elif isinstance(condition_data, dict):
-                    path_triggers = _extract_all_methods_from_condition(condition_data)
-
-                if str(path) in path_triggers:
-                    edges.append(
-                        EdgeInfo(
-                            from_method=router_name,
-                            to_method=listener_name,
-                            edge_type="route",
-                            condition=str(path),
-                        )
-                    )
-
-    return edges
-
-
-def _extract_state_schema(flow_class: type) -> StateSchemaInfo | None:
-    """Extract state schema from a Flow class.
-
-    Checks for:
-    - Generic type parameter (Flow[MyState])
-    - initial_state class attribute
-
-    Args:
-        flow_class: The Flow class to inspect.
-
-    Returns:
-        StateSchemaInfo if a Pydantic model state is detected, None otherwise.
-    """
-    state_type: type | None = None
-
-    # _initial_state_t is set by Flow.__class_getitem__
-    if hasattr(flow_class, "_initial_state_t"):
-        state_type = flow_class._initial_state_t
-
-    if state_type is None and hasattr(flow_class, "initial_state"):
-        initial_state = flow_class.initial_state
-        if isinstance(initial_state, type) and issubclass(initial_state, BaseModel):
-            state_type = initial_state
-        elif isinstance(initial_state, BaseModel):
-            state_type = type(initial_state)
-
-    if state_type is None and hasattr(flow_class, "__orig_bases__"):
-        for base in flow_class.__orig_bases__:
-            origin = get_origin(base)
-            if origin is not None:
-                args = get_args(base)
-                if args:
-                    candidate = args[0]
-                    if isinstance(candidate, type) and issubclass(candidate, BaseModel):
-                        state_type = candidate
-                        break
-
-    if state_type is None or not issubclass(state_type, BaseModel):
-        return None
-
-    fields: list[StateFieldInfo] = []
-    try:
-        model_fields = state_type.model_fields
-        for field_name, field_info in model_fields.items():
-            field_type_str = "Any"
-            if field_info.annotation is not None:
-                field_type_str = str(field_info.annotation)
-                field_type_str = field_type_str.replace("typing.", "")
-                field_type_str = field_type_str.replace("<class '", "").replace(
-                    "'>", ""
-                )
-
-            default_value = None
-            if (
-                field_info.default is not PydanticUndefined
-                and field_info.default is not None
-                and not callable(field_info.default)
-            ):
-                try:
-                    default_value = field_info.default
-                except Exception:
-                    default_value = str(field_info.default)
-
-            fields.append(
-                StateFieldInfo(
-                    name=field_name,
-                    type=field_type_str,
-                    default=default_value,
-                )
-            )
-    except Exception:
-        logger.debug(
-            "Failed to extract state schema fields for %s", flow_class.__name__
-        )
-
-    return StateSchemaInfo(fields=fields) if fields else None
-
-
-def _detect_flow_inputs(flow_class: type) -> list[str]:
-    """Detect flow input parameters.
-
-    Inspects the __init__ signature for custom parameters beyond standard Flow params.
-
-    Args:
-        flow_class: The Flow class to inspect.
-
-    Returns:
-        List of detected input names.
-    """
-    inputs: list[str] = []
-
-    try:
-        init_method = flow_class.__init__  # type: ignore[misc]
-        init_sig = inspect.signature(init_method)
-        standard_params = {
-            "self",
-            "persistence",
-            "tracing",
-            "suppress_flow_events",
-            "max_method_calls",
-            "kwargs",
-        }
-        inputs.extend(
-            param_name
-            for param_name in init_sig.parameters
-            if param_name not in standard_params and not param_name.startswith("_")
-        )
-    except Exception:
-        logger.debug(
-            "Failed to detect inputs from __init__ for %s", flow_class.__name__
-        )
-
-    return inputs
-
-
-def flow_structure(flow_class: type) -> FlowStructureInfo:
-    """Introspect a Flow class and return its structure as a JSON-serializable dict.
-
-    This function analyzes a Flow CLASS (not instance) and returns complete
-    information about its graph structure including methods, edges, and state.
-
-    Args:
-        flow_class: A Flow class (not an instance) to introspect.
-
-    Returns:
-        FlowStructureInfo dictionary containing:
-        - name: Flow class name
-        - description: Docstring if available
-        - methods: List of method info dicts
-        - edges: List of edge info dicts
-        - state_schema: State schema if typed, None otherwise
-        - inputs: Detected input names
-
-    Raises:
-        TypeError: If flow_class is not a class.
-
-    Example:
-        >>> structure = flow_structure(MyFlow)
-        >>> print(structure["name"])
-        'MyFlow'
-        >>> for method in structure["methods"]:
-        ...     print(method["name"], method["type"])
-    """
-    if not isinstance(flow_class, type):
-        raise TypeError(
-            f"flow_structure requires a Flow class, not an instance. "
-            f"Got {type(flow_class).__name__}"
-        )
-
-    start_methods: list[str] = getattr(flow_class, "_start_methods", [])
-    listeners: dict[str, Any] = getattr(flow_class, "_listeners", {})
-    routers: set[str] = getattr(flow_class, "_routers", set())
-    router_paths_registry: dict[str, list[str]] = getattr(
-        flow_class, "_router_paths", {}
-    )
-
-    methods: list[MethodInfo] = []
-    all_method_names: set[str] = set()
-
-    for attr_name in dir(flow_class):
-        if attr_name.startswith("_"):
-            continue
-
-        try:
-            attr = getattr(flow_class, attr_name)
-        except AttributeError:
-            continue
-
-        is_flow_method = (
-            isinstance(attr, (FlowMethod, StartMethod, ListenMethod, RouterMethod))
-            or hasattr(attr, "__is_flow_method__")
-            or hasattr(attr, "__is_start_method__")
-            or hasattr(attr, "__trigger_methods__")
-            or hasattr(attr, "__is_router__")
-        )
-
-        if not is_flow_method:
-            continue
-
-        all_method_names.add(attr_name)
-
-        method_type = _get_method_type(attr_name, attr, start_methods, routers)
-
-        trigger_methods, condition_type = _extract_trigger_methods(attr)
-
-        router_paths_list: list[str] = []
-        if method_type in ("router", "start_router"):
-            router_paths_list = _extract_router_paths(attr, router_paths_registry)
-
-        has_hf = _has_human_feedback(attr)
-
-        has_crew = _detect_crew_reference(attr)
-
-        method_info = MethodInfo(
-            name=attr_name,
-            type=method_type,
-            trigger_methods=trigger_methods,
-            condition_type=condition_type,
-            router_paths=router_paths_list,
-            has_human_feedback=has_hf,
-            has_crew=has_crew,
-        )
-        methods.append(method_info)
-
-    edges = _generate_edges(listeners, routers, router_paths_registry, all_method_names)
-
-    state_schema = _extract_state_schema(flow_class)
-
-    inputs = _detect_flow_inputs(flow_class)
-
-    description: str | None = None
-    if flow_class.__doc__:
-        description = flow_class.__doc__.strip()
-
-    return FlowStructureInfo(
-        name=flow_class.__name__,
-        description=description,
-        methods=methods,
-        edges=edges,
-        state_schema=state_schema,
-        inputs=inputs,
-    )

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

@@ -18,6 +18,17 @@ R = TypeVar("R")
 FlowConditionType: TypeAlias = Literal["OR", "AND"]
 SimpleFlowCondition: TypeAlias = tuple[FlowConditionType, list[FlowMethodName]]
 
+__all__ = [
+    "FlowCondition",
+    "FlowConditionType",
+    "FlowConditions",
+    "FlowMethod",
+    "ListenMethod",
+    "RouterMethod",
+    "SimpleFlowCondition",
+    "StartMethod",
+]
+
 
 class FlowCondition(TypedDict, total=False):
     """Type definition for flow trigger conditions.
@@ -26,16 +37,16 @@ class FlowCondition(TypedDict, total=False):
 
     Attributes:
         type: The type of the condition.
-        conditions: A list of conditions types.
-        methods: A list of methods.
+        conditions: A sequence of route labels, method names, or nested conditions.
+        methods: A legacy sequence of route labels or method names.
     """
 
     type: Required[FlowConditionType]
-    conditions: Sequence[FlowMethodName | FlowCondition]
-    methods: list[FlowMethodName]
+    conditions: Sequence[str | FlowMethodName | FlowCondition]
+    methods: Sequence[str | FlowMethodName]
 
 
-FlowConditions: TypeAlias = list[FlowMethodName | FlowCondition]
+FlowConditions: TypeAlias = Sequence[str | FlowMethodName | FlowCondition]
 
 
 class FlowMethod(Generic[P, R]):
@@ -73,9 +84,12 @@ class FlowMethod(Generic[P, R]):
         # Preserve flow-related attributes from wrapped method (e.g., from @human_feedback)
         for attr in [
             "__is_router__",
-            "__router_paths__",
+            "__router_emit__",
             "__human_feedback_config__",
-            "_hf_llm",  # Live LLM object for HITL resume
+            "__conversational_only__",  # gates registration on Flow.conversational
+            "__flow_persistence_config__",
+            "__flow_method_definition__",
+            "_human_feedback_llm",  # Live LLM object for HITL resume
         ]:
             if hasattr(meth, attr):
                 setattr(self, attr, getattr(meth, attr))
@@ -165,3 +179,4 @@ class RouterMethod(FlowMethod[P, R]):
     __trigger_methods__: list[FlowMethodName] | None = None
     __condition_type__: FlowConditionType | None = None
     __trigger_condition__: FlowCondition | None = None
+    __router_emit__: list[str] | None = None

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

@@ -78,14 +78,10 @@ logger = logging.getLogger(__name__)
 
 F = TypeVar("F", bound=Callable[..., Any])
 
+__all__ = ["HumanFeedbackResult", "human_feedback"]
+
 
 def _serialize_llm_for_context(llm: Any) -> dict[str, Any] | str | None:
-    """Serialize a BaseLLM object to a dict preserving full config.
-
-    Delegates to ``llm.to_config_dict()`` when available (BaseLLM and
-    subclasses). Falls back to extracting the model string with provider
-    prefix for unknown LLM types.
-    """
     to_config: Callable[[], dict[str, Any]] | None = getattr(
         llm, "to_config_dict", None
     )
@@ -103,13 +99,6 @@ def _serialize_llm_for_context(llm: Any) -> dict[str, Any] | str | None:
 def _deserialize_llm_from_context(
     llm_data: dict[str, Any] | str | None,
 ) -> BaseLLM | None:
-    """Reconstruct an LLM instance from serialized context data.
-
-    Handles both the new dict format (with full config) and the legacy
-    string format (model name only) for backward compatibility.
-
-    Returns a BaseLLM instance, or None if llm_data is None.
-    """
     if llm_data is None:
         return None
 
@@ -202,12 +191,12 @@ class HumanFeedbackMethod(FlowMethod[Any, Any]):
 
     Attributes:
         __is_router__: True when emit is specified, enabling router behavior.
-        __router_paths__: List of possible outcomes when acting as a router.
+        __router_emit__: List of possible outcomes when acting as a router.
         __human_feedback_config__: The HumanFeedbackConfig for this method.
     """
 
     __is_router__: bool = False
-    __router_paths__: list[str] | None = None
+    __router_emit__: list[str] | None = None
     __human_feedback_config__: HumanFeedbackConfig | None = None
 
 
@@ -232,7 +221,7 @@ class DistilledLessons(BaseModel):
     )
 
 
-def human_feedback(
+def _build_human_feedback_runtime_decorator(
     message: str,
     emit: Sequence[str] | None = None,
     llm: str | BaseLLM | None = "gpt-4o-mini",
@@ -243,102 +232,6 @@ def human_feedback(
     learn_source: str = "hitl",
     learn_strict: bool = False,
 ) -> Callable[[F], F]:
-    """Decorator for Flow methods that require human feedback.
-
-    This decorator wraps a Flow method to:
-    1. Execute the method and capture its output
-    2. Display the output to the human with a feedback request
-    3. Collect the human's free-form feedback
-    4. Optionally collapse the feedback to a predefined outcome using an LLM
-    5. Store the result for access by downstream methods
-
-    When `emit` is specified, the decorator acts as a router, and the
-    collapsed outcome triggers the appropriate @listen decorated method.
-
-    Supports both synchronous (blocking) and asynchronous (non-blocking)
-    feedback collection through the `provider` parameter. If no provider
-    is specified, defaults to synchronous console input.
-
-    Args:
-        message: The message shown to the human when requesting feedback.
-            This should clearly explain what kind of feedback is expected.
-        emit: Optional sequence of outcome strings. When provided, the
-            human's feedback will be collapsed to one of these outcomes
-            using the specified LLM. The outcome then triggers @listen
-            methods that match.
-        llm: The LLM model to use for collapsing feedback to outcomes.
-            Required when emit is specified. Can be a model string
-            like "gpt-4o-mini" or a BaseLLM instance.
-        default_outcome: The outcome to use when the human provides no
-            feedback (empty input). Must be one of the emit values
-            if emit is specified.
-        metadata: Optional metadata for enterprise integrations. This is
-            passed through to the HumanFeedbackResult and can be used
-            by enterprise forks for features like Slack/Teams integration.
-        provider: Optional HumanFeedbackProvider for custom feedback
-            collection. Use this for async workflows that integrate with
-            external systems like Slack, Teams, or webhooks. When the
-            provider raises HumanFeedbackPending, the flow pauses and
-            can be resumed later with Flow.resume().
-        learn: Enable HITL learning. Recall past lessons to pre-review
-            output before the human sees it, and distill new lessons
-            from feedback after.
-        learn_source: Memory source tag for stored/recalled lessons.
-        learn_strict: When True, re-raise exceptions from the pre-review
-            and distillation steps instead of falling back to raw output.
-            Default False preserves graceful degradation; failures are
-            always logged via ``logger.warning`` regardless of this flag.
-
-    Returns:
-        A decorator function that wraps the method with human feedback
-        collection logic.
-
-    Raises:
-        ValueError: If emit is specified but llm is not provided.
-        ValueError: If default_outcome is specified but emit is not.
-        ValueError: If default_outcome is not in the emit list.
-        HumanFeedbackPending: When an async provider pauses execution.
-
-    Example:
-        Basic feedback without routing:
-        ```python
-        @start()
-        @human_feedback(message="Please review this output:")
-        def generate_content(self):
-            return "Generated content..."
-        ```
-
-        With routing based on feedback:
-        ```python
-        @start()
-        @human_feedback(
-            message="Review and approve or reject:",
-            emit=["approved", "rejected", "needs_revision"],
-            llm="gpt-4o-mini",
-            default_outcome="needs_revision",
-        )
-        def review_document(self):
-            return document_content
-
-
-        @listen("approved")
-        def publish(self):
-            print(f"Publishing: {self.last_human_feedback.output}")
-        ```
-
-        Async feedback with custom provider:
-        ```python
-        @start()
-        @human_feedback(
-            message="Review this content:",
-            emit=["approved", "rejected"],
-            llm="gpt-4o-mini",
-            provider=SlackProvider(channel="#reviews"),
-        )
-        def generate_content(self):
-            return "Content to review..."
-        ```
-    """
     if emit is not None:
         if not llm:
             raise ValueError(
@@ -356,20 +249,12 @@ def human_feedback(
         raise ValueError("default_outcome requires emit to be specified.")
 
     def decorator(func: F) -> F:
-        """Inner decorator that wraps the function."""
-
         def _get_hitl_prompt(key: str) -> str:
-            """Read a HITL prompt from the i18n translations."""
             from crewai.utilities.i18n import I18N_DEFAULT
 
             return I18N_DEFAULT.slice(key)
 
         def _resolve_llm_instance() -> Any:
-            """Resolve the ``llm`` parameter to a BaseLLM instance.
-
-            Uses the SAME model specified in the decorator so pre-review,
-            distillation, and outcome collapsing all share one model.
-            """
             if llm is None:
                 from crewai.llm import LLM
 
@@ -383,7 +268,6 @@ def human_feedback(
         def _pre_review_with_lessons(
             flow_instance: Flow[Any], method_output: Any
         ) -> Any:
-            """Recall past HITL lessons and use LLM to pre-review the output."""
             try:
                 mem = flow_instance.memory
                 if mem is None:
@@ -431,7 +315,6 @@ def human_feedback(
         def _distill_and_store_lessons(
             flow_instance: Flow[Any], method_output: Any, raw_feedback: str
         ) -> None:
-            """Extract generalizable lessons from output + feedback, store in memory."""
             try:
                 mem = flow_instance.memory
                 if mem is None:
@@ -485,7 +368,6 @@ def human_feedback(
         def _build_feedback_context(
             flow_instance: Flow[Any], method_output: Any
         ) -> tuple[Any, Any]:
-            """Build the PendingFeedbackContext and resolve the effective provider."""
             from crewai.flow.async_feedback.types import PendingFeedbackContext
 
             context = PendingFeedbackContext(
@@ -509,7 +391,6 @@ def human_feedback(
             return context, effective_provider
 
         def _request_feedback(flow_instance: Flow[Any], method_output: Any) -> str:
-            """Request feedback using provider or default console (sync)."""
             context, effective_provider = _build_feedback_context(
                 flow_instance, method_output
             )
@@ -535,7 +416,6 @@ def human_feedback(
         async def _request_feedback_async(
             flow_instance: Flow[Any], method_output: Any
         ) -> str:
-            """Request feedback, awaiting the provider if it returns a coroutine."""
             context, effective_provider = _build_feedback_context(
                 flow_instance, method_output
             )
@@ -559,7 +439,6 @@ def human_feedback(
             method_output: Any,
             raw_feedback: str,
         ) -> HumanFeedbackResult | str:
-            """Process feedback and return result or outcome."""
             collapsed_outcome: str | None = None
 
             if not raw_feedback.strip():
@@ -655,42 +534,33 @@ def human_feedback(
 
             wrapper = sync_wrapper
 
-        for attr in [
-            "__is_start_method__",
-            "__trigger_methods__",
-            "__condition_type__",
-            "__trigger_condition__",
-            "__is_flow_method__",
-        ]:
-            if hasattr(func, attr):
-                setattr(wrapper, attr, getattr(func, attr))
-
-        # Create config inline to avoid race conditions
-        wrapper.__human_feedback_config__ = HumanFeedbackConfig(
-            message=message,
-            emit=emit,
-            llm=llm,
-            default_outcome=default_outcome,
-            metadata=metadata,
-            provider=provider,
-            learn=learn,
-            learn_source=learn_source,
-            learn_strict=learn_strict,
-        )
-        wrapper.__is_flow_method__ = True
-
-        if emit:
-            wrapper.__is_router__ = True
-            wrapper.__router_paths__ = list(emit)
-
-        # Stash the live LLM object for HITL resume to retrieve.
-        # When a flow pauses for human feedback and later resumes (possibly in a
-        # different process), the serialized context only contains a model string.
-        # By storing the original LLM on the wrapper, resume_async can retrieve
-        # the fully-configured LLM (with credentials, project, safety_settings, etc.)
-        # instead of creating a bare LLM from just the model string.
-        wrapper._hf_llm = llm
-
         return wrapper  # type: ignore[no-any-return]
 
     return decorator
+
+
+def human_feedback(
+    message: str,
+    emit: Sequence[str] | None = None,
+    llm: str | BaseLLM | None = "gpt-4o-mini",
+    default_outcome: str | None = None,
+    metadata: dict[str, Any] | None = None,
+    provider: HumanFeedbackProvider | None = None,
+    learn: bool = False,
+    learn_source: str = "hitl",
+    learn_strict: bool = False,
+) -> Callable[[F], F]:
+    """Compatibility import path for the Flow human-feedback DSL decorator."""
+    from crewai.flow.dsl._human_feedback import human_feedback as dsl_human_feedback
+
+    return dsl_human_feedback(
+        message=message,
+        emit=emit,
+        llm=llm,
+        default_outcome=default_outcome,
+        metadata=metadata,
+        provider=provider,
+        learn=learn,
+        learn_source=learn_source,
+        learn_strict=learn_strict,
+    )

lib/crewai/src/crewai/flow/persistence/__init__.py

@@ -4,16 +4,9 @@ CrewAI Flow Persistence.
 This module provides interfaces and implementations for persisting flow states.
 """
 
-from typing import Any, TypeVar
-
-from pydantic import BaseModel
-
 from crewai.flow.persistence.base import FlowPersistence
 from crewai.flow.persistence.decorators import persist
 from crewai.flow.persistence.sqlite import SQLiteFlowPersistence
 
 
 __all__ = ["FlowPersistence", "SQLiteFlowPersistence", "persist"]
-
-StateType = TypeVar("StateType", bound=dict[str, Any] | BaseModel)
-DictStateType = dict[str, Any]

lib/crewai/src/crewai/flow/persistence/decorators.py

@@ -28,6 +28,7 @@ import asyncio
 from collections.abc import Callable
 import functools
 import logging
+from types import SimpleNamespace
 from typing import TYPE_CHECKING, Any, Final, TypeVar, cast
 
 from crewai_core.printer import PRINTER
@@ -44,6 +45,8 @@ if TYPE_CHECKING:
 logger = logging.getLogger(__name__)
 T = TypeVar("T")
 
+__all__ = ["PersistenceDecorator", "persist"]
+
 LOG_MESSAGES: Final[dict[str, str]] = {
     "save_state": "Saving flow state to memory for ID: {}",
     "save_error": "Failed to persist state for method {}: {}",
@@ -52,6 +55,31 @@ LOG_MESSAGES: Final[dict[str, str]] = {
 }
 
 
+def _stamp_persistence_metadata(
+    target: Any,
+    persistence: FlowPersistence,
+    verbose: bool,
+) -> None:
+    target.__flow_persistence_config__ = SimpleNamespace(
+        persistence=persistence,
+        verbose=verbose,
+    )
+
+
+_PRESERVED_FLOW_ATTRS: Final[tuple[str, ...]] = (
+    "__is_start_method__",
+    "__trigger_methods__",
+    "__condition_type__",
+    "__trigger_condition__",
+    "__is_router__",
+    "__router_emit__",
+    "__human_feedback_config__",
+    "__flow_persistence_config__",
+    "__flow_method_definition__",
+    "_human_feedback_llm",
+)
+
+
 class PersistenceDecorator:
     """Class to handle flow state persistence with consistent logging."""
 
@@ -163,10 +191,10 @@ def persist(
     """
 
     def decorator(target: type | Callable[..., T]) -> type | Callable[..., T]:
-        """Decorator that handles both class and method decoration."""
         actual_persistence = persistence or SQLiteFlowPersistence()
 
         if isinstance(target, type):
+            _stamp_persistence_metadata(target, actual_persistence, verbose)
             original_init = target.__init__  # type: ignore[misc]
 
             @functools.wraps(original_init)
@@ -211,12 +239,7 @@ def persist(
 
                     wrapped = create_async_wrapper(name, method)
 
-                    for attr in [
-                        "__is_start_method__",
-                        "__trigger_methods__",
-                        "__condition_type__",
-                        "__is_router__",
-                    ]:
+                    for attr in _PRESERVED_FLOW_ATTRS:
                         if hasattr(method, attr):
                             setattr(wrapped, attr, getattr(method, attr))
                     wrapped.__is_flow_method__ = True  # type: ignore[attr-defined]
@@ -239,12 +262,7 @@ def persist(
 
                     wrapped = create_sync_wrapper(name, method)
 
-                    for attr in [
-                        "__is_start_method__",
-                        "__trigger_methods__",
-                        "__condition_type__",
-                        "__is_router__",
-                    ]:
+                    for attr in _PRESERVED_FLOW_ATTRS:
                         if hasattr(method, attr):
                             setattr(wrapped, attr, getattr(method, attr))
                     wrapped.__is_flow_method__ = True  # type: ignore[attr-defined]
@@ -254,6 +272,7 @@ def persist(
             return target
         method = target
         method.__is_flow_method__ = True  # type: ignore[attr-defined]
+        _stamp_persistence_metadata(method, actual_persistence, verbose)
 
         if asyncio.iscoroutinefunction(method):
 
@@ -271,15 +290,13 @@ def persist(
                 )
                 return cast(T, result)
 
-            for attr in [
-                "__is_start_method__",
-                "__trigger_methods__",
-                "__condition_type__",
-                "__is_router__",
-            ]:
+            for attr in _PRESERVED_FLOW_ATTRS:
                 if hasattr(method, attr):
                     setattr(method_async_wrapper, attr, getattr(method, attr))
             method_async_wrapper.__is_flow_method__ = True  # type: ignore[attr-defined]
+            _stamp_persistence_metadata(
+                method_async_wrapper, actual_persistence, verbose
+            )
             return cast(Callable[..., T], method_async_wrapper)
 
         @functools.wraps(method)
@@ -290,15 +307,11 @@ def persist(
             )
             return result
 
-        for attr in [
-            "__is_start_method__",
-            "__trigger_methods__",
-            "__condition_type__",
-            "__is_router__",
-        ]:
+        for attr in _PRESERVED_FLOW_ATTRS:
             if hasattr(method, attr):
                 setattr(method_sync_wrapper, attr, getattr(method, attr))
         method_sync_wrapper.__is_flow_method__ = True  # type: ignore[attr-defined]
+        _stamp_persistence_metadata(method_sync_wrapper, actual_persistence, verbose)
         return cast(Callable[..., T], method_sync_wrapper)
 
     return decorator

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

@@ -1,9 +1,9 @@
-"""Flow runtime: the Flow execution engine, its metaclass, and state proxies.
+"""Flow Runtime: the engine that executes a Flow.
 
-Holds the Flow class (kickoff/resume/listener dispatch), the FlowMeta
-metaclass (Pydantic model construction; structural extraction is delegated to
-``flow_definition.extract_flow_definition``), and the thread-safe state
-proxies. The authoring decorators live in ``crewai.flow.dsl``.
+Provides the ``Flow`` class (kickoff/resume/listener dispatch), the
+``FlowMeta`` metaclass, and the thread-safe state proxies. Flows
+authored with the Python DSL (see ``dsl``) are described by a Flow
+Structure (see ``flow_definition``) and executed here.
 """
 
 from __future__ import annotations
@@ -84,18 +84,26 @@ 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.constants import AND_CONDITION, OR_CONDITION
-from crewai.flow.flow_context import current_flow_id, current_flow_request_id
-from crewai.flow.flow_definition import (
+from crewai.flow.dsl._conditions import (
     _extract_all_methods,
     _extract_all_methods_recursive,
     _normalize_condition,
-    extract_flow_definition,
     is_flow_condition_dict,
-    is_flow_method,
-    is_flow_method_name,
     is_simple_flow_condition,
 )
+from crewai.flow.dsl._utils import (
+    build_flow_definition,
+    extract_flow_definition,
+    is_flow_method,
+)
+from crewai.flow.flow_context import current_flow_id, current_flow_request_id
+from crewai.flow.flow_definition import FlowDefinition
 from crewai.flow.flow_wrappers import (
     FlowCondition,
     FlowMethod,
@@ -141,6 +149,16 @@ 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
+# annotation in subclass modules without those modules needing to import
+# ``crewai.context.ExecutionContext`` themselves. The real class is brought
+# in under ``TYPE_CHECKING`` above for static analysis. We can't import it at
+# runtime because ``crewai.context`` is loaded mid-initialization when this
+# module is imported through ``crewai.__init__`` (circular).
+ExecutionContext = Any  # type: ignore[assignment,misc]
 
 
 logger = logging.getLogger(__name__)
@@ -585,19 +603,88 @@ class FlowMeta(ModelMetaclass):
 
         cls = super().__new__(mcs, name, bases, namespace)
 
-        start_methods, listeners, routers, router_paths = extract_flow_definition(
+        start_methods, listeners, routers, router_emit = extract_flow_definition(
             namespace
         )
 
+        # === EXPERIMENTAL: conversational gating ===
+        # The built-in conversational graph (``conversation_start``,
+        # ``route_conversation``, ``converse_turn``, ``end_conversation``,
+        # ``answer_from_history_turn``) lives on ``Flow`` itself, decorated
+        # with ``@_conversational_only``. We don't want those methods to
+        # register on non-chat flows. The opt-in is ``conversational = True``
+        # on the subclass; otherwise the methods exist as inert attributes.
+        is_conversational = bool(namespace.get("conversational", False))
+        if not is_conversational:
+            for base in bases:
+                if getattr(base, "conversational", False):
+                    is_conversational = True
+                    break
+
+        # 1. Strip conversational-only methods that landed in the namespace
+        # extraction when this class isn't conversational. Applies to ``Flow``
+        # itself (its own namespace declares the conversational methods).
+        if not is_conversational:
+
+            def _is_conv_only(attr_name: str) -> bool:
+                attr_value = namespace.get(attr_name)
+                return bool(getattr(attr_value, "__conversational_only__", False))
+
+            start_methods = [m for m in start_methods if not _is_conv_only(m)]
+            listeners = {k: v for k, v in listeners.items() if not _is_conv_only(k)}
+            routers = {r for r in routers if not _is_conv_only(r)}
+            router_emit = {k: v for k, v in router_emit.items() if not _is_conv_only(k)}
+
+        # 2. Harvest conversational-only methods from base classes when this
+        # subclass opts in. (extract_flow_definition only scans the current
+        # namespace; without this step, ``class MyChat(Flow): conversational
+        # = True`` would have an empty graph.)
+        if is_conversational:
+            already_registered: set[str] = set(start_methods) | set(listeners.keys())
+            for base in bases:
+                for attr_name in dir(base):
+                    if attr_name.startswith("_") or attr_name in already_registered:
+                        continue
+                    attr_value = getattr(base, attr_name, None)
+                    if not is_flow_method(attr_value):
+                        continue
+                    if not getattr(attr_value, "__conversational_only__", False):
+                        continue
+                    already_registered.add(attr_name)
+
+                    if hasattr(attr_value, "__is_start_method__"):
+                        start_methods.append(attr_name)
+
+                    trigger_methods = getattr(attr_value, "__trigger_methods__", None)
+                    if trigger_methods is not None:
+                        condition_type = getattr(
+                            attr_value, "__condition_type__", OR_CONDITION
+                        )
+                        trigger_condition = getattr(
+                            attr_value, "__trigger_condition__", None
+                        )
+                        if trigger_condition is not None:
+                            listeners[attr_name] = trigger_condition
+                        else:
+                            listeners[attr_name] = (condition_type, trigger_methods)
+
+                        if getattr(attr_value, "__is_router__", False):
+                            routers.add(attr_name)
+                            emit = getattr(attr_value, "__router_emit__", None)
+                            router_emit[attr_name] = list(emit) if emit else []
+
         cls._start_methods = start_methods  # type: ignore[attr-defined]
         cls._listeners = listeners  # type: ignore[attr-defined]
         cls._routers = routers  # type: ignore[attr-defined]
-        cls._router_paths = router_paths  # type: ignore[attr-defined]
+        cls._router_emit = router_emit  # type: ignore[attr-defined]
+        # The static FlowDefinition is built lazily (on first access via
+        # ``Flow.flow_definition()`` or visualization), not at class-definition
+        # time, to avoid AST parsing and diagnostic logging on every import.
 
         return cls
 
 
-class Flow(BaseModel, Generic[T], metaclass=FlowMeta):
+class Flow(_ConversationalMixin, BaseModel, Generic[T], metaclass=FlowMeta):
     """Base class for all flows.
 
     type parameter T must be either dict[str, Any] or a subclass of BaseModel."""
@@ -612,10 +699,53 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):
     _start_methods: ClassVar[list[FlowMethodName]] = []
     _listeners: ClassVar[dict[FlowMethodName, SimpleFlowCondition | FlowCondition]] = {}
     _routers: ClassVar[set[FlowMethodName]] = set()
-    _router_paths: ClassVar[dict[FlowMethodName, list[FlowMethodName]]] = {}
+    _router_emit: ClassVar[dict[FlowMethodName, list[FlowMethodName]]] = {}
+    _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"
 
+    @classmethod
+    def flow_definition(cls) -> FlowDefinition:
+        """Return the static Flow Definition built from this Flow class."""
+        flow_definition = cls.__dict__.get("_flow_definition")
+        if flow_definition is None:
+            flow_definition = build_flow_definition(cls)
+            cls._flow_definition = flow_definition
+        return flow_definition
+
     initial_state: Annotated[  # type: ignore[type-arg]
         type[BaseModel] | type[dict] | dict[str, Any] | BaseModel | None,
         BeforeValidator(_deserialize_initial_state),
@@ -639,6 +769,15 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):
         ),
     ] = Field(default=None)
     suppress_flow_events: bool = Field(default=False)
+    defer_trace_finalization: bool = Field(
+        default=False,
+        description=(
+            "When True, skip per-kickoff ``FlowFinishedEvent`` + trace-batch "
+            "finalization. ``finalize_session_traces()`` does the final emit "
+            "+ finalize. Use for multi-turn chat sessions where every "
+            "``handle_turn()`` is a turn within one logical trace."
+        ),
+    )
     human_feedback_history: list[HumanFeedbackResult] = Field(default_factory=list)
     last_human_feedback: HumanFeedbackResult | None = Field(default=None)
 
@@ -769,6 +908,11 @@ class Flow(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]
         class _FlowGeneric(cls):  # type: ignore[valid-type,misc]
@@ -821,13 +965,48 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):
             flow_name = sanitize_scope_name(self.name or self.__class__.__name__)
             self.memory = Memory(root_scope=f"/flow/{flow_name}")
 
-        for method_name in dir(self):
-            if not method_name.startswith("_"):
-                method = getattr(self, method_name)
-                if is_flow_method(method):
-                    if not hasattr(method, "__self__"):
-                        method = method.__get__(self, self.__class__)
-                    self._methods[method.__name__] = method
+        # Build the runtime method lookup. ``_start_methods`` / ``_listeners`` /
+        # ``_routers`` are populated by ``FlowMeta.__new__`` and are the source
+        # of truth for which slots are flow methods — including slots a
+        # subclass overrode without re-decorating. Walk those slots first so
+        # the override (which may be a plain function) still gets bound here.
+        registered_slots: set[str] = set()
+        registered_slots.update(getattr(type(self), "_start_methods", []))
+        registered_slots.update(getattr(type(self), "_listeners", {}).keys())
+        registered_slots.update(getattr(type(self), "_routers", set()))
+        for method_name in registered_slots:
+            method = getattr(self, method_name, None)
+            if method is None:
+                continue
+            if not hasattr(method, "__self__"):
+                method = method.__get__(self, self.__class__)
+            self._methods[FlowMethodName(method_name)] = method
+
+        # Also pick up any leftover flow-decorated attributes that aren't
+        # already registered (defensive — preserves the prior catch-all scan).
+        # We walk the MRO's class ``__dict__`` rather than ``dir(self)`` +
+        # ``getattr`` so we don't trigger ``@property`` descriptors (those
+        # would run user code mid-init, before state is set up — e.g. a
+        # user property accessing ``self.state.messages`` would crash).
+        # Conversational-only methods are skipped on non-chat flows.
+        is_conversational = getattr(type(self), "conversational", False)
+        seen_in_dict: set[str] = set()
+        for klass in type(self).__mro__:
+            for method_name, raw in klass.__dict__.items():
+                if method_name.startswith("_") or method_name in self._methods:
+                    continue
+                if method_name in seen_in_dict:
+                    continue
+                seen_in_dict.add(method_name)
+                if not is_flow_method(raw):
+                    continue
+                if (
+                    getattr(raw, "__conversational_only__", False)
+                    and not is_conversational
+                ):
+                    continue
+                bound = raw.__get__(self, self.__class__)
+                self._methods[FlowMethodName(method_name)] = bound
 
     def recall(self, query: str, **kwargs: Any) -> Any:
         """Recall relevant memories. Delegates to this flow's memory.
@@ -1293,7 +1472,7 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):
         llm = None
         method = self._methods.get(FlowMethodName(context.method_name))
         if method is not None:
-            live_llm = getattr(method, "_hf_llm", None)
+            live_llm = getattr(method, "_human_feedback_llm", None)
             if live_llm is not None:
                 from crewai.llms.base_llm import BaseLLM as BaseLLMClass
 
@@ -1458,6 +1637,18 @@ class Flow(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 and hasattr(self, "_initial_state_t"):
             state_type = self._initial_state_t
             if isinstance(state_type, type):
@@ -2011,32 +2202,67 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):
                 if filtered_inputs:
                     self._initialize_state(filtered_inputs)
 
-            if get_current_parent_id() is None:
+            defer_trace_finalization = self._should_defer_trace_finalization()
+            deferred_started_event_id = self._deferred_flow_started_event_id
+            should_emit_flow_started = not (
+                defer_trace_finalization and deferred_started_event_id
+            )
+
+            if (
+                defer_trace_finalization
+                and deferred_started_event_id
+                and get_current_parent_id() is None
+            ):
+                restore_event_scope(((deferred_started_event_id, "flow_started"),))
+            elif get_current_parent_id() is None:
                 reset_emission_counter()
                 reset_last_event_id()
 
-            if not self.suppress_flow_events:
-                future = crewai_event_bus.emit(
-                    self,
-                    FlowStartedEvent(
-                        type="flow_started",
-                        flow_name=self.name or self.__class__.__name__,
-                        inputs=inputs,
-                    ),
+            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.
+                started_event = FlowStartedEvent(
+                    type="flow_started",
+                    flow_name=self.name or self.__class__.__name__,
+                    inputs=inputs,
                 )
+                future = crewai_event_bus.emit(self, started_event)
                 if future:
                     try:
                         await asyncio.wrap_future(future)
                     except Exception:
                         logger.warning("FlowStartedEvent handler failed", exc_info=True)
-                self._log_flow_event(
-                    f"Flow started with ID: {self.flow_id}", color="bold magenta"
-                )
+                # Stash the started event id so a deferred
+                # ``finalize_session_traces()`` can restore the event scope
+                # before emitting ``FlowFinishedEvent`` (otherwise the bus
+                # warns "Ending event 'flow_finished' emitted with empty
+                # scope stack").
+                if defer_trace_finalization:
+                    object.__setattr__(
+                        self, "_deferred_flow_started_event_id", started_event.event_id
+                    )
+                if not self.suppress_flow_events:
+                    self._log_flow_event(
+                        f"Flow started with ID: {self.flow_id}", color="bold magenta"
+                    )
 
-            # After FlowStarted (when not suppressed): env events must not pre-empt
-            # trace batch init with implicit "crew" execution_type.
+            # After FlowStarted: env events must not pre-empt trace batch init
+            # 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 inputs is not None and "id" not in inputs:
                 self._initialize_state(inputs)
 
@@ -2061,11 +2287,21 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):
                     if unconditional_starts
                     else self._start_methods
                 )
-                tasks = [
-                    self._execute_start_method(start_method)
-                    for start_method in starts_to_execute
-                ]
-                await asyncio.gather(*tasks)
+                if getattr(type(self), "conversational", False):
+                    # Conversational mode: run @start methods sequentially so
+                    # user setup (e.g. permission loading) completes before
+                    # the router fires. ``_start_methods`` preserves
+                    # declaration + harvest order, with ``conversation_start``
+                    # at the end — its router decision only runs after every
+                    # user start finishes.
+                    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
@@ -2133,7 +2369,13 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):
                 )
                 self._event_futures.clear()
 
-            if not self.suppress_flow_events:
+            # 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``.
+            if not self._should_defer_trace_finalization():
                 future = crewai_event_bus.emit(
                     self,
                     FlowFinishedEvent(
@@ -2151,7 +2393,6 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):
                             "FlowFinishedEvent handler failed", exc_info=True
                         )
 
-            if not self.suppress_flow_events:
                 trace_listener = TraceCollectionListener()
                 if trace_listener.batch_manager.batch_owner_type == "flow":
                     if trace_listener.first_time_handler.is_first_time:
@@ -2343,19 +2584,20 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):
                 kwargs or {}
             )
 
-            if not self.suppress_flow_events:
-                future = crewai_event_bus.emit(
-                    self,
-                    MethodExecutionStartedEvent(
-                        type="method_execution_started",
-                        method_name=method_name,
-                        flow_name=self.name or self.__class__.__name__,
-                        params=dumped_params,
-                        state=self._copy_and_serialize_state(),
-                    ),
-                )
-                if future:
-                    self._event_futures.append(future)
+            # MethodExecution events always fire — ``suppress_flow_events``
+            # only hides the Rich console panel, not observability events.
+            future = crewai_event_bus.emit(
+                self,
+                MethodExecutionStartedEvent(
+                    type="method_execution_started",
+                    method_name=method_name,
+                    flow_name=self.name or self.__class__.__name__,
+                    params=dumped_params,
+                    state=self._copy_and_serialize_state(),
+                ),
+            )
+            if future:
+                self._event_futures.append(future)
 
             # Set method name in context so ask() can read it without
             # stack inspection.  Must happen before copy_context() so the
@@ -2397,18 +2639,19 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):
             self._completed_methods.add(method_name)
 
             finished_event_id: str | None = None
-            if not self.suppress_flow_events:
-                finished_event = MethodExecutionFinishedEvent(
-                    type="method_execution_finished",
-                    method_name=method_name,
-                    flow_name=self.name or self.__class__.__name__,
-                    state=self._copy_and_serialize_state(),
-                    result=result,
-                )
-                finished_event_id = finished_event.event_id
-                future = crewai_event_bus.emit(self, finished_event)
-                if future:
-                    self._event_futures.append(future)
+            # MethodExecution events always fire even when console panels are
+            # suppressed; tracing depends on them.
+            finished_event = MethodExecutionFinishedEvent(
+                type="method_execution_finished",
+                method_name=method_name,
+                flow_name=self.name or self.__class__.__name__,
+                state=self._copy_and_serialize_state(),
+                result=result,
+            )
+            finished_event_id = finished_event.event_id
+            future = crewai_event_bus.emit(self, finished_event)
+            if future:
+                self._event_futures.append(future)
 
             return result, finished_event_id
         except Exception as e:
@@ -2604,7 +2847,7 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):
 
     def _evaluate_condition(
         self,
-        condition: FlowMethodName | FlowCondition,
+        condition: str | FlowMethodName | FlowCondition,
         trigger_method: FlowMethodName,
         listener_name: FlowMethodName,
     ) -> bool:
@@ -2618,7 +2861,7 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):
         Returns:
             True if the condition is satisfied, False otherwise
         """
-        if is_flow_method_name(condition):
+        if isinstance(condition, str):
             return condition == trigger_method
 
         if is_flow_condition_dict(condition):

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

@@ -22,7 +22,6 @@ P = ParamSpec("P")
 R = TypeVar("R", covariant=True)
 
 FlowMethodName = NewType("FlowMethodName", str)
-FlowRouteName = NewType("FlowRouteName", str)
 PendingListenerKey = NewType(
     "PendingListenerKey",
     Annotated[str, "nested flow conditions use 'listener_name:object_id'"],
@@ -32,7 +31,7 @@ PendingListenerKey = NewType(
 class FlowMethodCallable(Protocol[P, R]):
     """A callable that can be used as a flow method reference."""
 
-    __name__: FlowMethodName
+    __name__: str
 
     def __call__(self, *args: P.args, **kwargs: P.kwargs) -> R: ...
 

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

@@ -1,53 +0,0 @@
-"""Backwards-compatible shim. The implementation moved to ``crewai.flow.flow_definition``.
-
-Import from ``crewai.flow.flow_definition`` directly in new code.
-"""
-
-from crewai.flow.flow_definition import (
-    _extract_all_methods,
-    _extract_all_methods_recursive,
-    _extract_string_literals_from_type_annotation,
-    _normalize_condition,
-    _unwrap_function,
-    build_ancestor_dict,
-    build_parent_children_dict,
-    calculate_node_levels,
-    count_outgoing_edges,
-    dfs_ancestors,
-    extract_flow_definition,
-    get_child_index,
-    get_possible_return_constants,
-    is_ancestor,
-    is_flow_condition_dict,
-    is_flow_condition_list,
-    is_flow_method,
-    is_flow_method_callable,
-    is_flow_method_name,
-    is_simple_flow_condition,
-    process_router_paths,
-)
-
-
-__all__ = [
-    "_extract_all_methods",
-    "_extract_all_methods_recursive",
-    "_extract_string_literals_from_type_annotation",
-    "_normalize_condition",
-    "_unwrap_function",
-    "build_ancestor_dict",
-    "build_parent_children_dict",
-    "calculate_node_levels",
-    "count_outgoing_edges",
-    "dfs_ancestors",
-    "extract_flow_definition",
-    "get_child_index",
-    "get_possible_return_constants",
-    "is_ancestor",
-    "is_flow_condition_dict",
-    "is_flow_condition_list",
-    "is_flow_method",
-    "is_flow_method_callable",
-    "is_flow_method_name",
-    "is_simple_flow_condition",
-    "process_router_paths",
-]

lib/crewai/src/crewai/flow/visualization/assets/interactive.js

@@ -684,7 +684,7 @@ class TriggeredByHighlighter {
         });
       } else {
         for (const [nodeName, nodeInfo] of Object.entries(nodeData)) {
-          if (nodeInfo.router_paths && nodeInfo.router_paths.includes(triggerNodeId)) {
+          if (nodeInfo.router_events && nodeInfo.router_events.includes(triggerNodeId)) {
             const routerNode = nodeName;
 
             const routerEdges = allEdges.filter(
@@ -768,7 +768,7 @@ class TriggeredByHighlighter {
     this.animateEdgeStyles();
   }
 
-  highlightAllRouterPaths() {
+  highlightAllRouterEvents() {
     this.clear();
 
     if (!this.activeDrawerNodeId) {
@@ -792,10 +792,10 @@ class TriggeredByHighlighter {
       routerEdges.forEach(edge => {
         pathNodes.add(edge.to);
       });
-    } else if (activeMetadata && activeMetadata.router_paths && activeMetadata.router_paths.length > 0) {
-      activeMetadata.router_paths.forEach(pathName => {
+    } else if (activeMetadata && activeMetadata.router_events && activeMetadata.router_events.length > 0) {
+      activeMetadata.router_events.forEach(eventName => {
         for (const [nodeName, nodeInfo] of Object.entries(nodeData)) {
-          if (nodeInfo.router_paths && nodeInfo.router_paths.includes(pathName)) {
+          if (nodeInfo.router_events && nodeInfo.router_events.includes(eventName)) {
             const edgeFromRouter = allEdges.filter(
               (edge) => edge.from === nodeName && edge.to === this.activeDrawerNodeId && edge.dashes
             );
@@ -821,6 +821,42 @@ class TriggeredByHighlighter {
     this.animateEdgeStyles();
   }
 
+  highlightRouterEvent(eventName) {
+    this.clear();
+
+    if (this.activeDrawerEdges && this.activeDrawerEdges.length > 0) {
+      this.resetEdgesToDefault(this.activeDrawerEdges);
+      this.activeDrawerEdges = [];
+    }
+
+    if (!this.activeDrawerNodeId || !eventName) {
+      return;
+    }
+
+    const routerEdges = this.edges.get().filter(
+      (edge) =>
+        edge.from === this.activeDrawerNodeId &&
+        edge.dashes &&
+        edge.label === eventName,
+    );
+
+    if (routerEdges.length === 0) {
+      return;
+    }
+
+    const pathNodes = new Set([this.activeDrawerNodeId]);
+    routerEdges.forEach((edge) => {
+      pathNodes.add(edge.from);
+      pathNodes.add(edge.to);
+    });
+
+    this.highlightedNodes = Array.from(pathNodes);
+    this.highlightedEdges = routerEdges.map((e) => e.id);
+
+    this.animateNodeOpacity();
+    this.animateEdgeStyles();
+  }
+
   highlightTriggeredBy(triggerNodeId) {
     this.clear();
 
@@ -892,8 +928,8 @@ class TriggeredByHighlighter {
       ) {
         for (const [nodeName, nodeInfo] of Object.entries(nodeData)) {
           if (
-            nodeInfo.router_paths &&
-            nodeInfo.router_paths.includes(triggerNodeId)
+            nodeInfo.router_events &&
+            nodeInfo.router_events.includes(triggerNodeId)
           ) {
             const routerNode = nodeName;
 
@@ -1501,7 +1537,7 @@ class DrawerManager {
     const activeMetadata = nodeData[activeNodeId];
     if (activeMetadata && activeMetadata.trigger_methods && activeMetadata.trigger_methods.includes(triggerNodeId)) {
       for (const [nodeName, nodeInfo] of Object.entries(nodeData)) {
-        if (nodeInfo.router_paths && nodeInfo.router_paths.includes(triggerNodeId)) {
+        if (nodeInfo.router_events && nodeInfo.router_events.includes(triggerNodeId)) {
           const routerEdges = allEdges.filter(
             (edge) => edge.from === nodeName && edge.dashes
           );
@@ -1660,16 +1696,16 @@ class DrawerManager {
             `;
     }
 
-    if (metadata.router_paths && metadata.router_paths.length > 0) {
-      const uniqueRouterPaths = [...new Set(metadata.router_paths)];
-      const routerPathsJson = JSON.stringify(uniqueRouterPaths).replace(/"/g, '"');
+    if (metadata.router_events && metadata.router_events.length > 0) {
+      const uniqueRouterEvents = [...new Set(metadata.router_events)];
+      const routerEventsJson = JSON.stringify(uniqueRouterEvents).replace(/"/g, '"');
       metadataContent += `
                 <div class="drawer-section">
-                    <div class="drawer-section-title router-paths-title" data-router-paths="${routerPathsJson}" style="cursor: pointer; display: inline-flex; align-items: center; gap: 4px;">
-                        Router Paths <i data-lucide="chevron-down" style="width: 14px; height: 14px; color: var(--text-primary);"></i>
+                    <div class="drawer-section-title router-events-title" data-router-events="${routerEventsJson}" style="cursor: pointer; display: inline-flex; align-items: center; gap: 4px;">
+                        Router Events <i data-lucide="chevron-down" style="width: 14px; height: 14px; color: var(--text-primary);"></i>
                     </div>
                     <ul class="drawer-list">
-                        ${uniqueRouterPaths.map((p) => `<li><span class="drawer-code-link" data-node-id="${p}" style="color: {{ CREWAI_ORANGE }}; border-color: rgba(255,90,80,0.3);">${p}</span></li>`).join("")}
+                        ${uniqueRouterEvents.map((eventName) => `<li><span class="drawer-code-link" data-router-event="${eventName}" style="color: {{ CREWAI_ORANGE }}; border-color: rgba(255,90,80,0.3);">${eventName}</span></li>`).join("")}
                     </ul>
                 </div>
             `;
@@ -1823,14 +1859,26 @@ class DrawerManager {
       });
     });
 
-    const routerPathsTitle = this.elements.content.querySelector(
-      ".router-paths-title[data-router-paths]",
+    const routerEventLinks = this.elements.content.querySelectorAll(
+      ".drawer-code-link[data-router-event]",
     );
-    if (routerPathsTitle) {
-      routerPathsTitle.addEventListener("click", (e) => {
+    routerEventLinks.forEach((link) => {
+      link.addEventListener("click", (e) => {
         e.preventDefault();
         e.stopPropagation();
-        this.triggeredByHighlighter.highlightAllRouterPaths();
+        const routerEvent = link.getAttribute("data-router-event");
+        this.triggeredByHighlighter.highlightRouterEvent(routerEvent);
+      });
+    });
+
+    const routerEventsTitle = this.elements.content.querySelector(
+      ".router-events-title[data-router-events]",
+    );
+    if (routerEventsTitle) {
+      routerEventsTitle.addEventListener("click", (e) => {
+        e.preventDefault();
+        e.stopPropagation();
+        this.triggeredByHighlighter.highlightAllRouterEvents();
       });
     }
   }

lib/crewai/src/crewai/flow/visualization/builder.py

@@ -1,131 +1,118 @@
-"""Flow structure builder for analyzing Flow execution."""
+"""Flow structure builder for definition-only Flow visualization."""
 
 from __future__ import annotations
 
 from collections import defaultdict
-import inspect
 import logging
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, cast
 
 from crewai.flow.constants import AND_CONDITION, OR_CONDITION
-from crewai.flow.flow_wrappers import FlowCondition
-from crewai.flow.types import FlowMethodName
-from crewai.flow.utils import (
-    is_flow_condition_dict,
-    is_simple_flow_condition,
+from crewai.flow.flow_definition import (
+    FlowDefinition,
+    FlowDefinitionCondition,
+    FlowMethodDefinition,
 )
-from crewai.flow.visualization.schema import extract_method_signature
 from crewai.flow.visualization.types import FlowStructure, NodeMetadata, StructureEdge
 
 
 logger = logging.getLogger(__name__)
 
+__all__ = ["build_flow_structure", "calculate_execution_paths"]
+
 
 if TYPE_CHECKING:
     from crewai.flow.flow import Flow
 
 
+def _definition_condition_items(
+    condition: dict[str, Any],
+    key: str,
+) -> list[FlowDefinitionCondition]:
+    return cast(list[FlowDefinitionCondition], condition.get(key, []))
+
+
+def _definition_condition_parts(
+    condition: dict[str, Any],
+) -> tuple[str, list[FlowDefinitionCondition]]:
+    if "and" in condition:
+        return AND_CONDITION, _definition_condition_items(condition, "and")
+    return OR_CONDITION, _definition_condition_items(condition, "or")
+
+
+def _condition_type_from_definition(
+    condition: FlowDefinitionCondition | None,
+) -> str | None:
+    if isinstance(condition, dict):
+        if "and" in condition:
+            return AND_CONDITION
+        if "or" in condition:
+            return OR_CONDITION
+    if isinstance(condition, str):
+        return OR_CONDITION
+    return None
+
+
+def _runtime_condition_from_definition(
+    condition: FlowDefinitionCondition,
+) -> str | dict[str, Any]:
+    if isinstance(condition, str):
+        return condition
+    condition_type, conditions = _definition_condition_parts(condition)
+    return {
+        "type": condition_type,
+        "conditions": [_runtime_condition_from_definition(item) for item in conditions],
+    }
+
+
+def _method_trigger_condition(
+    method_definition: FlowMethodDefinition,
+) -> FlowDefinitionCondition | None:
+    if method_definition.listen is not None:
+        return method_definition.listen
+    if isinstance(method_definition.start, str | dict):
+        return method_definition.start
+    return None
+
+
+def _method_router_events(method_definition: FlowMethodDefinition) -> list[str]:
+    if method_definition.human_feedback and method_definition.human_feedback.emit:
+        return [str(event) for event in method_definition.human_feedback.emit]
+    if method_definition.emit:
+        return [str(event) for event in method_definition.emit]
+    return []
+
+
 def _extract_direct_or_triggers(
-    condition: str | dict[str, Any] | list[Any] | FlowCondition,
+    condition: FlowDefinitionCondition,
 ) -> list[str]:
-    """Extract direct OR-level trigger strings from a condition.
-
-    This function extracts strings that would directly trigger a listener,
-    meaning they appear at the top level of an OR condition. Strings nested
-    inside AND conditions are NOT considered direct triggers for router paths.
-
-    For example:
-    - or_("a", "b") -> ["a", "b"] (both are direct triggers)
-    - and_("a", "b") -> [] (neither are direct triggers, both required)
-    - or_(and_("a", "b"), "c") -> ["c"] (only "c" is a direct trigger)
-
-    Args:
-        condition: Can be a string, dict, or list.
-
-    Returns:
-        List of direct OR-level trigger strings.
-    """
     if isinstance(condition, str):
         return [condition]
-    if isinstance(condition, dict):
-        cond_type = condition.get("type", OR_CONDITION)
-        conditions_list = condition.get("conditions", [])
-
-        if cond_type == OR_CONDITION:
-            strings = []
-            for sub_cond in conditions_list:
-                strings.extend(_extract_direct_or_triggers(sub_cond))
-            return strings
+    condition_type, conditions = _definition_condition_parts(condition)
+    if condition_type == AND_CONDITION:
         return []
-    if isinstance(condition, list):
-        strings = []
-        for item in condition:
-            strings.extend(_extract_direct_or_triggers(item))
-        return strings
-    if callable(condition) and hasattr(condition, "__name__"):
-        return [condition.__name__]
-    return []
+    strings: list[str] = []
+    for sub_condition in conditions:
+        strings.extend(_extract_direct_or_triggers(sub_condition))
+    return strings
 
 
 def _extract_all_trigger_names(
-    condition: str | dict[str, Any] | list[Any] | FlowCondition,
+    condition: FlowDefinitionCondition,
 ) -> list[str]:
-    """Extract ALL trigger names from a condition for display purposes.
-
-    Unlike _extract_direct_or_triggers, this extracts ALL strings and method
-    names from the entire condition tree, including those nested in AND conditions.
-    This is used for displaying trigger information in the UI.
-
-    For example:
-    - or_("a", "b") -> ["a", "b"]
-    - and_("a", "b") -> ["a", "b"]
-    - or_(and_("a", method_6), method_4) -> ["a", "method_6", "method_4"]
-
-    Args:
-        condition: Can be a string, dict, or list.
-
-    Returns:
-        List of all trigger names found in the condition.
-    """
     if isinstance(condition, str):
         return [condition]
-    if isinstance(condition, dict):
-        conditions_list = condition.get("conditions", [])
-        strings = []
-        for sub_cond in conditions_list:
-            strings.extend(_extract_all_trigger_names(sub_cond))
-        return strings
-    if isinstance(condition, list):
-        strings = []
-        for item in condition:
-            strings.extend(_extract_all_trigger_names(item))
-        return strings
-    if callable(condition) and hasattr(condition, "__name__"):
-        return [condition.__name__]
-    return []
+    _, conditions = _definition_condition_parts(condition)
+    strings: list[str] = []
+    for sub_condition in conditions:
+        strings.extend(_extract_all_trigger_names(sub_condition))
+    return strings
 
 
 def _create_edges_from_condition(
-    condition: str | dict[str, Any] | list[Any] | FlowCondition,
+    condition: FlowDefinitionCondition,
     target: str,
     nodes: dict[str, NodeMetadata],
 ) -> list[StructureEdge]:
-    """Create edges from a condition tree, preserving AND/OR semantics.
-
-    This function recursively processes the condition tree and creates edges
-    with the appropriate condition_type for each trigger.
-
-    For AND conditions, all triggers get edges with condition_type="AND".
-    For OR conditions, triggers get edges with condition_type="OR".
-
-    Args:
-        condition: The condition tree (string, dict, or list).
-        target: The target node name.
-        nodes: Dictionary of all nodes for validation.
-
-    Returns:
-        List of StructureEdge objects representing the condition.
-    """
     edges: list[StructureEdge] = []
 
     if isinstance(condition, str):
@@ -135,24 +122,11 @@ def _create_edges_from_condition(
                     source=condition,
                     target=target,
                     condition_type=OR_CONDITION,
-                    is_router_path=False,
-                )
-            )
-    elif callable(condition) and hasattr(condition, "__name__"):
-        method_name = condition.__name__
-        if method_name in nodes:
-            edges.append(
-                StructureEdge(
-                    source=method_name,
-                    target=target,
-                    condition_type=OR_CONDITION,
-                    is_router_path=False,
+                    is_router_event=False,
                 )
             )
     elif isinstance(condition, dict):
-        cond_type = condition.get("type", OR_CONDITION)
-        conditions_list = condition.get("conditions", [])
-
+        cond_type, conditions = _definition_condition_parts(condition)
         if cond_type == AND_CONDITION:
             triggers = _extract_all_trigger_names(condition)
             edges.extend(
@@ -160,277 +134,144 @@ def _create_edges_from_condition(
                     source=trigger,
                     target=target,
                     condition_type=AND_CONDITION,
-                    is_router_path=False,
+                    is_router_event=False,
                 )
                 for trigger in triggers
                 if trigger in nodes
             )
         else:
-            for sub_cond in conditions_list:
-                edges.extend(_create_edges_from_condition(sub_cond, target, nodes))
-    elif isinstance(condition, list):
-        for item in condition:
-            edges.extend(_create_edges_from_condition(item, target, nodes))
+            for sub_condition in conditions:
+                edges.extend(_create_edges_from_condition(sub_condition, target, nodes))
 
     return edges
 
 
-def build_flow_structure(flow: Flow[Any]) -> FlowStructure:
-    """Build a structure representation of a Flow's execution.
+def _flow_definition_from(
+    flow_or_definition: Flow[Any] | type[Flow[Any]] | FlowDefinition,
+) -> FlowDefinition:
+    if isinstance(flow_or_definition, FlowDefinition):
+        return flow_or_definition
 
-    Args:
-        flow: Flow instance to analyze.
+    flow_class = (
+        flow_or_definition
+        if isinstance(flow_or_definition, type)
+        else type(flow_or_definition)
+    )
+    flow_definition = getattr(flow_class, "flow_definition", None)
+    if callable(flow_definition):
+        return cast(FlowDefinition, flow_definition())
+    raise TypeError(
+        "build_flow_structure requires a FlowDefinition or a Flow class/instance "
+        "with flow_definition()."
+    )
 
-    Returns:
-        Dictionary with nodes, edges, start_methods, and router_methods.
-    """
+
+def build_flow_structure(
+    flow_or_definition: Flow[Any] | type[Flow[Any]] | FlowDefinition,
+) -> FlowStructure:
+    """Build a visualization structure projection from a FlowDefinition."""
+    definition = _flow_definition_from(flow_or_definition)
     nodes: dict[str, NodeMetadata] = {}
     edges: list[StructureEdge] = []
     start_methods: list[str] = []
     router_methods: list[str] = []
 
-    for method_name, method in flow._methods.items():
-        node_metadata: NodeMetadata = {"type": "listen"}
+    for method_name, method_definition in definition.methods.items():
+        node_metadata: NodeMetadata = {"type": "listen", "class_name": definition.name}
 
-        if hasattr(method, "__is_start_method__") and method.__is_start_method__:
+        if method_definition.is_start:
             node_metadata["type"] = "start"
             start_methods.append(method_name)
 
-        if hasattr(method, "__is_router__") and method.__is_router__:
+        if method_definition.router:
             node_metadata["is_router"] = True
             node_metadata["type"] = "router"
             router_methods.append(method_name)
+            router_events = _method_router_events(method_definition)
+            if router_events:
+                node_metadata["router_events"] = router_events
 
-            if method_name in flow._router_paths:
-                node_metadata["router_paths"] = [
-                    str(p) for p in flow._router_paths[method_name]
-                ]
-
-        if hasattr(method, "__trigger_methods__") and method.__trigger_methods__:
-            node_metadata["trigger_methods"] = [
-                str(m) for m in method.__trigger_methods__
-            ]
-
-        if hasattr(method, "__condition_type__") and method.__condition_type__:
-            node_metadata["trigger_condition_type"] = method.__condition_type__
-            if "condition_type" not in node_metadata:
-                node_metadata["condition_type"] = method.__condition_type__
+        trigger_condition = _method_trigger_condition(method_definition)
+        condition_type = _condition_type_from_definition(trigger_condition)
+        if condition_type is not None and trigger_condition is not None:
+            node_metadata["trigger_condition_type"] = condition_type
+            node_metadata["condition_type"] = condition_type
+            extracted = _extract_all_trigger_names(trigger_condition)
+            if extracted:
+                node_metadata["trigger_methods"] = extracted
+            runtime_condition = _runtime_condition_from_definition(trigger_condition)
+            if isinstance(runtime_condition, dict):
+                node_metadata["trigger_condition"] = runtime_condition
 
         if node_metadata.get("is_router") and "condition_type" not in node_metadata:
             node_metadata["condition_type"] = "IF"
 
-        if (
-            hasattr(method, "__trigger_condition__")
-            and method.__trigger_condition__ is not None
-        ):
-            node_metadata["trigger_condition"] = method.__trigger_condition__
-
-            if "trigger_methods" not in node_metadata:
-                extracted = _extract_all_trigger_names(method.__trigger_condition__)
-                if extracted:
-                    node_metadata["trigger_methods"] = extracted
-
-        node_metadata["method_signature"] = extract_method_signature(
-            method, method_name
-        )
-
-        try:
-            source_code = inspect.getsource(method)
-            node_metadata["source_code"] = source_code
-
-            try:
-                source_lines, start_line = inspect.getsourcelines(method)
-                node_metadata["source_lines"] = source_lines
-                node_metadata["source_start_line"] = start_line
-            except (OSError, TypeError):
-                pass
-
-            try:
-                source_file = inspect.getsourcefile(method)
-                if source_file:
-                    node_metadata["source_file"] = source_file
-            except (OSError, TypeError):
-                try:
-                    class_file = inspect.getsourcefile(flow.__class__)
-                    if class_file:
-                        node_metadata["source_file"] = class_file
-                except (OSError, TypeError):
-                    pass
-        except (OSError, TypeError):
-            pass
-
-        try:
-            class_obj = flow.__class__
-
-            if class_obj:
-                class_name = class_obj.__name__
-
-                bases = class_obj.__bases__
-                if bases:
-                    base_strs = []
-                    for base in bases:
-                        if hasattr(base, "__name__"):
-                            if hasattr(base, "__origin__"):
-                                base_strs.append(str(base))
-                            else:
-                                base_strs.append(base.__name__)
-                        else:
-                            base_strs.append(str(base))
-
-                    try:
-                        source_lines = inspect.getsource(class_obj).split("\n")
-                        _, class_start_line = inspect.getsourcelines(class_obj)
-
-                        for idx, line in enumerate(source_lines):
-                            stripped = line.strip()
-                            if stripped.startswith("class ") and class_name in stripped:
-                                class_signature = stripped.rstrip(":")
-                                node_metadata["class_signature"] = class_signature
-                                node_metadata["class_line_number"] = (
-                                    class_start_line + idx
-                                )
-                                break
-                    except (OSError, TypeError):
-                        class_signature = f"class {class_name}({', '.join(base_strs)})"
-                        node_metadata["class_signature"] = class_signature
-                else:
-                    class_signature = f"class {class_name}"
-                    node_metadata["class_signature"] = class_signature
-
-                node_metadata["class_name"] = class_name
-        except (OSError, TypeError, AttributeError):
-            pass
-
         nodes[method_name] = node_metadata
 
-    for listener_name, condition_data in flow._listeners.items():
-        if listener_name in router_methods:
+    for method_name, method_definition in definition.methods.items():
+        trigger_condition = _method_trigger_condition(method_definition)
+        if trigger_condition is None:
             continue
-
-        if is_simple_flow_condition(condition_data):
-            cond_type, methods = condition_data
-            edges.extend(
-                StructureEdge(
-                    source=str(trigger_method),
-                    target=str(listener_name),
-                    condition_type=cond_type,
-                    is_router_path=False,
-                )
-                for trigger_method in methods
-                if str(trigger_method) in nodes
-            )
-        elif is_flow_condition_dict(condition_data):
-            edges.extend(
-                _create_edges_from_condition(condition_data, str(listener_name), nodes)
-            )
-
-    for method_name, node_metadata in nodes.items():  # type: ignore[assignment]
-        if node_metadata.get("is_router") and "trigger_methods" in node_metadata:
-            trigger_methods = node_metadata["trigger_methods"]
-            condition_type = node_metadata.get("trigger_condition_type", OR_CONDITION)
-
-            if "trigger_condition" in node_metadata:
-                edges.extend(
-                    _create_edges_from_condition(
-                        node_metadata["trigger_condition"],  # type: ignore[arg-type]
-                        method_name,
-                        nodes,
-                    )
-                )
-            else:
-                edges.extend(
-                    StructureEdge(
-                        source=trigger_method,
-                        target=method_name,
-                        condition_type=condition_type,
-                        is_router_path=False,
-                    )
-                    for trigger_method in trigger_methods
-                    if trigger_method in nodes
-                )
+        edges.extend(
+            _create_edges_from_condition(trigger_condition, method_name, nodes)
+        )
 
     all_string_triggers: set[str] = set()
-    for condition_data in flow._listeners.values():
-        if is_simple_flow_condition(condition_data):
-            _, methods = condition_data
-            for m in methods:
-                if str(m) not in nodes:  # It's a string trigger, not a method name
-                    all_string_triggers.add(str(m))
-        elif is_flow_condition_dict(condition_data):
-            for trigger in _extract_direct_or_triggers(condition_data):
-                if trigger not in nodes:
-                    all_string_triggers.add(trigger)
+    for method_definition in definition.methods.values():
+        trigger_condition = _method_trigger_condition(method_definition)
+        if trigger_condition is None:
+            continue
+        for trigger in _extract_direct_or_triggers(trigger_condition):
+            if trigger not in nodes:
+                all_string_triggers.add(trigger)
 
-    all_router_outputs: set[str] = set()
+    all_router_events: set[str] = set()
     for router_method_name in router_methods:
-        if router_method_name not in flow._router_paths:
-            flow._router_paths[FlowMethodName(router_method_name)] = []
+        router_events = _method_router_events(definition.methods[router_method_name])
+        if router_events and router_method_name in nodes:
+            nodes[router_method_name]["router_events"] = router_events
+            all_router_events.update(router_events)
 
-        current_paths = flow._router_paths.get(FlowMethodName(router_method_name), [])
-        if current_paths and router_method_name in nodes:
-            nodes[router_method_name]["router_paths"] = [str(p) for p in current_paths]
-            all_router_outputs.update(str(p) for p in current_paths)
-
-        if not current_paths:
+        if not router_events:
             logger.warning(
-                f"Could not determine return paths for router '{router_method_name}'. "
-                f"Add a return type annotation like "
-                f"'-> Literal[\"path1\", \"path2\"]' or '-> YourEnum' "
-                f"to enable proper flow visualization."
+                f"Router events for '{router_method_name}' are dynamic or not "
+                f"statically inferable; static visualization may omit event edges."
             )
 
-    orphaned_triggers = all_string_triggers - all_router_outputs
+    orphaned_triggers = all_string_triggers - all_router_events
     if orphaned_triggers:
-        logger.error(
-            f"Found listeners waiting for triggers {orphaned_triggers} "
-            f"but no router outputs these values explicitly. "
-            f"If your router returns a non-static value, check that your router has proper return type annotations."
+        logger.warning(
+            f"Static visualization could not match listener triggers "
+            f"{orphaned_triggers} to explicit router events. "
+            f"Dynamic router values may still trigger these listeners at runtime."
         )
 
     for router_method_name in router_methods:
-        if router_method_name not in flow._router_paths:
-            continue
+        router_events = _method_router_events(definition.methods[router_method_name])
 
-        router_paths = flow._router_paths[FlowMethodName(router_method_name)]
-
-        for path in router_paths:
-            for listener_name, condition_data in flow._listeners.items():
+        for event in router_events:
+            for listener_name, method_definition in definition.methods.items():
                 if listener_name == router_method_name:
                     continue
 
-                trigger_strings_from_cond: list[str] = []
+                trigger_condition = _method_trigger_condition(method_definition)
+                if trigger_condition is None:
+                    continue
+                trigger_strings_from_cond = _extract_direct_or_triggers(
+                    trigger_condition
+                )
 
-                if is_simple_flow_condition(condition_data):
-                    _, methods = condition_data
-                    trigger_strings_from_cond = [str(m) for m in methods]
-                elif is_flow_condition_dict(condition_data):
-                    trigger_strings_from_cond = _extract_direct_or_triggers(
-                        condition_data
-                    )
-
-                if str(path) in trigger_strings_from_cond:
+                if str(event) in trigger_strings_from_cond:
                     edges.append(
                         StructureEdge(
                             source=router_method_name,
-                            target=str(listener_name),
+                            target=listener_name,
                             condition_type=None,
-                            is_router_path=True,
-                            router_path_label=str(path),
+                            is_router_event=True,
+                            router_event=str(event),
                         )
                     )
 
-    for start_method in flow._start_methods:
-        if start_method not in nodes and start_method in flow._methods:
-            method = flow._methods[start_method]
-            nodes[str(start_method)] = NodeMetadata(type="start")
-
-            if hasattr(method, "__trigger_methods__") and method.__trigger_methods__:
-                nodes[str(start_method)]["trigger_methods"] = [
-                    str(m) for m in method.__trigger_methods__
-                ]
-            if hasattr(method, "__condition_type__") and method.__condition_type__:
-                nodes[str(start_method)]["condition_type"] = method.__condition_type__
-
     return FlowStructure(
         nodes=nodes,
         edges=edges,
@@ -453,7 +294,7 @@ def calculate_execution_paths(structure: FlowStructure) -> int:
         graph[edge["source"]].append(
             {
                 "target": edge["target"],
-                "is_router": edge["is_router_path"],
+                "is_router": edge["is_router_event"],
                 "condition": edge["condition_type"],
             }
         )
@@ -466,15 +307,6 @@ def calculate_execution_paths(structure: FlowStructure) -> int:
         return 0
 
     def count_paths_from(node: str, visited: set[str]) -> int:
-        """Recursively count execution paths from a given node.
-
-        Args:
-            node: Node name to start counting from.
-            visited: Set of already visited nodes to prevent cycles.
-
-        Returns:
-            Number of execution paths from this node to terminal nodes.
-        """
         if node in terminal_nodes:
             return 1
 

lib/crewai/src/crewai/flow/visualization/renderers/interactive.py

@@ -309,18 +309,18 @@ def render_interactive(
                 </div>
             """)
 
-        if metadata.get("router_paths"):
-            paths = metadata["router_paths"]
-            paths_items = "".join(
+        if metadata.get("router_events"):
+            router_events = metadata["router_events"]
+            event_items = "".join(
                 [
                     f'<li style="margin: 3px 0;"><code style="background: rgba(255,90,80,0.08); padding: 2px 6px; border-radius: 3px; font-size: 10px; color: {CREWAI_ORANGE}; border: 1px solid rgba(255,90,80,0.2); font-weight: 600;">{p}</code></li>'
-                    for p in paths
+                    for p in router_events
                 ]
             )
             title_parts.append(f"""
                 <div>
-                    <div style="font-size: 10px; text-transform: uppercase; color: {GRAY}; letter-spacing: 0.5px; margin-bottom: 4px; font-weight: 600;">Router Paths</div>
-                    <ul style="list-style: none; padding: 0; margin: 0;">{paths_items}</ul>
+                    <div style="font-size: 10px; text-transform: uppercase; color: {GRAY}; letter-spacing: 0.5px; margin-bottom: 4px; font-weight: 600;">Router Events</div>
+                    <ul style="list-style: none; padding: 0; margin: 0;">{event_items}</ul>
                 </div>
             """)
 
@@ -364,11 +364,11 @@ def render_interactive(
         edge_color: str = GRAY
         edge_dashes: bool | list[int] = False
 
-        if edge["is_router_path"]:
+        if edge["is_router_event"]:
             edge_color = CREWAI_ORANGE
             edge_dashes = [15, 10]
-            if "router_path_label" in edge:
-                edge_label = edge["router_path_label"]
+            if "router_event" in edge:
+                edge_label = edge["router_event"] or ""
         elif edge["condition_type"] == "AND":
             edge_label = "AND"
             edge_color = CREWAI_ORANGE

lib/crewai/src/crewai/flow/visualization/schema.py

@@ -1,104 +0,0 @@
-"""OpenAPI schema conversion utilities for Flow methods."""
-
-import inspect
-from typing import Any, get_args, get_origin
-
-
-def type_to_openapi_schema(type_hint: Any) -> dict[str, Any]:
-    """Convert Python type hint to OpenAPI schema.
-
-    Args:
-        type_hint: Python type hint to convert.
-
-    Returns:
-        OpenAPI schema dictionary.
-    """
-    if type_hint is inspect.Parameter.empty:
-        return {}
-
-    if type_hint is None or type_hint is type(None):
-        return {"type": "null"}
-
-    if hasattr(type_hint, "__module__") and hasattr(type_hint, "__name__"):
-        if type_hint.__module__ == "typing" and type_hint.__name__ == "Any":
-            return {}
-
-    type_str = str(type_hint)
-    if type_str == "typing.Any" or type_str == "<class 'typing.Any'>":
-        return {}
-
-    if isinstance(type_hint, str):
-        return {"type": type_hint}
-
-    origin = get_origin(type_hint)
-    args = get_args(type_hint)
-
-    if type_hint is str:
-        return {"type": "string"}
-    if type_hint is int:
-        return {"type": "integer"}
-    if type_hint is float:
-        return {"type": "number"}
-    if type_hint is bool:
-        return {"type": "boolean"}
-    if type_hint is dict or origin is dict:
-        if args and len(args) > 1:
-            return {
-                "type": "object",
-                "additionalProperties": type_to_openapi_schema(args[1]),
-            }
-        return {"type": "object"}
-    if type_hint is list or origin is list:
-        if args:
-            return {"type": "array", "items": type_to_openapi_schema(args[0])}
-        return {"type": "array"}
-    if hasattr(type_hint, "__name__"):
-        return {"type": "object", "className": type_hint.__name__}
-
-    return {}
-
-
-def extract_method_signature(method: Any, method_name: str) -> dict[str, Any]:
-    """Extract method signature as OpenAPI schema with documentation.
-
-    Args:
-        method: Method to analyze.
-        method_name: Method name.
-
-    Returns:
-        Dictionary with operationId, parameters, returns, summary, and description.
-    """
-    try:
-        sig = inspect.signature(method)
-
-        parameters = {}
-        for param_name, param in sig.parameters.items():
-            if param_name == "self":
-                continue
-            parameters[param_name] = type_to_openapi_schema(param.annotation)
-
-        return_type = type_to_openapi_schema(sig.return_annotation)
-
-        docstring = inspect.getdoc(method)
-
-        result: dict[str, Any] = {
-            "operationId": method_name,
-            "parameters": parameters,
-            "returns": return_type,
-        }
-
-        if docstring:
-            lines = docstring.strip().split("\n")
-            summary = lines[0].strip()
-
-            if summary:
-                result["summary"] = summary
-
-            if len(lines) > 1:
-                description = "\n".join(line.strip() for line in lines[1:]).strip()
-                if description:
-                    result["description"] = description
-
-        return result
-    except Exception:
-        return {"operationId": method_name, "parameters": {}, "returns": {}}

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

@@ -1,6 +1,11 @@
 """Type definitions for Flow structure visualization."""
 
-from typing import Any, TypedDict
+from typing import Any
+
+from typing_extensions import Required, TypedDict
+
+
+__all__ = ["FlowStructure", "NodeMetadata", "StructureEdge"]
 
 
 class NodeMetadata(TypedDict, total=False):
@@ -8,19 +13,12 @@ class NodeMetadata(TypedDict, total=False):
 
     type: str
     is_router: bool
-    router_paths: list[str]
+    router_events: list[str]
     condition_type: str | None
     trigger_condition_type: str | None
     trigger_methods: list[str]
     trigger_condition: dict[str, Any] | None
-    method_signature: dict[str, Any]
-    source_code: str
-    source_lines: list[str]
-    source_start_line: int
-    source_file: str
-    class_signature: str
     class_name: str
-    class_line_number: int
 
 
 class StructureEdge(TypedDict, total=False):
@@ -29,8 +27,8 @@ class StructureEdge(TypedDict, total=False):
     source: str
     target: str
     condition_type: str | None
-    is_router_path: bool
-    router_path_label: str
+    is_router_event: Required[bool]
+    router_event: str | None
 
 
 class FlowStructure(TypedDict):

lib/crewai/src/crewai/llm.py

@@ -23,7 +23,6 @@ from crewai.events.event_bus import crewai_event_bus
 from crewai.events.types.llm_events import (
     LLMCallCompletedEvent,
     LLMCallFailedEvent,
-    LLMCallStartedEvent,
     LLMCallType,
     LLMStreamChunkEvent,
 )
@@ -32,6 +31,7 @@ from crewai.events.types.tool_usage_events import (
     ToolUsageFinishedEvent,
     ToolUsageStartedEvent,
 )
+from crewai.llms._finish_reason_utils import extract_choices_finish_reason_and_id
 from crewai.llms.base_llm import (
     BaseLLM,
     JsonResponseFormat,
@@ -732,6 +732,11 @@ class LLM(BaseLLM):
         last_chunk = None
         chunk_count = 0
         usage_info = None
+        # Tracked across the loop: LiteLLM with include_usage emits a final
+        # usage-only chunk with empty choices, so the post-loop last_chunk has
+        # no finish_reason. Capture both incrementally instead.
+        stream_finish_reason: str | None = None
+        stream_response_id: str | None = None
 
         accumulated_tool_args: defaultdict[int, AccumulatedToolArgs] = defaultdict(
             AccumulatedToolArgs
@@ -750,6 +755,16 @@ class LLM(BaseLLM):
 
                 if isinstance(chunk, ModelResponseBase):
                     response_id = chunk.id
+                elif isinstance(chunk, dict):
+                    response_id = chunk.get("id")
+
+                chunk_finish, chunk_id = self._extract_finish_reason_and_response_id(
+                    chunk
+                )
+                if chunk_finish:
+                    stream_finish_reason = chunk_finish
+                if chunk_id and not stream_response_id:
+                    stream_response_id = chunk_id
 
                 try:
                     choices = None
@@ -922,6 +937,11 @@ class LLM(BaseLLM):
                 if tool_calls_list:
                     return tool_calls_list
 
+            finish_reason, response_id_last = (
+                stream_finish_reason,
+                stream_response_id,
+            )
+
             if not tool_calls or not available_functions:
                 if response_model and self.is_litellm:
                     instructor_instance = InternalInstructor(
@@ -939,6 +959,8 @@ class LLM(BaseLLM):
                         from_agent=from_agent,
                         messages=params["messages"],
                         usage=usage_dict,
+                        finish_reason=finish_reason,
+                        response_id=response_id_last,
                     )
                     return structured_response
 
@@ -950,6 +972,8 @@ class LLM(BaseLLM):
                     from_agent=from_agent,
                     messages=params["messages"],
                     usage=usage_dict,
+                    finish_reason=finish_reason,
+                    response_id=response_id_last,
                 )
                 return full_response
 
@@ -965,6 +989,8 @@ class LLM(BaseLLM):
                 from_agent=from_agent,
                 messages=params["messages"],
                 usage=usage_dict,
+                finish_reason=finish_reason,
+                response_id=response_id_last,
             )
             return full_response
 
@@ -978,6 +1004,10 @@ class LLM(BaseLLM):
             logging.error(f"Error in streaming response: {e!s}")
             if full_response.strip():
                 logging.warning(f"Returning partial response despite error: {e!s}")
+                finish_reason, response_id_last = (
+                    stream_finish_reason,
+                    stream_response_id,
+                )
                 self._handle_emit_call_events(
                     response=full_response,
                     call_type=LLMCallType.LLM_CALL,
@@ -985,6 +1015,8 @@ class LLM(BaseLLM):
                     from_agent=from_agent,
                     messages=params["messages"],
                     usage=self._usage_to_dict(usage_info),
+                    finish_reason=finish_reason,
+                    response_id=response_id_last,
                 )
                 return full_response
 
@@ -1169,6 +1201,10 @@ class LLM(BaseLLM):
             else None
         )
 
+        finish_reason, response_id = self._extract_finish_reason_and_response_id(
+            response
+        )
+
         if response_model is not None:
             # When using instructor/response_model, litellm returns a Pydantic model instance
             if isinstance(response, BaseModel):
@@ -1180,6 +1216,8 @@ class LLM(BaseLLM):
                     from_agent=from_agent,
                     messages=params["messages"],
                     usage=response_usage,
+                    finish_reason=finish_reason,
+                    response_id=response_id,
                 )
                 return structured_response
 
@@ -1216,6 +1254,8 @@ class LLM(BaseLLM):
                 from_agent=from_agent,
                 messages=params["messages"],
                 usage=response_usage,
+                finish_reason=finish_reason,
+                response_id=response_id,
             )
             return text_response
 
@@ -1233,6 +1273,8 @@ class LLM(BaseLLM):
             from_agent=from_agent,
             messages=params["messages"],
             usage=response_usage,
+            finish_reason=finish_reason,
+            response_id=response_id,
         )
         return text_response
 
@@ -1310,6 +1352,10 @@ class LLM(BaseLLM):
             else None
         )
 
+        finish_reason, response_id = self._extract_finish_reason_and_response_id(
+            response
+        )
+
         if response_model is not None:
             if isinstance(response, BaseModel):
                 structured_response = response.model_dump_json()
@@ -1320,6 +1366,8 @@ class LLM(BaseLLM):
                     from_agent=from_agent,
                     messages=params["messages"],
                     usage=response_usage,
+                    finish_reason=finish_reason,
+                    response_id=response_id,
                 )
                 return structured_response
 
@@ -1358,6 +1406,8 @@ class LLM(BaseLLM):
                 from_agent=from_agent,
                 messages=params["messages"],
                 usage=response_usage,
+                finish_reason=finish_reason,
+                response_id=response_id,
             )
             return text_response
 
@@ -1375,6 +1425,8 @@ class LLM(BaseLLM):
             from_agent=from_agent,
             messages=params["messages"],
             usage=response_usage,
+            finish_reason=finish_reason,
+            response_id=response_id,
         )
         return text_response
 
@@ -1412,12 +1464,29 @@ class LLM(BaseLLM):
         params["stream"] = True
         params["stream_options"] = {"include_usage": True}
         response_id = None
+        # See sync sibling: incrementally track finish_reason/response_id so the
+        # usage-only final chunk doesn't wipe them.
+        stream_finish_reason: str | None = None
+        stream_response_id: str | None = None
 
         try:
             async for chunk in await litellm.acompletion(**params):
                 chunk_count += 1
                 chunk_content = None
-                response_id = chunk.id if isinstance(chunk, ModelResponseBase) else None
+                if isinstance(chunk, ModelResponseBase):
+                    response_id = chunk.id
+                elif isinstance(chunk, dict):
+                    response_id = chunk.get("id")
+                else:
+                    response_id = None
+
+                chunk_finish, chunk_id = self._extract_finish_reason_and_response_id(
+                    chunk
+                )
+                if chunk_finish:
+                    stream_finish_reason = chunk_finish
+                if chunk_id and not stream_response_id:
+                    stream_response_id = chunk_id
 
                 try:
                     choices = None
@@ -1525,6 +1594,10 @@ class LLM(BaseLLM):
                         return tool_calls_list
 
             usage_dict = self._usage_to_dict(usage_info)
+            finish_reason, response_id_last = (
+                stream_finish_reason,
+                stream_response_id,
+            )
             self._handle_emit_call_events(
                 response=full_response,
                 call_type=LLMCallType.LLM_CALL,
@@ -1532,6 +1605,8 @@ class LLM(BaseLLM):
                 from_agent=from_agent,
                 messages=params.get("messages"),
                 usage=usage_dict,
+                finish_reason=finish_reason,
+                response_id=response_id_last,
             )
             return full_response
 
@@ -1545,6 +1620,10 @@ class LLM(BaseLLM):
             if chunk_count == 0:
                 raise
             if full_response:
+                finish_reason, response_id_last = (
+                    stream_finish_reason,
+                    stream_response_id,
+                )
                 self._handle_emit_call_events(
                     response=full_response,
                     call_type=LLMCallType.LLM_CALL,
@@ -1552,6 +1631,8 @@ class LLM(BaseLLM):
                     from_agent=from_agent,
                     messages=params.get("messages"),
                     usage=self._usage_to_dict(usage_info),
+                    finish_reason=finish_reason,
+                    response_id=response_id_last,
                 )
                 return full_response
             raise
@@ -1678,19 +1759,14 @@ class LLM(BaseLLM):
             ValueError: If response format is not supported
             LLMContextLengthExceededError: If input exceeds model's context limit
         """
-        with llm_call_context() as call_id:
-            crewai_event_bus.emit(
-                self,
-                event=LLMCallStartedEvent(
-                    messages=messages,
-                    tools=tools,
-                    callbacks=callbacks,
-                    available_functions=available_functions,
-                    from_task=from_task,
-                    from_agent=from_agent,
-                    model=self.model,
-                    call_id=call_id,
-                ),
+        with llm_call_context():
+            self._emit_call_started_event(
+                messages=messages,
+                tools=tools,
+                callbacks=callbacks,
+                available_functions=available_functions,
+                from_task=from_task,
+                from_agent=from_agent,
             )
 
             self._validate_call_params()
@@ -1822,19 +1898,14 @@ class LLM(BaseLLM):
             ValueError: If response format is not supported
             LLMContextLengthExceededError: If input exceeds model's context limit
         """
-        with llm_call_context() as call_id:
-            crewai_event_bus.emit(
-                self,
-                event=LLMCallStartedEvent(
-                    messages=messages,
-                    tools=tools,
-                    callbacks=callbacks,
-                    available_functions=available_functions,
-                    from_task=from_task,
-                    from_agent=from_agent,
-                    model=self.model,
-                    call_id=call_id,
-                ),
+        with llm_call_context():
+            self._emit_call_started_event(
+                messages=messages,
+                tools=tools,
+                callbacks=callbacks,
+                available_functions=available_functions,
+                from_task=from_task,
+                from_agent=from_agent,
             )
 
             self._validate_call_params()
@@ -1925,16 +1996,62 @@ class LLM(BaseLLM):
 
     @staticmethod
     def _usage_to_dict(usage: Any) -> dict[str, Any] | None:
+        """Convert a provider usage object to a plain dict and flatten the
+        cache/reasoning sub-counts that LiteLLM nests under provider-specific
+        shapes into the top-level keys the rest of the pipeline expects.
+
+        LiteLLM hands back provider usage as-is, so cache-read, cache-creation
+        and reasoning tokens may live in nested objects (e.g.
+        ``prompt_tokens_details.cached_tokens``) or under Anthropic-style keys
+        (``cache_read_input_tokens``). Downstream span mapping only reads the
+        flat ``cached_prompt_tokens`` / ``reasoning_tokens`` /
+        ``cache_creation_tokens`` keys, so we surface them here.
+
+        Only those derived buckets are populated; ``prompt_tokens`` /
+        ``completion_tokens`` / ``total_tokens`` are left untouched. Extraction
+        precedence mirrors ``BaseLLM._track_token_usage_internal``.
+        """
         if usage is None:
             return None
         if isinstance(usage, dict):
-            return usage
-        if isinstance(usage, BaseModel):
-            result: dict[str, Any] = usage.model_dump()
-            return result
-        if hasattr(usage, "__dict__"):
-            return {k: v for k, v in vars(usage).items() if not k.startswith("_")}
-        return None
+            data: dict[str, Any] = dict(usage)
+        elif isinstance(usage, BaseModel):
+            data = usage.model_dump()
+        elif hasattr(usage, "__dict__"):
+            data = {k: v for k, v in vars(usage).items() if not k.startswith("_")}
+        else:
+            return None
+
+        def _nested(container: Any, key: str) -> Any:
+            if isinstance(container, dict):
+                return container.get(key)
+            return getattr(container, key, None)
+
+        prompt_details = data.get("prompt_tokens_details")
+        completion_details = data.get("completion_tokens_details")
+
+        cached_prompt_tokens = (
+            data.get("cached_tokens")
+            or data.get("cached_prompt_tokens")
+            or data.get("cache_read_input_tokens")
+            or _nested(prompt_details, "cached_tokens")
+        )
+        if cached_prompt_tokens is not None:
+            data["cached_prompt_tokens"] = cached_prompt_tokens
+
+        reasoning_tokens = data.get("reasoning_tokens") or _nested(
+            completion_details, "reasoning_tokens"
+        )
+        if reasoning_tokens is not None:
+            data["reasoning_tokens"] = reasoning_tokens
+
+        cache_creation_tokens = data.get("cache_creation_tokens") or data.get(
+            "cache_creation_input_tokens"
+        )
+        if cache_creation_tokens is not None:
+            data["cache_creation_tokens"] = cache_creation_tokens
+
+        return data
 
     def _handle_emit_call_events(
         self,
@@ -1944,6 +2061,8 @@ class LLM(BaseLLM):
         from_agent: BaseAgent | None = None,
         messages: str | list[LLMMessage] | None = None,
         usage: dict[str, Any] | None = None,
+        finish_reason: str | None = None,
+        response_id: str | None = None,
     ) -> None:
         """Handle the events for the LLM call.
 
@@ -1954,6 +2073,10 @@ class LLM(BaseLLM):
             from_agent: Optional agent object
             messages: Optional messages object
             usage: Optional token usage data
+            finish_reason: Raw provider finish reason (e.g. "stop", "length",
+                "tool_calls"). Optional; downstream telemetry coerces to the
+                OTel GenAI enum.
+            response_id: Raw provider response identifier. Optional.
         """
         crewai_event_bus.emit(
             self,
@@ -1966,9 +2089,24 @@ class LLM(BaseLLM):
                 model=self.model,
                 call_id=get_current_call_id(),
                 usage=usage,
+                finish_reason=finish_reason,
+                response_id=response_id,
             ),
         )
 
+    def _effective_max_tokens(self) -> int | float | None:
+        """LiteLLM sends ``max_tokens or max_completion_tokens`` as the cap."""
+        return self.max_tokens or self.max_completion_tokens
+
+    @staticmethod
+    def _extract_finish_reason_and_response_id(
+        response_or_chunk: Any,
+    ) -> tuple[str | None, str | None]:
+        """LiteLLM responses/chunks share the choices-shape with OpenAI/Azure;
+        delegate to the shared extractor.
+        """
+        return extract_choices_finish_reason_and_id(response_or_chunk)
+
     def _process_message_files(self, messages: list[LLMMessage]) -> list[LLMMessage]:
         """Process files attached to messages and format for provider.
 

lib/crewai/src/crewai/llms/_finish_reason_utils.py

@@ -0,0 +1,55 @@
+"""Shared extractors for ``finish_reason`` + ``response_id`` across LLM providers.
+
+OpenAI Chat Completions, Azure AI Inference, and LiteLLM all expose the same
+choices-based response shape (``response.id`` + ``response.choices[0].finish_reason``),
+both as object attributes and (for LiteLLM stream chunks) as dict keys. This
+module centralises that introspection so every provider doesn't reinvent the
+defensive walk. Providers with genuinely different shapes — Anthropic
+(``stop_reason``), Bedrock (``stopReason``), Gemini (protobuf enum), OpenAI
+Responses (``status``) — keep their own helpers.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def _as_str(value: Any) -> str | None:
+    return value if isinstance(value, str) else None
+
+
+def extract_choices_finish_reason_and_id(
+    response_or_chunk: Any,
+) -> tuple[str | None, str | None]:
+    """Extract ``(finish_reason, response_id)`` from a choices-shaped response.
+
+    Handles both object-style (``response.id``, ``response.choices[0].finish_reason``)
+    and dict-style (``response["id"]``, ``response["choices"][0]["finish_reason"]``)
+    inputs. Returns ``(None, None)`` on any failure; never raises. Non-string
+    raw values are coerced to ``None`` so test mocks and exotic provider types
+    (MagicMock, protobuf enums, etc.) don't propagate downstream.
+    """
+    raw_id = getattr(response_or_chunk, "id", None)
+    if raw_id is None and isinstance(response_or_chunk, dict):
+        raw_id = response_or_chunk.get("id")
+    response_id = _as_str(raw_id)
+
+    if isinstance(response_or_chunk, dict):
+        choices = response_or_chunk.get("choices")
+    else:
+        choices = getattr(response_or_chunk, "choices", None)
+
+    finish_reason: str | None = None
+    if choices:
+        try:
+            first = choices[0]
+        except (IndexError, TypeError, KeyError):
+            first = None
+        if first is not None:
+            if isinstance(first, dict):
+                raw_finish = first.get("finish_reason")
+            else:
+                raw_finish = getattr(first, "finish_reason", None)
+            finish_reason = _as_str(raw_finish)
+
+    return finish_reason, response_id

lib/crewai/src/crewai/llms/base_llm.py

@@ -150,6 +150,13 @@ class BaseLLM(BaseModel, ABC):
     llm_type: str = "base"
     model: str
     temperature: float | None = None
+    top_p: float | None = None
+    max_tokens: int | float | None = None
+    stream: bool | None = None
+    seed: int | None = None
+    frequency_penalty: float | None = None
+    presence_penalty: float | None = None
+    n: int | None = None
     api_key: str | None = None
     base_url: str | None = None
     provider: str = Field(default="openai")
@@ -464,6 +471,16 @@ class BaseLLM(BaseModel, ABC):
         """
         return None
 
+    def _effective_max_tokens(self) -> int | float | None:
+        """Token cap actually sent to the provider, for start-event telemetry.
+
+        Defaults to ``self.max_tokens``. Providers that cap generation through a
+        differently named field (e.g. ``max_completion_tokens`` on OpenAI/Azure,
+        ``max_output_tokens`` on Gemini) override this so ``LLMCallStartedEvent``
+        reports the real limit instead of ``None``.
+        """
+        return self.max_tokens
+
     def _emit_call_started_event(
         self,
         messages: str | list[LLMMessage],
@@ -472,10 +489,38 @@ class BaseLLM(BaseModel, ABC):
         available_functions: dict[str, Any] | None = None,
         from_task: Task | None = None,
         from_agent: BaseAgent | None = None,
+        temperature: float | None = None,
+        top_p: float | None = None,
+        max_tokens: int | float | None = None,
+        stream: bool | None = None,
+        seed: int | None = None,
+        stop_sequences: list[str] | None = None,
+        frequency_penalty: float | None = None,
+        presence_penalty: float | None = None,
+        n: int | None = None,
     ) -> None:
         """Emit LLM call started event."""
         from crewai.utilities.serialization import to_serializable
 
+        if temperature is None:
+            temperature = self.temperature
+        if top_p is None:
+            top_p = self.top_p
+        if max_tokens is None:
+            max_tokens = self._effective_max_tokens()
+        if stream is None:
+            stream = self.stream
+        if seed is None:
+            seed = self.seed
+        if stop_sequences is None:
+            stop_sequences = self.stop_sequences or None
+        if frequency_penalty is None:
+            frequency_penalty = self.frequency_penalty
+        if presence_penalty is None:
+            presence_penalty = self.presence_penalty
+        if n is None:
+            n = self.n
+
         crewai_event_bus.emit(
             self,
             event=LLMCallStartedEvent(
@@ -487,6 +532,15 @@ class BaseLLM(BaseModel, ABC):
                 from_agent=from_agent,
                 model=self.model,
                 call_id=get_current_call_id(),
+                temperature=temperature,
+                top_p=top_p,
+                max_tokens=max_tokens,
+                stream=stream,
+                seed=seed,
+                stop_sequences=stop_sequences,
+                frequency_penalty=frequency_penalty,
+                presence_penalty=presence_penalty,
+                n=n,
             ),
         )
 
@@ -498,6 +552,8 @@ class BaseLLM(BaseModel, ABC):
         from_agent: BaseAgent | None = None,
         messages: str | list[LLMMessage] | None = None,
         usage: dict[str, Any] | None = None,
+        finish_reason: str | None = None,
+        response_id: str | None = None,
     ) -> None:
         """Emit LLM call completed event."""
         from crewai.utilities.serialization import to_serializable
@@ -513,6 +569,8 @@ class BaseLLM(BaseModel, ABC):
                 model=self.model,
                 call_id=get_current_call_id(),
                 usage=usage,
+                finish_reason=finish_reason,
+                response_id=response_id,
             ),
         )
 

lib/crewai/src/crewai/llms/providers/anthropic/completion.py

@@ -923,6 +923,8 @@ class AnthropicCompletion(BaseLLM):
         usage = self._extract_anthropic_token_usage(response)
         self._track_token_usage_internal(usage)
 
+        finish_reason, response_id = self._extract_finish_reason_and_id(response)
+
         if _is_pydantic_model_class(response_model) and response.content:
             if use_native_structured_output:
                 for block in response.content:
@@ -935,6 +937,8 @@ class AnthropicCompletion(BaseLLM):
                             from_agent=from_agent,
                             messages=params["messages"],
                             usage=usage,
+                            finish_reason=finish_reason,
+                            response_id=response_id,
                         )
                         return structured_data
             else:
@@ -951,6 +955,8 @@ class AnthropicCompletion(BaseLLM):
                             from_agent=from_agent,
                             messages=params["messages"],
                             usage=usage,
+                            finish_reason=finish_reason,
+                            response_id=response_id,
                         )
                         return structured_data
 
@@ -973,6 +979,8 @@ class AnthropicCompletion(BaseLLM):
                         from_agent=from_agent,
                         messages=params["messages"],
                         usage=usage,
+                        finish_reason=finish_reason,
+                        response_id=response_id,
                     )
                     return list(tool_uses)
 
@@ -1005,6 +1013,8 @@ class AnthropicCompletion(BaseLLM):
             from_agent=from_agent,
             messages=params["messages"],
             usage=usage,
+            finish_reason=finish_reason,
+            response_id=response_id,
         )
 
         if usage.get("total_tokens", 0) > 0:
@@ -1147,6 +1157,10 @@ class AnthropicCompletion(BaseLLM):
         usage = self._extract_anthropic_token_usage(final_message)
         self._track_token_usage_internal(usage)
 
+        finish_reason, final_response_id = self._extract_finish_reason_and_id(
+            final_message
+        )
+
         if _is_pydantic_model_class(response_model):
             if use_native_structured_output:
                 structured_data = response_model.model_validate_json(full_response)
@@ -1157,6 +1171,8 @@ class AnthropicCompletion(BaseLLM):
                     from_agent=from_agent,
                     messages=params["messages"],
                     usage=usage,
+                    finish_reason=finish_reason,
+                    response_id=final_response_id,
                 )
                 return structured_data
             for block in final_message.content:
@@ -1172,6 +1188,8 @@ class AnthropicCompletion(BaseLLM):
                         from_agent=from_agent,
                         messages=params["messages"],
                         usage=usage,
+                        finish_reason=finish_reason,
+                        response_id=final_response_id,
                     )
                     return structured_data
 
@@ -1201,6 +1219,8 @@ class AnthropicCompletion(BaseLLM):
             from_agent=from_agent,
             messages=params["messages"],
             usage=usage,
+            finish_reason=finish_reason,
+            response_id=final_response_id,
         )
 
         return self._invoke_after_llm_call_hooks(
@@ -1361,6 +1381,10 @@ class AnthropicCompletion(BaseLLM):
 
             final_content = self._apply_stop_words(final_content)
 
+            finish_reason, final_response_id = self._extract_finish_reason_and_id(
+                final_response
+            )
+
             self._emit_call_completed_event(
                 response=final_content,
                 call_type=LLMCallType.LLM_CALL,
@@ -1368,6 +1392,8 @@ class AnthropicCompletion(BaseLLM):
                 from_agent=from_agent,
                 messages=follow_up_params["messages"],
                 usage=follow_up_usage,
+                finish_reason=finish_reason,
+                response_id=final_response_id,
             )
 
             total_usage = {
@@ -1447,6 +1473,8 @@ class AnthropicCompletion(BaseLLM):
         usage = self._extract_anthropic_token_usage(response)
         self._track_token_usage_internal(usage)
 
+        finish_reason, response_id = self._extract_finish_reason_and_id(response)
+
         if _is_pydantic_model_class(response_model) and response.content:
             if use_native_structured_output:
                 for block in response.content:
@@ -1459,6 +1487,8 @@ class AnthropicCompletion(BaseLLM):
                             from_agent=from_agent,
                             messages=params["messages"],
                             usage=usage,
+                            finish_reason=finish_reason,
+                            response_id=response_id,
                         )
                         return structured_data
             else:
@@ -1475,6 +1505,8 @@ class AnthropicCompletion(BaseLLM):
                             from_agent=from_agent,
                             messages=params["messages"],
                             usage=usage,
+                            finish_reason=finish_reason,
+                            response_id=response_id,
                         )
                         return structured_data
 
@@ -1495,6 +1527,8 @@ class AnthropicCompletion(BaseLLM):
                         from_agent=from_agent,
                         messages=params["messages"],
                         usage=usage,
+                        finish_reason=finish_reason,
+                        response_id=response_id,
                     )
                     return list(tool_uses)
 
@@ -1519,6 +1553,8 @@ class AnthropicCompletion(BaseLLM):
             from_agent=from_agent,
             messages=params["messages"],
             usage=usage,
+            finish_reason=finish_reason,
+            response_id=response_id,
         )
 
         if usage.get("total_tokens", 0) > 0:
@@ -1647,6 +1683,10 @@ class AnthropicCompletion(BaseLLM):
         usage = self._extract_anthropic_token_usage(final_message)
         self._track_token_usage_internal(usage)
 
+        finish_reason, final_response_id = self._extract_finish_reason_and_id(
+            final_message
+        )
+
         if _is_pydantic_model_class(response_model):
             if use_native_structured_output:
                 structured_data = response_model.model_validate_json(full_response)
@@ -1657,6 +1697,8 @@ class AnthropicCompletion(BaseLLM):
                     from_agent=from_agent,
                     messages=params["messages"],
                     usage=usage,
+                    finish_reason=finish_reason,
+                    response_id=final_response_id,
                 )
                 return structured_data
             for block in final_message.content:
@@ -1672,6 +1714,8 @@ class AnthropicCompletion(BaseLLM):
                         from_agent=from_agent,
                         messages=params["messages"],
                         usage=usage,
+                        finish_reason=finish_reason,
+                        response_id=final_response_id,
                     )
                     return structured_data
 
@@ -1701,6 +1745,8 @@ class AnthropicCompletion(BaseLLM):
             from_agent=from_agent,
             messages=params["messages"],
             usage=usage,
+            finish_reason=finish_reason,
+            response_id=final_response_id,
         )
 
         return full_response
@@ -1753,6 +1799,10 @@ class AnthropicCompletion(BaseLLM):
 
             final_content = self._apply_stop_words(final_content)
 
+            finish_reason, final_response_id = self._extract_finish_reason_and_id(
+                final_response
+            )
+
             self._emit_call_completed_event(
                 response=final_content,
                 call_type=LLMCallType.LLM_CALL,
@@ -1760,6 +1810,8 @@ class AnthropicCompletion(BaseLLM):
                 from_agent=from_agent,
                 messages=follow_up_params["messages"],
                 usage=follow_up_usage,
+                finish_reason=finish_reason,
+                response_id=final_response_id,
             )
 
             total_usage = {
@@ -1813,6 +1865,20 @@ class AnthropicCompletion(BaseLLM):
 
         return int(200000 * CONTEXT_WINDOW_USAGE_RATIO)
 
+    @staticmethod
+    def _extract_finish_reason_and_id(
+        message: Any,
+    ) -> tuple[str | None, str | None]:
+        """Extract raw finish_reason and response_id from an Anthropic
+        ``Message`` / ``BetaMessage``. Anthropic exposes ``stop_reason`` (e.g.
+        ``"end_turn"``, ``"max_tokens"``, ``"tool_use"``); we forward it raw
+        and let downstream telemetry map to the OTel GenAI enum.
+        """
+        return (
+            getattr(message, "stop_reason", None),
+            getattr(message, "id", None),
+        )
+
     @staticmethod
     def _extract_anthropic_token_usage(
         response: Message | BetaMessage,

lib/crewai/src/crewai/llms/providers/azure/completion.py

@@ -9,6 +9,7 @@ from urllib.parse import urlparse
 from pydantic import BaseModel, PrivateAttr, model_validator
 from typing_extensions import Self
 
+from crewai.llms._finish_reason_utils import extract_choices_finish_reason_and_id
 from crewai.llms.hooks.base import BaseInterceptor
 from crewai.utilities.agent_utils import is_context_length_exceeded
 from crewai.utilities.exceptions.context_window_exceeding_exception import (
@@ -783,6 +784,8 @@ class AzureCompletion(BaseLLM):
         from_task: Any | None = None,
         from_agent: Any | None = None,
         usage: dict[str, Any] | None = None,
+        finish_reason: str | None = None,
+        response_id: str | None = None,
     ) -> BaseModel:
         """Validate content against response model and emit completion event.
 
@@ -792,6 +795,8 @@ class AzureCompletion(BaseLLM):
             params: Completion parameters containing messages
             from_task: Task that initiated the call
             from_agent: Agent that initiated the call
+            finish_reason: Raw provider finish reason.
+            response_id: Raw provider response id.
 
         Returns:
             Validated Pydantic model instance
@@ -809,6 +814,8 @@ class AzureCompletion(BaseLLM):
                 from_agent=from_agent,
                 messages=params["messages"],
                 usage=usage,
+                finish_reason=finish_reason,
+                response_id=response_id,
             )
 
             return structured_data
@@ -848,6 +855,8 @@ class AzureCompletion(BaseLLM):
         usage = self._extract_azure_token_usage(response)
         self._track_token_usage_internal(usage)
 
+        finish_reason, response_id = self._extract_finish_reason_and_id(response)
+
         # Without available_functions, return tool_calls so the caller (executor) handles execution
         if message.tool_calls and not available_functions:
             self._emit_call_completed_event(
@@ -857,6 +866,8 @@ class AzureCompletion(BaseLLM):
                 from_agent=from_agent,
                 messages=params["messages"],
                 usage=usage,
+                finish_reason=finish_reason,
+                response_id=response_id,
             )
             return list(message.tool_calls)
 
@@ -892,6 +903,8 @@ class AzureCompletion(BaseLLM):
                 from_task=from_task,
                 from_agent=from_agent,
                 usage=usage,
+                finish_reason=finish_reason,
+                response_id=response_id,
             )
 
         content = self._apply_stop_words(content)
@@ -903,6 +916,8 @@ class AzureCompletion(BaseLLM):
             from_agent=from_agent,
             messages=params["messages"],
             usage=usage,
+            finish_reason=finish_reason,
+            response_id=response_id,
         )
 
         return self._invoke_after_llm_call_hooks(
@@ -1011,6 +1026,8 @@ class AzureCompletion(BaseLLM):
         from_task: Any | None = None,
         from_agent: Any | None = None,
         response_model: type[BaseModel] | None = None,
+        finish_reason: str | None = None,
+        response_id: str | None = None,
     ) -> str | Any:
         """Finalize streaming response with usage tracking, tool execution, and events.
 
@@ -1039,6 +1056,8 @@ class AzureCompletion(BaseLLM):
                 from_task=from_task,
                 from_agent=from_agent,
                 usage=usage_data,
+                finish_reason=finish_reason,
+                response_id=response_id,
             )
 
         # Without available_functions, return tool calls in OpenAI-compatible format for the executor
@@ -1061,6 +1080,8 @@ class AzureCompletion(BaseLLM):
                 from_agent=from_agent,
                 messages=params["messages"],
                 usage=usage_data,
+                finish_reason=finish_reason,
+                response_id=response_id,
             )
             return formatted_tool_calls
 
@@ -1094,6 +1115,8 @@ class AzureCompletion(BaseLLM):
             from_agent=from_agent,
             messages=params["messages"],
             usage=usage_data,
+            finish_reason=finish_reason,
+            response_id=response_id,
         )
 
         return self._invoke_after_llm_call_hooks(
@@ -1113,8 +1136,16 @@ class AzureCompletion(BaseLLM):
         tool_calls: dict[int, dict[str, Any]] = {}
 
         usage_data: dict[str, Any] | None = None
+        stream_finish_reason: str | None = None
+        stream_response_id: str | None = None
         for update in self._get_sync_client().complete(**params):
             if isinstance(update, StreamingChatCompletionsUpdate):
+                chunk_finish, chunk_id = self._extract_finish_reason_and_id(update)
+                if chunk_finish:
+                    stream_finish_reason = chunk_finish
+                if chunk_id:
+                    stream_response_id = chunk_id
+
                 if update.usage:
                     usage = update.usage
                     usage_data = {
@@ -1141,6 +1172,8 @@ class AzureCompletion(BaseLLM):
             from_task=from_task,
             from_agent=from_agent,
             response_model=response_model,
+            finish_reason=stream_finish_reason,
+            response_id=stream_response_id,
         )
 
     async def _ahandle_completion(
@@ -1180,10 +1213,18 @@ class AzureCompletion(BaseLLM):
         tool_calls: dict[int, dict[str, Any]] = {}
 
         usage_data: dict[str, Any] | None = None
+        stream_finish_reason: str | None = None
+        stream_response_id: str | None = None
 
         stream = await self._get_async_client().complete(**params)
         async for update in stream:
             if isinstance(update, StreamingChatCompletionsUpdate):
+                chunk_finish, chunk_id = self._extract_finish_reason_and_id(update)
+                if chunk_finish:
+                    stream_finish_reason = chunk_finish
+                if chunk_id:
+                    stream_response_id = chunk_id
+
                 if hasattr(update, "usage") and update.usage:
                     usage = update.usage
                     usage_data = {
@@ -1210,6 +1251,8 @@ class AzureCompletion(BaseLLM):
             from_task=from_task,
             from_agent=from_agent,
             response_model=response_model,
+            finish_reason=stream_finish_reason,
+            response_id=stream_response_id,
         )
 
     def supports_function_calling(self) -> bool:
@@ -1271,6 +1314,19 @@ class AzureCompletion(BaseLLM):
 
         return int(8192 * CONTEXT_WINDOW_USAGE_RATIO)
 
+    def _effective_max_tokens(self) -> int | float | None:
+        """Azure reasoning/newer chat models cap via ``max_completion_tokens``."""
+        return self.max_tokens or self.max_completion_tokens
+
+    @staticmethod
+    def _extract_finish_reason_and_id(
+        response_or_update: Any,
+    ) -> tuple[str | None, str | None]:
+        """Azure ``ChatCompletions`` / ``StreamingChatCompletionsUpdate``
+        share the choices-shape; delegate to the shared extractor.
+        """
+        return extract_choices_finish_reason_and_id(response_or_update)
+
     @staticmethod
     def _extract_azure_token_usage(response: ChatCompletions) -> dict[str, Any]:
         """Extract token usage and response metadata from Azure response."""

lib/crewai/src/crewai/llms/providers/bedrock/completion.py

@@ -677,7 +677,7 @@ class BedrockCompletion(BaseLLM):
             if usage:
                 self._track_token_usage_internal(usage)
 
-            stop_reason = response.get("stopReason")
+            stop_reason, response_id = self._extract_finish_reason_and_id(response)
             if stop_reason:
                 logging.debug(f"Response stop reason: {stop_reason}")
                 if stop_reason == "max_tokens":
@@ -716,6 +716,8 @@ class BedrockCompletion(BaseLLM):
                                 from_agent=from_agent,
                                 messages=messages,
                                 usage=usage,
+                                finish_reason=stop_reason,
+                                response_id=response_id,
                             )
                             return result
                         except Exception as e:
@@ -738,6 +740,8 @@ class BedrockCompletion(BaseLLM):
                     from_agent=from_agent,
                     messages=messages,
                     usage=usage,
+                    finish_reason=stop_reason,
+                    response_id=response_id,
                 )
                 return non_structured_output_tool_uses
 
@@ -812,6 +816,8 @@ class BedrockCompletion(BaseLLM):
                 from_agent=from_agent,
                 messages=messages,
                 usage=usage,
+                finish_reason=stop_reason,
+                response_id=response_id,
             )
 
             return self._invoke_after_llm_call_hooks(
@@ -951,7 +957,9 @@ class BedrockCompletion(BaseLLM):
             )
 
             stream = response.get("stream")
-            response_id = None
+            _, stream_response_id = self._extract_finish_reason_and_id(response)
+            response_id = stream_response_id
+            stream_finish_reason: str | None = None
             if stream:
                 for event in stream:
                     if "messageStart" in event:
@@ -1042,6 +1050,9 @@ class BedrockCompletion(BaseLLM):
                                     result = response_model.model_validate(
                                         function_args
                                     )
+                                    # contentBlockStop fires before messageStop sets
+                                    # stream_finish_reason; structured output always
+                                    # completes via the tool-call path.
                                     self._emit_call_completed_event(
                                         response=result.model_dump_json(),
                                         call_type=LLMCallType.LLM_CALL,
@@ -1049,6 +1060,9 @@ class BedrockCompletion(BaseLLM):
                                         from_agent=from_agent,
                                         messages=messages,
                                         usage=usage_data,
+                                        finish_reason=stream_finish_reason
+                                        or "tool_use",
+                                        response_id=response_id,
                                     )
                                     return result  # type: ignore[return-value]
                                 except Exception as e:
@@ -1102,6 +1116,7 @@ class BedrockCompletion(BaseLLM):
                             tool_use_id = None
                     elif "messageStop" in event:
                         stop_reason = event["messageStop"].get("stopReason")
+                        stream_finish_reason = stop_reason
                         logging.debug(f"Streaming message stopped: {stop_reason}")
                         if stop_reason == "max_tokens":
                             logging.warning(
@@ -1147,6 +1162,8 @@ class BedrockCompletion(BaseLLM):
             from_agent=from_agent,
             messages=messages,
             usage=usage_data,
+            finish_reason=stream_finish_reason,
+            response_id=response_id,
         )
 
         return full_response
@@ -1262,7 +1279,7 @@ class BedrockCompletion(BaseLLM):
             if usage:
                 self._track_token_usage_internal(usage)
 
-            stop_reason = response.get("stopReason")
+            stop_reason, response_id = self._extract_finish_reason_and_id(response)
             if stop_reason:
                 logging.debug(f"Response stop reason: {stop_reason}")
                 if stop_reason == "max_tokens":
@@ -1300,6 +1317,8 @@ class BedrockCompletion(BaseLLM):
                                 from_agent=from_agent,
                                 messages=messages,
                                 usage=usage,
+                                finish_reason=stop_reason,
+                                response_id=response_id,
                             )
                             return result
                         except Exception as e:
@@ -1322,6 +1341,8 @@ class BedrockCompletion(BaseLLM):
                     from_agent=from_agent,
                     messages=messages,
                     usage=usage,
+                    finish_reason=stop_reason,
+                    response_id=response_id,
                 )
                 return non_structured_output_tool_uses
 
@@ -1397,6 +1418,8 @@ class BedrockCompletion(BaseLLM):
                 from_agent=from_agent,
                 messages=messages,
                 usage=usage,
+                finish_reason=stop_reason,
+                response_id=response_id,
             )
 
             return text_content
@@ -1531,7 +1554,9 @@ class BedrockCompletion(BaseLLM):
             )
 
             stream = response.get("stream")
-            response_id = None
+            _, stream_response_id = self._extract_finish_reason_and_id(response)
+            response_id = stream_response_id
+            stream_finish_reason: str | None = None
             if stream:
                 async for event in stream:
                     if "messageStart" in event:
@@ -1623,6 +1648,9 @@ class BedrockCompletion(BaseLLM):
                                     result = response_model.model_validate(
                                         function_args
                                     )
+                                    # contentBlockStop fires before messageStop sets
+                                    # stream_finish_reason; structured output always
+                                    # completes via the tool-call path.
                                     self._emit_call_completed_event(
                                         response=result.model_dump_json(),
                                         call_type=LLMCallType.LLM_CALL,
@@ -1630,6 +1658,9 @@ class BedrockCompletion(BaseLLM):
                                         from_agent=from_agent,
                                         messages=messages,
                                         usage=usage_data,
+                                        finish_reason=stream_finish_reason
+                                        or "tool_use",
+                                        response_id=response_id,
                                     )
                                     return result  # type: ignore[return-value]
                                 except Exception as e:
@@ -1687,6 +1718,7 @@ class BedrockCompletion(BaseLLM):
 
                     elif "messageStop" in event:
                         stop_reason = event["messageStop"].get("stopReason")
+                        stream_finish_reason = stop_reason
                         logging.debug(f"Streaming message stopped: {stop_reason}")
                         if stop_reason == "max_tokens":
                             logging.warning(
@@ -1733,6 +1765,8 @@ class BedrockCompletion(BaseLLM):
             from_agent=from_agent,
             messages=messages,
             usage=usage_data,
+            finish_reason=stream_finish_reason,
+            response_id=response_id,
         )
 
         return self._invoke_after_llm_call_hooks(
@@ -1988,6 +2022,25 @@ class BedrockCompletion(BaseLLM):
 
         return config
 
+    @staticmethod
+    def _extract_finish_reason_and_id(
+        response: Any,
+    ) -> tuple[str | None, str | None]:
+        """Extract raw finish_reason (``stopReason``) from a Bedrock Converse
+        response dict. Defensive — returns (None, None) on any failure.
+
+        Bedrock Converse has no model-level response id; ResponseMetadata.RequestId
+        is an AWS infra trace id (semantically different from OpenAI's chatcmpl-XXX),
+        so we omit response_id rather than mislead downstream telemetry consumers.
+        """
+        finish_reason: str | None = None
+        try:
+            if isinstance(response, dict):
+                finish_reason = response.get("stopReason")
+        except (AttributeError, KeyError, TypeError, IndexError):
+            finish_reason = None
+        return finish_reason, None
+
     def _handle_client_error(self, e: ClientError) -> str:
         """Handle AWS ClientError with specific error codes and return error message."""
         error_code = e.response.get("Error", {}).get("Code", "Unknown")

lib/crewai/src/crewai/llms/providers/gemini/completion.py

@@ -682,6 +682,8 @@ class GeminiCompletion(BaseLLM):
         from_task: Any | None = None,
         from_agent: Any | None = None,
         usage: dict[str, Any] | None = None,
+        finish_reason: str | None = None,
+        response_id: str | None = None,
     ) -> BaseModel:
         """Validate content against response model and emit completion event.
 
@@ -691,6 +693,8 @@ class GeminiCompletion(BaseLLM):
             messages_for_event: Messages to include in event
             from_task: Task that initiated the call
             from_agent: Agent that initiated the call
+            finish_reason: Raw provider finish reason.
+            response_id: Raw provider response id.
 
         Returns:
             Validated Pydantic model instance
@@ -708,6 +712,8 @@ class GeminiCompletion(BaseLLM):
                 from_agent=from_agent,
                 messages=messages_for_event,
                 usage=usage,
+                finish_reason=finish_reason,
+                response_id=response_id,
             )
 
             return structured_data
@@ -724,6 +730,8 @@ class GeminiCompletion(BaseLLM):
         from_task: Any | None = None,
         from_agent: Any | None = None,
         usage: dict[str, Any] | None = None,
+        finish_reason: str | None = None,
+        response_id: str | None = None,
     ) -> str | BaseModel:
         """Finalize completion response with validation and event emission.
 
@@ -747,6 +755,8 @@ class GeminiCompletion(BaseLLM):
                 from_task=from_task,
                 from_agent=from_agent,
                 usage=usage,
+                finish_reason=finish_reason,
+                response_id=response_id,
             )
 
         self._emit_call_completed_event(
@@ -756,6 +766,8 @@ class GeminiCompletion(BaseLLM):
             from_agent=from_agent,
             messages=messages_for_event,
             usage=usage,
+            finish_reason=finish_reason,
+            response_id=response_id,
         )
 
         return self._invoke_after_llm_call_hooks(
@@ -770,6 +782,8 @@ class GeminiCompletion(BaseLLM):
         from_task: Any | None = None,
         from_agent: Any | None = None,
         usage: dict[str, Any] | None = None,
+        finish_reason: str | None = None,
+        response_id: str | None = None,
     ) -> BaseModel:
         """Validate and emit event for structured_output tool call.
 
@@ -795,6 +809,8 @@ class GeminiCompletion(BaseLLM):
                 from_agent=from_agent,
                 messages=self._convert_contents_to_dict(contents),
                 usage=usage,
+                finish_reason=finish_reason,
+                response_id=response_id,
             )
             return validated_data
         except Exception as e:
@@ -828,6 +844,8 @@ class GeminiCompletion(BaseLLM):
         Returns:
             Final response content or function call result
         """
+        finish_reason, response_id = self._extract_finish_reason_and_id(response)
+
         if response.candidates and (self.tools or available_functions):
             candidate = response.candidates[0]
             if candidate.content and candidate.content.parts:
@@ -854,6 +872,8 @@ class GeminiCompletion(BaseLLM):
                                 from_task=from_task,
                                 from_agent=from_agent,
                                 usage=usage,
+                                finish_reason=finish_reason,
+                                response_id=response_id,
                             )
 
                 non_structured_output_parts = [
@@ -875,6 +895,8 @@ class GeminiCompletion(BaseLLM):
                         from_agent=from_agent,
                         messages=self._convert_contents_to_dict(contents),
                         usage=usage,
+                        finish_reason=finish_reason,
+                        response_id=response_id,
                     )
                     return non_structured_output_parts
 
@@ -915,6 +937,8 @@ class GeminiCompletion(BaseLLM):
             from_task=from_task,
             from_agent=from_agent,
             usage=usage,
+            finish_reason=finish_reason,
+            response_id=response_id,
         )
 
     def _process_stream_chunk(
@@ -925,7 +949,13 @@ class GeminiCompletion(BaseLLM):
         usage_data: dict[str, int] | None,
         from_task: Any | None = None,
         from_agent: Any | None = None,
-    ) -> tuple[str, dict[int, dict[str, Any]], dict[str, int] | None]:
+    ) -> tuple[
+        str,
+        dict[int, dict[str, Any]],
+        dict[str, int] | None,
+        str | None,
+        str | None,
+    ]:
         """Process a single streaming chunk.
 
         Args:
@@ -937,9 +967,13 @@ class GeminiCompletion(BaseLLM):
             from_agent: Agent that initiated the call
 
         Returns:
-            Tuple of (updated full_response, updated function_calls, updated usage_data)
+            Tuple of (updated full_response, updated function_calls, updated
+            usage_data, chunk finish_reason, chunk response_id).
         """
         response_id = chunk.response_id if hasattr(chunk, "response_id") else None
+        chunk_finish_reason, chunk_response_id = self._extract_finish_reason_and_id(
+            chunk
+        )
         if chunk.usage_metadata:
             usage_data = self._extract_token_usage(chunk)
 
@@ -996,7 +1030,13 @@ class GeminiCompletion(BaseLLM):
                             response_id=response_id,
                         )
 
-        return full_response, function_calls, usage_data
+        return (
+            full_response,
+            function_calls,
+            usage_data,
+            chunk_finish_reason,
+            chunk_response_id,
+        )
 
     def _finalize_streaming_response(
         self,
@@ -1008,6 +1048,8 @@ class GeminiCompletion(BaseLLM):
         from_task: Any | None = None,
         from_agent: Any | None = None,
         response_model: type[BaseModel] | None = None,
+        finish_reason: str | None = None,
+        response_id: str | None = None,
     ) -> str | BaseModel | list[dict[str, Any]]:
         """Finalize streaming response with usage tracking, function execution, and events.
 
@@ -1038,6 +1080,8 @@ class GeminiCompletion(BaseLLM):
                         from_task=from_task,
                         from_agent=from_agent,
                         usage=usage_data,
+                        finish_reason=finish_reason,
+                        response_id=response_id,
                     )
 
         non_structured_output_calls = {
@@ -1058,6 +1102,8 @@ class GeminiCompletion(BaseLLM):
                 from_agent=from_agent,
                 messages=self._convert_contents_to_dict(contents),
                 usage=usage_data,
+                finish_reason=finish_reason,
+                response_id=response_id,
             )
             return raw_parts
 
@@ -1095,6 +1141,8 @@ class GeminiCompletion(BaseLLM):
             from_task=from_task,
             from_agent=from_agent,
             usage=usage_data,
+            finish_reason=finish_reason,
+            response_id=response_id,
         )
 
     def _handle_completion(
@@ -1148,6 +1196,8 @@ class GeminiCompletion(BaseLLM):
         full_response = ""
         function_calls: dict[int, dict[str, Any]] = {}
         usage_data: dict[str, int] | None = None
+        stream_finish_reason: str | None = None
+        stream_response_id: str | None = None
 
         # The API accepts list[Content] but mypy is overly strict about variance
         contents_for_api: Any = contents
@@ -1156,7 +1206,13 @@ class GeminiCompletion(BaseLLM):
             contents=contents_for_api,
             config=config,
         ):
-            full_response, function_calls, usage_data = self._process_stream_chunk(
+            (
+                full_response,
+                function_calls,
+                usage_data,
+                chunk_finish_reason,
+                chunk_response_id,
+            ) = self._process_stream_chunk(
                 chunk=chunk,
                 full_response=full_response,
                 function_calls=function_calls,
@@ -1164,6 +1220,10 @@ class GeminiCompletion(BaseLLM):
                 from_task=from_task,
                 from_agent=from_agent,
             )
+            if chunk_finish_reason:
+                stream_finish_reason = chunk_finish_reason
+            if chunk_response_id:
+                stream_response_id = chunk_response_id
 
         return self._finalize_streaming_response(
             full_response=full_response,
@@ -1174,6 +1234,8 @@ class GeminiCompletion(BaseLLM):
             from_task=from_task,
             from_agent=from_agent,
             response_model=response_model,
+            finish_reason=stream_finish_reason,
+            response_id=stream_response_id,
         )
 
     async def _ahandle_completion(
@@ -1227,6 +1289,8 @@ class GeminiCompletion(BaseLLM):
         full_response = ""
         function_calls: dict[int, dict[str, Any]] = {}
         usage_data: dict[str, int] | None = None
+        stream_finish_reason: str | None = None
+        stream_response_id: str | None = None
 
         # The API accepts list[Content] but mypy is overly strict about variance
         contents_for_api: Any = contents
@@ -1236,7 +1300,13 @@ class GeminiCompletion(BaseLLM):
             config=config,
         )
         async for chunk in stream:
-            full_response, function_calls, usage_data = self._process_stream_chunk(
+            (
+                full_response,
+                function_calls,
+                usage_data,
+                chunk_finish_reason,
+                chunk_response_id,
+            ) = self._process_stream_chunk(
                 chunk=chunk,
                 full_response=full_response,
                 function_calls=function_calls,
@@ -1244,6 +1314,10 @@ class GeminiCompletion(BaseLLM):
                 from_task=from_task,
                 from_agent=from_agent,
             )
+            if chunk_finish_reason:
+                stream_finish_reason = chunk_finish_reason
+            if chunk_response_id:
+                stream_response_id = chunk_response_id
 
         return self._finalize_streaming_response(
             full_response=full_response,
@@ -1254,6 +1328,8 @@ class GeminiCompletion(BaseLLM):
             from_task=from_task,
             from_agent=from_agent,
             response_model=response_model,
+            finish_reason=stream_finish_reason,
+            response_id=stream_response_id,
         )
 
     def supports_function_calling(self) -> bool:
@@ -1300,6 +1376,34 @@ class GeminiCompletion(BaseLLM):
 
         return int(1048576 * CONTEXT_WINDOW_USAGE_RATIO)  # 1M tokens default
 
+    def _effective_max_tokens(self) -> int | float | None:
+        """Gemini caps generation via ``max_output_tokens``."""
+        return self.max_output_tokens or self.max_tokens
+
+    @staticmethod
+    def _extract_finish_reason_and_id(
+        response: Any,
+    ) -> tuple[str | None, str | None]:
+        """Extract raw finish_reason and response_id from a Gemini
+        ``GenerateContentResponse``. ``finish_reason`` is the protobuf enum's
+        ``.name`` attribute (e.g. ``"STOP"``, ``"MAX_TOKENS"``); we forward
+        it raw and let downstream telemetry map to the OTel GenAI enum.
+        """
+        raw_response_id = getattr(response, "response_id", None)
+        response_id = raw_response_id if isinstance(raw_response_id, str) else None
+
+        finish_reason: str | None = None
+        candidates = getattr(response, "candidates", None)
+        if candidates:
+            try:
+                candidate_finish = getattr(candidates[0], "finish_reason", None)
+            except (IndexError, TypeError, KeyError):
+                candidate_finish = None
+            if candidate_finish is not None:
+                name = getattr(candidate_finish, "name", None)
+                finish_reason = name if isinstance(name, str) else None
+        return finish_reason, response_id
+
     @staticmethod
     def _extract_token_usage(response: GenerateContentResponse) -> dict[str, Any]:
         """Extract token usage and response metadata from Gemini response."""

lib/crewai/src/crewai/llms/providers/openai/completion.py

@@ -29,6 +29,7 @@ from openai.types.responses import (
 from pydantic import BaseModel, PrivateAttr, model_validator
 
 from crewai.events.types.llm_events import LLMCallType
+from crewai.llms._finish_reason_utils import extract_choices_finish_reason_and_id
 from crewai.llms.base_llm import BaseLLM, JsonResponseFormat, llm_call_context
 from crewai.llms.hooks.base import BaseInterceptor
 from crewai.llms.hooks.transport import AsyncHTTPTransport, HTTPTransport
@@ -825,6 +826,10 @@ class OpenAICompletion(BaseLLM):
             usage = self._extract_responses_token_usage(response)
             self._track_token_usage_internal(usage)
 
+            finish_reason, response_id = self._extract_responses_finish_reason_and_id(
+                response
+            )
+
             if self.parse_tool_outputs:
                 parsed_result = self._extract_builtin_tool_outputs(response)
                 parsed_result.text = self._apply_stop_words(parsed_result.text)
@@ -836,6 +841,8 @@ class OpenAICompletion(BaseLLM):
                     from_agent=from_agent,
                     messages=params.get("input", []),
                     usage=usage,
+                    finish_reason=finish_reason,
+                    response_id=response_id,
                 )
 
                 return parsed_result
@@ -849,6 +856,8 @@ class OpenAICompletion(BaseLLM):
                     from_agent=from_agent,
                     messages=params.get("input", []),
                     usage=usage,
+                    finish_reason=finish_reason,
+                    response_id=response_id,
                 )
                 return function_calls
 
@@ -887,6 +896,8 @@ class OpenAICompletion(BaseLLM):
                         from_agent=from_agent,
                         messages=params.get("input", []),
                         usage=usage,
+                        finish_reason=finish_reason,
+                        response_id=response_id,
                     )
                     return structured_result
                 except ValueError as e:
@@ -901,6 +912,8 @@ class OpenAICompletion(BaseLLM):
                 from_agent=from_agent,
                 messages=params.get("input", []),
                 usage=usage,
+                finish_reason=finish_reason,
+                response_id=response_id,
             )
 
             content = self._invoke_after_llm_call_hooks(
@@ -960,6 +973,10 @@ class OpenAICompletion(BaseLLM):
             usage = self._extract_responses_token_usage(response)
             self._track_token_usage_internal(usage)
 
+            finish_reason, response_id = self._extract_responses_finish_reason_and_id(
+                response
+            )
+
             if self.parse_tool_outputs:
                 parsed_result = self._extract_builtin_tool_outputs(response)
                 parsed_result.text = self._apply_stop_words(parsed_result.text)
@@ -971,6 +988,8 @@ class OpenAICompletion(BaseLLM):
                     from_agent=from_agent,
                     messages=params.get("input", []),
                     usage=usage,
+                    finish_reason=finish_reason,
+                    response_id=response_id,
                 )
 
                 return parsed_result
@@ -984,6 +1003,8 @@ class OpenAICompletion(BaseLLM):
                     from_agent=from_agent,
                     messages=params.get("input", []),
                     usage=usage,
+                    finish_reason=finish_reason,
+                    response_id=response_id,
                 )
                 return function_calls
 
@@ -1022,6 +1043,8 @@ class OpenAICompletion(BaseLLM):
                         from_agent=from_agent,
                         messages=params.get("input", []),
                         usage=usage,
+                        finish_reason=finish_reason,
+                        response_id=response_id,
                     )
                     return structured_result
                 except ValueError as e:
@@ -1036,6 +1059,8 @@ class OpenAICompletion(BaseLLM):
                 from_agent=from_agent,
                 messages=params.get("input", []),
                 usage=usage,
+                finish_reason=finish_reason,
+                response_id=response_id,
             )
 
         except NotFoundError as e:
@@ -1123,6 +1148,12 @@ class OpenAICompletion(BaseLLM):
                     usage = self._extract_responses_token_usage(event.response)
                     self._track_token_usage_internal(usage)
 
+        finish_reason, response_id = (
+            self._extract_responses_finish_reason_and_id(final_response)
+            if final_response is not None
+            else (None, response_id_stream)
+        )
+
         if self.parse_tool_outputs and final_response:
             parsed_result = self._extract_builtin_tool_outputs(final_response)
             parsed_result.text = self._apply_stop_words(parsed_result.text)
@@ -1134,6 +1165,8 @@ class OpenAICompletion(BaseLLM):
                 from_agent=from_agent,
                 messages=params.get("input", []),
                 usage=usage,
+                finish_reason=finish_reason,
+                response_id=response_id,
             )
 
             return parsed_result
@@ -1171,6 +1204,8 @@ class OpenAICompletion(BaseLLM):
                     from_agent=from_agent,
                     messages=params.get("input", []),
                     usage=usage,
+                    finish_reason=finish_reason,
+                    response_id=response_id,
                 )
                 return structured_result
             except ValueError as e:
@@ -1185,6 +1220,8 @@ class OpenAICompletion(BaseLLM):
             from_agent=from_agent,
             messages=params.get("input", []),
             usage=usage,
+            finish_reason=finish_reason,
+            response_id=response_id,
         )
 
         return self._invoke_after_llm_call_hooks(
@@ -1248,6 +1285,12 @@ class OpenAICompletion(BaseLLM):
                     usage = self._extract_responses_token_usage(event.response)
                     self._track_token_usage_internal(usage)
 
+        finish_reason, response_id = (
+            self._extract_responses_finish_reason_and_id(final_response)
+            if final_response is not None
+            else (None, response_id_stream)
+        )
+
         if self.parse_tool_outputs and final_response:
             parsed_result = self._extract_builtin_tool_outputs(final_response)
             parsed_result.text = self._apply_stop_words(parsed_result.text)
@@ -1259,6 +1302,8 @@ class OpenAICompletion(BaseLLM):
                 from_agent=from_agent,
                 messages=params.get("input", []),
                 usage=usage,
+                finish_reason=finish_reason,
+                response_id=response_id,
             )
 
             return parsed_result
@@ -1296,6 +1341,8 @@ class OpenAICompletion(BaseLLM):
                     from_agent=from_agent,
                     messages=params.get("input", []),
                     usage=usage,
+                    finish_reason=finish_reason,
+                    response_id=response_id,
                 )
                 return structured_result
             except ValueError as e:
@@ -1310,6 +1357,8 @@ class OpenAICompletion(BaseLLM):
             from_agent=from_agent,
             messages=params.get("input", []),
             usage=usage,
+            finish_reason=finish_reason,
+            response_id=response_id,
         )
 
         return full_response
@@ -1603,6 +1652,9 @@ class OpenAICompletion(BaseLLM):
                 usage = self._extract_openai_token_usage(parsed_response)
                 self._track_token_usage_internal(usage)
 
+                parsed_finish_reason, parsed_response_id = (
+                    self._extract_chat_finish_reason_and_id(parsed_response)
+                )
                 parsed_object = parsed_response.choices[0].message.parsed
                 if parsed_object:
                     self._emit_call_completed_event(
@@ -1612,6 +1664,8 @@ class OpenAICompletion(BaseLLM):
                         from_agent=from_agent,
                         messages=params["messages"],
                         usage=usage,
+                        finish_reason=parsed_finish_reason,
+                        response_id=parsed_response_id,
                     )
                     return parsed_object
 
@@ -1625,6 +1679,9 @@ class OpenAICompletion(BaseLLM):
 
             choice: Choice = response.choices[0]
             message = choice.message
+            finish_reason, response_id = self._extract_chat_finish_reason_and_id(
+                response
+            )
 
             # Without available_functions, return tool_calls so the caller (executor) handles execution
             if message.tool_calls and not available_functions:
@@ -1635,6 +1692,8 @@ class OpenAICompletion(BaseLLM):
                     from_agent=from_agent,
                     messages=params["messages"],
                     usage=usage,
+                    finish_reason=finish_reason,
+                    response_id=response_id,
                 )
                 return list(message.tool_calls)
 
@@ -1675,6 +1734,8 @@ class OpenAICompletion(BaseLLM):
                         from_agent=from_agent,
                         messages=params["messages"],
                         usage=usage,
+                        finish_reason=finish_reason,
+                        response_id=response_id,
                     )
                     return structured_result
                 except ValueError as e:
@@ -1689,6 +1750,8 @@ class OpenAICompletion(BaseLLM):
                 from_agent=from_agent,
                 messages=params["messages"],
                 usage=usage,
+                finish_reason=finish_reason,
+                response_id=response_id,
             )
 
             if usage.get("total_tokens", 0) > 0:
@@ -1734,6 +1797,8 @@ class OpenAICompletion(BaseLLM):
         available_functions: dict[str, Any] | None = None,
         from_task: Any | None = None,
         from_agent: Any | None = None,
+        finish_reason: str | None = None,
+        response_id: str | None = None,
     ) -> str | list[dict[str, Any]]:
         """Finalize a streaming response with usage tracking, tool call handling, and events.
 
@@ -1745,6 +1810,9 @@ class OpenAICompletion(BaseLLM):
             available_functions: Available functions for tool calling.
             from_task: Task that initiated the call.
             from_agent: Agent that initiated the call.
+            finish_reason: Raw provider finish reason (e.g. "stop", "length",
+                "tool_calls") extracted from the last streaming chunk.
+            response_id: Raw provider response id from any chunk.
 
         Returns:
             Tool calls list when tools were invoked without available_functions,
@@ -1774,6 +1842,8 @@ class OpenAICompletion(BaseLLM):
                 from_agent=from_agent,
                 messages=params["messages"],
                 usage=usage_data,
+                finish_reason=finish_reason,
+                response_id=response_id,
             )
             return tool_calls_list
 
@@ -1817,6 +1887,8 @@ class OpenAICompletion(BaseLLM):
             from_agent=from_agent,
             messages=params["messages"],
             usage=usage_data,
+            finish_reason=finish_reason,
+            response_id=response_id,
         )
 
         return full_response
@@ -1861,6 +1933,9 @@ class OpenAICompletion(BaseLLM):
                 if final_completion:
                     usage = self._extract_openai_token_usage(final_completion)
                     self._track_token_usage_internal(usage)
+                    parsed_finish_reason, parsed_response_id = (
+                        self._extract_chat_finish_reason_and_id(final_completion)
+                    )
                     if final_completion.choices:
                         parsed_result = final_completion.choices[0].message.parsed
                         if parsed_result:
@@ -1871,6 +1946,8 @@ class OpenAICompletion(BaseLLM):
                                 from_agent=from_agent,
                                 messages=params["messages"],
                                 usage=usage,
+                                finish_reason=parsed_finish_reason,
+                                response_id=parsed_response_id,
                             )
                             return parsed_result
 
@@ -1882,11 +1959,15 @@ class OpenAICompletion(BaseLLM):
         )
 
         usage_data: dict[str, Any] | None = None
+        stream_finish_reason: str | None = None
+        stream_response_id: str | None = None
 
         for completion_chunk in completion_stream:
             response_id_stream = (
                 completion_chunk.id if hasattr(completion_chunk, "id") else None
             )
+            if response_id_stream:
+                stream_response_id = response_id_stream
 
             if hasattr(completion_chunk, "usage") and completion_chunk.usage:
                 usage_data = self._extract_openai_token_usage(completion_chunk)
@@ -1897,6 +1978,9 @@ class OpenAICompletion(BaseLLM):
 
             choice = completion_chunk.choices[0]
             chunk_delta: ChoiceDelta = choice.delta
+            chunk_finish = getattr(choice, "finish_reason", None)
+            if chunk_finish:
+                stream_finish_reason = chunk_finish
 
             if chunk_delta.content:
                 full_response += chunk_delta.content
@@ -1954,6 +2038,8 @@ class OpenAICompletion(BaseLLM):
             available_functions=available_functions,
             from_task=from_task,
             from_agent=from_agent,
+            finish_reason=stream_finish_reason,
+            response_id=stream_response_id,
         )
         if isinstance(result, str):
             return self._invoke_after_llm_call_hooks(
@@ -1989,6 +2075,9 @@ class OpenAICompletion(BaseLLM):
                 usage = self._extract_openai_token_usage(parsed_response)
                 self._track_token_usage_internal(usage)
 
+                parsed_finish_reason, parsed_response_id = (
+                    self._extract_chat_finish_reason_and_id(parsed_response)
+                )
                 parsed_object = parsed_response.choices[0].message.parsed
                 if parsed_object:
                     self._emit_call_completed_event(
@@ -1998,6 +2087,8 @@ class OpenAICompletion(BaseLLM):
                         from_agent=from_agent,
                         messages=params["messages"],
                         usage=usage,
+                        finish_reason=parsed_finish_reason,
+                        response_id=parsed_response_id,
                     )
                     return parsed_object
 
@@ -2011,6 +2102,9 @@ class OpenAICompletion(BaseLLM):
 
             choice: Choice = response.choices[0]
             message = choice.message
+            finish_reason, response_id = self._extract_chat_finish_reason_and_id(
+                response
+            )
 
             # Without available_functions, return tool_calls so the caller (executor) handles execution
             if message.tool_calls and not available_functions:
@@ -2021,6 +2115,8 @@ class OpenAICompletion(BaseLLM):
                     from_agent=from_agent,
                     messages=params["messages"],
                     usage=usage,
+                    finish_reason=finish_reason,
+                    response_id=response_id,
                 )
                 return list(message.tool_calls)
 
@@ -2065,6 +2161,8 @@ class OpenAICompletion(BaseLLM):
                         from_agent=from_agent,
                         messages=params["messages"],
                         usage=usage,
+                        finish_reason=finish_reason,
+                        response_id=response_id,
                     )
                     return structured_result
                 except ValueError as e:
@@ -2079,6 +2177,8 @@ class OpenAICompletion(BaseLLM):
                 from_agent=from_agent,
                 messages=params["messages"],
                 usage=usage,
+                finish_reason=finish_reason,
+                response_id=response_id,
             )
 
             if usage.get("total_tokens", 0) > 0:
@@ -2130,8 +2230,12 @@ class OpenAICompletion(BaseLLM):
 
             accumulated_content = ""
             usage_data: dict[str, Any] | None = None
+            parsed_stream_finish_reason: str | None = None
+            parsed_stream_response_id: str | None = None
             async for chunk in completion_stream:
                 response_id_stream = chunk.id if hasattr(chunk, "id") else None
+                if response_id_stream:
+                    parsed_stream_response_id = response_id_stream
 
                 if hasattr(chunk, "usage") and chunk.usage:
                     usage_data = self._extract_openai_token_usage(chunk)
@@ -2142,6 +2246,9 @@ class OpenAICompletion(BaseLLM):
 
                 choice = chunk.choices[0]
                 delta: ChoiceDelta = choice.delta
+                chunk_finish = getattr(choice, "finish_reason", None)
+                if chunk_finish:
+                    parsed_stream_finish_reason = chunk_finish
 
                 if delta.content:
                     accumulated_content += delta.content
@@ -2165,6 +2272,8 @@ class OpenAICompletion(BaseLLM):
                     from_agent=from_agent,
                     messages=params["messages"],
                     usage=usage_data,
+                    finish_reason=parsed_stream_finish_reason,
+                    response_id=parsed_stream_response_id,
                 )
 
                 return parsed_object
@@ -2177,6 +2286,8 @@ class OpenAICompletion(BaseLLM):
                     from_agent=from_agent,
                     messages=params["messages"],
                     usage=usage_data,
+                    finish_reason=parsed_stream_finish_reason,
+                    response_id=parsed_stream_response_id,
                 )
                 return accumulated_content
 
@@ -2185,9 +2296,13 @@ class OpenAICompletion(BaseLLM):
         ] = await self._get_async_client().chat.completions.create(**params)
 
         usage_data = None
+        stream_finish_reason: str | None = None
+        stream_response_id: str | None = None
 
         async for chunk in stream:
             response_id_stream = chunk.id if hasattr(chunk, "id") else None
+            if response_id_stream:
+                stream_response_id = response_id_stream
 
             if hasattr(chunk, "usage") and chunk.usage:
                 usage_data = self._extract_openai_token_usage(chunk)
@@ -2198,6 +2313,9 @@ class OpenAICompletion(BaseLLM):
 
             choice = chunk.choices[0]
             chunk_delta: ChoiceDelta = choice.delta
+            chunk_finish = getattr(choice, "finish_reason", None)
+            if chunk_finish:
+                stream_finish_reason = chunk_finish
 
             if chunk_delta.content:
                 full_response += chunk_delta.content
@@ -2255,6 +2373,8 @@ class OpenAICompletion(BaseLLM):
             available_functions=available_functions,
             from_task=from_task,
             from_agent=from_agent,
+            finish_reason=stream_finish_reason,
+            response_id=stream_response_id,
         )
 
     def supports_function_calling(self) -> bool:
@@ -2305,6 +2425,32 @@ class OpenAICompletion(BaseLLM):
 
         return int(8192 * CONTEXT_WINDOW_USAGE_RATIO)
 
+    def _effective_max_tokens(self) -> int | float | None:
+        """Newer OpenAI chat models cap via ``max_completion_tokens``."""
+        return self.max_tokens or self.max_completion_tokens
+
+    @staticmethod
+    def _extract_chat_finish_reason_and_id(
+        response: Any,
+    ) -> tuple[str | None, str | None]:
+        """ChatCompletion / ChatCompletionChunk share the choices-shape;
+        delegate to the shared extractor.
+        """
+        return extract_choices_finish_reason_and_id(response)
+
+    @staticmethod
+    def _extract_responses_finish_reason_and_id(
+        response: Any,
+    ) -> tuple[str | None, str | None]:
+        """Extract finish_reason and response_id from an OpenAI Responses
+        API ``Response`` object. The Responses API exposes ``status`` rather
+        than ``finish_reason``; we forward the raw status value.
+        """
+        return (
+            getattr(response, "status", None),
+            getattr(response, "id", None),
+        )
+
     def _extract_openai_token_usage(
         self, response: ChatCompletion | ChatCompletionChunk
     ) -> dict[str, Any]:

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

@@ -337,7 +337,7 @@ class RecallFlow(Flow[RecallState]):
     @router(re_search)
     def re_decide_depth(self) -> str:
         """Re-evaluate depth after re-search. Same logic as decide_depth."""
-        return self.decide_depth()  # type: ignore[call-arg]
+        return self.decide_depth()
 
     @listen("synthesize")
     def synthesize_results(self) -> list[MemoryMatch]:

lib/crewai/src/crewai/translations/en.json

@@ -35,6 +35,8 @@
     "knowledge_search_query": "The original query is: {task_prompt}.",
     "knowledge_search_query_system_prompt": "Your goal is to rewrite the user query so that it is optimized for retrieval from a vector database. Consider how the query will be used to find relevant documents, and aim to make it more specific and context-aware. \n\n Do not include any other text than the rewritten query, especially any preamble or postamble and only add expected output format if its relevant to the rewritten query. \n\n Focus on the key words of the intended task and to retrieve the most relevant information. \n\n There will be some extra context provided that might need to be removed such as expected_output formats structured_outputs and other instructions.",
     "human_feedback_collapse": "Based on the following human feedback, determine which outcome best matches their intent.\n\nFeedback: {feedback}\n\nPossible outcomes: {outcomes}\n\nRespond with ONLY one of the exact outcome values listed above, nothing else.",
+    "conversational_system_prompt": "You are a helpful conversational assistant. Maintain context across turns, answer using the canonical message history when possible, and respond clearly and concisely. Ask for clarification when the user's intent is ambiguous.",
+    "conversational_answer_from_history_prompt": "Given the current user message and the canonical message history, decide whether the assistant can answer from message_history without running additional tools or agents. If so, answer clearly using only that context.",
     "hitl_pre_review_system": "You are reviewing content before a human sees it. Apply the lessons from past human feedback to improve the output. Preserve the original meaning and structure, but incorporate the corrections and preferences indicated by the lessons.",
     "hitl_pre_review_user": "Output to review:\n{output}\n\nLessons from past human feedback:\n{lessons}\n\nApply the lessons to improve the output.",
     "hitl_distill_system": "You extract generalizable lessons from human feedback on system outputs. A lesson should be a reusable rule or preference that applies to future similar outputs -- not a one-time correction specific to this exact content.\n\nExamples of good lessons:\n- Always include source citations when making factual claims\n- Use bullet points instead of long paragraphs for action items\n- Avoid technical jargon when the audience is non-technical\n\nIf the feedback is just approval (e.g. looks good, approved) or contains no generalizable guidance, return an empty list.",

lib/crewai/tests/cassettes/tracing/TestTraceListenerSetup.test_trace_listener_collects_crew_events.yaml

@@ -17,251 +17,6 @@ interactions:
     status:
       code: 200
       message: OK
-- request:
-    body: '{"messages": [{"role": "system", "content": "You are Test Agent. Test backstory\nYour
-      personal goal is: Test goal\nTo give my best complete final answer to the task
-      respond using the exact following format:\n\nThought: I now can give a great
-      answer\nFinal Answer: Your final answer must be the great and the most complete
-      as possible, it must be outcome described.\n\nI MUST use these formats, my job
-      depends on it!"}, {"role": "user", "content": "\nCurrent Task: Say hello to
-      the world\n\nThis is the expected criteria for your final answer: hello world\nyou
-      MUST return the actual complete content as the final answer, not a summary.\n\nBegin!
-      This is VERY important to you, use the tools available and give your best Final
-      Answer, your job depends on it!\n\nThought:"}], "model": "gpt-4o-mini", "stop":
-      ["\nObservation:"]}'
-    headers:
-      accept:
-      - application/json
-      accept-encoding:
-      - gzip, deflate, zstd
-      connection:
-      - keep-alive
-      content-length:
-      - '825'
-      content-type:
-      - application/json
-      cookie:
-      - __cf_bm=ePO5hy0kEoADCuKcboFy1iS1qckCE5KCpifQaXnlomM-1754508545-1.0.1.1-ieWfjcdIxQIXGfaMizvmgTvZPRFehqDXliegaOT7EO.kt7KSSFGmNDcC35_D9hOhE.fJ5K302uX0snQF3nLaapds2dqgGbNcsyFPOKNvAdI;
-        _cfuvid=NaXWifUGChHp6Ap1mvfMrNzmO4HdzddrqXkSR9T.hYo-1754508545647-0.0.1.1-604800000
-      host:
-      - api.openai.com
-      user-agent:
-      - OpenAI/Python 1.93.0
-      x-stainless-arch:
-      - arm64
-      x-stainless-async:
-      - 'false'
-      x-stainless-lang:
-      - python
-      x-stainless-os:
-      - MacOS
-      x-stainless-package-version:
-      - 1.93.0
-      x-stainless-raw-response:
-      - 'true'
-      x-stainless-read-timeout:
-      - '600.0'
-      x-stainless-retry-count:
-      - '0'
-      x-stainless-runtime:
-      - CPython
-      x-stainless-runtime-version:
-      - 3.12.9
-    method: POST
-    uri: https://api.openai.com/v1/chat/completions
-  response:
-    body:
-      string: "{\n  \"id\": \"chatcmpl-C1e6uBsZ3iMw51p03hHTkBgHjA5ym\",\n  \"object\"\
-        : \"chat.completion\",\n  \"created\": 1754508548,\n  \"model\": \"gpt-4o-mini-2024-07-18\"\
-        ,\n  \"choices\": [\n    {\n      \"index\": 0,\n      \"message\": {\n  \
-        \      \"role\": \"assistant\",\n        \"content\": \"I now can give a great\
-        \ answer  \\nFinal Answer: hello world\",\n        \"refusal\": null,\n  \
-        \      \"annotations\": []\n      },\n      \"logprobs\": null,\n      \"\
-        finish_reason\": \"stop\"\n    }\n  ],\n  \"usage\": {\n    \"prompt_tokens\"\
-        : 157,\n    \"completion_tokens\": 13,\n    \"total_tokens\": 170,\n    \"\
-        prompt_tokens_details\": {\n      \"cached_tokens\": 0,\n      \"audio_tokens\"\
-        : 0\n    },\n    \"completion_tokens_details\": {\n      \"reasoning_tokens\"\
-        : 0,\n      \"audio_tokens\": 0,\n      \"accepted_prediction_tokens\": 0,\n\
-        \      \"rejected_prediction_tokens\": 0\n    }\n  },\n  \"service_tier\"\
-        : \"default\",\n  \"system_fingerprint\": \"fp_34a54ae93c\"\n}\n"
-    headers:
-      CF-RAY:
-      - 96b0f0fb5c067ad9-SJC
-      Connection:
-      - keep-alive
-      Content-Type:
-      - application/json
-      Date:
-      - Wed, 06 Aug 2025 19:29:09 GMT
-      Server:
-      - cloudflare
-      Strict-Transport-Security:
-      - max-age=31536000; includeSubDomains; preload
-      Transfer-Encoding:
-      - chunked
-      X-Content-Type-Options:
-      - nosniff
-      access-control-expose-headers:
-      - X-Request-ID
-      alt-svc:
-      - h3=":443"; ma=86400
-      cf-cache-status:
-      - DYNAMIC
-      openai-organization:
-      - crewai-iuxna1
-      openai-processing-ms:
-      - '628'
-      openai-project:
-      - proj_xitITlrFeen7zjNSzML82h9x
-      openai-version:
-      - '2020-10-01'
-      x-envoy-upstream-service-time:
-      - '657'
-      x-ratelimit-limit-project-tokens:
-      - '150000000'
-      x-ratelimit-limit-requests:
-      - '30000'
-      x-ratelimit-limit-tokens:
-      - '150000000'
-      x-ratelimit-remaining-project-tokens:
-      - '149999827'
-      x-ratelimit-remaining-requests:
-      - '29999'
-      x-ratelimit-remaining-tokens:
-      - '149999827'
-      x-ratelimit-reset-project-tokens:
-      - 0s
-      x-ratelimit-reset-requests:
-      - 2ms
-      x-ratelimit-reset-tokens:
-      - 0s
-      x-request-id:
-      - req_a0daca00035c423daf0e9df208720180
-    status:
-      code: 200
-      message: OK
-- request:
-    body: '{"messages": [{"role": "system", "content": "You are Test Agent. Test backstory\nYour
-      personal goal is: Test goal\nTo give my best complete final answer to the task
-      respond using the exact following format:\n\nThought: I now can give a great
-      answer\nFinal Answer: Your final answer must be the great and the most complete
-      as possible, it must be outcome described.\n\nI MUST use these formats, my job
-      depends on it!"}, {"role": "user", "content": "\nCurrent Task: Say hello to
-      the world\n\nThis is the expected criteria for your final answer: hello world\nyou
-      MUST return the actual complete content as the final answer, not a summary.\n\nBegin!
-      This is VERY important to you, use the tools available and give your best Final
-      Answer, your job depends on it!\n\nThought:"}], "model": "gpt-4o-mini"}'
-    headers:
-      accept:
-      - application/json
-      accept-encoding:
-      - gzip, deflate, zstd
-      connection:
-      - keep-alive
-      content-length:
-      - '797'
-      content-type:
-      - application/json
-      cookie:
-      - __cf_bm=f59gEPi_nA3TTxtjbKaSQpvkTwezaAqOvqfxiGzRnVQ-1754508546-1.0.1.1-JrSaytxVIQSVE00I.vyGj7d4HJbbMV6R9fWPJbkDKu0Y8ueMRzTwTUnfz0YzP5nsZX5oxoE6WlmFxOuz0rRuq9YhZZsO_TbaFBOFk1jGK9U;
-        _cfuvid=3D66v3.J_RcVoYy9dlF.jHwq1zTIm842xynZxzSy1Wc-1754508546352-0.0.1.1-604800000
-      host:
-      - api.openai.com
-      user-agent:
-      - OpenAI/Python 1.93.0
-      x-stainless-arch:
-      - arm64
-      x-stainless-async:
-      - 'false'
-      x-stainless-lang:
-      - python
-      x-stainless-os:
-      - MacOS
-      x-stainless-package-version:
-      - 1.93.0
-      x-stainless-raw-response:
-      - 'true'
-      x-stainless-read-timeout:
-      - '200.0'
-      x-stainless-retry-count:
-      - '0'
-      x-stainless-runtime:
-      - CPython
-      x-stainless-runtime-version:
-      - 3.12.9
-    method: POST
-    uri: https://api.openai.com/v1/chat/completions
-  response:
-    body:
-      string: "{\n  \"id\": \"chatcmpl-C1e6vUMjwrC8Zt9Htraa70hbbt5d7\",\n  \"object\"\
-        : \"chat.completion\",\n  \"created\": 1754508549,\n  \"model\": \"gpt-4o-mini-2024-07-18\"\
-        ,\n  \"choices\": [\n    {\n      \"index\": 0,\n      \"message\": {\n  \
-        \      \"role\": \"assistant\",\n        \"content\": \"I now can give a great\
-        \ answer  \\nFinal Answer: hello world\",\n        \"refusal\": null,\n  \
-        \      \"annotations\": []\n      },\n      \"logprobs\": null,\n      \"\
-        finish_reason\": \"stop\"\n    }\n  ],\n  \"usage\": {\n    \"prompt_tokens\"\
-        : 157,\n    \"completion_tokens\": 13,\n    \"total_tokens\": 170,\n    \"\
-        prompt_tokens_details\": {\n      \"cached_tokens\": 0,\n      \"audio_tokens\"\
-        : 0\n    },\n    \"completion_tokens_details\": {\n      \"reasoning_tokens\"\
-        : 0,\n      \"audio_tokens\": 0,\n      \"accepted_prediction_tokens\": 0,\n\
-        \      \"rejected_prediction_tokens\": 0\n    }\n  },\n  \"service_tier\"\
-        : \"default\",\n  \"system_fingerprint\": \"fp_34a54ae93c\"\n}\n"
-    headers:
-      CF-RAY:
-      - 96b0f101793aeb2c-SJC
-      Connection:
-      - keep-alive
-      Content-Type:
-      - application/json
-      Date:
-      - Wed, 06 Aug 2025 19:29:09 GMT
-      Server:
-      - cloudflare
-      Strict-Transport-Security:
-      - max-age=31536000; includeSubDomains; preload
-      Transfer-Encoding:
-      - chunked
-      X-Content-Type-Options:
-      - nosniff
-      access-control-expose-headers:
-      - X-Request-ID
-      alt-svc:
-      - h3=":443"; ma=86400
-      cf-cache-status:
-      - DYNAMIC
-      openai-organization:
-      - crewai-iuxna1
-      openai-processing-ms:
-      - '541'
-      openai-project:
-      - proj_xitITlrFeen7zjNSzML82h9x
-      openai-version:
-      - '2020-10-01'
-      x-envoy-upstream-service-time:
-      - '557'
-      x-ratelimit-limit-project-tokens:
-      - '150000000'
-      x-ratelimit-limit-requests:
-      - '30000'
-      x-ratelimit-limit-tokens:
-      - '150000000'
-      x-ratelimit-remaining-project-tokens:
-      - '149999827'
-      x-ratelimit-remaining-requests:
-      - '29999'
-      x-ratelimit-remaining-tokens:
-      - '149999827'
-      x-ratelimit-reset-project-tokens:
-      - 0s
-      x-ratelimit-reset-requests:
-      - 2ms
-      x-ratelimit-reset-tokens:
-      - 0s
-      x-request-id:
-      - req_df70f95325b14817a692f23cf9cca880
-    status:
-      code: 200
-      message: OK
 - request:
     body: '{"trace_id": "2487456d-e03a-4eae-92a1-e9779e8f06a1", "execution_type":
       "crew", "execution_context": {"crew_fingerprint": null, "crew_name": "Unknown
@@ -330,6 +85,117 @@ interactions:
     status:
       code: 404
       message: Not Found
+- request:
+    body: '{"messages":[{"role":"system","content":"You are Test Agent. Test backstory\nYour
+      personal goal is: Test goal"},{"role":"user","content":"\nCurrent Task: Say
+      hello to the world\n\nThis is the expected criteria for your final answer: hello
+      world\nyou MUST return the actual complete content as the final answer, not
+      a summary.\n\nProvide your complete response:"}],"model":"gpt-4o-mini"}'
+    headers:
+      User-Agent:
+      - X-USER-AGENT-XXX
+      accept:
+      - application/json
+      accept-encoding:
+      - ACCEPT-ENCODING-XXX
+      authorization:
+      - AUTHORIZATION-XXX
+      connection:
+      - keep-alive
+      content-length:
+      - '386'
+      content-type:
+      - application/json
+      host:
+      - api.openai.com
+      x-stainless-arch:
+      - X-STAINLESS-ARCH-XXX
+      x-stainless-async:
+      - 'false'
+      x-stainless-lang:
+      - python
+      x-stainless-os:
+      - X-STAINLESS-OS-XXX
+      x-stainless-package-version:
+      - 2.32.0
+      x-stainless-read-timeout:
+      - X-STAINLESS-READ-TIMEOUT-XXX
+      x-stainless-retry-count:
+      - '0'
+      x-stainless-runtime:
+      - CPython
+      x-stainless-runtime-version:
+      - 3.13.3
+    method: POST
+    uri: https://api.openai.com/v1/chat/completions
+  response:
+    body:
+      string: "{\n  \"id\": \"chatcmpl-DmQBou4covfqbekZpX1DEVm8haN4N\",\n  \"object\"\
+        : \"chat.completion\",\n  \"created\": 1780432788,\n  \"model\": \"gpt-4o-mini-2024-07-18\"\
+        ,\n  \"choices\": [\n    {\n      \"index\": 0,\n      \"message\": {\n  \
+        \      \"role\": \"assistant\",\n        \"content\": \"hello world\",\n \
+        \       \"refusal\": null,\n        \"annotations\": []\n      },\n      \"\
+        logprobs\": null,\n      \"finish_reason\": \"stop\"\n    }\n  ],\n  \"usage\"\
+        : {\n    \"prompt_tokens\": 71,\n    \"completion_tokens\": 2,\n    \"total_tokens\"\
+        : 73,\n    \"prompt_tokens_details\": {\n      \"cached_tokens\": 0,\n   \
+        \   \"audio_tokens\": 0\n    },\n    \"completion_tokens_details\": {\n  \
+        \    \"reasoning_tokens\": 0,\n      \"audio_tokens\": 0,\n      \"accepted_prediction_tokens\"\
+        : 0,\n      \"rejected_prediction_tokens\": 0\n    }\n  },\n  \"service_tier\"\
+        : \"default\",\n  \"system_fingerprint\": \"fp_df8c8d3b43\"\n}\n"
+    headers:
+      Access-Control-Expose-Headers:
+      - ACCESS-CONTROL-XXX
+      CF-Cache-Status:
+      - DYNAMIC
+      CF-Ray:
+      - a05944f98aa2456e-SJC
+      Connection:
+      - keep-alive
+      Content-Type:
+      - application/json
+      Date:
+      - Tue, 02 Jun 2026 20:39:48 GMT
+      Server:
+      - cloudflare
+      Strict-Transport-Security:
+      - STS-XXX
+      Transfer-Encoding:
+      - chunked
+      X-Content-Type-Options:
+      - X-CONTENT-TYPE-XXX
+      access-control-expose-headers:
+      - ACCESS-CONTROL-XXX
+      alt-svc:
+      - h3=":443"; ma=86400
+      openai-organization:
+      - OPENAI-ORG-XXX
+      openai-processing-ms:
+      - '394'
+      openai-project:
+      - OPENAI-PROJECT-XXX
+      openai-version:
+      - '2020-10-01'
+      set-cookie:
+      - SET-COOKIE-XXX
+      x-openai-proxy-wasm:
+      - v0.1
+      x-ratelimit-limit-requests:
+      - X-RATELIMIT-LIMIT-REQUESTS-XXX
+      x-ratelimit-limit-tokens:
+      - X-RATELIMIT-LIMIT-TOKENS-XXX
+      x-ratelimit-remaining-requests:
+      - X-RATELIMIT-REMAINING-REQUESTS-XXX
+      x-ratelimit-remaining-tokens:
+      - X-RATELIMIT-REMAINING-TOKENS-XXX
+      x-ratelimit-reset-requests:
+      - X-RATELIMIT-RESET-REQUESTS-XXX
+      x-ratelimit-reset-tokens:
+      - X-RATELIMIT-RESET-TOKENS-XXX
+      x-request-id:
+      - X-REQUEST-ID-XXX
+    status:
+      code: 200
+      message: OK
 - request:
     body: '{"version": "0.152.0", "batch_id": "2487456d-e03a-4eae-92a1-e9779e8f06a1",
       "user_context": {"user_id": "anonymous", "organization_id": "", "session_id":
@@ -471,4 +337,3 @@ interactions:
     status:
       code: 404
       message: Not Found
-version: 1

lib/crewai/tests/cassettes/tracing/TestTraceListenerSetup.test_trace_listener_ephemeral_batch.yaml

@@ -1,4 +1,115 @@
 interactions:
+- request:
+    body: '{"messages":[{"role":"system","content":"You are Test Agent. Test backstory\nYour
+      personal goal is: Test goal"},{"role":"user","content":"\nCurrent Task: Say
+      hello to the world\n\nThis is the expected criteria for your final answer: hello
+      world\nyou MUST return the actual complete content as the final answer, not
+      a summary.\n\nProvide your complete response:"}],"model":"gpt-4o-mini"}'
+    headers:
+      User-Agent:
+      - X-USER-AGENT-XXX
+      accept:
+      - application/json
+      accept-encoding:
+      - ACCEPT-ENCODING-XXX
+      authorization:
+      - AUTHORIZATION-XXX
+      connection:
+      - keep-alive
+      content-length:
+      - '386'
+      content-type:
+      - application/json
+      host:
+      - api.openai.com
+      x-stainless-arch:
+      - X-STAINLESS-ARCH-XXX
+      x-stainless-async:
+      - 'false'
+      x-stainless-lang:
+      - python
+      x-stainless-os:
+      - X-STAINLESS-OS-XXX
+      x-stainless-package-version:
+      - 2.32.0
+      x-stainless-read-timeout:
+      - X-STAINLESS-READ-TIMEOUT-XXX
+      x-stainless-retry-count:
+      - '0'
+      x-stainless-runtime:
+      - CPython
+      x-stainless-runtime-version:
+      - 3.13.3
+    method: POST
+    uri: https://api.openai.com/v1/chat/completions
+  response:
+    body:
+      string: "{\n  \"id\": \"chatcmpl-DmQXbDeAmcQ7GbteZjiMuOWd66nWp\",\n  \"object\"\
+        : \"chat.completion\",\n  \"created\": 1780434139,\n  \"model\": \"gpt-4o-mini-2024-07-18\"\
+        ,\n  \"choices\": [\n    {\n      \"index\": 0,\n      \"message\": {\n  \
+        \      \"role\": \"assistant\",\n        \"content\": \"hello world\",\n \
+        \       \"refusal\": null,\n        \"annotations\": []\n      },\n      \"\
+        logprobs\": null,\n      \"finish_reason\": \"stop\"\n    }\n  ],\n  \"usage\"\
+        : {\n    \"prompt_tokens\": 71,\n    \"completion_tokens\": 2,\n    \"total_tokens\"\
+        : 73,\n    \"prompt_tokens_details\": {\n      \"cached_tokens\": 0,\n   \
+        \   \"audio_tokens\": 0\n    },\n    \"completion_tokens_details\": {\n  \
+        \    \"reasoning_tokens\": 0,\n      \"audio_tokens\": 0,\n      \"accepted_prediction_tokens\"\
+        : 0,\n      \"rejected_prediction_tokens\": 0\n    }\n  },\n  \"service_tier\"\
+        : \"default\",\n  \"system_fingerprint\": \"fp_df8c8d3b43\"\n}\n"
+    headers:
+      Access-Control-Expose-Headers:
+      - ACCESS-CONTROL-XXX
+      CF-Cache-Status:
+      - DYNAMIC
+      CF-Ray:
+      - a05965f97dd8ad81-SJC
+      Connection:
+      - keep-alive
+      Content-Type:
+      - application/json
+      Date:
+      - Tue, 02 Jun 2026 21:02:19 GMT
+      Server:
+      - cloudflare
+      Strict-Transport-Security:
+      - STS-XXX
+      Transfer-Encoding:
+      - chunked
+      X-Content-Type-Options:
+      - X-CONTENT-TYPE-XXX
+      access-control-expose-headers:
+      - ACCESS-CONTROL-XXX
+      alt-svc:
+      - h3=":443"; ma=86400
+      openai-organization:
+      - OPENAI-ORG-XXX
+      openai-processing-ms:
+      - '330'
+      openai-project:
+      - OPENAI-PROJECT-XXX
+      openai-version:
+      - '2020-10-01'
+      set-cookie:
+      - SET-COOKIE-XXX
+      x-openai-proxy-wasm:
+      - v0.1
+      x-ratelimit-limit-requests:
+      - X-RATELIMIT-LIMIT-REQUESTS-XXX
+      x-ratelimit-limit-tokens:
+      - X-RATELIMIT-LIMIT-TOKENS-XXX
+      x-ratelimit-remaining-requests:
+      - X-RATELIMIT-REMAINING-REQUESTS-XXX
+      x-ratelimit-remaining-tokens:
+      - X-RATELIMIT-REMAINING-TOKENS-XXX
+      x-ratelimit-reset-requests:
+      - X-RATELIMIT-RESET-REQUESTS-XXX
+      x-ratelimit-reset-tokens:
+      - X-RATELIMIT-RESET-TOKENS-XXX
+      x-request-id:
+      - X-REQUEST-ID-XXX
+    status:
+      code: 200
+      message: OK
 - request:
     body: '{}'
     headers:
@@ -88,129 +199,6 @@ interactions:
     status:
       code: 201
       message: Created
-- request:
-    body: '{"messages":[{"role":"system","content":"You are Test Agent. Test backstory\nYour
-      personal goal is: Test goal\nTo give my best complete final answer to the task
-      respond using the exact following format:\n\nThought: I now can give a great
-      answer\nFinal Answer: Your final answer must be the great and the most complete
-      as possible, it must be outcome described.\n\nI MUST use these formats, my job
-      depends on it!"},{"role":"user","content":"\nCurrent Task: Say hello to the
-      world\n\nThis is the expected criteria for your final answer: hello world\nyou
-      MUST return the actual complete content as the final answer, not a summary.\n\nBegin!
-      This is VERY important to you, use the tools available and give your best Final
-      Answer, your job depends on it!\n\nThought:"}],"model":"gpt-4o-mini"}'
-    headers:
-      accept:
-      - application/json
-      accept-encoding:
-      - gzip, deflate
-      authorization:
-      - AUTHORIZATION-XXX
-      connection:
-      - keep-alive
-      content-length:
-      - '787'
-      content-type:
-      - application/json
-      host:
-      - api.openai.com
-      user-agent:
-      - OpenAI/Python 1.109.1
-      x-stainless-arch:
-      - X-STAINLESS-ARCH-XXX
-      x-stainless-async:
-      - 'false'
-      x-stainless-lang:
-      - python
-      x-stainless-os:
-      - X-STAINLESS-OS-XXX
-      x-stainless-package-version:
-      - 1.109.1
-      x-stainless-read-timeout:
-      - X-STAINLESS-READ-TIMEOUT-XXX
-      x-stainless-retry-count:
-      - '0'
-      x-stainless-runtime:
-      - CPython
-      x-stainless-runtime-version:
-      - 3.12.10
-    method: POST
-    uri: https://api.openai.com/v1/chat/completions
-  response:
-    body:
-      string: "{\n  \"id\": \"chatcmpl-Ch5flaLDqIqyRdYlrrvZ3Pu6emSal\",\n  \"object\"\
-        : \"chat.completion\",\n  \"created\": 1764385945,\n  \"model\": \"gpt-4o-mini-2024-07-18\"\
-        ,\n  \"choices\": [\n    {\n      \"index\": 0,\n      \"message\": {\n  \
-        \      \"role\": \"assistant\",\n        \"content\": \"I now can give a great\
-        \ answer  \\nFinal Answer: hello world\",\n        \"refusal\": null,\n  \
-        \      \"annotations\": []\n      },\n      \"logprobs\": null,\n      \"\
-        finish_reason\": \"stop\"\n    }\n  ],\n  \"usage\": {\n    \"prompt_tokens\"\
-        : 157,\n    \"completion_tokens\": 13,\n    \"total_tokens\": 170,\n    \"\
-        prompt_tokens_details\": {\n      \"cached_tokens\": 0,\n      \"audio_tokens\"\
-        : 0\n    },\n    \"completion_tokens_details\": {\n      \"reasoning_tokens\"\
-        : 0,\n      \"audio_tokens\": 0,\n      \"accepted_prediction_tokens\": 0,\n\
-        \      \"rejected_prediction_tokens\": 0\n    }\n  },\n  \"service_tier\"\
-        : \"default\",\n  \"system_fingerprint\": \"fp_560af6e559\"\n}\n"
-    headers:
-      CF-RAY:
-      - CF-RAY-XXX
-      Connection:
-      - keep-alive
-      Content-Type:
-      - application/json
-      Date:
-      - Sat, 29 Nov 2025 03:12:26 GMT
-      Server:
-      - cloudflare
-      Set-Cookie:
-      - SET-COOKIE-XXX
-      Strict-Transport-Security:
-      - STS-XXX
-      Transfer-Encoding:
-      - chunked
-      X-Content-Type-Options:
-      - X-CONTENT-TYPE-XXX
-      access-control-expose-headers:
-      - ACCESS-CONTROL-XXX
-      alt-svc:
-      - h3=":443"; ma=86400
-      cf-cache-status:
-      - DYNAMIC
-      openai-organization:
-      - OPENAI-ORG-XXX
-      openai-processing-ms:
-      - '443'
-      openai-project:
-      - OPENAI-PROJECT-XXX
-      openai-version:
-      - '2020-10-01'
-      x-envoy-upstream-service-time:
-      - '655'
-      x-openai-proxy-wasm:
-      - v0.1
-      x-ratelimit-limit-project-tokens:
-      - '150000000'
-      x-ratelimit-limit-requests:
-      - X-RATELIMIT-LIMIT-REQUESTS-XXX
-      x-ratelimit-limit-tokens:
-      - X-RATELIMIT-LIMIT-TOKENS-XXX
-      x-ratelimit-remaining-project-tokens:
-      - '149999827'
-      x-ratelimit-remaining-requests:
-      - X-RATELIMIT-REMAINING-REQUESTS-XXX
-      x-ratelimit-remaining-tokens:
-      - X-RATELIMIT-REMAINING-TOKENS-XXX
-      x-ratelimit-reset-project-tokens:
-      - 0s
-      x-ratelimit-reset-requests:
-      - X-RATELIMIT-RESET-REQUESTS-XXX
-      x-ratelimit-reset-tokens:
-      - X-RATELIMIT-RESET-TOKENS-XXX
-      x-request-id:
-      - X-REQUEST-ID-XXX
-    status:
-      code: 200
-      message: OK
 - request:
     body: '{"events": [{"event_id": "e73c85bb-b00f-46be-b07f-cfbd398e24d9", "timestamp":
       "2025-11-29T03:12:24.774266+00:00", "type": "crew_kickoff_started", "event_data":
@@ -416,4 +404,3 @@ interactions:
     status:
       code: 200
       message: OK
-version: 1

lib/crewai/tests/cassettes/tracing/TestTraceListenerSetup.test_trace_listener_with_authenticated_user.yaml

@@ -18,126 +18,113 @@ interactions:
       code: 200
       message: OK
 - request:
-    body: '{"messages": [{"role": "system", "content": "You are Test Agent. Test backstory\nYour
-      personal goal is: Test goal\nTo give my best complete final answer to the task
-      respond using the exact following format:\n\nThought: I now can give a great
-      answer\nFinal Answer: Your final answer must be the great and the most complete
-      as possible, it must be outcome described.\n\nI MUST use these formats, my job
-      depends on it!"}, {"role": "user", "content": "\nCurrent Task: Say hello to
-      the world\n\nThis is the expected criteria for your final answer: hello world\nyou
-      MUST return the actual complete content as the final answer, not a summary.\n\nBegin!
-      This is VERY important to you, use the tools available and give your best Final
-      Answer, your job depends on it!\n\nThought:"}], "model": "gpt-4o-mini", "stop":
-      ["\nObservation:"]}'
+    body: '{"messages":[{"role":"system","content":"You are Test Agent. Test backstory\nYour
+      personal goal is: Test goal"},{"role":"user","content":"\nCurrent Task: Say
+      hello to the world\n\nThis is the expected criteria for your final answer: hello
+      world\nyou MUST return the actual complete content as the final answer, not
+      a summary.\n\nProvide your complete response:"}],"model":"gpt-4o-mini"}'
     headers:
+      User-Agent:
+      - X-USER-AGENT-XXX
       accept:
       - application/json
       accept-encoding:
-      - gzip, deflate, zstd
+      - ACCEPT-ENCODING-XXX
+      authorization:
+      - AUTHORIZATION-XXX
       connection:
       - keep-alive
       content-length:
-      - '825'
+      - '386'
       content-type:
       - application/json
-      cookie:
-      - __cf_bm=oA9oTa3cE0ZaEUDRf0hCpnarSAQKzrVUhl6qDS4j09w-1755302115-1.0.1.1-gUUDl4ZqvBQkg7244DTwOmSiDUT2z_AiQu0P1xUaABjaufSpZuIlI5G0H7OSnW.ldypvpxjj45NGWesJ62M_2U7r20tHz_gMmDFw6D5ZiNc;
-        _cfuvid=ICenEGMmOE5jaOjwD30bAOwrF8.XRbSIKTBl1EyWs0o-1755302115700-0.0.1.1-604800000
       host:
       - api.openai.com
-      user-agent:
-      - OpenAI/Python 1.93.0
       x-stainless-arch:
-      - arm64
+      - X-STAINLESS-ARCH-XXX
       x-stainless-async:
       - 'false'
       x-stainless-lang:
       - python
       x-stainless-os:
-      - MacOS
+      - X-STAINLESS-OS-XXX
       x-stainless-package-version:
-      - 1.93.0
-      x-stainless-raw-response:
-      - 'true'
+      - 2.32.0
       x-stainless-read-timeout:
-      - '600.0'
+      - X-STAINLESS-READ-TIMEOUT-XXX
       x-stainless-retry-count:
       - '0'
       x-stainless-runtime:
       - CPython
       x-stainless-runtime-version:
-      - 3.12.9
+      - 3.13.3
     method: POST
     uri: https://api.openai.com/v1/chat/completions
   response:
     body:
-      string: "{\n  \"id\": \"chatcmpl-C4yYNqrSmM0fkSWqb4T6tcks2vwV3\",\n  \"object\"\
-        : \"chat.completion\",\n  \"created\": 1755302115,\n  \"model\": \"gpt-4o-mini-2024-07-18\"\
+      string: "{\n  \"id\": \"chatcmpl-DmQXhgUdsjl74u2ygEBsUUnuMOpRq\",\n  \"object\"\
+        : \"chat.completion\",\n  \"created\": 1780434145,\n  \"model\": \"gpt-4o-mini-2024-07-18\"\
         ,\n  \"choices\": [\n    {\n      \"index\": 0,\n      \"message\": {\n  \
-        \      \"role\": \"assistant\",\n        \"content\": \"I now can give a great\
-        \ answer  \\nFinal Answer: hello world\",\n        \"refusal\": null,\n  \
-        \      \"annotations\": []\n      },\n      \"logprobs\": null,\n      \"\
-        finish_reason\": \"stop\"\n    }\n  ],\n  \"usage\": {\n    \"prompt_tokens\"\
-        : 157,\n    \"completion_tokens\": 13,\n    \"total_tokens\": 170,\n    \"\
-        prompt_tokens_details\": {\n      \"cached_tokens\": 0,\n      \"audio_tokens\"\
-        : 0\n    },\n    \"completion_tokens_details\": {\n      \"reasoning_tokens\"\
-        : 0,\n      \"audio_tokens\": 0,\n      \"accepted_prediction_tokens\": 0,\n\
-        \      \"rejected_prediction_tokens\": 0\n    }\n  },\n  \"service_tier\"\
-        : \"default\",\n  \"system_fingerprint\": \"fp_560af6e559\"\n}\n"
+        \      \"role\": \"assistant\",\n        \"content\": \"hello world\",\n \
+        \       \"refusal\": null,\n        \"annotations\": []\n      },\n      \"\
+        logprobs\": null,\n      \"finish_reason\": \"stop\"\n    }\n  ],\n  \"usage\"\
+        : {\n    \"prompt_tokens\": 71,\n    \"completion_tokens\": 2,\n    \"total_tokens\"\
+        : 73,\n    \"prompt_tokens_details\": {\n      \"cached_tokens\": 0,\n   \
+        \   \"audio_tokens\": 0\n    },\n    \"completion_tokens_details\": {\n  \
+        \    \"reasoning_tokens\": 0,\n      \"audio_tokens\": 0,\n      \"accepted_prediction_tokens\"\
+        : 0,\n      \"rejected_prediction_tokens\": 0\n    }\n  },\n  \"service_tier\"\
+        : \"default\",\n  \"system_fingerprint\": \"fp_df8c8d3b43\"\n}\n"
     headers:
-      CF-RAY:
-      - 96fc9f301bf7cf1f-SJC
+      Access-Control-Expose-Headers:
+      - ACCESS-CONTROL-XXX
+      CF-Cache-Status:
+      - DYNAMIC
+      CF-Ray:
+      - a059661ddb01cf93-SJC
       Connection:
       - keep-alive
       Content-Type:
       - application/json
       Date:
-      - Fri, 15 Aug 2025 23:55:16 GMT
+      - Tue, 02 Jun 2026 21:02:25 GMT
       Server:
       - cloudflare
       Strict-Transport-Security:
-      - max-age=31536000; includeSubDomains; preload
+      - STS-XXX
       Transfer-Encoding:
       - chunked
       X-Content-Type-Options:
-      - nosniff
+      - X-CONTENT-TYPE-XXX
       access-control-expose-headers:
-      - X-Request-ID
+      - ACCESS-CONTROL-XXX
       alt-svc:
       - h3=":443"; ma=86400
-      cf-cache-status:
-      - DYNAMIC
       openai-organization:
-      - crewai-iuxna1
+      - OPENAI-ORG-XXX
       openai-processing-ms:
-      - '685'
+      - '494'
       openai-project:
-      - proj_xitITlrFeen7zjNSzML82h9x
+      - OPENAI-PROJECT-XXX
       openai-version:
       - '2020-10-01'
-      x-envoy-upstream-service-time:
-      - '711'
-      x-ratelimit-limit-project-tokens:
-      - '150000000'
+      set-cookie:
+      - SET-COOKIE-XXX
+      x-openai-proxy-wasm:
+      - v0.1
       x-ratelimit-limit-requests:
-      - '30000'
+      - X-RATELIMIT-LIMIT-REQUESTS-XXX
       x-ratelimit-limit-tokens:
-      - '150000000'
-      x-ratelimit-remaining-project-tokens:
-      - '149999827'
+      - X-RATELIMIT-LIMIT-TOKENS-XXX
       x-ratelimit-remaining-requests:
-      - '29999'
+      - X-RATELIMIT-REMAINING-REQUESTS-XXX
       x-ratelimit-remaining-tokens:
-      - '149999827'
-      x-ratelimit-reset-project-tokens:
-      - 0s
+      - X-RATELIMIT-REMAINING-TOKENS-XXX
       x-ratelimit-reset-requests:
-      - 2ms
+      - X-RATELIMIT-RESET-REQUESTS-XXX
       x-ratelimit-reset-tokens:
-      - 0s
+      - X-RATELIMIT-RESET-TOKENS-XXX
       x-request-id:
-      - req_3f0ec42447374a76a22a4cdb9f336279
+      - X-REQUEST-ID-XXX
     status:
       code: 200
       message: OK
-version: 1

lib/crewai/tests/events/test_llm_finish_reason_response_id.py

@@ -0,0 +1,526 @@
+from types import SimpleNamespace
+from typing import Any
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from crewai.events.event_bus import CrewAIEventsBus
+from crewai.events.types.llm_events import (
+    LLMCallCompletedEvent,
+    LLMCallStartedEvent,
+    LLMCallType,
+    LLMStreamChunkEvent,
+)
+from crewai.llm import LLM
+from crewai.llms._finish_reason_utils import extract_choices_finish_reason_and_id
+from crewai.llms.base_llm import BaseLLM
+
+
+class _StubLLM(BaseLLM):
+    model: str = "test-model"
+
+    def call(self, *args: Any, **kwargs: Any) -> str:
+        return ""
+
+    async def acall(self, *args: Any, **kwargs: Any) -> str:
+        return ""
+
+    def supports_function_calling(self) -> bool:
+        return False
+
+
+@pytest.fixture
+def mock_emit():
+    with patch.object(CrewAIEventsBus, "emit") as mock:
+        yield mock
+
+
+class TestLLMCallCompletedEventFinishReasonAndResponseId:
+    def test_accepts_string_values(self):
+        event = LLMCallCompletedEvent(
+            response="hi",
+            call_type=LLMCallType.LLM_CALL,
+            call_id="call-1",
+            finish_reason="stop",
+            response_id="resp_123",
+        )
+        assert event.finish_reason == "stop"
+        assert event.response_id == "resp_123"
+
+    def test_defaults_to_none(self):
+        event = LLMCallCompletedEvent(
+            response="hi",
+            call_type=LLMCallType.LLM_CALL,
+            call_id="call-1",
+        )
+        assert event.finish_reason is None
+        assert event.response_id is None
+
+    @pytest.mark.parametrize(
+        "value",
+        [MagicMock(), 42, 1.5, ["stop"], {"reason": "stop"}, object()],
+    )
+    def test_coerces_non_string_to_none(self, value):
+        event = LLMCallCompletedEvent(
+            response="hi",
+            call_type=LLMCallType.LLM_CALL,
+            call_id="call-1",
+            finish_reason=value,
+            response_id=value,
+        )
+        assert event.finish_reason is None
+        assert event.response_id is None
+
+
+class TestLLMCallStartedEventSamplingParams:
+    def test_accepts_all_sampling_params(self):
+        event = LLMCallStartedEvent(
+            call_id="call-1",
+            temperature=0.7,
+            top_p=0.9,
+            max_tokens=512,
+            stream=True,
+            seed=42,
+            stop_sequences=["END"],
+            frequency_penalty=0.1,
+            presence_penalty=0.2,
+            n=3,
+        )
+        assert event.temperature == 0.7
+        assert event.top_p == 0.9
+        assert event.max_tokens == 512
+        assert event.stream is True
+        assert event.seed == 42
+        assert event.stop_sequences == ["END"]
+        assert event.frequency_penalty == 0.1
+        assert event.presence_penalty == 0.2
+        assert event.n == 3
+
+    def test_all_sampling_params_default_to_none(self):
+        event = LLMCallStartedEvent(call_id="call-1")
+        assert event.temperature is None
+        assert event.top_p is None
+        assert event.max_tokens is None
+        assert event.stream is None
+        assert event.seed is None
+        assert event.stop_sequences is None
+        assert event.frequency_penalty is None
+        assert event.presence_penalty is None
+        assert event.n is None
+
+
+class TestStopSequencesCoercion:
+    # The OTel SDK falls back to str(value) when a span attribute isn't a
+    # recognised Sequence[str], producing the protobuf textproto repr
+    # ("values { string_value: ... }") in downstream telemetry. The
+    # field_validator coerces exotic iterables (Vertex/Gemini protobuf
+    # containers, tuples, generators) to a clean list[str] up front so the
+    # OTel attribute is always shaped correctly.
+    def test_bare_string_is_wrapped_in_list(self):
+        event = LLMCallStartedEvent(call_id="call-1", stop_sequences="\nObservation:")
+        assert event.stop_sequences == ["\nObservation:"]
+
+    @pytest.mark.parametrize(
+        "raw, expected",
+        [
+            (["\nObservation:", "Final Answer:"], ["\nObservation:", "Final Answer:"]),
+            (("\nObservation:",), ["\nObservation:"]),
+            ((s for s in ["a", "b"]), ["a", "b"]),
+            ([], []),
+        ],
+    )
+    def test_python_iterables_pass_through(
+        self, raw: Any, expected: list[str]
+    ) -> None:
+        event = LLMCallStartedEvent(call_id="call-1", stop_sequences=raw)
+        assert event.stop_sequences == expected
+
+    def test_protobuf_like_repeated_container_is_coerced(self):
+        # Mirrors google.protobuf RepeatedScalarContainer: iterable yielding
+        # actual Python str objects. Should pass through cleanly.
+        class _RepeatedScalar:
+            def __init__(self, items: list[str]) -> None:
+                self._items = items
+
+            def __iter__(self):
+                return iter(self._items)
+
+        event = LLMCallStartedEvent(
+            call_id="call-1",
+            stop_sequences=_RepeatedScalar(["\nObservation:"]),
+        )
+        assert event.stop_sequences == ["\nObservation:"]
+
+    def test_protobuf_listvalue_with_nested_values_coerces_to_textproto_strings(self):
+        # Mirrors google.protobuf.struct_pb2.ListValue: iterable yielding
+        # `Value` messages whose str() is "string_value: \"...\"". The
+        # coercion will str() each element, which is still wrong-shaped but
+        # at least lands as a real list[str] for the OTel attribute instead
+        # of a single textproto-blob string. Documents observed behaviour;
+        # the upstream fix is to pass list[str] to LLM.stop, not ListValue.
+        class _PbValue:
+            def __init__(self, string_value: str) -> None:
+                self.string_value = string_value
+
+            def __str__(self) -> str:
+                return f'string_value: "{self.string_value}"'
+
+        class _PbListValue:
+            def __init__(self, values: list[_PbValue]) -> None:
+                self.values = values
+
+            def __iter__(self):
+                return iter(self.values)
+
+        event = LLMCallStartedEvent(
+            call_id="call-1",
+            stop_sequences=_PbListValue([_PbValue("\\nObservation:")]),
+        )
+        assert event.stop_sequences == ['string_value: "\\nObservation:"']
+
+    @pytest.mark.parametrize("bad_input", [123, 12.5, object()])
+    def test_non_iterable_falls_back_to_none(self, bad_input: Any) -> None:
+        event = LLMCallStartedEvent(call_id="call-1", stop_sequences=bad_input)
+        assert event.stop_sequences is None
+
+    def test_none_stays_none(self):
+        event = LLMCallStartedEvent(call_id="call-1", stop_sequences=None)
+        assert event.stop_sequences is None
+
+
+class TestEmitCallStartedEventIntrospectsSamplingParams:
+    def test_reads_sampling_params_off_self(self, mock_emit):
+        llm = _StubLLM(model="test-model", temperature=0.4)
+        llm.top_p = 0.8
+        llm.max_tokens = 256
+        llm.stream = False
+        llm.seed = 7
+        llm.frequency_penalty = 0.5
+        llm.presence_penalty = 0.6
+        llm.n = 2
+        llm.stop = ["STOP"]
+
+        llm._emit_call_started_event(messages="hi")
+
+        event = mock_emit.call_args[1]["event"]
+        assert isinstance(event, LLMCallStartedEvent)
+        assert event.temperature == 0.4
+        assert event.top_p == 0.8
+        assert event.max_tokens == 256
+        assert event.stream is False
+        assert event.seed == 7
+        assert event.stop_sequences == ["STOP"]
+        assert event.frequency_penalty == 0.5
+        assert event.presence_penalty == 0.6
+        assert event.n == 2
+
+    def test_explicit_kwargs_override_introspection(self, mock_emit):
+        llm = _StubLLM(model="test-model", temperature=0.4)
+
+        llm._emit_call_started_event(messages="hi", temperature=0.9)
+
+        event = mock_emit.call_args[1]["event"]
+        assert event.temperature == 0.9
+
+
+class TestBaseLLMSamplingParamFields:
+    # Regression: PR #5945 review feedback. Sampling params are declared as
+    # typed fields on BaseLLM so ``_emit_call_started_event`` reads them via
+    # plain attribute access instead of getattr/hasattr fallbacks. Kwargs
+    # like ``n=1`` bind directly to the typed field via Pydantic; there is
+    # no promotion from ``additional_params``.
+    def test_sampling_kwargs_bind_to_typed_fields(self, mock_emit):
+        from crewai.llms.providers.openai.completion import OpenAICompletion
+
+        llm = LLM(model="gpt-4", n=1, temperature=0.5, seed=42)
+
+        assert isinstance(llm, OpenAICompletion)
+        assert llm.n == 1
+        assert llm.temperature == 0.5
+        assert llm.seed == 42
+        assert "n" not in llm.additional_params
+        assert "temperature" not in llm.additional_params
+        assert "seed" not in llm.additional_params
+
+        llm._emit_call_started_event(messages="hi")
+
+        event = mock_emit.call_args[1]["event"]
+        assert isinstance(event, LLMCallStartedEvent)
+        assert event.n == 1
+        assert event.temperature == 0.5
+        assert event.seed == 42
+
+    def test_additional_params_are_not_promoted_to_typed_fields(self, mock_emit):
+        # Callers who pass sampling params through ``additional_params``
+        # opt out of typed-field semantics. We intentionally do NOT promote
+        # those values back into ``self.n`` / ``self.temperature``, so the
+        # emitter sees ``None`` for those attributes. If a caller wants the
+        # value surfaced in telemetry, they pass it as a kwarg.
+        llm = LLM(
+            model="gpt-4",
+            additional_params={"n": 1, "temperature": 0.5, "seed": 42},
+        )
+
+        assert llm.n is None
+        assert llm.temperature is None
+        assert llm.seed is None
+        assert llm.additional_params == {"n": 1, "temperature": 0.5, "seed": 42}
+
+        llm._emit_call_started_event(messages="hi")
+
+        event = mock_emit.call_args[1]["event"]
+        assert isinstance(event, LLMCallStartedEvent)
+        assert event.n is None
+        assert event.temperature is None
+        assert event.seed is None
+
+    def test_emit_uses_call_scoped_stop_override(self, mock_emit):
+        from crewai.llms.base_llm import call_stop_override
+
+        llm = _StubLLM(model="test-model", stop=["A"])
+
+        with call_stop_override(llm, ["X"]):
+            llm._emit_call_started_event(messages="hi")
+
+        event = mock_emit.call_args[1]["event"]
+        assert isinstance(event, LLMCallStartedEvent)
+        assert event.stop_sequences == ["X"]
+        # Instance-level stop is never mutated by the override.
+        assert llm.stop == ["A"]
+
+
+class TestEffectiveMaxTokensTelemetry:
+    def test_base_defaults_to_max_tokens(self, mock_emit):
+        llm = _StubLLM(model="test-model", max_tokens=256)
+
+        llm._emit_call_started_event(messages="hi")
+
+        event = mock_emit.call_args[1]["event"]
+        assert event.max_tokens == 256
+
+    def test_openai_surfaces_max_completion_tokens(self, mock_emit):
+        from crewai.llms.providers.openai.completion import OpenAICompletion
+
+        llm = LLM(model="gpt-4o", max_completion_tokens=512)
+        assert isinstance(llm, OpenAICompletion)
+        assert llm.max_tokens is None
+
+        llm._emit_call_started_event(messages="hi")
+
+        event = mock_emit.call_args[1]["event"]
+        assert event.max_tokens == 512
+
+    def test_explicit_max_tokens_takes_precedence(self, mock_emit):
+        llm = LLM(model="gpt-4o", max_tokens=128, max_completion_tokens=512)
+
+        llm._emit_call_started_event(messages="hi")
+
+        event = mock_emit.call_args[1]["event"]
+        assert event.max_tokens == 128
+
+
+class TestStreamingDictChunkResponseIdPropagation:
+    # Regression: PR #5945 coderabbitai feedback. The streaming loop only
+    # extracted ``chunk.id`` for ``ModelResponseBase`` instances; dict-shaped
+    # chunks (LiteLLM emits these in some configs) silently dropped the id
+    # and ``LLMStreamChunkEvent.response_id`` came through as ``None``.
+    def _dict_chunks(self) -> list[dict[str, Any]]:
+        return [
+            {
+                "id": "test-chunk-id",
+                "choices": [{"delta": {"content": "hi"}, "finish_reason": None}],
+            },
+            {
+                "id": "test-chunk-id",
+                "choices": [{"delta": {"content": " there"}, "finish_reason": "stop"}],
+            },
+        ]
+
+    def _stream_event_response_ids(self, mock_emit) -> list[str | None]:
+        return [
+            call.kwargs["event"].response_id
+            for call in mock_emit.call_args_list
+            if isinstance(call.kwargs.get("event"), LLMStreamChunkEvent)
+        ]
+
+    def test_sync_dict_chunk_id_propagates_to_stream_event(self, mock_emit):
+        llm = LLM(model="gpt-4o-mini", is_litellm=True, stream=True)
+
+        with patch(
+            "crewai.llm.litellm.completion",
+            return_value=iter(self._dict_chunks()),
+        ):
+            llm.call("anything")
+
+        ids = self._stream_event_response_ids(mock_emit)
+        assert ids, "expected at least one LLMStreamChunkEvent"
+        assert all(rid == "test-chunk-id" for rid in ids), ids
+
+    @pytest.mark.asyncio
+    async def test_async_dict_chunk_id_propagates_to_stream_event(self, mock_emit):
+        llm = LLM(model="gpt-4o-mini", is_litellm=True, stream=True)
+
+        async def _aiter():
+            for chunk in self._dict_chunks():
+                yield chunk
+
+        async def _acompletion(*_args, **_kwargs):
+            return _aiter()
+
+        with patch("crewai.llm.litellm.acompletion", side_effect=_acompletion):
+            await llm.acall("anything")
+
+        ids = self._stream_event_response_ids(mock_emit)
+        assert ids, "expected at least one LLMStreamChunkEvent"
+        assert all(rid == "test-chunk-id" for rid in ids), ids
+
+
+class TestEmitCallCompletedEventPassesFinishReasonAndResponseId:
+    def test_passes_through_to_event(self, mock_emit):
+        llm = _StubLLM(model="test-model")
+
+        llm._emit_call_completed_event(
+            response="hi",
+            call_type=LLMCallType.LLM_CALL,
+            finish_reason="stop",
+            response_id="resp_123",
+        )
+
+        event = mock_emit.call_args[1]["event"]
+        assert isinstance(event, LLMCallCompletedEvent)
+        assert event.finish_reason == "stop"
+        assert event.response_id == "resp_123"
+
+    def test_omitted_defaults_to_none(self, mock_emit):
+        llm = _StubLLM(model="test-model")
+
+        llm._emit_call_completed_event(
+            response="hi",
+            call_type=LLMCallType.LLM_CALL,
+        )
+
+        event = mock_emit.call_args[1]["event"]
+        assert event.finish_reason is None
+        assert event.response_id is None
+
+
+class TestLLMExtractFinishReasonAndResponseId:
+    def test_non_streaming_litellm_shape(self):
+        response = SimpleNamespace(
+            id="chatcmpl-abc",
+            choices=[SimpleNamespace(finish_reason="stop", message=SimpleNamespace())],
+        )
+
+        finish_reason, response_id = LLM._extract_finish_reason_and_response_id(
+            response
+        )
+
+        assert finish_reason == "stop"
+        assert response_id == "chatcmpl-abc"
+
+    def test_streaming_litellm_chunk_shape(self):
+        last_chunk = SimpleNamespace(
+            id="chatcmpl-stream-xyz",
+            choices=[SimpleNamespace(finish_reason="tool_calls", delta=SimpleNamespace())],
+        )
+
+        finish_reason, response_id = LLM._extract_finish_reason_and_response_id(
+            last_chunk
+        )
+
+        assert finish_reason == "tool_calls"
+        assert response_id == "chatcmpl-stream-xyz"
+
+    def test_dict_shape(self):
+        chunk = {
+            "id": "chatcmpl-dict",
+            "choices": [{"finish_reason": "length", "delta": {}}],
+        }
+
+        finish_reason, response_id = LLM._extract_finish_reason_and_response_id(chunk)
+
+        assert finish_reason == "length"
+        assert response_id == "chatcmpl-dict"
+
+    def test_missing_fields_return_none(self):
+        finish_reason, response_id = LLM._extract_finish_reason_and_response_id(
+            SimpleNamespace()
+        )
+
+        assert finish_reason is None
+        assert response_id is None
+
+    def test_non_string_values_coerced_to_none(self):
+        response = SimpleNamespace(
+            id=12345,
+            choices=[SimpleNamespace(finish_reason=MagicMock(), delta=SimpleNamespace())],
+        )
+
+        finish_reason, response_id = LLM._extract_finish_reason_and_response_id(
+            response
+        )
+
+        assert finish_reason is None
+        assert response_id is None
+
+    def test_never_raises_on_unexpected_input(self):
+        assert LLM._extract_finish_reason_and_response_id(None) == (None, None)
+        assert LLM._extract_finish_reason_and_response_id(42) == (None, None)
+        assert LLM._extract_finish_reason_and_response_id("string") == (None, None)
+
+
+class TestExtractChoicesFinishReasonAndIdHelper:
+    # The shared extractor is consumed by LLM (LiteLLM), OpenAI Chat, and Azure.
+    # TestLLMExtractFinishReasonAndResponseId exercises the choices-shape paths
+    # transitively; these tests cover the direct-call surface and the
+    # import contract.
+    @pytest.mark.parametrize(
+        "response, expected",
+        [
+            (
+                SimpleNamespace(
+                    id="resp-1", choices=[SimpleNamespace(finish_reason="stop")]
+                ),
+                ("stop", "resp-1"),
+            ),
+            (
+                {"id": "resp-2", "choices": [{"finish_reason": "length"}]},
+                ("length", "resp-2"),
+            ),
+            (
+                SimpleNamespace(
+                    id="resp-3", choices=[{"finish_reason": "tool_calls"}]
+                ),
+                ("tool_calls", "resp-3"),
+            ),
+            (
+                {
+                    "id": "resp-4",
+                    "choices": [SimpleNamespace(finish_reason="content_filter")],
+                },
+                ("content_filter", "resp-4"),
+            ),
+        ],
+    )
+    def test_extracts_choices_shape(
+        self, response: Any, expected: tuple[str | None, str | None]
+    ) -> None:
+        assert extract_choices_finish_reason_and_id(response) == expected
+
+    @pytest.mark.parametrize(
+        "bad_input",
+        [
+            None,
+            42,
+            "string",
+            {},
+            SimpleNamespace(),
+            SimpleNamespace(choices=[]),
+            SimpleNamespace(choices=[SimpleNamespace()]),
+            {"id": 12345, "choices": [{"finish_reason": MagicMock()}]},
+        ],
+    )
+    def test_never_raises_returns_nones_or_coerces(self, bad_input: Any) -> None:
+        finish_reason, response_id = extract_choices_finish_reason_and_id(bad_input)
+        assert finish_reason is None or isinstance(finish_reason, str)
+        assert response_id is None or isinstance(response_id, str)

lib/crewai/tests/events/test_llm_usage_event.py

@@ -61,9 +61,84 @@ class TestUsageToDict:
     def test_none_returns_none(self):
         assert LLM._usage_to_dict(None) is None
 
-    def test_dict_passes_through(self):
+    def test_dict_without_nested_shapes_is_returned_unchanged(self):
         usage = {"prompt_tokens": 10, "total_tokens": 30}
-        assert LLM._usage_to_dict(usage) is usage
+        result = LLM._usage_to_dict(usage)
+        assert result == usage
+        # The input dict is copied, not mutated, so derived keys are not added.
+        assert "cached_prompt_tokens" not in result
+
+    @pytest.mark.parametrize(
+        ("usage", "expected"),
+        [
+            pytest.param(
+                {"prompt_tokens": 100, "prompt_tokens_details": {"cached_tokens": 40}},
+                {"cached_prompt_tokens": 40},
+                id="openai-nested-cached-tokens",
+            ),
+            pytest.param(
+                {"prompt_tokens": 100, "cached_tokens": 30},
+                {"cached_prompt_tokens": 30},
+                id="flat-cached-tokens",
+            ),
+            pytest.param(
+                {"input_tokens": 100, "cache_read_input_tokens": 25},
+                {"cached_prompt_tokens": 25},
+                id="anthropic-cache-read-input-tokens",
+            ),
+            pytest.param(
+                {
+                    "completion_tokens": 200,
+                    "completion_tokens_details": {"reasoning_tokens": 60},
+                },
+                {"reasoning_tokens": 60},
+                id="openai-nested-reasoning-tokens",
+            ),
+            pytest.param(
+                {"input_tokens": 100, "cache_creation_input_tokens": 70},
+                {"cache_creation_tokens": 70},
+                id="anthropic-cache-creation-input-tokens",
+            ),
+            pytest.param(
+                {
+                    "prompt_tokens": 100,
+                    "completion_tokens": 200,
+                    "prompt_tokens_details": {"cached_tokens": 40},
+                    "completion_tokens_details": {"reasoning_tokens": 60},
+                    "cache_creation_input_tokens": 10,
+                },
+                {
+                    "cached_prompt_tokens": 40,
+                    "reasoning_tokens": 60,
+                    "cache_creation_tokens": 10,
+                },
+                id="all-buckets-from-nested-shapes",
+            ),
+        ],
+    )
+    def test_normalizes_nested_litellm_buckets(self, usage, expected):
+        result = LLM._usage_to_dict(usage)
+        for key, value in expected.items():
+            assert result[key] == value
+
+    def test_does_not_alter_core_token_counts(self):
+        usage = {
+            "prompt_tokens": 100,
+            "completion_tokens": 200,
+            "total_tokens": 300,
+            "prompt_tokens_details": {"cached_tokens": 40},
+        }
+        result = LLM._usage_to_dict(usage)
+        assert result["prompt_tokens"] == 100
+        assert result["completion_tokens"] == 200
+        assert result["total_tokens"] == 300
+
+    def test_absent_buckets_are_not_added(self):
+        usage = {"prompt_tokens": 100, "completion_tokens": 200, "total_tokens": 300}
+        result = LLM._usage_to_dict(usage)
+        assert "cached_prompt_tokens" not in result
+        assert "reasoning_tokens" not in result
+        assert "cache_creation_tokens" not in result
 
     def test_pydantic_model_uses_model_dump(self):
         class Usage(BaseModel):

lib/crewai/tests/llms/google/test_google.py

@@ -122,6 +122,20 @@ def test_gemini_completion_initialization_parameters():
     assert llm.top_k == 40
 
 
+def test_gemini_started_event_surfaces_max_output_tokens():
+    from crewai.events.event_bus import CrewAIEventsBus
+    from crewai.events.types.llm_events import LLMCallStartedEvent
+
+    llm = LLM(model="google/gemini-2.0-flash-001", max_output_tokens=2000, api_key="test-key")
+
+    with patch.object(CrewAIEventsBus, "emit") as mock_emit:
+        llm._emit_call_started_event(messages="hi")
+
+    event = mock_emit.call_args[1]["event"]
+    assert isinstance(event, LLMCallStartedEvent)
+    assert event.max_tokens == 2000
+
+
 def test_gemini_specific_parameters():
     """
     Test Gemini-specific parameters like stop_sequences, streaming, and safety settings

lib/crewai/tests/test_async_human_feedback.py

@@ -1012,7 +1012,7 @@ class TestLLMObjectPreservedInContext:
             call_kwargs = mock_collapse.call_args
             assert call_kwargs.kwargs["feedback"] == "this looks good, proceed!"
             assert call_kwargs.kwargs["outcomes"] == ["needs_changes", "approved"]
-            # LLM should be a live object (from _hf_llm) or reconstructed, not None
+            # LLM should be a live object (from _human_feedback_llm) or reconstructed, not None
             assert call_kwargs.kwargs["llm"] is not None
             assert getattr(call_kwargs.kwargs["llm"], "model", None) == "gemini-2.0-flash"
             assert flow2.last_human_feedback.outcome == "approved"
@@ -1171,8 +1171,8 @@ class TestAsyncHumanFeedbackEdgeCases:
 class TestLiveLLMPreservationOnResume:
     """Tests for preserving the full LLM config across HITL resume."""
 
-    def test_hf_llm_attribute_set_on_wrapper_with_basellm(self) -> None:
-        """Test that _hf_llm is set on the wrapper when llm is a BaseLLM instance."""
+    def test_human_feedback_llm_attribute_set_on_wrapper_with_basellm(self) -> None:
+        """Test that _human_feedback_llm is set on the wrapper when llm is a BaseLLM instance."""
         from crewai.llms.base_llm import BaseLLM
 
         mock_llm = MagicMock(spec=BaseLLM)
@@ -1191,11 +1191,11 @@ class TestLiveLLMPreservationOnResume:
         flow = TestFlow()
         method = flow._methods.get("review")
         assert method is not None
-        assert hasattr(method, "_hf_llm")
-        assert method._hf_llm is mock_llm
+        assert hasattr(method, "_human_feedback_llm")
+        assert method._human_feedback_llm is mock_llm
 
-    def test_hf_llm_attribute_set_on_wrapper_with_string(self) -> None:
-        """Test that _hf_llm is set on the wrapper even when llm is a string."""
+    def test_human_feedback_llm_attribute_set_on_wrapper_with_string(self) -> None:
+        """Test that _human_feedback_llm is set on the wrapper even when llm is a string."""
 
         class TestFlow(Flow):
             @start()
@@ -1210,8 +1210,8 @@ class TestLiveLLMPreservationOnResume:
         flow = TestFlow()
         method = flow._methods.get("review")
         assert method is not None
-        assert hasattr(method, "_hf_llm")
-        assert method._hf_llm == "gpt-4o-mini"
+        assert hasattr(method, "_human_feedback_llm")
+        assert method._human_feedback_llm == "gpt-4o-mini"
 
     @patch("crewai.flow.runtime.crewai_event_bus.emit")
     def test_resume_async_uses_live_basellm_over_serialized_string(
@@ -1277,20 +1277,20 @@ class TestLiveLLMPreservationOnResume:
                 flow.resume("looks good!")
 
             # NOT the serialized string. The live_llm was captured at class definition
-            # time and stored on the method wrapper as _hf_llm.
+            # time and stored on the method wrapper as _human_feedback_llm.
             assert len(captured_llm) == 1
-            # (which is stored on the method's _hf_llm attribute)
+            # (which is stored on the method's _human_feedback_llm attribute)
             method = flow._methods.get("review")
             assert method is not None
-            assert captured_llm[0] is method._hf_llm
+            assert captured_llm[0] is method._human_feedback_llm
             # And verify it's a BaseLLM instance, not a string
             assert isinstance(captured_llm[0], BaseLLM)
 
     @patch("crewai.flow.runtime.crewai_event_bus.emit")
-    def test_resume_async_falls_back_to_serialized_string_when_no_hf_llm(
+    def test_resume_async_falls_back_to_serialized_string_when_no_human_feedback_llm(
         self, mock_emit: MagicMock
     ) -> None:
-        """Test that resume_async falls back to context.llm when _hf_llm is not available.
+        """Test that resume_async falls back to context.llm when _human_feedback_llm is not available.
 
         This ensures backward compatibility with flows that were paused before this fix.
         """
@@ -1325,10 +1325,10 @@ class TestLiveLLMPreservationOnResume:
 
             flow = TestFlow.from_pending("fallback-test", persistence)
 
-            # Remove _hf_llm to simulate old decorator without this attribute
+            # Remove _human_feedback_llm to simulate old decorator without this attribute
             method = flow._methods.get("review")
-            if hasattr(method, "_hf_llm"):
-                delattr(method, "_hf_llm")
+            if hasattr(method, "_human_feedback_llm"):
+                delattr(method, "_human_feedback_llm")
 
             captured_llm = []
 
@@ -1345,10 +1345,10 @@ class TestLiveLLMPreservationOnResume:
             assert captured_llm[0].model == "gpt-4o-mini"
 
     @patch("crewai.flow.runtime.crewai_event_bus.emit")
-    def test_resume_async_uses_string_from_context_when_hf_llm_is_string(
+    def test_resume_async_uses_string_from_context_when_human_feedback_llm_is_string(
         self, mock_emit: MagicMock
     ) -> None:
-        """Test that when _hf_llm is a string (not BaseLLM), we still use context.llm.
+        """Test that when _human_feedback_llm is a string (not BaseLLM), we still use context.llm.
 
         String LLM values offer no benefit over the serialized context.llm,
         so we don't prefer them.
@@ -1385,7 +1385,7 @@ class TestLiveLLMPreservationOnResume:
             flow = TestFlow.from_pending("string-llm-test", persistence)
 
             method = flow._methods.get("review")
-            assert method._hf_llm == "gpt-4o-mini"
+            assert method._human_feedback_llm == "gpt-4o-mini"
 
             captured_llm = []
 
@@ -1396,14 +1396,14 @@ class TestLiveLLMPreservationOnResume:
             with patch.object(flow, "_collapse_to_outcome", side_effect=capture_llm):
                 flow.resume("looks good!")
 
-            # _hf_llm is a string, so resume deserializes context.llm into an LLM instance
+            # _human_feedback_llm is a string, so resume deserializes context.llm into an LLM instance
             assert len(captured_llm) == 1
             from crewai.llms.base_llm import BaseLLM as BaseLLMClass
             assert isinstance(captured_llm[0], BaseLLMClass)
             assert captured_llm[0].model == "gpt-4o-mini"
 
-    def test_hf_llm_set_for_async_wrapper(self) -> None:
-        """Test that _hf_llm is set on async wrapper functions."""
+    def test_human_feedback_llm_set_for_async_wrapper(self) -> None:
+        """Test that _human_feedback_llm is set on async wrapper functions."""
         import asyncio
         from crewai.llms.base_llm import BaseLLM
 
@@ -1423,5 +1423,5 @@ class TestLiveLLMPreservationOnResume:
         flow = TestFlow()
         method = flow._methods.get("async_review")
         assert method is not None
-        assert hasattr(method, "_hf_llm")
-        assert method._hf_llm is mock_llm
+        assert hasattr(method, "_human_feedback_llm")
+        assert method._human_feedback_llm is mock_llm

lib/crewai/tests/test_flow.py

@@ -1160,9 +1160,9 @@ def test_router_cascade_chain():
         @router(process_level_1)
         def router_level_2(self):
             execution_order.append("router_level_2")
-            return "level_2_path"
+            return "level_2_event"
 
-        @listen("level_2_path")
+        @listen("level_2_event")
         def process_level_2(self):
             execution_order.append("process_level_2")
             self.state["level"] = 3
@@ -1171,9 +1171,9 @@ def test_router_cascade_chain():
         @router(process_level_2)
         def router_level_3(self):
             execution_order.append("router_level_3")
-            return "final_path"
+            return "final_event"
 
-        @listen("final_path")
+        @listen("final_event")
         def finalize(self):
             execution_order.append("finalize")
             return "complete"
@@ -1261,14 +1261,14 @@ def test_complex_and_or_branching():
     assert execution_order.index("final") > execution_order.index("branch_2b")
 
 
-def test_conditional_router_paths_exclusivity():
-    """Test that only the returned router path activates, not all paths."""
+def test_conditional_router_events_exclusivity():
+    """Test that only the returned router event activates, not all events."""
     execution_order = []
 
     class ConditionalRouterFlow(Flow):
         def __init__(self):
             super().__init__()
-            self.state["condition"] = "take_path_b"
+            self.state["condition"] = "take_event_b"
 
         @start()
         def begin(self):
@@ -1277,33 +1277,33 @@ def test_conditional_router_paths_exclusivity():
         @router(begin)
         def decision_point(self):
             execution_order.append("decision_point")
-            if self.state["condition"] == "take_path_a":
-                return "path_a"
-            elif self.state["condition"] == "take_path_b":
-                return "path_b"
+            if self.state["condition"] == "take_event_a":
+                return "event_a"
+            elif self.state["condition"] == "take_event_b":
+                return "event_b"
             else:
-                return "path_c"
+                return "event_c"
 
-        @listen("path_a")
-        def handle_path_a(self):
-            execution_order.append("handle_path_a")
+        @listen("event_a")
+        def handle_event_a(self):
+            execution_order.append("handle_event_a")
 
-        @listen("path_b")
-        def handle_path_b(self):
-            execution_order.append("handle_path_b")
+        @listen("event_b")
+        def handle_event_b(self):
+            execution_order.append("handle_event_b")
 
-        @listen("path_c")
-        def handle_path_c(self):
-            execution_order.append("handle_path_c")
+        @listen("event_c")
+        def handle_event_c(self):
+            execution_order.append("handle_event_c")
 
     flow = ConditionalRouterFlow()
     flow.kickoff()
 
     assert "begin" in execution_order
     assert "decision_point" in execution_order
-    assert "handle_path_b" in execution_order
-    assert "handle_path_a" not in execution_order
-    assert "handle_path_c" not in execution_order
+    assert "handle_event_b" in execution_order
+    assert "handle_event_a" not in execution_order
+    assert "handle_event_c" not in execution_order
 
 
 def test_state_consistency_across_parallel_branches():

lib/crewai/tests/test_flow_definition.py

@@ -0,0 +1,862 @@
+"""Tests for the static Flow Definition contract."""
+
+import ast
+from enum import Enum
+import importlib
+import inspect
+import logging
+from pathlib import Path
+from typing import Annotated, Literal
+
+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.flow import Flow, and_, human_feedback, listen, or_, persist, router, start
+from crewai.flow.dsl._conditions import is_flow_condition_dict
+
+
+def test_flow_public_exports_are_explicit():
+    import crewai.flow.visualization as flow_visualization
+
+    flow_package = importlib.import_module("crewai.flow")
+
+    assert "FlowDefinition" not in flow_package.__all__
+    assert "FlowDefinitionDiagnostic" not in flow_package.__all__
+    assert "build_flow_definition" not in flow_package.__all__
+    assert "flow_structure" not in flow_package.__all__
+    assert set(flow_dsl.__all__) == {
+        "HumanFeedbackResult",
+        "and_",
+        "human_feedback",
+        "listen",
+        "or_",
+        "router",
+        "start",
+    }
+    assert set(flow_definition.__all__) == {
+        "FlowConfigDefinition",
+        "FlowDefinition",
+        "FlowDefinitionCondition",
+        "FlowDefinitionDiagnostic",
+        "FlowHumanFeedbackDefinition",
+        "FlowMethodDefinition",
+        "FlowPersistenceDefinition",
+        "FlowStateDefinition",
+    }
+    assert "build_flow_structure" in flow_visualization.__all__
+    assert "calculate_node_levels" not in flow_visualization.__all__
+
+
+def test_flow_condition_dict_accepts_non_string_sequences():
+    condition = {
+        "type": "OR",
+        "conditions": (
+            "approved",
+            {"type": "AND", "methods": ("validated", "processed")},
+        ),
+    }
+
+    assert is_flow_condition_dict(condition)
+    assert not is_flow_condition_dict({"type": "OR", "conditions": "approved"})
+    assert not is_flow_condition_dict({"type": "OR", "methods": b"approved"})
+
+
+def test_private_flow_helpers_do_not_have_docstrings():
+    import crewai.flow.flow_wrappers as flow_wrappers
+    import crewai.flow.human_feedback as human_feedback
+    import crewai.flow.persistence.decorators as persistence_decorators
+    import crewai.flow.visualization.types as visualization_types
+
+    modules = [
+        flow_dsl,
+        flow_definition,
+        flow_wrappers,
+        human_feedback,
+        persistence_decorators,
+        visualization_builder,
+        visualization_types,
+    ]
+    violations: list[str] = []
+
+    for module in modules:
+        source_path = Path(inspect.getsourcefile(module) or "")
+        tree = ast.parse(source_path.read_text())
+        stack: list[ast.AST] = []
+        if getattr(module, "__all__", None) == [] and ast.get_docstring(tree):
+            violations.append(f"{source_path}:1:<module>")
+
+        class PrivateDocstringVisitor(ast.NodeVisitor):
+            def visit_ClassDef(self, node: ast.ClassDef) -> None:
+                self._check_docstring(node)
+                stack.append(node)
+                self.generic_visit(node)
+                stack.pop()
+
+            def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
+                self._check_docstring(node)
+                stack.append(node)
+                self.generic_visit(node)
+                stack.pop()
+
+            def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> None:
+                self._check_docstring(node)
+                stack.append(node)
+                self.generic_visit(node)
+                stack.pop()
+
+            def _check_docstring(
+                self,
+                node: ast.ClassDef | ast.FunctionDef | ast.AsyncFunctionDef,
+            ) -> None:
+                is_dunder = node.name.startswith("__") and node.name.endswith("__")
+                is_private_name = node.name.startswith("_") and not is_dunder
+                is_nested_function = any(
+                    isinstance(parent, (ast.FunctionDef, ast.AsyncFunctionDef))
+                    for parent in stack
+                )
+                if (is_private_name or is_nested_function) and ast.get_docstring(node):
+                    violations.append(f"{source_path}:{node.lineno}:{node.name}")
+
+        PrivateDocstringVisitor().visit(tree)
+
+    assert violations == []
+
+
+def test_flow_definition_contract_is_dsl_agnostic():
+    source_path = Path(inspect.getsourcefile(flow_definition) or "")
+    source = source_path.read_text()
+
+    assert "DSL" not in source
+    assert "flow_wrappers" not in source
+    assert "build_flow_definition" not in source
+    assert "extract_flow_definition" not in source
+
+
+def test_flow_definition_maps_dsl_to_static_contract():
+    class ContractState(BaseModel):
+        topic: str = ""
+
+    class ContractFlow(Flow[ContractState]):
+        """A flow with every core DSL role."""
+
+        initial_state = ContractState
+        stream = True
+        max_method_calls = 7
+
+        @start()
+        def begin(self):
+            return "started"
+
+        @listen(begin)
+        def process(self):
+            return "processed"
+
+        @router(process)
+        def decide(self):
+            return "approved"
+
+        @listen(or_("approved", "revise"))
+        @human_feedback(
+            message="Review this output.",
+            emit=["done", "revise"],
+            llm="gpt-4o-mini",
+            default_outcome="done",
+            metadata={"team": "qa"},
+            learn=True,
+            learn_source="hitl",
+            learn_strict=True,
+        )
+        def review(self):
+            return "review"
+
+        @listen(and_(begin, process))
+        def audit(self):
+            return "audit"
+
+    definition = ContractFlow.flow_definition()
+
+    assert definition.schema_ == "crewai.flow/v1"
+    assert definition.name == "ContractFlow"
+    assert definition.description == "A flow with every core DSL role."
+    assert definition.state is not None
+    assert definition.state.type == "pydantic"
+    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.methods["begin"].start is True
+    assert definition.methods["process"].listen == "begin"
+
+    decide = definition.methods["decide"]
+    assert decide.listen == "process"
+    assert decide.router is True
+    assert decide.emit is None
+
+    review = definition.methods["review"]
+    assert review.listen == {"or": ["approved", "revise"]}
+    assert review.router is True
+    assert review.emit is None
+    assert review.human_feedback is not None
+    assert review.human_feedback.emit == ["done", "revise"]
+    assert review.human_feedback.default_outcome == "done"
+    assert review.human_feedback.metadata == {"team": "qa"}
+    assert review.human_feedback.learn is True
+    assert review.human_feedback.learn_strict is True
+
+    assert definition.methods["audit"].listen == {"and": ["begin", "process"]}
+    assert definition.diagnostics == []
+
+
+def test_flow_definition_excludes_conversational_builtins_for_regular_flows():
+    class RegularFlow(Flow):
+        @start()
+        def begin(self):
+            return "begin"
+
+    methods = RegularFlow.flow_definition().methods
+
+    assert set(methods) == {"begin"}
+    assert "conversation_start" not in methods
+    assert "route_conversation" not in methods
+    assert "converse_turn" not in methods
+
+
+def test_flow_definition_includes_conversational_builtins_when_enabled():
+    class ChatFlow(Flow):
+        conversational = True
+
+    methods = ChatFlow.flow_definition().methods
+
+    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_human_feedback_metadata():
+    marker = object()
+
+    class MetadataFlow(Flow):
+        @start()
+        def begin(self):
+            return "started"
+
+        @listen(begin)
+        @human_feedback(message="Review this output.", metadata={"marker": marker})
+        def review(self):
+            return "review"
+
+    definition = MetadataFlow.flow_definition()
+    review = definition.methods["review"]
+
+    assert review.human_feedback is not None
+    assert review.human_feedback.metadata == {"ref": "builtins:dict"}
+    assert any(
+        diagnostic.code == "non_serializable_value"
+        and diagnostic.path == "methods.review.human_feedback.metadata"
+        for diagnostic in definition.diagnostics
+    )
+    definition.to_json()
+
+
+def test_flow_definition_fragments_cover_start_listen_and_condition_sugar():
+    class FragmentFlow(Flow):
+        @start()
+        def begin(self):
+            return "begin"
+
+        @start("restart_event")
+        def restart(self):
+            return "restart"
+
+        @listen(begin)
+        def by_callable(self):
+            return "callable"
+
+        @listen("manual_event")
+        def by_string(self):
+            return "string"
+
+        @listen(and_(begin, by_callable))
+        def by_and(self):
+            return "and"
+
+        @listen(or_(and_("manual_event", by_string), "fallback_event"))
+        def nested(self):
+            return "nested"
+
+    definition = FragmentFlow.flow_definition()
+
+    assert definition.methods["begin"].start is True
+    assert definition.methods["restart"].start == "restart_event"
+    assert definition.methods["by_callable"].listen == "begin"
+    assert definition.methods["by_string"].listen == "manual_event"
+    assert definition.methods["by_and"].listen == {"and": ["begin", "by_callable"]}
+    assert definition.methods["nested"].listen == {
+        "or": [{"and": ["manual_event", "by_string"]}, "fallback_event"]
+    }
+
+    assert set(FragmentFlow._start_methods) == {"begin", "restart"}
+    assert FragmentFlow._listeners["restart"] == ("OR", ["restart_event"])
+    assert FragmentFlow._listeners["by_callable"] == ("OR", ["begin"])
+    assert FragmentFlow._listeners["by_string"] == ("OR", ["manual_event"])
+    assert FragmentFlow._listeners["by_and"] == {
+        "type": "AND",
+        "conditions": ["begin", "by_callable"],
+    }
+    assert FragmentFlow._listeners["nested"] == {
+        "type": "OR",
+        "conditions": [
+            {"type": "AND", "conditions": ["manual_event", "by_string"]},
+            "fallback_event",
+        ],
+    }
+
+
+def test_extract_flow_definition_prefers_fragments_over_legacy_metadata():
+    class RegistryFlow(Flow):
+        @start()
+        def begin(self):
+            return "begin"
+
+        @listen(begin)
+        def handle(self):
+            return "handle"
+
+        @router(handle, emit=["done"])
+        def decide(self):
+            return "done"
+
+    handle = RegistryFlow.__dict__["handle"]
+    original_trigger_methods = handle.__trigger_methods__
+    handle.__trigger_methods__ = ["wrong"]
+    try:
+        _, listeners, routers, router_emit = flow_dsl.extract_flow_definition(
+            {
+                "begin": RegistryFlow.__dict__["begin"],
+                "handle": handle,
+                "decide": RegistryFlow.__dict__["decide"],
+            }
+        )
+    finally:
+        handle.__trigger_methods__ = original_trigger_methods
+
+    assert listeners["handle"] == ("OR", ["begin"])
+    assert listeners["decide"] == ("OR", ["handle"])
+    assert routers == {"decide"}
+    assert router_emit == {"decide": ["done"]}
+
+
+def test_flow_definition_falls_back_to_legacy_metadata_without_fragment():
+    class LegacyMetadataFlow(Flow):
+        @start()
+        def begin(self):
+            return "begin"
+
+        @router(begin, emit=["left"])
+        def decide(self):
+            return "left"
+
+        @listen("left")
+        def left(self):
+            return "left"
+
+    for method_name in ("begin", "decide", "left"):
+        method = LegacyMetadataFlow.__dict__[method_name]
+        delattr(method, "__flow_method_definition__")
+
+    definition = flow_dsl.build_flow_definition(LegacyMetadataFlow)
+
+    assert definition.methods["begin"].start is True
+    assert definition.methods["decide"].listen == "begin"
+    assert definition.methods["decide"].router is True
+    assert definition.methods["decide"].emit == ["left"]
+    assert definition.methods["left"].listen == "left"
+
+
+def test_human_feedback_emit_overrides_inner_router_emit():
+    class FeedbackOverRouterFlow(Flow):
+        @start()
+        def begin(self):
+            return "data"
+
+        @human_feedback(
+            message="Review:",
+            emit=["approved", "rejected"],
+            llm="gpt-4o-mini",
+        )
+        @router(begin, emit=["x", "y"])
+        def route(self):
+            return "approved"
+
+        @listen("approved")
+        def proceed(self):
+            return "ok"
+
+    assert "route" in FeedbackOverRouterFlow._routers
+    assert FeedbackOverRouterFlow._router_emit["route"] == ["approved", "rejected"]
+
+    route = FeedbackOverRouterFlow.flow_definition().methods["route"]
+    assert route.router is True
+    assert route.human_feedback is not None
+    assert route.human_feedback.emit == ["approved", "rejected"]
+    assert route.emit is None
+
+
+def test_flow_definition_classifies_start_router_from_human_feedback_emit():
+    class StartRouterFlow(Flow):
+        @start()
+        @human_feedback(
+            message="Review:",
+            emit=["continue", "stop"],
+            llm="gpt-4o-mini",
+        )
+        def entry_point(self):
+            return "data"
+
+        @listen("continue")
+        def proceed(self):
+            return "proceeding"
+
+        @listen("stop")
+        def halt(self):
+            return "halted"
+
+    definition = StartRouterFlow.flow_definition()
+    entry_point = definition.methods["entry_point"]
+
+    assert entry_point.is_start is True
+    assert entry_point.router is True
+    assert entry_point.human_feedback is not None
+    assert entry_point.human_feedback.emit == ["continue", "stop"]
+    assert entry_point.emit is None
+
+
+def test_flow_definition_round_trips_json_and_yaml():
+    class RoundTripFlow(Flow):
+        @start()
+        def begin(self):
+            return "started"
+
+        @router(begin)
+        def decide(self):
+            return "left"
+
+        @listen("left")
+        def left(self):
+            return "left"
+
+    definition = RoundTripFlow.flow_definition()
+
+    json_round_trip = flow_definition.FlowDefinition.from_json(definition.to_json())
+    yaml_round_trip = flow_definition.FlowDefinition.from_yaml(definition.to_yaml())
+
+    assert json_round_trip.to_dict() == definition.to_dict()
+    assert yaml_round_trip.to_dict() == definition.to_dict()
+    assert yaml_round_trip.methods["decide"].router is True
+    assert yaml_round_trip.methods["decide"].listen == "begin"
+
+
+def test_flow_definition_detects_persist_metadata():
+    @persist(verbose=True)
+    class PersistedFlow(Flow[dict]):
+        initial_state = {}
+
+        @start()
+        def begin(self):
+            return "started"
+
+        @persist(verbose=False)
+        @listen(begin)
+        def checkpoint(self):
+            return "saved"
+
+    definition = PersistedFlow.flow_definition()
+
+    assert definition.persist is not None
+    assert definition.persist.enabled is True
+    assert definition.persist.verbose is True
+
+    assert definition.methods["begin"].persist is None
+
+    method_persist = definition.methods["checkpoint"].persist
+    assert method_persist is not None
+    assert method_persist.enabled is True
+    assert method_persist.verbose is False
+
+
+def test_flow_definition_allows_dynamic_router_emit():
+    class DynamicRouterFlow(Flow):
+        @start()
+        def begin(self):
+            return "started"
+
+        @router(begin)
+        def decide(self):
+            return self.state["dynamic_event"]
+
+    definition = DynamicRouterFlow.flow_definition()
+
+    assert definition.methods["decide"].emit is None
+    assert definition.diagnostics == []
+
+
+def test_flow_definition_infers_literal_router_emit():
+    class LiteralRouterFlow(Flow):
+        @start()
+        def begin(self):
+            return "started"
+
+        @router(begin)
+        def decide(self) -> Literal["left", "right"]:
+            return "left"
+
+        @listen("left")
+        def left(self):
+            return "left"
+
+        @listen("right")
+        def right(self):
+            return "right"
+
+    definition = LiteralRouterFlow.flow_definition()
+
+    assert definition.methods["decide"].emit == ["left", "right"]
+
+
+def test_flow_definition_infers_enum_router_emit():
+    class Decision(str, Enum):
+        APPROVE = "approve"
+        REJECT = "reject"
+
+    class EnumRouterFlow(Flow):
+        @start()
+        def begin(self):
+            return "started"
+
+        @router(begin)
+        def decide(self) -> Decision:
+            return Decision.APPROVE
+
+        @listen("approve")
+        def approve(self):
+            return "approve"
+
+        @listen("reject")
+        def reject(self):
+            return "reject"
+
+    definition = EnumRouterFlow.flow_definition()
+
+    assert definition.methods["decide"].emit == ["approve", "reject"]
+
+
+def test_flow_definition_infers_literal_union_router_emit():
+    class LiteralUnionRouterFlow(Flow):
+        @start()
+        def begin(self):
+            return "started"
+
+        @router(begin)
+        def decide(self) -> Literal["left"] | Literal["right"]:
+            return "left"
+
+        @listen("left")
+        def left(self):
+            return "left"
+
+        @listen("right")
+        def right(self):
+            return "right"
+
+    definition = LiteralUnionRouterFlow.flow_definition()
+
+    assert definition.methods["decide"].emit == ["left", "right"]
+
+
+def test_flow_definition_infers_annotated_literal_router_emit():
+    class AnnotatedRouterFlow(Flow):
+        @start()
+        def begin(self):
+            return "started"
+
+        @router(begin)
+        def decide(self) -> Annotated[Literal["left"] | None, "route"]:
+            return "left"
+
+    definition = AnnotatedRouterFlow.flow_definition()
+
+    assert definition.methods["decide"].emit == ["left"]
+
+
+def test_flow_definition_does_not_infer_container_literal_router_emit():
+    class ContainerLiteralRouterFlow(Flow):
+        @start()
+        def begin(self):
+            return "started"
+
+        @router(begin)
+        def list_route(self) -> list[Literal["left"]]:
+            return ["left"]
+
+        @router(begin)
+        def dict_route(self) -> dict[str, Literal["right"]]:
+            return {"route": "right"}
+
+    definition = ContainerLiteralRouterFlow.flow_definition()
+
+    assert definition.methods["list_route"].emit is None
+    assert definition.methods["dict_route"].emit is None
+
+
+def test_flow_definition_does_not_infer_unannotated_router_body_emit():
+    class UnannotatedRouterFlow(Flow):
+        @start()
+        def begin(self):
+            return "started"
+
+        @router(begin)
+        def decide(self):
+            return "left"
+
+        @listen("left")
+        def left(self):
+            return "left"
+
+    definition = UnannotatedRouterFlow.flow_definition()
+
+    assert definition.methods["decide"].emit is None
+
+
+def test_flow_definition_accepts_explicit_router_events():
+    class ExplicitRouterFlow(Flow):
+        @start()
+        def begin(self):
+            return "started"
+
+        @router(begin, emit=["left", "right", "left"])
+        def decide(self):
+            return self.state["dynamic_event"]
+
+        @listen("left")
+        def left(self):
+            return "left"
+
+        @listen("right")
+        def right(self):
+            return "right"
+
+    definition = ExplicitRouterFlow.flow_definition()
+
+    assert definition.methods["decide"].emit == ["left", "right"]
+
+
+def test_flow_definition_preserves_diagnostics_loaded_from_contract():
+    definition = flow_definition.FlowDefinition.from_dict(
+        {
+            "schema": "crewai.flow/v1",
+            "name": "LoadedDiagnosticsFlow",
+            "methods": {
+                "decision": {
+                    "router": True,
+                    "emit": ["continue"],
+                }
+            },
+            "diagnostics": [
+                {
+                    "code": "serialized_warning",
+                    "message": "Preserved serialized diagnostic",
+                    "severity": "warning",
+                    "path": "methods.decision",
+                },
+                {
+                    "code": "router_without_trigger",
+                    "message": "router: true requires either start or listen",
+                    "severity": "error",
+                    "path": "methods.decision",
+                },
+            ],
+        }
+    )
+
+    codes = [diagnostic.code for diagnostic in definition.diagnostics]
+    assert "serialized_warning" in codes
+    assert codes.count("router_without_trigger") == 1
+
+
+def test_router_start_false_without_listen_reports_missing_trigger():
+    definition = flow_definition.FlowDefinition.from_dict(
+        {
+            "schema": "crewai.flow/v1",
+            "name": "LoadedFlow",
+            "methods": {
+                "decision": {
+                    "router": True,
+                    "start": False,
+                    "emit": ["continue"],
+                }
+            },
+        }
+    )
+
+    assert any(
+        diagnostic.code == "router_without_trigger"
+        and diagnostic.path == "methods.decision"
+        for diagnostic in definition.diagnostics
+    )
+
+
+def test_router_human_feedback_preserves_existing_router_metadata():
+    class RouterHumanFeedbackFlow(Flow):
+        @start()
+        def begin(self):
+            return "started"
+
+        @human_feedback(message="Review route:")
+        @router(begin, emit=["approved", "rejected"])
+        def decide(self):
+            return "approved"
+
+        @listen("approved")
+        def approved(self):
+            return "approved"
+
+    definition = RouterHumanFeedbackFlow.flow_definition()
+    method = definition.methods["decide"]
+
+    assert method.router is True
+    assert method.listen == "begin"
+    assert method.emit == ["approved", "rejected"]
+    assert method.human_feedback is not None
+
+
+def test_dynamic_router_flow_definition_has_no_diagnostics():
+    class LazyDynamicRouterFlow(Flow):
+        @start()
+        def begin(self):
+            return "started"
+
+        @router(begin)
+        def decide(self):
+            return self.state["dynamic_event"]
+
+    definition = LazyDynamicRouterFlow.flow_definition()
+    assert definition.diagnostics == []
+
+
+def test_dynamic_router_string_listener_is_valid_contract():
+    class DynamicRouterListenerFlow(Flow):
+        @start()
+        def begin(self):
+            return "started"
+
+        @router(begin)
+        def decide(self):
+            return self.state["dynamic_event"]
+
+        @listen("dynamic_event")
+        def handle(self):
+            return "handled"
+
+    definition = DynamicRouterListenerFlow.flow_definition()
+
+    assert definition.diagnostics == []
+
+
+def test_static_string_listener_is_allowed_by_contract():
+    definition = flow_definition.FlowDefinition.from_dict(
+        {
+            "schema": "crewai.flow/v1",
+            "name": "TypoFlow",
+            "methods": {
+                "begin": {"start": True},
+                "handle": {"listen": "begni"},
+            },
+        }
+    )
+    assert definition.diagnostics == []
+
+
+def test_start_false_not_classified_as_start_method():
+    definition = flow_definition.FlowDefinition.from_dict(
+        {
+            "schema": "crewai.flow/v1",
+            "name": "ExplicitNonStartFlow",
+            "methods": {
+                "begin": {"start": True},
+                "handle": {"start": False, "listen": "begin"},
+            },
+        }
+    )
+
+    assert definition.methods["begin"].is_start is True
+    assert definition.methods["handle"].is_start is False
+
+    class ExplicitNonStartFlow(Flow):
+        @start()
+        def begin(self):
+            return "started"
+
+        @listen(begin)
+        def handle(self):
+            return "handled"
+
+    # Attach the loaded contract (with explicit ``start: false``) so the
+    # projections read from it rather than rebuilding from the DSL.
+    ExplicitNonStartFlow._flow_definition = definition
+
+    flow = ExplicitNonStartFlow()
+    viz_structure = visualization_builder.build_flow_structure(flow)
+    assert "handle" not in viz_structure["start_methods"]
+    assert viz_structure["nodes"]["handle"]["type"] != "start"
+
+
+def test_flow_definition_cache_is_not_inherited_by_subclasses():
+    class ParentFlow(Flow):
+        @start()
+        def begin(self):
+            return "begin"
+
+    parent_definition = ParentFlow.flow_definition()
+
+    class ChildFlow(ParentFlow):
+        @listen(ParentFlow.begin)
+        def child_step(self):
+            return "child"
+
+    child_definition = ChildFlow.flow_definition()
+
+    assert parent_definition.name == "ParentFlow"
+    assert child_definition.name == "ChildFlow"
+    assert child_definition is not parent_definition
+    assert set(child_definition.methods) == {"begin", "child_step"}
+
+
+def test_flow_definition_logs_diagnostics_when_loaded_from_contract(caplog):
+    caplog.set_level(logging.WARNING, logger="crewai.flow.flow_definition")
+
+    definition = flow_definition.FlowDefinition.from_dict(
+        {
+            "schema": "crewai.flow/v1",
+            "name": "LoadedFlow",
+            "methods": {
+                "decision": {
+                    "router": True,
+                    "emit": ["continue"],
+                }
+            },
+        }
+    )
+
+    assert any(
+        diagnostic.code == "router_without_trigger"
+        for diagnostic in definition.diagnostics
+    )
+    assert any(
+        record.levelno == logging.ERROR
+        and "LoadedFlow" in record.message
+        and "router_without_trigger" in record.message
+        for record in caplog.records
+    )

lib/crewai/tests/test_flow_serializer.py

@@ -1,818 +0,0 @@
-"""Tests for flow_serializer.py - Flow structure serialization for Studio UI."""
-
-from typing import Literal
-
-import pytest
-from pydantic import BaseModel, Field
-
-from crewai.flow.flow import Flow, and_, listen, or_, router, start
-from crewai.flow.flow_serializer import flow_structure
-from crewai.flow.human_feedback import human_feedback
-
-
-class TestSimpleLinearFlow:
-    """Test simple linear flow (start → listen → listen)."""
-
-    def test_linear_flow_structure(self):
-        """Test a simple sequential flow structure."""
-
-        class LinearFlow(Flow):
-            """A simple linear flow for testing."""
-
-            @start()
-            def begin(self):
-                return "started"
-
-            @listen(begin)
-            def process(self):
-                return "processed"
-
-            @listen(process)
-            def finalize(self):
-                return "done"
-
-        structure = flow_structure(LinearFlow)
-
-        assert structure["name"] == "LinearFlow"
-        assert structure["description"] == "A simple linear flow for testing."
-        assert len(structure["methods"]) == 3
-
-        method_map = {m["name"]: m for m in structure["methods"]}
-
-        assert method_map["begin"]["type"] == "start"
-        assert method_map["process"]["type"] == "listen"
-        assert method_map["finalize"]["type"] == "listen"
-
-        assert len(structure["edges"]) == 2
-
-        edge_pairs = [(e["from_method"], e["to_method"]) for e in structure["edges"]]
-        assert ("begin", "process") in edge_pairs
-        assert ("process", "finalize") in edge_pairs
-
-        for edge in structure["edges"]:
-            assert edge["edge_type"] == "listen"
-            assert edge["condition"] is None
-
-
-class TestRouterFlow:
-    """Test flow with router branching."""
-
-    def test_router_flow_structure(self):
-        """Test a flow with router that branches to different paths."""
-
-        class BranchingFlow(Flow):
-            @start()
-            def init(self):
-                return "initialized"
-
-            @router(init)
-            def decide(self) -> Literal["path_a", "path_b"]:
-                return "path_a"
-
-            @listen("path_a")
-            def handle_a(self):
-                return "handled_a"
-
-            @listen("path_b")
-            def handle_b(self):
-                return "handled_b"
-
-        structure = flow_structure(BranchingFlow)
-
-        assert structure["name"] == "BranchingFlow"
-        assert len(structure["methods"]) == 4
-
-        method_map = {m["name"]: m for m in structure["methods"]}
-
-        assert method_map["init"]["type"] == "start"
-        assert method_map["decide"]["type"] == "router"
-        assert method_map["handle_a"]["type"] == "listen"
-        assert method_map["handle_b"]["type"] == "listen"
-
-        assert "path_a" in method_map["decide"]["router_paths"]
-        assert "path_b" in method_map["decide"]["router_paths"]
-
-        # Should have: init -> decide (listen), decide -> handle_a (route), decide -> handle_b (route)
-        listen_edges = [e for e in structure["edges"] if e["edge_type"] == "listen"]
-        route_edges = [e for e in structure["edges"] if e["edge_type"] == "route"]
-
-        assert len(listen_edges) == 1
-        assert listen_edges[0]["from_method"] == "init"
-        assert listen_edges[0]["to_method"] == "decide"
-
-        assert len(route_edges) == 2
-        route_targets = {e["to_method"] for e in route_edges}
-        assert "handle_a" in route_targets
-        assert "handle_b" in route_targets
-
-        route_conditions = {e["to_method"]: e["condition"] for e in route_edges}
-        assert route_conditions["handle_a"] == "path_a"
-        assert route_conditions["handle_b"] == "path_b"
-
-
-class TestAndOrConditions:
-    """Test flow with AND/OR conditions."""
-
-    def test_and_condition_flow(self):
-        """Test a flow where a method waits for multiple methods (AND)."""
-
-        class AndConditionFlow(Flow):
-            @start()
-            def step_a(self):
-                return "a"
-
-            @start()
-            def step_b(self):
-                return "b"
-
-            @listen(and_(step_a, step_b))
-            def converge(self):
-                return "converged"
-
-        structure = flow_structure(AndConditionFlow)
-
-        assert len(structure["methods"]) == 3
-
-        method_map = {m["name"]: m for m in structure["methods"]}
-
-        assert method_map["step_a"]["type"] == "start"
-        assert method_map["step_b"]["type"] == "start"
-        assert method_map["converge"]["type"] == "listen"
-
-        assert method_map["converge"]["condition_type"] == "AND"
-
-        triggers = method_map["converge"]["trigger_methods"]
-        assert "step_a" in triggers
-        assert "step_b" in triggers
-
-        converge_edges = [e for e in structure["edges"] if e["to_method"] == "converge"]
-        assert len(converge_edges) == 2
-
-    def test_or_condition_flow(self):
-        """Test a flow where a method is triggered by any of multiple methods (OR)."""
-
-        class OrConditionFlow(Flow):
-            @start()
-            def path_1(self):
-                return "1"
-
-            @start()
-            def path_2(self):
-                return "2"
-
-            @listen(or_(path_1, path_2))
-            def handle_any(self):
-                return "handled"
-
-        structure = flow_structure(OrConditionFlow)
-
-        method_map = {m["name"]: m for m in structure["methods"]}
-
-        assert method_map["handle_any"]["condition_type"] == "OR"
-
-        triggers = method_map["handle_any"]["trigger_methods"]
-        assert "path_1" in triggers
-        assert "path_2" in triggers
-
-
-class TestHumanFeedbackMethods:
-    """Test flow with @human_feedback decorated methods."""
-
-    def test_human_feedback_detection(self):
-        """Test that human feedback methods are correctly identified."""
-
-        class HumanFeedbackFlow(Flow):
-            @start()
-            @human_feedback(
-                message="Please review:",
-                emit=["approved", "rejected"],
-                llm="gpt-4o-mini",
-            )
-            def review_step(self):
-                return "content to review"
-
-            @listen("approved")
-            def handle_approved(self):
-                return "approved"
-
-            @listen("rejected")
-            def handle_rejected(self):
-                return "rejected"
-
-        structure = flow_structure(HumanFeedbackFlow)
-
-        method_map = {m["name"]: m for m in structure["methods"]}
-
-        # review_step should have human feedback
-        assert method_map["review_step"]["has_human_feedback"] is True
-        # It's a start+router (due to emit)
-        assert method_map["review_step"]["type"] == "start_router"
-        assert "approved" in method_map["review_step"]["router_paths"]
-        assert "rejected" in method_map["review_step"]["router_paths"]
-
-        # Other methods should not have human feedback
-        assert method_map["handle_approved"]["has_human_feedback"] is False
-        assert method_map["handle_rejected"]["has_human_feedback"] is False
-
-    def test_listen_plus_human_feedback_router_edges(self):
-        """Test that @listen + @human_feedback(emit=...) generates router edges.
-
-        This is the pattern used in the whitepaper generator:
-        a listener method that also acts as a router via @human_feedback(emit=[...]).
-        The serializer must generate edges from this method to listeners of its emit paths.
-        """
-
-        class ReviewFlow(Flow):
-            @start()
-            def generate(self):
-                return "content"
-
-            @listen(generate)
-            @human_feedback(
-                message="Review this:",
-                emit=["approved", "needs_changes", "cancelled"],
-                llm="gpt-4o-mini",
-            )
-            def review(self):
-                return "review result"
-
-            @listen("approved")
-            def handle_approved(self):
-                return "done"
-
-            @listen("needs_changes")
-            def handle_changes(self):
-                return "regenerating"
-
-            @listen("cancelled")
-            def handle_cancelled(self):
-                return "cancelled"
-
-        structure = flow_structure(ReviewFlow)
-
-        method_map = {m["name"]: m for m in structure["methods"]}
-        edge_set = {(e["from_method"], e["to_method"], e.get("condition")) for e in structure["edges"]}
-
-        # review should be detected as a router with the emit paths
-        assert method_map["review"]["type"] == "router"
-        assert set(method_map["review"]["router_paths"]) == {"approved", "needs_changes", "cancelled"}
-        assert method_map["review"]["has_human_feedback"] is True
-
-        assert ("generate", "review", None) in edge_set
-
-        assert ("review", "handle_approved", "approved") in edge_set
-        assert ("review", "handle_changes", "needs_changes") in edge_set
-        assert ("review", "handle_cancelled", "cancelled") in edge_set
-
-
-class TestCrewReferences:
-    """Test detection of Crew references in method bodies."""
-
-    def test_crew_detection_with_crew_call(self):
-        """Test that .crew() calls are detected."""
-
-        class FlowWithCrew(Flow):
-            @start()
-            def run_crew(self):
-                return "result"
-
-            @listen(run_crew)
-            def no_crew(self):
-                return "done"
-
-        structure = flow_structure(FlowWithCrew)
-
-        method_map = {m["name"]: m for m in structure["methods"]}
-
-        # Note: Since the actual .crew() call is in a comment/string,
-        # We're testing the mechanism exists.
-        assert "has_crew" in method_map["run_crew"]
-        assert "has_crew" in method_map["no_crew"]
-
-    def test_no_crew_when_absent(self):
-        """Test that methods without Crew refs return has_crew=False."""
-
-        class SimpleNonCrewFlow(Flow):
-            @start()
-            def calculate(self):
-                return 1 + 1
-
-            @listen(calculate)
-            def display(self):
-                return "result"
-
-        structure = flow_structure(SimpleNonCrewFlow)
-
-        method_map = {m["name"]: m for m in structure["methods"]}
-
-        assert method_map["calculate"]["has_crew"] is False
-        assert method_map["display"]["has_crew"] is False
-
-
-class TestTypedStateSchema:
-    """Test flow with typed Pydantic state."""
-
-    def test_pydantic_state_schema_extraction(self):
-        """Test extracting state schema from a Flow with Pydantic state."""
-
-        class MyState(BaseModel):
-            counter: int = 0
-            message: str = ""
-            items: list[str] = Field(default_factory=list)
-
-        class TypedStateFlow(Flow[MyState]):
-            initial_state = MyState
-
-            @start()
-            def increment(self):
-                self.state.counter += 1
-                return self.state.counter
-
-            @listen(increment)
-            def display(self):
-                return f"Count: {self.state.counter}"
-
-        structure = flow_structure(TypedStateFlow)
-
-        assert structure["state_schema"] is not None
-        fields = structure["state_schema"]["fields"]
-
-        field_names = {f["name"] for f in fields}
-        assert "counter" in field_names
-        assert "message" in field_names
-        assert "items" in field_names
-
-        field_map = {f["name"]: f for f in fields}
-        assert "int" in field_map["counter"]["type"]
-        assert "str" in field_map["message"]["type"]
-
-        assert field_map["counter"]["default"] == 0
-        assert field_map["message"]["default"] == ""
-
-    def test_dict_state_returns_none(self):
-        """Test that flows using dict state return None for state_schema."""
-
-        class DictStateFlow(Flow):
-            @start()
-            def begin(self):
-                self.state["count"] = 1
-                return "started"
-
-        structure = flow_structure(DictStateFlow)
-
-        assert structure["state_schema"] is None
-
-
-class TestEdgeCases:
-    """Test edge cases and special scenarios."""
-
-    def test_start_router_combo(self):
-        """Test a method that is both @start and a router (via human_feedback emit)."""
-
-        class StartRouterFlow(Flow):
-            @start()
-            @human_feedback(
-                message="Review:",
-                emit=["continue", "stop"],
-                llm="gpt-4o-mini",
-            )
-            def entry_point(self):
-                return "data"
-
-            @listen("continue")
-            def proceed(self):
-                return "proceeding"
-
-            @listen("stop")
-            def halt(self):
-                return "halted"
-
-        structure = flow_structure(StartRouterFlow)
-
-        method_map = {m["name"]: m for m in structure["methods"]}
-
-        assert method_map["entry_point"]["type"] == "start_router"
-        assert method_map["entry_point"]["has_human_feedback"] is True
-        assert "continue" in method_map["entry_point"]["router_paths"]
-        assert "stop" in method_map["entry_point"]["router_paths"]
-
-    def test_multiple_start_methods(self):
-        """Test a flow with multiple start methods."""
-
-        class MultiStartFlow(Flow):
-            @start()
-            def start_a(self):
-                return "a"
-
-            @start()
-            def start_b(self):
-                return "b"
-
-            @listen(and_(start_a, start_b))
-            def combine(self):
-                return "combined"
-
-        structure = flow_structure(MultiStartFlow)
-
-        start_methods = [m for m in structure["methods"] if m["type"] == "start"]
-        assert len(start_methods) == 2
-
-        start_names = {m["name"] for m in start_methods}
-        assert "start_a" in start_names
-        assert "start_b" in start_names
-
-    def test_orphan_methods(self):
-        """Test that orphan methods (not connected to flow) are still captured."""
-
-        class FlowWithOrphan(Flow):
-            @start()
-            def begin(self):
-                return "started"
-
-            @listen(begin)
-            def connected(self):
-                return "connected"
-
-            @listen("never_triggered")
-            def orphan(self):
-                return "orphan"
-
-        structure = flow_structure(FlowWithOrphan)
-
-        method_names = {m["name"] for m in structure["methods"]}
-        assert "orphan" in method_names
-
-        method_map = {m["name"]: m for m in structure["methods"]}
-        assert method_map["orphan"]["trigger_methods"] == ["never_triggered"]
-
-    def test_empty_flow(self):
-        """Test building structure for a flow with no methods."""
-
-        class EmptyFlow(Flow):
-            pass
-
-        structure = flow_structure(EmptyFlow)
-
-        assert structure["name"] == "EmptyFlow"
-        assert structure["methods"] == []
-        assert structure["edges"] == []
-        assert structure["state_schema"] is None
-
-    def test_flow_with_docstring(self):
-        """Test that flow docstring is captured."""
-
-        class DocumentedFlow(Flow):
-            """This is a well-documented flow.
-
-            It has multiple lines of documentation.
-            """
-
-            @start()
-            def begin(self):
-                return "started"
-
-        structure = flow_structure(DocumentedFlow)
-
-        assert structure["description"] is not None
-        assert "well-documented flow" in structure["description"]
-
-    def test_flow_without_docstring(self):
-        """Test that missing docstring returns None."""
-
-        class UndocumentedFlow(Flow):
-            @start()
-            def begin(self):
-                return "started"
-
-        structure = flow_structure(UndocumentedFlow)
-
-        assert structure["description"] is None
-
-    def test_nested_conditions(self):
-        """Test flow with nested AND/OR conditions."""
-
-        class NestedConditionFlow(Flow):
-            @start()
-            def a(self):
-                return "a"
-
-            @start()
-            def b(self):
-                return "b"
-
-            @start()
-            def c(self):
-                return "c"
-
-            @listen(or_(and_(a, b), c))
-            def complex_trigger(self):
-                return "triggered"
-
-        structure = flow_structure(NestedConditionFlow)
-
-        method_map = {m["name"]: m for m in structure["methods"]}
-
-        triggers = method_map["complex_trigger"]["trigger_methods"]
-        assert len(triggers) == 3
-        assert "a" in triggers
-        assert "b" in triggers
-        assert "c" in triggers
-
-
-class TestErrorHandling:
-    """Test error handling and validation."""
-
-    def test_instance_raises_type_error(self):
-        """Test that passing an instance raises TypeError."""
-
-        class TestFlow(Flow):
-            @start()
-            def begin(self):
-                return "started"
-
-        flow_instance = TestFlow()
-
-        with pytest.raises(TypeError) as exc_info:
-            flow_structure(flow_instance)
-
-        assert "requires a Flow class, not an instance" in str(exc_info.value)
-
-    def test_non_class_raises_type_error(self):
-        """Test that passing non-class raises TypeError."""
-
-        with pytest.raises(TypeError):
-            flow_structure("not a class")
-
-        with pytest.raises(TypeError):
-            flow_structure(123)
-
-
-class TestEdgeGeneration:
-    """Test edge generation in various scenarios."""
-
-    def test_all_edges_generated_correctly(self):
-        """Verify all edges are correctly generated for a complex flow."""
-
-        class ComplexFlow(Flow):
-            @start()
-            def entry(self):
-                return "started"
-
-            @listen(entry)
-            def step_1(self):
-                return "step_1"
-
-            @router(step_1)
-            def branch(self) -> Literal["left", "right"]:
-                return "left"
-
-            @listen("left")
-            def left_path(self):
-                return "left_done"
-
-            @listen("right")
-            def right_path(self):
-                return "right_done"
-
-            @listen(or_(left_path, right_path))
-            def converge(self):
-                return "done"
-
-        structure = flow_structure(ComplexFlow)
-
-        edges = structure["edges"]
-
-        listen_edges = [(e["from_method"], e["to_method"]) for e in edges if e["edge_type"] == "listen"]
-
-        assert ("entry", "step_1") in listen_edges
-        assert ("step_1", "branch") in listen_edges
-        assert ("left_path", "converge") in listen_edges
-        assert ("right_path", "converge") in listen_edges
-
-        route_edges = [(e["from_method"], e["to_method"], e["condition"]) for e in edges if e["edge_type"] == "route"]
-
-        assert ("branch", "left_path", "left") in route_edges
-        assert ("branch", "right_path", "right") in route_edges
-
-    def test_router_edge_conditions(self):
-        """Test that router edge conditions are properly set."""
-
-        class RouterConditionFlow(Flow):
-            @start()
-            def begin(self):
-                return "start"
-
-            @router(begin)
-            def route(self) -> Literal["option_1", "option_2", "option_3"]:
-                return "option_1"
-
-            @listen("option_1")
-            def handle_1(self):
-                return "1"
-
-            @listen("option_2")
-            def handle_2(self):
-                return "2"
-
-            @listen("option_3")
-            def handle_3(self):
-                return "3"
-
-        structure = flow_structure(RouterConditionFlow)
-
-        route_edges = [e for e in structure["edges"] if e["edge_type"] == "route"]
-
-        assert len(route_edges) == 3
-
-        conditions = {e["to_method"]: e["condition"] for e in route_edges}
-        assert conditions["handle_1"] == "option_1"
-        assert conditions["handle_2"] == "option_2"
-        assert conditions["handle_3"] == "option_3"
-
-
-class TestMethodTypeClassification:
-    """Test method type classification."""
-
-    def test_all_method_types(self):
-        """Test classification of all method types."""
-
-        class AllTypesFlow(Flow):
-            @start()
-            def start_only(self):
-                return "start"
-
-            @listen(start_only)
-            def listen_only(self):
-                return "listen"
-
-            @router(listen_only)
-            def router_only(self) -> Literal["path"]:
-                return "path"
-
-            @listen("path")
-            def after_router(self):
-                return "after"
-
-            @start()
-            @human_feedback(
-                message="Review",
-                emit=["yes", "no"],
-                llm="gpt-4o-mini",
-            )
-            def start_and_router(self):
-                return "data"
-
-        structure = flow_structure(AllTypesFlow)
-
-        method_map = {m["name"]: m for m in structure["methods"]}
-
-        assert method_map["start_only"]["type"] == "start"
-        assert method_map["listen_only"]["type"] == "listen"
-        assert method_map["router_only"]["type"] == "router"
-        assert method_map["after_router"]["type"] == "listen"
-        assert method_map["start_and_router"]["type"] == "start_router"
-
-
-class TestInputDetection:
-    """Test flow input detection."""
-
-    def test_inputs_list_exists(self):
-        """Test that inputs list is always present."""
-
-        class SimpleFlow(Flow):
-            @start()
-            def begin(self):
-                return "started"
-
-        structure = flow_structure(SimpleFlow)
-
-        assert "inputs" in structure
-        assert isinstance(structure["inputs"], list)
-
-
-class TestJsonSerializable:
-    """Test that output is JSON serializable."""
-
-    def test_structure_is_json_serializable(self):
-        """Test that the entire structure can be JSON serialized."""
-        import json
-
-        class MyState(BaseModel):
-            value: int = 0
-
-        class SerializableFlow(Flow[MyState]):
-            """Test flow for JSON serialization."""
-
-            initial_state = MyState
-
-            @start()
-            @human_feedback(
-                message="Review",
-                emit=["ok", "not_ok"],
-                llm="gpt-4o-mini",
-            )
-            def begin(self):
-                return "data"
-
-            @listen("ok")
-            def proceed(self):
-                return "done"
-
-        structure = flow_structure(SerializableFlow)
-
-        json_str = json.dumps(structure)
-        assert json_str is not None
-
-        parsed = json.loads(json_str)
-        assert parsed["name"] == "SerializableFlow"
-        assert len(parsed["methods"]) > 0
-
-
-class TestFlowInheritance:
-    """Test flow inheritance scenarios."""
-
-    def test_child_flow_inherits_parent_methods(self):
-        """Test that FlowB inheriting from FlowA includes methods from both.
-
-        Note: FlowMeta propagates methods but does NOT fully propagate the
-        _listeners registry from parent classes. This means edges defined
-        in the parent class (e.g., parent_start -> parent_process) may not
-        appear in the child's structure. This is a known FlowMeta limitation.
-        """
-
-        class FlowA(Flow):
-            """Parent flow with start method."""
-
-            @start()
-            def parent_start(self):
-                return "parent started"
-
-            @listen(parent_start)
-            def parent_process(self):
-                return "parent processed"
-
-        class FlowB(FlowA):
-            """Child flow with additional methods."""
-
-            @listen(FlowA.parent_process)
-            def child_continue(self):
-                return "child continued"
-
-            @listen(child_continue)
-            def child_finalize(self):
-                return "child finalized"
-
-        structure = flow_structure(FlowB)
-
-        assert structure["name"] == "FlowB"
-
-        method_names = {m["name"] for m in structure["methods"]}
-        assert "parent_start" in method_names
-        assert "parent_process" in method_names
-        assert "child_continue" in method_names
-        assert "child_finalize" in method_names
-
-        method_map = {m["name"]: m for m in structure["methods"]}
-        assert method_map["parent_start"]["type"] == "start"
-        assert method_map["parent_process"]["type"] == "listen"
-        assert method_map["child_continue"]["type"] == "listen"
-        assert method_map["child_finalize"]["type"] == "listen"
-
-        edge_pairs = [(e["from_method"], e["to_method"]) for e in structure["edges"]]
-        assert ("parent_process", "child_continue") in edge_pairs
-        assert ("child_continue", "child_finalize") in edge_pairs
-
-        # KNOWN LIMITATION: Edges defined in parent class (parent_start -> parent_process)
-        # are NOT propagated to child's _listeners registry by FlowMeta.
-        # This is a FlowMeta limitation, not a serializer bug.
-
-    def test_child_flow_can_override_parent_method(self):
-        """Test that child can override parent methods."""
-
-        class BaseFlow(Flow):
-            @start()
-            def begin(self):
-                return "base begin"
-
-            @listen(begin)
-            def process(self):
-                return "base process"
-
-        class ExtendedFlow(BaseFlow):
-            @listen(BaseFlow.begin)
-            def process(self):
-                return "extended process"
-
-            @listen(process)
-            def finalize(self):
-                return "extended finalize"
-
-        structure = flow_structure(ExtendedFlow)
-
-        method_names = {m["name"] for m in structure["methods"]}
-        assert "begin" in method_names
-        assert "process" in method_names
-        assert "finalize" in method_names
-
-        # Should have 3 methods total (not 4, since process is overridden)
-        assert len(structure["methods"]) == 3

lib/crewai/tests/test_flow_visualization.py

@@ -8,6 +8,7 @@ from pathlib import Path
 import pytest
 
 from crewai.flow.flow import Flow, and_, listen, or_, router, start
+from crewai.flow.flow_definition import FlowDefinition
 from crewai.flow.visualization import (
     build_flow_structure,
     visualize_flow_structure,
@@ -36,14 +37,14 @@ class RouterFlow(Flow):
     @router(init)
     def decide(self):
         if hasattr(self, "state") and self.state.get("path") == "b":
-            return "path_b"
-        return "path_a"
+            return "event_b"
+        return "event_a"
 
-    @listen("path_a")
+    @listen("event_a")
     def handle_a(self):
         return "handled_a"
 
-    @listen("path_b")
+    @listen("event_b")
     def handle_b(self):
         return "handled_b"
 
@@ -69,13 +70,23 @@ class ComplexFlow(Flow):
 
     @router(converge_and)
     def router_decision(self):
-        return "final_path"
+        return "final_event"
 
-    @listen("final_path")
+    @listen("final_event")
     def finalize(self):
         return "complete"
 
 
+def _attach_flow_definition(flow_class: type[Flow], methods: dict[str, object]) -> None:
+    flow_class._flow_definition = FlowDefinition.from_dict(
+        {
+            "schema": "crewai.flow/v1",
+            "name": flow_class.__name__,
+            "methods": methods,
+        }
+    )
+
+
 def test_build_flow_structure_simple():
     """Test building structure for a simple sequential flow."""
     flow = SimpleFlow()
@@ -98,6 +109,47 @@ def test_build_flow_structure_simple():
     assert edge["condition_type"] == "OR"
 
 
+def test_build_flow_structure_from_flow_class():
+    """Test building structure from a Flow class via its FlowDefinition."""
+    structure = build_flow_structure(SimpleFlow)
+
+    assert set(structure["nodes"]) == {"begin", "process"}
+    assert structure["start_methods"] == ["begin"]
+    assert structure["nodes"]["begin"]["class_name"] == "SimpleFlow"
+
+
+def test_build_flow_structure_from_flow_definition():
+    """Test building visualization directly from a FlowDefinition."""
+    definition = FlowDefinition.from_dict(
+        {
+            "schema": "crewai.flow/v1",
+            "name": "DefinedFlow",
+            "methods": {
+                "begin": {"start": True},
+                "decide": {
+                    "listen": "begin",
+                    "router": True,
+                    "emit": ["done"],
+                },
+                "finish": {"listen": "done"},
+            },
+        }
+    )
+
+    structure = build_flow_structure(definition)
+
+    assert set(structure["nodes"]) == {"begin", "decide", "finish"}
+    assert structure["start_methods"] == ["begin"]
+    assert structure["router_methods"] == ["decide"]
+    assert structure["nodes"]["begin"]["class_name"] == "DefinedFlow"
+    assert any(
+        edge["source"] == "decide"
+        and edge["target"] == "finish"
+        and edge["router_event"] == "done"
+        for edge in structure["edges"]
+    )
+
+
 def test_build_flow_structure_with_router():
     """Test building structure for a flow with router."""
     flow = RouterFlow()
@@ -111,13 +163,10 @@ def test_build_flow_structure_with_router():
 
     router_node = structure["nodes"]["decide"]
     assert router_node["type"] == "router"
+    assert "router_events" not in router_node
 
-    if "router_paths" in router_node:
-        assert len(router_node["router_paths"]) >= 1
-        assert any("path" in path for path in router_node["router_paths"])
-
-    router_edges = [edge for edge in structure["edges"] if edge["is_router_path"]]
-    assert len(router_edges) >= 1
+    router_edges = [edge for edge in structure["edges"] if edge["is_router_event"]]
+    assert router_edges == []
 
 
 def test_build_flow_structure_with_and_or_conditions():
@@ -203,49 +252,40 @@ def test_visualize_flow_structure_json_data():
     assert "handle_b" in js_content
 
     assert "router" in js_content.lower()
-    assert "path_a" in js_content
-    assert "path_b" in js_content
+    assert "event_a" in js_content
+    assert "event_b" in js_content
 
 
-def test_node_metadata_includes_source_info():
-    """Test that nodes include source code and line number information."""
+def test_node_metadata_omits_source_info():
+    """Test that definition-only visualization omits Python source metadata."""
     flow = SimpleFlow()
     structure = build_flow_structure(flow)
 
-    for node_name, node_metadata in structure["nodes"].items():
-        assert node_metadata["source_code"] is not None
-        assert len(node_metadata["source_code"]) > 0
-        assert node_metadata["source_start_line"] is not None
-        assert node_metadata["source_start_line"] > 0
-        assert node_metadata["source_file"] is not None
-        assert node_metadata["source_file"].endswith(".py")
+    for node_metadata in structure["nodes"].values():
+        assert "source_code" not in node_metadata
+        assert "source_lines" not in node_metadata
+        assert "source_start_line" not in node_metadata
+        assert "source_file" not in node_metadata
 
 
-def test_node_metadata_includes_method_signature():
-    """Test that nodes include method signature information."""
+def test_node_metadata_omits_method_signature():
+    """Test that definition-only visualization omits Python method signatures."""
     flow = SimpleFlow()
     structure = build_flow_structure(flow)
 
     begin_node = structure["nodes"]["begin"]
-    assert begin_node["method_signature"] is not None
-    assert "operationId" in begin_node["method_signature"]
-    assert begin_node["method_signature"]["operationId"] == "begin"
-    assert "parameters" in begin_node["method_signature"]
-    assert "returns" in begin_node["method_signature"]
+    assert "method_signature" not in begin_node
 
 
 def test_router_node_has_correct_metadata():
-    """Test that router nodes have correct type and paths."""
+    """Test that router nodes have correct type and event metadata."""
     flow = RouterFlow()
     structure = build_flow_structure(flow)
 
     router_node = structure["nodes"]["decide"]
     assert router_node["type"] == "router"
     assert router_node["is_router"] is True
-    assert router_node["router_paths"] is not None
-    assert len(router_node["router_paths"]) == 2
-    assert "path_a" in router_node["router_paths"]
-    assert "path_b" in router_node["router_paths"]
+    assert "router_events" not in router_node
 
 
 def test_listen_node_has_trigger_methods():
@@ -255,7 +295,7 @@ def test_listen_node_has_trigger_methods():
 
     handle_a_node = structure["nodes"]["handle_a"]
     assert handle_a_node["trigger_methods"] is not None
-    assert "path_a" in handle_a_node["trigger_methods"]
+    assert "event_a" in handle_a_node["trigger_methods"]
 
 
 def test_and_condition_node_metadata():
@@ -317,16 +357,15 @@ def test_topological_path_counting():
     assert len(structure["edges"]) > 0
 
 
-def test_class_signature_metadata():
-    """Test that nodes include class signature information."""
+def test_class_metadata_comes_from_definition():
+    """Test that nodes include only definition-derived class metadata."""
     flow = SimpleFlow()
     structure = build_flow_structure(flow)
 
-    for node_name, node_metadata in structure["nodes"].items():
+    for node_metadata in structure["nodes"].values():
         assert node_metadata["class_name"] is not None
         assert node_metadata["class_name"] == "SimpleFlow"
-        assert node_metadata["class_signature"] is not None
-        assert "SimpleFlow" in node_metadata["class_signature"]
+        assert "class_signature" not in node_metadata
 
 
 def test_visualization_plot_method():
@@ -338,8 +377,8 @@ def test_visualization_plot_method():
     assert os.path.exists(html_file)
 
 
-def test_router_paths_to_string_conditions():
-    """Test that router paths correctly connect to listeners with string conditions."""
+def test_router_events_to_string_conditions():
+    """Test that router events correctly connect to listeners with string conditions."""
 
     class RouterToStringFlow(Flow):
         @start()
@@ -349,25 +388,34 @@ def test_router_paths_to_string_conditions():
         @router(init)
         def decide(self):
             if hasattr(self, "state") and self.state.get("path") == "b":
-                return "path_b"
-            return "path_a"
+                return "event_b"
+            return "event_a"
 
-        @listen(or_("path_a", "path_b"))
+        @listen(or_("event_a", "event_b"))
         def handle_either(self):
             return "handled"
 
-        @listen("path_b")
+        @listen("event_b")
         def handle_b_only(self):
             return "handled_b"
 
     flow = RouterToStringFlow()
+    _attach_flow_definition(
+        RouterToStringFlow,
+        {
+            "init": {"start": True},
+            "decide": {"listen": "init", "router": True, "emit": ["event_a", "event_b"]},
+            "handle_either": {"listen": {"or": ["event_a", "event_b"]}},
+            "handle_b_only": {"listen": "event_b"},
+        },
+    )
     structure = build_flow_structure(flow)
 
     decide_node = structure["nodes"]["decide"]
-    assert "path_a" in decide_node["router_paths"]
-    assert "path_b" in decide_node["router_paths"]
+    assert "event_a" in decide_node["router_events"]
+    assert "event_b" in decide_node["router_events"]
 
-    router_edges = [edge for edge in structure["edges"] if edge["is_router_path"]]
+    router_edges = [edge for edge in structure["edges"] if edge["is_router_event"]]
 
     assert len(router_edges) == 3
 
@@ -382,8 +430,8 @@ def test_router_paths_to_string_conditions():
     assert len(edges_to_handle_b_only) == 1
 
 
-def test_router_paths_not_in_and_conditions():
-    """Test that router paths don't create edges to AND-nested conditions."""
+def test_router_events_not_in_and_conditions():
+    """Test that router events don't create edges to AND-nested conditions."""
 
     class RouterAndConditionFlow(Flow):
         @start()
@@ -392,24 +440,34 @@ def test_router_paths_not_in_and_conditions():
 
         @router(init)
         def decide(self):
-            return "path_a"
+            return "event_a"
 
-        @listen("path_a")
+        @listen("event_a")
         def step_1(self):
             return "step_1_done"
 
-        @listen(and_("path_a", step_1))
+        @listen(and_("event_a", step_1))
         def step_2_and(self):
             return "step_2_done"
 
-        @listen(or_(and_("path_a", step_1), "path_a"))
+        @listen(or_(and_("event_a", step_1), "event_a"))
         def step_3_or(self):
             return "step_3_done"
 
     flow = RouterAndConditionFlow()
+    _attach_flow_definition(
+        RouterAndConditionFlow,
+        {
+            "init": {"start": True},
+            "decide": {"listen": "init", "router": True, "emit": ["event_a"]},
+            "step_1": {"listen": "event_a"},
+            "step_2_and": {"listen": {"and": ["event_a", "step_1"]}},
+            "step_3_or": {"listen": {"or": [{"and": ["event_a", "step_1"]}, "event_a"]}},
+        },
+    )
     structure = build_flow_structure(flow)
 
-    router_edges = [edge for edge in structure["edges"] if edge["is_router_path"]]
+    router_edges = [edge for edge in structure["edges"] if edge["is_router_event"]]
 
     targets = [edge["target"] for edge in router_edges]
 
@@ -454,6 +512,17 @@ def test_chained_routers_no_self_loops():
             return "need_auth"
 
     flow = ChainedRouterFlow()
+    _attach_flow_definition(
+        ChainedRouterFlow,
+        {
+            "entrance": {"start": True},
+            "session_in_cache": {"listen": "entrance", "router": True, "emit": ["exp"]},
+            "check_exp": {"listen": "exp", "router": True, "emit": ["auth"]},
+            "call_ai_auth": {"listen": "auth", "router": True, "emit": ["action"]},
+            "forward_to_action": {"listen": "action"},
+            "forward_to_authenticate": {"listen": "authenticate"},
+        },
+    )
     structure = build_flow_structure(flow)
 
     for edge in structure["edges"]:
@@ -461,13 +530,13 @@ def test_chained_routers_no_self_loops():
             f"Self-loop detected: {edge['source']} -> {edge['target']}"
         )
 
-    router_edges = [edge for edge in structure["edges"] if edge["is_router_path"]]
+    router_edges = [edge for edge in structure["edges"] if edge["is_router_event"]]
 
     # session_in_cache -> check_exp (via 'exp')
     exp_edges = [
         edge
         for edge in router_edges
-        if edge["router_path_label"] == "exp" and edge["source"] == "session_in_cache"
+        if edge["router_event"] == "exp" and edge["source"] == "session_in_cache"
     ]
     assert len(exp_edges) == 1
     assert exp_edges[0]["target"] == "check_exp"
@@ -476,7 +545,7 @@ def test_chained_routers_no_self_loops():
     auth_edges = [
         edge
         for edge in router_edges
-        if edge["router_path_label"] == "auth" and edge["source"] == "check_exp"
+        if edge["router_event"] == "auth" and edge["source"] == "check_exp"
     ]
     assert len(auth_edges) == 1
     assert auth_edges[0]["target"] == "call_ai_auth"
@@ -485,7 +554,7 @@ def test_chained_routers_no_self_loops():
     action_edges = [
         edge
         for edge in router_edges
-        if edge["router_path_label"] == "action" and edge["source"] == "call_ai_auth"
+        if edge["router_event"] == "action" and edge["source"] == "call_ai_auth"
     ]
     assert len(action_edges) == 1
     assert action_edges[0]["target"] == "forward_to_action"
@@ -523,6 +592,16 @@ def test_routers_with_shared_output_strings():
             return "skipped"
 
     flow = SharedOutputRouterFlow()
+    _attach_flow_definition(
+        SharedOutputRouterFlow,
+        {
+            "start": {"start": True},
+            "router_a": {"listen": "start", "router": True, "emit": ["auth"]},
+            "router_b": {"listen": "auth", "router": True, "emit": ["done"]},
+            "finalize": {"listen": "done"},
+            "handle_skip": {"listen": "skip"},
+        },
+    )
     structure = build_flow_structure(flow)
 
     for edge in structure["edges"]:
@@ -531,11 +610,11 @@ def test_routers_with_shared_output_strings():
         )
 
     # router_a should connect to router_b via 'auth'
-    router_edges = [edge for edge in structure["edges"] if edge["is_router_path"]]
+    router_edges = [edge for edge in structure["edges"] if edge["is_router_event"]]
     auth_from_a = [
         edge
         for edge in router_edges
-        if edge["source"] == "router_a" and edge["router_path_label"] == "auth"
+        if edge["source"] == "router_a" and edge["router_event"] == "auth"
     ]
     assert len(auth_from_a) == 1
     assert auth_from_a[0]["target"] == "router_b"
@@ -544,17 +623,17 @@ def test_routers_with_shared_output_strings():
     done_from_b = [
         edge
         for edge in router_edges
-        if edge["source"] == "router_b" and edge["router_path_label"] == "done"
+        if edge["source"] == "router_b" and edge["router_event"] == "done"
     ]
     assert len(done_from_b) == 1
     assert done_from_b[0]["target"] == "finalize"
 
 
-def test_warning_for_router_without_paths(caplog):
-    """Test that a warning is logged when a router has no determinable paths."""
+def test_warning_for_router_without_events(caplog):
+    """Test that a warning is logged when a router has no determinable events."""
     import logging
 
-    class RouterWithoutPathsFlow(Flow):
+    class RouterWithoutEventsFlow(Flow):
         """Flow with a router that returns a dynamic value."""
 
         @start()
@@ -564,34 +643,35 @@ def test_warning_for_router_without_paths(caplog):
         @router(begin)
         def dynamic_router(self):
             import random
-            return random.choice(["path_a", "path_b"])
+            return random.choice(["event_a", "event_b"])
 
-        @listen("path_a")
+        @listen("event_a")
         def handle_a(self):
             return "a"
 
-        @listen("path_b")
+        @listen("event_b")
         def handle_b(self):
             return "b"
 
-    flow = RouterWithoutPathsFlow()
+    flow = RouterWithoutEventsFlow()
 
     with caplog.at_level(logging.WARNING):
         build_flow_structure(flow)
 
     assert any(
-        "Could not determine return paths for router 'dynamic_router'" in record.message
+        "Router events for 'dynamic_router' are dynamic" in record.message
         for record in caplog.records
     )
 
     assert any(
-        "Found listeners waiting for triggers" in record.message
+        "Static visualization could not match listener triggers" in record.message
         for record in caplog.records
     )
+    assert not any(record.levelno >= logging.ERROR for record in caplog.records)
 
 
 def test_warning_for_orphaned_listeners(caplog):
-    """Test that an error is logged when listeners wait for triggers no router outputs."""
+    """Test that a warning is logged when a trigger has no explicit router output."""
     import logging
     from typing import Literal
 
@@ -615,19 +695,33 @@ def test_warning_for_orphaned_listeners(caplog):
             return "orphan"
 
     flow = OrphanedListenerFlow()
+    _attach_flow_definition(
+        OrphanedListenerFlow,
+        {
+            "begin": {"start": True},
+            "my_router": {
+                "listen": "begin",
+                "router": True,
+                "emit": ["option_a", "option_b"],
+            },
+            "handle_a": {"listen": "option_a"},
+            "handle_orphan": {"listen": "option_c"},
+        },
+    )
 
-    with caplog.at_level(logging.ERROR):
+    with caplog.at_level(logging.WARNING):
         build_flow_structure(flow)
 
     assert any(
-        "Found listeners waiting for triggers" in record.message
+        "Static visualization could not match listener triggers" in record.message
         and "option_c" in record.message
         for record in caplog.records
     )
+    assert not any(record.levelno >= logging.ERROR for record in caplog.records)
 
 
-def test_no_warning_for_properly_typed_router(caplog):
-    """Test that no warning is logged when router has proper type annotations."""
+def test_no_warning_for_explicit_contract_router_events(caplog):
+    """Test no warning is logged when router events are declared in the contract."""
     import logging
     from typing import Literal
 
@@ -639,23 +733,39 @@ def test_no_warning_for_properly_typed_router(caplog):
             return "started"
 
         @router(begin)
-        def typed_router(self) -> Literal["path_a", "path_b"]:
-            return "path_a"
+        def typed_router(self) -> Literal["event_a", "event_b"]:
+            return "event_a"
 
-        @listen("path_a")
+        @listen("event_a")
         def handle_a(self):
             return "a"
 
-        @listen("path_b")
+        @listen("event_b")
         def handle_b(self):
             return "b"
 
     flow = ProperlyTypedRouterFlow()
+    _attach_flow_definition(
+        ProperlyTypedRouterFlow,
+        {
+            "begin": {"start": True},
+            "typed_router": {
+                "listen": "begin",
+                "router": True,
+                "emit": ["event_a", "event_b"],
+            },
+            "handle_a": {"listen": "event_a"},
+            "handle_b": {"listen": "event_b"},
+        },
+    )
 
     with caplog.at_level(logging.WARNING):
         build_flow_structure(flow)
 
     # No warnings should be logged
     warning_messages = [r.message for r in caplog.records if r.levelno >= logging.WARNING]
-    assert not any("Could not determine return paths" in msg for msg in warning_messages)
-    assert not any("Found listeners waiting for triggers" in msg for msg in warning_messages)
+    assert not any("Router events for" in msg for msg in warning_messages)
+    assert not any(
+        "Static visualization could not match listener triggers" in msg
+        for msg in warning_messages
+    )

lib/crewai/tests/test_human_feedback_decorator.py

@@ -13,7 +13,7 @@ from unittest.mock import MagicMock, patch
 
 import pytest
 
-from crewai.flow import Flow, human_feedback, listen, start
+from crewai.flow import Flow, human_feedback, listen, persist, start
 from crewai.flow.human_feedback import (
     HumanFeedbackConfig,
     HumanFeedbackResult,
@@ -79,7 +79,7 @@ class TestHumanFeedbackValidation:
 
         assert hasattr(test_method, "__human_feedback_config__")
         assert test_method.__is_router__ is True
-        assert test_method.__router_paths__ == ["approve", "reject"]
+        assert test_method.__router_emit__ == ["approve", "reject"]
 
     def test_valid_configuration_without_routing(self):
         """Test that valid configuration without routing doesn't raise."""
@@ -91,6 +91,22 @@ class TestHumanFeedbackValidation:
         assert hasattr(test_method, "__human_feedback_config__")
         assert not hasattr(test_method, "__is_router__") or not test_method.__is_router__
 
+    def test_persist_preserves_human_feedback_llm_attribute(self):
+        """Test @persist preserves the live LLM stashed by @human_feedback."""
+        llm = object()
+
+        @persist()
+        @human_feedback(
+            message="Review this:",
+            emit=["approve", "reject"],
+            llm=llm,
+        )
+        def test_method(self):
+            return "output"
+
+        assert hasattr(test_method, "_human_feedback_llm")
+        assert test_method._human_feedback_llm is llm
+
 
 class TestHumanFeedbackConfig:
     """Tests for HumanFeedbackConfig dataclass."""
@@ -189,7 +205,7 @@ class TestDecoratorAttributePreservation:
             return "output"
 
         assert review_method.__is_router__ is True
-        assert review_method.__router_paths__ == ["approved", "rejected"]
+        assert review_method.__router_emit__ == ["approved", "rejected"]
 
 
 class TestAsyncSupport:

lib/crewai/tests/test_human_feedback_integration.py

@@ -778,14 +778,14 @@ class TestEdgeCases:
 class TestLLMConfigPreservation:
     """Tests that LLM config is preserved through @human_feedback serialization.
 
-    PR #4970 introduced _hf_llm stashing so the live LLM object survives
+    PR #4970 introduced _human_feedback_llm stashing so the live LLM object survives
     decorator wrapping for same-process resume. The serialization path
     (_serialize_llm_for_context / _deserialize_llm_from_context) preserves
     config for cross-process resume.
     """
 
-    def test_hf_llm_stashed_on_wrapper_with_llm_instance(self):
-        """Test that passing an LLM instance stashes it on the wrapper as _hf_llm."""
+    def test_human_feedback_llm_stashed_on_wrapper_with_llm_instance(self):
+        """Test that passing an LLM instance stashes it on the wrapper as _human_feedback_llm."""
         from crewai.llm import LLM
 
         llm_instance = LLM(model="gpt-4o-mini", temperature=0.42)
@@ -801,11 +801,11 @@ class TestLLMConfigPreservation:
                 return "content"
 
         method = ConfigFlow.review
-        assert hasattr(method, "_hf_llm"), "_hf_llm not found on wrapper"
-        assert method._hf_llm is llm_instance, "_hf_llm is not the same object"
+        assert hasattr(method, "_human_feedback_llm"), "_human_feedback_llm not found on wrapper"
+        assert method._human_feedback_llm is llm_instance, "_human_feedback_llm is not the same object"
 
-    def test_hf_llm_preserved_on_listen_method(self):
-        """Test that _hf_llm is preserved when @human_feedback is on a @listen method."""
+    def test_human_feedback_llm_preserved_on_listen_method(self):
+        """Test that _human_feedback_llm is preserved when @human_feedback is on a @listen method."""
         from crewai.llm import LLM
 
         llm_instance = LLM(model="gpt-4o-mini", temperature=0.7)
@@ -825,11 +825,11 @@ class TestLLMConfigPreservation:
                 return "content"
 
         method = ListenConfigFlow.review
-        assert hasattr(method, "_hf_llm")
-        assert method._hf_llm is llm_instance
+        assert hasattr(method, "_human_feedback_llm")
+        assert method._human_feedback_llm is llm_instance
 
-    def test_hf_llm_accessible_on_instance(self):
-        """Test that _hf_llm survives Flow instantiation (bound method access)."""
+    def test_human_feedback_llm_accessible_on_instance(self):
+        """Test that _human_feedback_llm survives Flow instantiation (bound method access)."""
         from crewai.llm import LLM
 
         llm_instance = LLM(model="gpt-4o-mini", temperature=0.42)
@@ -846,8 +846,8 @@ class TestLLMConfigPreservation:
 
         flow = InstanceFlow()
         instance_method = flow.review
-        assert hasattr(instance_method, "_hf_llm")
-        assert instance_method._hf_llm is llm_instance
+        assert hasattr(instance_method, "_human_feedback_llm")
+        assert instance_method._human_feedback_llm is llm_instance
 
     def test_serialize_llm_preserves_config_fields(self):
         """Test that _serialize_llm_for_context captures temperature, base_url, etc."""

lib/crewai/tests/test_llm_streaming_finish_reason.py

@@ -0,0 +1,96 @@
+"""Regression: LiteLLM emits a final usage-only chunk (choices=[]) when
+``stream_options.include_usage`` is set. The old post-loop
+``_extract_finish_reason_and_response_id(last_chunk)`` then silently returned
+(None, None). These tests pin that we capture finish_reason/response_id
+incrementally during the stream loop instead.
+"""
+from __future__ import annotations
+
+from typing import Any
+from unittest.mock import patch
+
+import pytest
+
+from crewai.events.event_bus import CrewAIEventsBus
+from crewai.events.types.llm_events import LLMCallCompletedEvent
+from crewai.llm import LLM
+
+
+@pytest.fixture
+def mock_emit():
+    with patch.object(CrewAIEventsBus, "emit") as mock:
+        yield mock
+
+
+def _completed_event(mock_emit) -> LLMCallCompletedEvent:
+    matches = [
+        call.kwargs["event"]
+        for call in mock_emit.call_args_list
+        if isinstance(call.kwargs.get("event"), LLMCallCompletedEvent)
+    ]
+    assert matches, "expected an LLMCallCompletedEvent to be emitted"
+    assert len(matches) == 1, f"expected one completed event, got {len(matches)}"
+    return matches[0]
+
+
+def _chunks_with_usage_tail() -> list[dict[str, Any]]:
+    """Three-chunk stream mirroring LiteLLM's include_usage behavior:
+    two content chunks where the second carries finish_reason="stop",
+    then a final usage-only chunk with choices=[]."""
+    return [
+        {
+            "id": "chatcmpl-stream-1",
+            "choices": [
+                {"delta": {"content": "hi"}, "finish_reason": None}
+            ],
+        },
+        {
+            "id": "chatcmpl-stream-1",
+            "choices": [
+                {"delta": {"content": " there"}, "finish_reason": "stop"}
+            ],
+        },
+        {
+            "id": "chatcmpl-stream-1",
+            "choices": [],
+            "usage": {
+                "prompt_tokens": 1,
+                "completion_tokens": 2,
+                "total_tokens": 3,
+            },
+        },
+    ]
+
+
+def test_sync_stream_emits_finish_reason_and_response_id_from_loop(mock_emit):
+    llm = LLM(model="gpt-4o-mini", is_litellm=True, stream=True)
+
+    with patch("crewai.llm.litellm.completion", return_value=iter(_chunks_with_usage_tail())):
+        result = llm.call("anything")
+
+    assert result == "hi there"
+
+    event = _completed_event(mock_emit)
+    assert event.finish_reason == "stop"
+    assert event.response_id == "chatcmpl-stream-1"
+
+
+@pytest.mark.asyncio
+async def test_async_stream_emits_finish_reason_and_response_id_from_loop(mock_emit):
+    llm = LLM(model="gpt-4o-mini", is_litellm=True, stream=True)
+
+    async def _aiter():
+        for chunk in _chunks_with_usage_tail():
+            yield chunk
+
+    async def _acompletion(*_args, **_kwargs):
+        return _aiter()
+
+    with patch("crewai.llm.litellm.acompletion", side_effect=_acompletion):
+        result = await llm.acall("anything")
+
+    assert result == "hi there"
+
+    event = _completed_event(mock_emit)
+    assert event.finish_reason == "stop"
+    assert event.response_id == "chatcmpl-stream-1"

lib/crewai/tests/tracing/test_tracing.py

@@ -1,4 +1,5 @@
 import os
+from threading import Thread
 from unittest.mock import MagicMock, Mock, patch
 
 import pytest
@@ -867,6 +868,122 @@ class TestTraceListenerSetup:
                 mock_mark_failed.assert_called_once_with(
                     "test_batch_id_12345", "Internal Server Error"
                 )
+                assert batch_manager.current_batch is not None
+                assert batch_manager.trace_batch_id == "test_batch_id_12345"
+                assert batch_manager._batch_finalized is False
+
+    def test_finalize_batch_clears_buffer_after_successful_send(self) -> None:
+        """Successful send must not restore a stale event buffer (duplicate events)."""
+        from crewai.events.listeners.tracing.types import TraceEvent
+
+        with patch(
+            "crewai.events.listeners.tracing.trace_batch_manager.is_tracing_enabled_in_context",
+            return_value=True,
+        ):
+            batch_manager = TraceBatchManager()
+            batch_manager.current_batch = batch_manager.initialize_batch(
+                user_context={"privacy_level": "standard"},
+                execution_metadata={
+                    "execution_type": "flow",
+                    "flow_name": "TestFlow",
+                },
+            )
+            batch_manager.trace_batch_id = "batch-clear-test"
+            batch_manager.backend_initialized = True
+            batch_manager.event_buffer = [
+                TraceEvent(
+                    type="llm_call_started",
+                    timestamp="2026-01-01T00:00:00",
+                    event_id="evt-1",
+                    emission_sequence=1,
+                )
+            ]
+
+            with (
+                patch.object(
+                    batch_manager.plus_api,
+                    "send_trace_events",
+                    return_value=MagicMock(status_code=200),
+                ),
+                patch.object(
+                    batch_manager.plus_api,
+                    "finalize_trace_batch",
+                    return_value=MagicMock(status_code=200, json=MagicMock(return_value={})),
+                ),
+            ):
+                batch_manager.finalize_batch()
+
+            assert batch_manager.event_buffer == []
+
+    def test_finalize_backend_batch_uses_captured_batch_id_for_ephemeral_panel(
+        self,
+    ) -> None:
+        """Finalization output must not render None if manager state is reset."""
+        batch_manager = TraceBatchManager()
+        batch_manager.trace_batch_id = "ephemeral-batch-id"
+        batch_manager.is_current_batch_ephemeral = True
+
+        def clear_batch_id_during_response() -> dict[str, str]:
+            batch_manager.trace_batch_id = None
+            return {"access_code": "TRACE-test"}
+
+        with (
+            patch.object(
+                batch_manager.plus_api,
+                "finalize_ephemeral_trace_batch",
+                return_value=MagicMock(
+                    status_code=200,
+                    json=clear_batch_id_during_response,
+                ),
+            ),
+            patch(
+                "crewai.events.listeners.tracing.trace_batch_manager.should_auto_collect_first_time_traces",
+                return_value=False,
+            ),
+            patch(
+                "crewai.events.listeners.tracing.trace_batch_manager.Console.print"
+            ) as mock_print,
+        ):
+            assert batch_manager._finalize_backend_batch() is True
+
+        panel = mock_print.call_args.args[0]
+        panel_text = str(panel.renderable)
+        assert "session ID: ephemeral-batch-id" in panel_text
+        assert "ephemeral_trace_batches/ephemeral-batch-id" in panel_text
+        assert "session ID: None" not in panel_text
+        assert "ephemeral_trace_batches/None" not in panel_text
+
+    def test_finalize_backend_batch_is_serialized(self) -> None:
+        """Concurrent finalizers must only call the backend once."""
+        batch_manager = TraceBatchManager()
+        batch_manager.trace_batch_id = "ephemeral-batch-id"
+        batch_manager.is_current_batch_ephemeral = True
+        response = MagicMock(status_code=200, json=MagicMock(return_value={}))
+
+        with (
+            patch.object(
+                batch_manager.plus_api,
+                "finalize_ephemeral_trace_batch",
+                return_value=response,
+            ) as mock_finalize,
+            patch(
+                "crewai.events.listeners.tracing.trace_batch_manager.should_auto_collect_first_time_traces",
+                return_value=True,
+            ),
+        ):
+            results: list[bool] = []
+
+            def finalize() -> None:
+                results.append(batch_manager._finalize_backend_batch())
+
+            threads = [Thread(target=finalize), Thread(target=finalize)]
+            for thread in threads:
+                thread.start()
+            for thread in threads:
+                thread.join()
+
+        assert results == [True, True]
+        mock_finalize.assert_called_once()
 
     def test_ephemeral_batch_includes_anon_id(self):
         """Test that ephemeral batch initialization sends anon_id from get_user_id()"""

lib/crewai/tests/utilities/test_lock_store.py

@@ -1,11 +1,13 @@
 """Tests for lock_store.
 
-We verify our own logic: the _redis_available guard and which portalocker
-backend is selected. We trust portalocker to handle actual locking mechanics.
+We verify our own logic: the _redis_available guard, which portalocker
+backend is selected, and that a custom backend can be plugged in. We trust
+portalocker to handle actual locking mechanics.
 """
 
 from __future__ import annotations
 
+from contextlib import contextmanager
 import sys
 from unittest import mock
 
@@ -20,6 +22,14 @@ def no_redis_url(monkeypatch):
     monkeypatch.setattr(lock_store, "_REDIS_URL", None)
 
 
+@pytest.fixture(autouse=True)
+def reset_backend():
+    """Ensure a custom backend never leaks across tests."""
+    lock_store.set_lock_backend(None)
+    yield
+    lock_store.set_lock_backend(None)
+
+
 # _redis_available
 
 
@@ -64,3 +74,40 @@ def test_uses_redis_lock_when_redis_available(monkeypatch):
     kwargs = mock_redis_lock.call_args.kwargs
     assert kwargs["channel"].startswith("crewai:")
     assert kwargs["connection"] is fake_conn
+
+
+# custom backend
+
+
+def test_custom_backend_is_used():
+    calls = []
+
+    @contextmanager
+    def fake_backend(name, *, timeout):
+        calls.append((name, timeout))
+        yield
+
+    lock_store.set_lock_backend(fake_backend)
+
+    # The default file/redis path must not be touched when overridden.
+    with mock.patch("portalocker.Lock") as mock_lock:
+        with lock("custom_test", timeout=5):
+            pass
+
+    mock_lock.assert_not_called()
+    assert calls == [("custom_test", 5)]
+
+
+def test_clearing_backend_restores_default():
+    @contextmanager
+    def fake_backend(name, *, timeout):
+        yield
+
+    lock_store.set_lock_backend(fake_backend)
+    lock_store.set_lock_backend(None)
+
+    with mock.patch("portalocker.Lock") as mock_lock:
+        with lock("after_clear"):
+            pass
+
+    mock_lock.assert_called_once()

lib/devtools/src/crewai_devtools/__init__.py

@@ -1,3 +1,3 @@
 """CrewAI development tools."""
 
-__version__ = "1.14.6"
+__version__ = "1.14.7a2"