fix: force aiohttp>=3.14.0 for GHSA-jg22-mg44-37j8, GHSA-hg6j-4rv6-33pg

.github/workflows/vulnerability-scan.yml

@@ -64,7 +64,6 @@ jobs:
             --ignore-vuln PYSEC-2025-197 \
             --ignore-vuln PYSEC-2025-210 \
             --ignore-vuln PYSEC-2026-139 \
-            --ignore-vuln GHSA-rrmf-rvhw-rf47 \
             --ignore-vuln PYSEC-2025-211 \
             --ignore-vuln PYSEC-2025-212 \
             --ignore-vuln PYSEC-2025-213 \
@@ -82,7 +81,6 @@ jobs:
         #   PYSEC-2025-183      - pyjwt 2.12.1: disputed weak-encryption claim; key length is application-chosen
         #   PYSEC-2025-189..197 - torch 2.11.0: memory-corruption/DoS in functions only reachable via untrusted models; no fix available
         #   PYSEC-2025-210, PYSEC-2026-139 - torch 2.11.0: profiler/deserialization issues; no fix available
-        #   GHSA-rrmf-rvhw-rf47 - torch 2.11.0 (CVE-2025-3000, alias of PYSEC-2025-194): memory corruption in torch.jit.script, CVSS 1.9, local-only; affected <=2.12.0, no fix available. pip-audit reports it under the GHSA id so the PYSEC ignore above does not catch it.
         #   PYSEC-2025-211..218 - transformers 5.5.4: deserialization/code injection via malicious model checkpoints; no fix available
         #   GHSA-f4j7-r4q5-qw2c - chromadb 1.1.1 (CVE-2026-45829): pre-auth RCE via /api/v2/tenants/{tenant}/databases/{db}/collections when trust_remote_code=true.
         #                         Advisory: vulnerable >=1.0.0,<=1.5.9, firstPatchedVersion=none. We only use chromadb.PersistentClient (lib/crewai/src/crewai/rag/chromadb/factory.py)

.pre-commit-config.yaml

@@ -47,7 +47,6 @@ repos:
           --ignore-vuln PYSEC-2025-197
           --ignore-vuln PYSEC-2025-210
           --ignore-vuln PYSEC-2026-139
-          --ignore-vuln GHSA-rrmf-rvhw-rf47
           --ignore-vuln PYSEC-2025-211
           --ignore-vuln PYSEC-2025-212
           --ignore-vuln PYSEC-2025-213

conftest.py

@@ -11,99 +11,7 @@ from typing import Any
 
 from dotenv import load_dotenv
 import pytest
-
-
-def _patch_vcrpy_aiohttp_compat() -> None:
-    """Keep vcrpy's aiohttp stub working under aiohttp 3.14.0.
-
-    aiohttp 3.14.0 (pulled in to fix GHSA-jg22-mg44-37j8 and GHSA-hg6j-4rv6-33pg):
-      * removed ``aiohttp.streams.AsyncStreamReaderMixin`` (folded into ``StreamReader``),
-        which vcrpy's ``MockStream`` still subclasses -- vcr's patch machinery then raises
-        ``AttributeError`` at collection time; and
-      * added a required ``stream_writer`` keyword-only arg to ``ClientResponse.__init__``,
-        which vcrpy's ``MockClientResponse`` does not pass -- raising ``TypeError`` at
-        cassette playback.
-
-    Restore the mixin, then rebuild ``MockClientResponse``'s ``super().__init__`` call from
-    the live ``ClientResponse`` signature (defaulting every required keyword-only arg to
-    ``None``, mirroring vcrpy's original call) so it also survives future aiohttp additions.
-    """
-    import asyncio
-    import inspect
-
-    from aiohttp import streams
-    from aiohttp.client_reqrep import ClientResponse
-
-    if not hasattr(streams, "AsyncStreamReaderMixin"):
-
-        class AsyncStreamReaderMixin:
-            __slots__ = ()
-
-            def __aiter__(self) -> streams.AsyncStreamIterator[bytes]:
-                return streams.AsyncStreamIterator(self.readline)  # type: ignore[attr-defined]
-
-            def iter_chunked(self, n: int) -> streams.AsyncStreamIterator[bytes]:
-                return streams.AsyncStreamIterator(lambda: self.read(n))  # type: ignore[attr-defined]
-
-            def iter_any(self) -> streams.AsyncStreamIterator[bytes]:
-                return streams.AsyncStreamIterator(self.readany)  # type: ignore[attr-defined]
-
-            def iter_chunks(self) -> streams.ChunkTupleAsyncStreamIterator:
-                return streams.ChunkTupleAsyncStreamIterator(self)  # type: ignore[arg-type]
-
-        streams.AsyncStreamReaderMixin = AsyncStreamReaderMixin  # type: ignore[attr-defined]
-
-    # Importing the stub builds MockStream/MockClientResponse, so it must run after the
-    # mixin is restored above.
-    import vcr.stubs.aiohttp_stubs as aiohttp_stubs  # type: ignore[import-untyped]
-
-    if getattr(aiohttp_stubs.MockClientResponse, "_crewai_aiohttp_patched", False):
-        return
-
-    keyword_only = [
-        name
-        for name, param in inspect.signature(ClientResponse.__init__).parameters.items()
-        if param.kind is inspect.Parameter.KEYWORD_ONLY
-    ]
-
-    class _NullStreamWriter:
-        # aiohttp 3.14.0 reads stream_writer.output_size in the "request already
-        # sent" branch (writer is None), so None is not enough -- supply a stub.
-        output_size = 0
-
-    fallback_loop: list[asyncio.AbstractEventLoop] = []
-
-    def _resolve_loop() -> asyncio.AbstractEventLoop:
-        # MockClientResponse is normally built inside aiohttp's running loop, so
-        # prefer that. In a sync context there is no running loop; avoid
-        # asyncio.get_event_loop(), which on 3.12+ emits a DeprecationWarning
-        # (and can RuntimeError) when no current loop is set. Use one cached
-        # loop instead -- the mock only stores it and calls loop.get_debug().
-        try:
-            return asyncio.get_running_loop()
-        except RuntimeError:
-            if not fallback_loop:
-                fallback_loop.append(asyncio.new_event_loop())
-            return fallback_loop[0]
-
-    def _mock_client_response_init(
-        self: Any, method: str, url: Any, request_info: Any = None
-    ) -> None:
-        kwargs: dict[str, Any] = dict.fromkeys(keyword_only)
-        kwargs["request_info"] = request_info
-        if "loop" in kwargs:
-            kwargs["loop"] = _resolve_loop()
-        if "stream_writer" in kwargs:
-            kwargs["stream_writer"] = _NullStreamWriter()
-        ClientResponse.__init__(self, method, url, **kwargs)
-
-    aiohttp_stubs.MockClientResponse.__init__ = _mock_client_response_init
-    aiohttp_stubs.MockClientResponse._crewai_aiohttp_patched = True
-
-
-_patch_vcrpy_aiohttp_compat()
-
-from vcr.request import Request  # type: ignore[import-untyped]  # noqa: E402
+from vcr.request import Request  # type: ignore[import-untyped]
 
 
 try:

docs/ar/changelog.mdx

@@ -4,178 +4,6 @@ description: "تحديثات المنتج والتحسينات وإصلاحات
 icon: "clock"
 mode: "wide"
 ---
-<Update label="11 يونيو 2026">
-  ## v1.14.7
-
-  [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7)
-
-  ## ما الذي تغير
-
-  ### الميزات
-  - إضافة واجهات خلفية افتراضية قابلة للتوصيل للذاكرة، والمعرفة، وrag، وflow.
-  - عرض السبب الحقيقي للإنهاء، ومعلمات العينة، وresponse.id في أحداث LLM.
-  - تصنيف مشغلات DSL كزخارف واعية للمسار.
-  - إضافة واجهة برمجة تطبيقات الدردشة لتدفقات المحادثة.
-  - جعل واجهة القفل قابلة للتجاوز.
-  - بناء FlowDefinition من بيانات التعريف الخاصة بـ Flow DSL.
-  - إضافة مزود LLM من Snowflake Cortex الأصلي.
-  - إضافة دعم لملفات الوكلاء المدربين من crew.
-
-  ### إصلاحات الأخطاء
-  - إصلاح نقطة التحقق لإعادة بناء BaseLLM مخصص كـ LLM ملموس عند الاستعادة.
-  - تقييد الاستعادة على علامة لمنع اللقطات الحية من إعادة التشغيل كاستئناف.
-  - تحديد حالة وقت التشغيل لكل تشغيل للحد من النمو وعزل التشغيل المتزامن.
-  - إصلاح إعدادات التتبع على crewai-login.
-  - احترام suppress_flow_events لأحداث تنفيذ الطريقة.
-  - استعادة [project.scripts] في حزمة crewai لتثبيت أداة uv.
-  - حل مشكلات CVE الخاصة بـ pip-audit لـ aiohttp وdocling وdocling-core.
-  - إصلاح إدخال الملفات الذي لا يعمل بشكل موثوق.
-  - إصلاح تاريخ نتائج أدوات Snowflake Claude غير المكتملة.
-
-  ### الوثائق
-  - تحديث سجل التغييرات والإصدار لـ v1.14.7.
-  - تحديث وثائق جامع OpenTelemetry.
-  - تحديث دليل NVIDIA Nemotron LLM.
-  - إضافة دليل تكامل Databricks.
-  - إضافة دليل تكامل Snowflake.
-
-  ### الأداء
-  - تحسين سرعة استيراد crewai من خلال تحميل مستندات docling بشكل كسول.
-
-  ### إعادة الهيكلة
-  - تبسيط تقييم شروط التدفق ليكون بلا حالة لكل حدث.
-  - فصل منطق المحادثة عن وقت التشغيل وإضافة تعريف المحادثة.
-  - تقسيم `flow.py` إلى DSL، وتعريف، ووقت تشغيل.
-
-  ## المساهمون
-
-  @Luzk, @alex-clawd, @devin-ai-integration[bot], @greysonlalonde, @gvieira, @jessemiller, @lorenzejay, @lucasgomide, @mattatcha, @vinibrsl
-
-</Update>
-
-<Update label="10 يونيو 2026">
-  ## v1.14.7rc2
-
-  [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7rc2)
-
-  ## ما الذي تغير
-
-  ### إصلاحات الأخطاء
-  - استعادة البوابة على علامة لمنع اللقطات الحية من إعادة التشغيل كاستئناف
-
-  ### الوثائق
-  - تحديث سجل التغييرات والإصدار لـ v1.14.7rc1
-
-  ## المساهمون
-
-  @greysonlalonde
-
-</Update>
-
-<Update label="10 يونيو 2026">
-  ## v1.14.7rc1
-
-  [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7rc1)
-
-  ## ما الذي تغير
-
-  ### الميزات
-  - إضافة `reset_runtime_state` لإطلاق حالة الحافلة المتراكمة
-  - التعامل مع دعم كل من الموجهات المخصصة
-  - فصل منطق المحادثة عن وقت التشغيل وإضافة `conversational_definition`
-
-  ### إصلاحات الأخطاء
-  - إصلاح نطاق حالة وقت التشغيل لكل تشغيل للحد من النمو وعزل التشغيلات المتزامنة
-  - إصلاح إعدادات القياس عن بُعد على `crewai-login`
-  - إصلاح احترام `suppress_flow_events` لفعاليات تنفيذ الأساليب
-
-  ### الوثائق
-  - تحديث صور OpenTelemetry
-  - تحديث الوثائق لتعكس الحالة الجديدة لجمع بيانات OpenTelemetry
-  - تحديث سجل التغييرات والإصدار لـ v1.14.7a4
-
-  ### إعادة الهيكلة
-  - تبسيط تقييم شرط التدفق ليكون بلا حالة لكل حدث
-  - تحسين دورة توجيه المحادثة مع تقليل مسار واحد
-
-  ## المساهمون
-
-  @greysonlalonde, @lorenzejay, @lucasgomide, @vinibrsl
-
-</Update>
-
-<Update label="9 يونيو 2026">
-  ## v1.14.7a4
-
-  [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7a4)
-
-  ## ما الذي تغير
-
-  ### الميزات
-  - نقل وقت التشغيل @listen/@router لقراءة من FlowDefinition
-  - إضافة واجهات خلفية افتراضية قابلة للتوصيل للذاكرة، والمعرفة، وrag، وflow
-
-  ### الوثائق
-  - تحديث سجل التغييرات والإصدار لـ v1.14.7a3
-
-  ## المساهمون
-
-  @greysonlalonde, @mattatcha, @vinibrsl
-
-</Update>
-
-<Update label="8 يونيو 2026">
-  ## v1.14.7a3
-
-  [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7a3)
-
-  ## ما الذي تغير
-
-  ### إصلاحات الأخطاء
-  - إصلاح تعرض `ask_for_human_input` في `AgentExecutor` التجريبي
-  - حل مشكلات CVEs الخاصة بـ pip-audit لـ `aiohttp`، `docling`، `docling-core`، و `pip`
-
-  ### إعادة هيكلة
-  - نقل `@start` لقراءة من `FlowDefinition`
-
-  ### الوثائق
-  - تحديث سجل التغييرات والإصدار لـ v1.14.7a2
-
-  ## المساهمون
-
-  @greysonlalonde، @lorenzejay، @vinibrsl
-
-</Update>
-
-<Update label="5 يونيو 2026">
-  ## v1.14.7a2
-
-  [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7a2)
-
-  ## ما الذي تغير
-
-  ### الميزات
-  - إضافة دعم تتبع تدفقات المحادثة.
-  - تحديث وثائق تدفق المحادثة لاستخدام `handle_turn`.
-  - عرض السبب الحقيقي لإنهاء المحادثة، ومعلمات العينة، و`response.id` في أحداث LLM.
-  - تصنيف مشغلات DSL كزخارف واعية بالمسار.
-  - تنفيذ واجهة برمجة التطبيقات للدردشة لتدفقات المحادثة.
-  - جعل قفل الخلفية قابلاً للتجاوز في متجر القفل.
-  - تقسيم أحادي تدفق DSL إلى وحدات زخرفية مركزة.
-  - تسطيح استخدام ذاكرة التخزين المؤقت LiteLLM/أعداد الأسباب الفرعية في `_usage_to_dict`.
-  - بناء `FlowDefinition` من بيانات التعريف الخاصة بتدفق DSL.
-
-  ### الوثائق
-  - إضافة دليل NVIDIA Nemotron LLM.
-  - توثيق عمليات نشر المونوريبو.
-  - تحديث سجل التغييرات والإصدار لـ v1.14.7a1.
-
-  ## المساهمون
-
-  @alex-clawd, @gvieira, @lorenzejay, @lucasgomide, @mattatcha, @vinibrsl
-
-</Update>
-
 <Update label="3 يونيو 2026">
   ## v1.14.7a1
 

docs/ar/concepts/flows.mdx

@@ -226,48 +226,6 @@ counter=2 message='Hello from first_method - updated by second_method'
 من خلال ضمان إعادة مخرجات الدالة الأخيرة وتوفير الوصول إلى الحالة، تجعل تدفقات CrewAI من السهل دمج نتائج سير عمل الذكاء الاصطناعي في التطبيقات أو الأنظمة الأكبر،
 مع الحفاظ على الوصول إلى الحالة طوال تنفيذ التدفق.
 
-## مقاييس استخدام التدفق
-
-بعد اكتمال تنفيذ التدفق، يمكنك الوصول إلى الخاصية `usage_metrics` لعرض إجمالي استخدام التوكنات عبر **كل استدعاء لنموذج اللغة** يتم خلال التشغيل — بما في ذلك الاستدعاءات من كل فريق (Crew) ينظمه التدفق، والاستدعاءات داخل أدوات الـ Agents، والاستدعاءات المباشرة لـ `LLM.call(...)` من دوال التدفق. هذا هو المكافئ على جانب الـ SDK للإجماليات المعروضة في واجهة CrewAI Enterprise.
-
-```python Code
-from crewai import LLM
-from crewai.flow.flow import Flow, listen, start
-
-class UsageMetricsFlow(Flow):
-    @start()
-    def run_first_crew(self):
-        self.state.first_result = FirstCrew().crew().kickoff()
-
-    @listen(run_first_crew)
-    def call_llm_directly(self):
-        # استدعاء مباشر لنموذج اللغة — يُحسب أيضًا ضمن flow.usage_metrics
-        llm = LLM(model="openai/gpt-4o-mini")
-        self.state.summary = llm.call("لخّص النقاط الرئيسية.")
-
-    @listen(call_llm_directly)
-    def run_second_crew(self):
-        self.state.second_result = SecondCrew().crew().kickoff()
-
-flow = UsageMetricsFlow()
-flow.kickoff()
-
-print(flow.usage_metrics)
-# UsageMetrics(total_tokens=8579, prompt_tokens=6210, completion_tokens=2369,
-#              cached_prompt_tokens=0, reasoning_tokens=0,
-#              cache_creation_tokens=0, successful_requests=5)
-```
-
-<Note>
-  `flow.usage_metrics` **ليست** نفس `flow.kickoff().token_usage`. هذه الأخيرة
-  ترجع فقط `CrewOutput.token_usage` لـ **آخر** دالة `@listen` أعادت
-  `CrewOutput`، مما يعني أنها تعكس فقط الفريق الأخير وتتجاهل الفرق السابقة
-  وكذلك أي استدعاءات مباشرة لـ `LLM.call(...)`. استخدم `flow.usage_metrics`
-  كلما احتجت إلى الإجمالي **الكامل** للتوكنات لتنفيذ التدفق.
-</Note>
-
-كل حقل في [`UsageMetrics`](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/types/usage_metrics.py) المُعاد هو مجموع جميع استدعاءات نموذج اللغة التي حدثت خلال استدعاء واحد لـ `flow.kickoff()`. تتم إعادة تعيين العدادات عند الاستدعاء التالي لـ `kickoff()` (وفي كل تكرار من `kickoff_for_each`)، لذلك لن تتكرر العدّات عبر التشغيلات المتتالية. يمكن قراءة هذه الخاصية بأمان في أي وقت بعد اكتمال `kickoff()`؛ قراءتها أثناء التنفيذ تُرجع المجموع الجزئي المتراكم حتى تلك اللحظة.
-
 ## إدارة حالة التدفق
 
 إدارة الحالة بفعالية أمر بالغ الأهمية لبناء سير عمل ذكاء اصطناعي موثوق وقابل للصيانة. توفر تدفقات CrewAI آليات قوية لإدارة الحالة غير المهيكلة والمهيكلة،

docs/ar/enterprise/guides/capture_telemetry_logs.mdx

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

docs/ar/guides/advanced/customizing-prompts.mdx

@@ -161,18 +161,6 @@ crew = Crew(
 )
 ```
 
-<Note>
-يُحتفظ بـ `agent.i18n` للتوافق مع الإصدارات السابقة فقط، وقد تم إهماله. لتخصيص المطالبات أثناء التشغيل، مرّر `prompt_file` إلى `Crew`. وللوصول البرمجي المباشر إلى شرائح المطالبات، استخدم أداة i18n مباشرة:
-</Note>
-
-```python
-from crewai.utilities.i18n import get_i18n
-
-i18n = get_i18n("custom_prompts.json")
-format_slice = i18n.slice("format")
-tool_prompt = i18n.tools("ask_question")
-```
-
 #### الخيار 3: تعطيل مطالبات النظام لنماذج o1
 ```python
 agent = Agent(
@@ -220,8 +208,6 @@ agent = Agent(
 
 يدمج CrewAI بعد ذلك تخصيصاتك مع الإعدادات الافتراضية، فلا تحتاج لإعادة تعريف كل مطالبة. إليك الطريقة:
 
-بالنسبة للكود الذي يحتاج إلى قراءة شرائح المطالبات مباشرة، استخدم `crewai.utilities.i18n.get_i18n()` مع ملف المطالبات نفسه بدلًا من قراءة `agent.i18n`.
-
 ### مثال: تخصيص أساسي للمطالبات
 
 أنشئ ملف `custom_prompts.json` بالمطالبات التي تريد تعديلها. تأكد من إدراج جميع المطالبات عالية المستوى التي يجب أن يحتويها، وليس فقط تغييراتك:

docs/ar/guides/flows/conversational-flows.mdx

@@ -7,87 +7,97 @@ mode: "wide"
 
 ## نظرة عامة
 
-تعامل التطبيقات المحادثية مع كل سطر من المستخدم كـ **تشغيل flow جديد** بنفس **معرّف الجلسة**. توفر CrewAI مساعدات لسجل الرسائل وتصنيف النية الاختياري وتأجيل التتبع وجسور الواجهة، إضافة إلى REPL محلي `flow.chat()` للتدفقات المحادثية.
+تعامل التطبيقات المحادثية مع كل سطر من المستخدم كـ **تشغيل flow جديد** بنفس **معرّف الجلسة**. توفر CrewAI مساعدات لسجل الرسائل وتصنيف النية الاختياري وتأجيل التتبع وجسور الواجهة — دون API منفصل `chat()` على `Flow`.
 
 | المفهوم | التنفيذ |
 |---------|---------|
-| معرّف الجلسة | `handle_turn(..., session_id=...)` → `kickoff(inputs={"id": ...})` → `state.id` |
-| سطر المستخدم | `handle_turn(message)` يضيف الرسالة إلى `state.messages` قبل تشغيل الرسم |
-| اكتمال الجولة | `FlowFinished` لهذا **التشغيل** فقط؛ تستمر المحادثة في `handle_turn` التالي |
-| تتبع الجلسة | `ConversationConfig(defer_trace_finalization=True)` + `finalize_session_traces()` |
+| معرّف الجلسة | `kickoff(session_id=...)` → `inputs["id"]` → `state.id` |
+| سطر المستخدم | `kickoff(user_message=...)` يُضاف إلى `state.messages` قبل تشغيل الرسم |
+| اكتمال الجولة | `FlowFinished` لهذا **التشغيل** فقط؛ تستمر المحادثة في `kickoff` التالي |
+| تتبع الجلسة | `ConversationalConfig(defer_trace_finalization=True)` + `finalize_session_traces()` |
 
-## واجهات الجولات
+## نقطة دخول واحدة: `kickoff`
 
-استخدم **`flow.handle_turn(message, session_id=...)`** لكل رسالة مستخدم من REST أو WebSocket أو الاختبارات أو الواجهات المخصصة. استخدم **`flow.chat()`** عندما تريد حلقة دردشة محلية في الطرفية لـ `Flow` محادثي.
-
-لا يقبل `Flow.kickoff()` الوسيطين `user_message=` أو `session_id=`. في التدفقات المحادثية، يخزن `handle_turn()` الرسالة المعلقة ويستدعي داخلياً `kickoff(inputs={"id": session_id})`.
+استخدم **`flow.kickoff(user_message=..., session_id=...)`** لكل رسالة مستخدم (REST أو WebSocket أو CLI). لا تنشئ غلاف `chat()` مخصصاً على `Flow`.
 
 | API | الاستخدام |
 |-----|-----------|
-| `handle_turn(message, session_id=...)` | غلاف مريح لجولة واحدة في `Flow` محادثي |
-| `chat()` | REPL محلي في الطرفية لـ `Flow` محادثي |
-| `kickoff(inputs={...})` | تشغيل متقدم للـ flow بدون معالجة جولة محادثية |
+| `kickoff(user_message=..., session_id=...)` | كل رسالة مستخدم |
+| `kickoff_async(...)` | نفس المعاملات؛ دخول async أصلي |
 | `ask()` | مطالبة حاجزة **داخل** خطوة واحدة |
 | `@human_feedback` | الموافقة/الرفض على **مخرجات خطوة** — وليس السطر التالي |
-| `ChatSession.handle_turn(...)` | طبقة نقل فوق `handle_turn` |
+| `ChatSession.handle_turn(...)` | طبقة نقل فوق `kickoff` |
 
 ## بداية سريعة
 
 ```python
 from uuid import uuid4
 
-from crewai import Flow
-from crewai.flow import listen
-from crewai.experimental.conversational import (
-    ConversationConfig,
-    ConversationState,
+from crewai.flow import (
+    ChatState,
+    ConversationalConfig,
+    Flow,
+    listen,
+    or_,
+    persist,
+    router,
+    start,
 )
+from crewai.flow.persistence import SQLiteFlowPersistence
 
 
-@ConversationConfig(defer_trace_finalization=True)
-class SupportFlow(Flow[ConversationState]):
-    conversational = True
+class SupportFlow(Flow[ChatState]):
+    conversational_config = ConversationalConfig(
+        default_intents=["order", "help", "goodbye"],
+        intent_llm="gpt-4o-mini",
+        defer_trace_finalization=True,
+    )
 
-    def route_turn(self, context):
-        message = (self.state.current_user_message or "").lower()
-        if "طلب" in message or "order" in message:
-            return "order"
-        if "وداع" in message or "goodbye" in message:
-            return "goodbye"
-        return "help"
+    @start()
+    def bootstrap(self):
+        if not self.state.session_ready:
+            self.state.session_ready = True
+        return "ready"
+
+    @router(bootstrap)
+    def route(self):
+        return self.state.last_intent or "help"
 
     @listen("order")
     def handle_order(self):
         reply = "طلبك في الطريق."
-        self.append_assistant_message(reply)
+        self.append_message("assistant", reply)
         return reply
 
     @listen("help")
     def handle_help(self):
         reply = "كيف يمكنني المساعدة؟"
-        self.append_assistant_message(reply)
+        self.append_message("assistant", reply)
         return reply
 
     @listen("goodbye")
     def handle_goodbye(self):
         reply = "وداعاً!"
-        self.append_assistant_message(reply)
+        self.append_message("assistant", reply)
         return reply
 
+    @persist(SQLiteFlowPersistence("support.db"))
+    @listen(or_(handle_order, handle_help, handle_goodbye))
+    def finalize(self):
+        return self.state.model_dump()
+
 
 session_id = str(uuid4())
 flow = SupportFlow()
 
-try:
-    flow.handle_turn("أين طلبي؟", session_id=session_id)
-    flow.handle_turn("وماذا عن الإرجاع؟", session_id=session_id)
-finally:
-    flow.finalize_session_traces()
+flow.kickoff(user_message="أين طلبي؟", session_id=session_id)
+flow.kickoff(user_message="وماذا عن الإرجاع؟", session_id=session_id)
+flow.finalize_session_traces()
 ```
 
 ## دورة حياة الجولة
 
-كل `handle_turn` يشغّل:
+كل `kickoff` مع `user_message` يشغّل:
 
 1. **`_configure_conversational_kickoff`** — دمج `session_id` / `user_message` في `inputs` وتطبيق `ConversationalConfig`.
 2. **استعادة الحالة** — عند وجود `inputs["id"]` و`@persist`.
@@ -96,7 +106,7 @@ finally:
 5. **تنفيذ الرسم** — `@start` → `@router` → معالجات `@listen`.
 6. **نهاية التشغيل** — يُتخطى `flow_finished` والتتبع لكل جولة عند التأجيل؛ `Agent.kickoff()` / crews لا تغلق دفعة الأب.
 
-استدعِ **`append_assistant_message(reply)`** في المعالجات. سطر المستخدم محفوظ عبر `handle_turn` — لا تُضفه مرة أخرى.
+استدعِ **`append_message("assistant", reply)`** في المعالجات. سطر المستخدم محفوظ عند kickoff — لا تُضفه مرة أخرى.
 
 ## `ConversationalConfig` (افتراضيات على مستوى الصنف)
 
@@ -280,15 +290,6 @@ finally:
     flow.finalize_session_traces()
 ```
 
-للدردشة المحلية في الطرفية، استخدم `chat()`:
-
-```python
-def kickoff() -> None:
-    SupportFlow().chat()
-```
-
-يلف `chat()` استدعاءات `handle_turn()` داخل REPL، ويخرج عند `exit` / `quit`، ويتجاهل الأسطر الفارغة افتراضياً، ويستدعي `finalize_session_traces()` عند انتهاء الجلسة.
-
 ### `ConversationConfig`
 
 مزخرف صنف يُلحق افتراضيات الدردشة على مستوى الصنف.
@@ -370,37 +371,7 @@ Routes:
 4. يخزّن الموجّه قراره في `state.last_intent` (يكون مرئياً لسياق التوجيه في الجولة التالية).
 5. إذا أعاد معالجك سلسلة نصية ولم يستدعِ `append_assistant_message`، فإن `handle_turn` يُلحقها نيابةً عنك.
 
-استدعِ `handle_turn()` لرسائل الدردشة. استدعاء `kickoff(inputs={"id": ...})` مباشرةً يشغل الرسم بدون غلاف الجولة المحادثية.
-
-### `chat()` للـ REPL المحلي
-
-`flow.chat()` هو غلاف الطرفية الجاهز فوق `handle_turn()`:
-
-```python
-flow = SupportFlow()
-flow.chat()
-```
-
-يتولى الحلقة المحلية الشائعة:
-
-1. يطلب رسالة من المستخدم.
-2. يتوقف عند `exit` / `quit` أو `EOFError` أو `KeyboardInterrupt`.
-3. يستدعي `handle_turn(message, session_id=...)`.
-4. يطبع نتيجة المساعد.
-5. ينهي traces الجلسة المؤجلة داخل كتلة `finally`.
-
-خصص سلوك الطرفية عبر I/O قابل للحقن:
-
-```python
-flow.chat(
-    session_id="demo-session",
-    prompt="You: ",
-    assistant_prefix="Assistant: ",
-    exit_commands=("exit", "quit", "bye"),
-)
-```
-
-لتطبيقات الويب والـ workers الخلفية والاختبارات ووسائط النقل المخصصة، استمر في استخدام `handle_turn()` مباشرةً.
+يمكنك أيضاً استدعاء `flow.kickoff(user_message=..., session_id=...)` مباشرةً — نفس منطق الإعادة والتشغيل يعمل. `handle_turn` هو الغلاف المريح.
 
 ### سلوك موجّه مخصص
 
@@ -436,10 +407,17 @@ class SupportFlow(Flow[ConversationState]):
 - **العمل المتداخل** (`Agent.kickoff()`, crews, Exa) يُلحق بدفعة **الأب**؛ flow داخلي من `AgentExecutor` لا يغلق دفعة الجلسة مبكراً.
 
 ```python
-flow.chat(session_id=session_id)
+try:
+    while True:
+        line = input("You: ").strip()
+        if not line:
+            break
+        flow.kickoff(user_message=line, session_id=session_id)
+finally:
+    flow.finalize_session_traces()
 ```
 
-`flow.chat()` يستدعي `finalize_session_traces()` نيابةً عنك. عندما تملك الحلقة عبر `handle_turn()` أو `kickoff(...)`، استدعِ `finalize_session_traces()` عند انتهاء الجلسة.
+`ChatSession.close()` يستدعي `finalize_session_traces()` عند التأجيل.
 
 `suppress_flow_events=True` يخفي لوحات Rich فقط؛ أحداث trace والـ methods تُصدر.
 

docs/en/changelog.mdx

@@ -4,178 +4,6 @@ description: "Product updates, improvements, and bug fixes for CrewAI"
 icon: "clock"
 mode: "wide"
 ---
-<Update label="Jun 11, 2026">
-  ## v1.14.7
-
-  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7)
-
-  ## What's Changed
-
-  ### Features
-  - Add pluggable default backends for memory, knowledge, rag, and flow.
-  - Surface real finish_reason, sampling params, and response.id on LLM events.
-  - Type DSL triggers as route-aware decorators.
-  - Add chat API for conversational flows.
-  - Make locking backend overridable.
-  - Build FlowDefinition from Flow DSL metadata.
-  - Add native Snowflake Cortex LLM provider.
-  - Add crew trained agents file support.
-
-  ### Bug Fixes
-  - Fix checkpoint to rebuild custom BaseLLM as concrete LLM on restore.
-  - Gate restore on a flag to prevent live snapshots from replaying as resume.
-  - Scope runtime state per run to bound growth and isolate concurrent runs.
-  - Fix telemetry setup on crewai-login.
-  - Respect suppress_flow_events for method-execution events.
-  - Restore [project.scripts] in crewai package for uv tool install.
-  - Resolve pip-audit CVEs for aiohttp, docling, and docling-core.
-  - Fix file input not working reliably.
-  - Fix Snowflake Claude incomplete tool result histories.
-
-  ### Documentation
-  - Update changelog and version for v1.14.7.
-  - Update OpenTelemetry collector documentation.
-  - Update NVIDIA Nemotron LLM guide.
-  - Add Databricks integration guide.
-  - Add Snowflake integration guide.
-
-  ### Performance
-  - Improve crewai import speed by lazy-loading docling imports.
-
-  ### Refactoring
-  - Simplify flow condition evaluation to be stateless per event.
-  - Decouple convo logic from runtime and add a conversational_definition.
-  - Split `flow.py` into DSL, definition, and runtime.
-
-  ## Contributors
-
-  @Luzk, @alex-clawd, @devin-ai-integration[bot], @greysonlalonde, @gvieira, @jessemiller, @lorenzejay, @lucasgomide, @mattatcha, @vinibrsl
-
-</Update>
-
-<Update label="Jun 10, 2026">
-  ## v1.14.7rc2
-
-  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7rc2)
-
-  ## What's Changed
-
-  ### Bug Fixes
-  - Gate restore on a flag to prevent live snapshots from replaying as resume
-
-  ### Documentation
-  - Update changelog and version for v1.14.7rc1
-
-  ## Contributors
-
-  @greysonlalonde
-
-</Update>
-
-<Update label="Jun 10, 2026">
-  ## v1.14.7rc1
-
-  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7rc1)
-
-  ## What's Changed
-
-  ### Features
-  - Add `reset_runtime_state` to release accumulated bus state
-  - Handle supporting both custom prompts
-  - Decouple conversation logic from runtime and add a `conversational_definition`
-
-  ### Bug Fixes
-  - Fix scope of runtime state per run to bound growth and isolate concurrent runs
-  - Fix telemetry setup on `crewai-login`
-  - Fix respect for `suppress_flow_events` for method-execution events
-
-  ### Documentation
-  - Update OpenTelemetry images
-  - Update documentation to reflect new state of OpenTelemetry collector
-  - Update changelog and version for v1.14.7a4
-
-  ### Refactoring
-  - Simplify flow condition evaluation to be stateless per event
-  - Improve conversation routing cycle with one less route
-
-  ## Contributors
-
-  @greysonlalonde, @lorenzejay, @lucasgomide, @vinibrsl
-
-</Update>
-
-<Update label="Jun 09, 2026">
-  ## v1.14.7a4
-
-  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7a4)
-
-  ## What's Changed
-
-  ### Features
-  - Migrate @listen/@router runtime to read from FlowDefinition
-  - Add pluggable default backends for memory, knowledge, rag, and flow
-
-  ### Documentation
-  - Update changelog and version for v1.14.7a3
-
-  ## Contributors
-
-  @greysonlalonde, @mattatcha, @vinibrsl
-
-</Update>
-
-<Update label="Jun 08, 2026">
-  ## v1.14.7a3
-
-  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7a3)
-
-  ## What's Changed
-
-  ### Bug Fixes
-  - Fix exposure of `ask_for_human_input` on experimental `AgentExecutor`
-  - Resolve pip-audit CVEs for `aiohttp`, `docling`, `docling-core`, and `pip`
-
-  ### Refactoring
-  - Migrate `@start` to read from `FlowDefinition`
-
-  ### Documentation
-  - Update changelog and version for v1.14.7a2
-
-  ## Contributors
-
-  @greysonlalonde, @lorenzejay, @vinibrsl
-
-</Update>
-
-<Update label="Jun 05, 2026">
-  ## v1.14.7a2
-
-  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7a2)
-
-  ## What's Changed
-
-  ### Features
-  - Add conversational flow traces support.
-  - Update conversational flow documentation to utilize `handle_turn`.
-  - Surface real `finish_reason`, sampling parameters, and `response.id` in LLM events.
-  - Type DSL triggers as route-aware decorators.
-  - Implement chat API for conversational flows.
-  - Make locking backend overridable in lock store.
-  - Split flow DSL monolith into focused decorator modules.
-  - Flatten LiteLLM cache/reasoning usage sub-counts in `_usage_to_dict`.
-  - Build `FlowDefinition` from Flow DSL metadata.
-
-  ### Documentation
-  - Add NVIDIA Nemotron LLM guide.
-  - Document monorepo deployments.
-  - Update changelog and version for v1.14.7a1.
-
-  ## Contributors
-
-  @alex-clawd, @gvieira, @lorenzejay, @lucasgomide, @mattatcha, @vinibrsl
-
-</Update>
-
 <Update label="Jun 03, 2026">
   ## v1.14.7a1
 

docs/en/concepts/flows.mdx

@@ -226,49 +226,6 @@ After the Flow has run, you can access the final state to see the updates made b
 By ensuring that the final method's output is returned and providing access to the state, CrewAI Flows make it easy to integrate the results of your AI workflows into larger applications or systems,
 while also maintaining and accessing the state throughout the Flow's execution.
 
-## Flow Usage Metrics
-
-After a Flow execution completes, you can access the `usage_metrics` property to view aggregated token usage across **every LLM call** made during the run — including calls from every Crew the Flow orchestrated, calls inside Agent tools, and bare `LLM.call(...)` invocations from Flow methods. This is the SDK-side equivalent of the totals shown in the CrewAI Enterprise UI.
-
-```python Code
-from crewai import LLM
-from crewai.flow.flow import Flow, listen, start
-
-class UsageMetricsFlow(Flow):
-    @start()
-    def run_first_crew(self):
-        self.state.first_result = FirstCrew().crew().kickoff()
-
-    @listen(run_first_crew)
-    def call_llm_directly(self):
-        # Bare LLM call — still counted by flow.usage_metrics
-        llm = LLM(model="openai/gpt-4o-mini")
-        self.state.summary = llm.call("Summarize the key takeaways.")
-
-    @listen(call_llm_directly)
-    def run_second_crew(self):
-        self.state.second_result = SecondCrew().crew().kickoff()
-
-flow = UsageMetricsFlow()
-flow.kickoff()
-
-print(flow.usage_metrics)
-# UsageMetrics(total_tokens=8579, prompt_tokens=6210, completion_tokens=2369,
-#              cached_prompt_tokens=0, reasoning_tokens=0,
-#              cache_creation_tokens=0, successful_requests=5)
-```
-
-<Note>
-  `flow.usage_metrics` is **not** the same as `flow.kickoff().token_usage`. The
-  latter returns the `CrewOutput.token_usage` of the **last** `@listen` method
-  that returned a `CrewOutput`, which means it only reflects the final Crew and
-  ignores prior Crews and bare `LLM.call(...)` invocations entirely. Use
-  `flow.usage_metrics` whenever you need the **full** token rollup for the Flow
-  execution.
-</Note>
-
-Each entry in the returned [`UsageMetrics`](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/types/usage_metrics.py) is the sum across all LLM calls made within a single `flow.kickoff()` invocation. Counters reset on the next `kickoff()` call (or on each iteration of `kickoff_for_each`), so successive runs don't double-count. The property is safe to read at any point after `kickoff()` completes; reading it during execution returns the partial total accumulated so far.
-
 ## Flow State Management
 
 Managing state effectively is crucial for building reliable and maintainable AI workflows. CrewAI Flows provides robust mechanisms for both unstructured and structured state management,

docs/en/enterprise/guides/capture_telemetry_logs.mdx

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

docs/en/guides/advanced/customizing-prompts.mdx

@@ -161,18 +161,6 @@ crew = Crew(
 )
 ```
 
-<Note>
-`agent.i18n` is maintained only for backward compatibility and is deprecated. For runtime prompt customization, pass `prompt_file` to `Crew`. For programmatic access to prompt slices, use the i18n utility directly:
-</Note>
-
-```python
-from crewai.utilities.i18n import get_i18n
-
-i18n = get_i18n("custom_prompts.json")
-format_slice = i18n.slice("format")
-tool_prompt = i18n.tools("ask_question")
-```
-
 #### Option 3: Disable System Prompts for o1 Models
 ```python
 agent = Agent(
@@ -220,8 +208,6 @@ One straightforward approach is to create a JSON file for the prompts you want t
 
 CrewAI then merges your customizations with the defaults, so you don't have to redefine every prompt. Here's how:
 
-For code that needs to read prompt slices directly, use `crewai.utilities.i18n.get_i18n()` with the same prompt file instead of reading `agent.i18n`.
-
 ### Example: Basic Prompt Customization
 
 Create a `custom_prompts.json` file with the prompts you want to modify. Ensure you list all top-level prompts it should contain, not just your changes:

docs/en/guides/concepts/evaluating-use-cases.mdx

@@ -172,7 +172,7 @@ Flows are ideal when:
 
 ```python
 # Example: Customer Support Flow with structured processing
-from crewai.flow.flow import Flow, listen, or_, router, start
+from crewai.flow.flow import Flow, listen, router, start
 from pydantic import BaseModel
 from typing import List, Dict
 
@@ -238,7 +238,7 @@ class CustomerSupportFlow(Flow[SupportTicketState]):
 
     # Additional category handlers...
 
-    @listen(or_("billing", "account_access", "technical_issue", "feature_request", "other"))
+    @listen("billing", "account_access", "technical_issue", "feature_request", "other")
     def resolve_ticket(self, resolution_info):
         # Final resolution step
         self.state.resolution = f"Issue resolved: {resolution_info}"

docs/en/guides/flows/conversational-flows.mdx

@@ -1,121 +1,130 @@
 ---
 title: Conversational Flows
-description: Build multi-turn chat apps with handle_turn per turn, message history, intent routing, tracing, and WebSocket bridges.
+description: Build multi-turn chat apps with kickoff per turn, message history, intent routing, tracing, and WebSocket bridges.
 icon: comments
 mode: "wide"
 ---
 
 ## Overview
 
-Conversational apps treat each user line as a **new flow run** with the **same session id**. CrewAI adds helpers for message history, optional intent routing, deferred tracing, UI bridges, and a local `flow.chat()` REPL for conversational flows.
+Conversational apps treat each user line as a **new flow run** with the **same session id**. CrewAI adds helpers for message history, optional intent classification, deferred tracing, and UI bridges — without a separate `chat()` API on `Flow`.
 
 | Concept | Implementation |
 |---------|----------------|
-| Session id | `handle_turn(..., session_id=...)` → `kickoff(inputs={"id": ...})` → `state.id` |
-| User line | `handle_turn(message)` appends to `state.messages` before the graph runs |
-| Turn complete | `FlowFinished` for **this run** only; chat continues on the next `handle_turn` |
-| Full-session trace | `ConversationConfig(defer_trace_finalization=True)` + `finalize_session_traces()` |
+| Session id | `kickoff(session_id=...)` → `inputs["id"]` → `state.id` |
+| User line | `kickoff(user_message=...)` appends to `state.messages` before the graph runs |
+| Turn complete | `FlowFinished` for **this run** only; chat continues on the next `kickoff` |
+| Full-session trace | `ConversationalConfig(defer_trace_finalization=True)` + `finalize_session_traces()` |
 
-## Turn APIs
+## One entry point: `kickoff`
 
-Use **`flow.handle_turn(message, session_id=...)`** for every user message from REST, WebSocket, tests, and custom UIs. Use **`flow.chat()`** when you want a local terminal chat loop for a conversational `Flow`.
-
-`Flow.kickoff()` does **not** accept `user_message=` or `session_id=` keyword arguments. For conversational flows, `handle_turn()` stores the pending message and calls `kickoff(inputs={"id": session_id})` internally after resetting per-turn execution state.
+Use **`flow.kickoff(user_message=..., session_id=...)`** for every user message (REST, WebSocket, CLI). Do not add a custom `chat()` wrapper on `Flow`.
 
 | API | Use for |
 |-----|---------|
-| `handle_turn(message, session_id=...)` | Ergonomic one-turn wrapper for conversational `Flow` |
-| `chat()` | Local terminal REPL for conversational `Flow` |
-| `kickoff(inputs={...})` | Advanced flow execution without conversational turn handling |
+| `kickoff(user_message=..., session_id=...)` | Each user message |
+| `kickoff_async(...)` | Same parameters; native async entry |
 | `ask()` | Blocking prompt **inside** one step (wizard, clarification) |
 | `@human_feedback` | Approve/reject **a step output** — not the next chat line |
-| `ChatSession.handle_turn(...)` | Transport layer over `handle_turn` (SSE / WebSocket) |
+| `ChatSession.handle_turn(...)` | Transport layer over `kickoff` (SSE / WebSocket) |
 
 ## Quick start
 
 ```python
 from uuid import uuid4
 
-from crewai import Flow
-from crewai.flow import listen
-from crewai.experimental.conversational import (
-    ConversationConfig,
-    ConversationState,
+from crewai.flow import (
+    ChatState,
+    ConversationalConfig,
+    Flow,
+    listen,
+    or_,
+    persist,
+    router,
+    start,
 )
+from crewai.flow.persistence import SQLiteFlowPersistence
 
 
-@ConversationConfig(defer_trace_finalization=True)
-class SupportFlow(Flow[ConversationState]):
-    conversational = True
+class SupportFlow(Flow[ChatState]):
+    conversational_config = ConversationalConfig(
+        default_intents=["order", "help", "goodbye"],
+        intent_llm="gpt-4o-mini",
+        defer_trace_finalization=True,
+    )
 
-    def route_turn(self, context):
-        message = (self.state.current_user_message or "").lower()
-        if "order" in message:
-            return "order"
-        if "bye" in message or "goodbye" in message:
-            return "goodbye"
-        return "help"
+    @start()
+    def bootstrap(self):
+        if not self.state.session_ready:
+            self.state.session_ready = True
+        return "ready"
+
+    @router(bootstrap)
+    def route(self):
+        # last_intent set in prepare_conversational_turn when default_intents is set
+        return self.state.last_intent or "help"
 
     @listen("order")
     def handle_order(self):
         reply = "Your order is on the way."
-        self.append_assistant_message(reply)
+        self.append_message("assistant", reply)
         return reply
 
     @listen("help")
     def handle_help(self):
         reply = "How can I help?"
-        self.append_assistant_message(reply)
+        self.append_message("assistant", reply)
         return reply
 
     @listen("goodbye")
     def handle_goodbye(self):
         reply = "Goodbye!"
-        self.append_assistant_message(reply)
+        self.append_message("assistant", reply)
         return reply
 
+    @persist(SQLiteFlowPersistence("support.db"))
+    @listen(or_(handle_order, handle_help, handle_goodbye))
+    def finalize(self):
+        return self.state.model_dump()
+
 
 session_id = str(uuid4())
 flow = SupportFlow()
 
-try:
-    flow.handle_turn("Where is my order?", session_id=session_id)
-    flow.handle_turn("What about returns?", session_id=session_id)
-finally:
-    flow.finalize_session_traces()  # one trace link for the whole chat
+flow.kickoff(user_message="Where is my order?", session_id=session_id)
+flow.kickoff(user_message="What about returns?", session_id=session_id)
+flow.finalize_session_traces()  # one trace link for the whole chat
 ```
 
 ## Turn lifecycle
 
-Each `handle_turn` runs this pipeline:
+Each `kickoff` with `user_message` runs this pipeline:
 
-1. **Turn setup** — stores the pending user message, resolves the session id, resets per-turn execution tracking, and calls `kickoff(inputs={"id": session_id})`.
+1. **`_configure_conversational_kickoff`** — merges `session_id` / `user_message` into `inputs`, applies `ConversationalConfig`, enables deferred tracing when configured.
 2. **State restore** — if `inputs["id"]` exists and `@persist` is configured, loads the latest snapshot.
 3. **`FlowStarted`** — emitted on the first deferred session turn only.
-4. **Pending turn hydration** — appends the user message to `state.messages`, sets `current_user_message` / `last_user_message`, and optionally classifies when `intents` / `default_intents` + `intent_llm` are set.
-5. **Graph execution** — `conversation_start` → `route_conversation` → the selected `@listen` handler.
+4. **`prepare_conversational_turn`** — appends the user message to `state.messages`, sets `last_user_message`, clears `last_intent`, optionally classifies when `intents` / `default_intents` + `intent_llm` are set.
+5. **Graph execution** — `@start` → `@router` → `@listen` handlers.
 6. **End of run** — per-turn `flow_finished` and trace finalization are **skipped** when deferral is enabled; nested `Agent.kickoff()` / crews do not close the parent batch either.
 
-Handlers should call **`append_assistant_message(reply)`** so the next turn’s `conversation_messages` includes assistant text. The user line is already stored by `handle_turn` — do not append it again in handlers.
+Handlers should call **`append_message("assistant", reply)`** so the next turn’s `conversation_messages` includes assistant text. The user line is already stored at kickoff — do not append it again in handlers.
 
-## `ConversationConfig` (class-level defaults)
+## `ConversationalConfig` (class-level defaults)
 
-Decorate your conversational `Flow` subclass with `ConversationConfig`.
+Set on your `Flow` subclass as `conversational_config: ClassVar[ConversationalConfig | None]`.
 
 | Field | Default | Purpose |
 |-------|---------|---------|
-| `system_prompt` | Framework default | System message used by the built-in `converse_turn`. |
-| `llm` | `None` | Conversation LLM used by `converse_turn` and as router fallback. |
-| `router` | `None` | `RouterConfig` for LLM-driven routing. |
-| `intent_llm` | `None` | LLM for `intents=` / `default_intents` pre-classification. |
-| `default_intents` | `None` | Outcome labels for pre-classification. |
-| `defer_trace_finalization` | `True` | Keep one trace batch open across `handle_turn()` calls. |
+| `default_intents` | `None` | Outcome labels for automatic pre-kickoff classification |
+| `intent_llm` | `None` | Model for classification (required when intents are used) |
+| `interactive_prompt` | `"You: "` | Prompt for `kickoff(interactive=True)` |
+| `interactive_timeout` | `None` | Per-line timeout in interactive mode |
+| `exit_commands` | `exit`, `quit` | Words that end interactive mode |
+| `defer_trace_finalization` | `True` | Keep one trace batch open across turns |
 
-Override pre-classification per turn with `handle_turn(..., intents=..., intent_llm=...)`.
+Override per kickoff with `intents=` and `intent_llm=` keyword arguments.
 
-## Lower-level `ChatState` helpers
-
-`ChatState`, `ConversationalConfig`, and `crewai.flow.conversation` helpers are still importable for advanced orchestration, tests, or custom wrappers. They do not add `user_message=` or `session_id=` keyword arguments to `Flow.kickoff()`.
+## `ChatState` (recommended persisted shape)
 
 ```python
 from crewai.flow import ChatState
@@ -129,7 +138,7 @@ class MyChatState(ChatState):
 
 | Field | Role |
 |-------|------|
-| `id` | Session UUID (same as `inputs["id"]`) |
+| `id` | Session UUID (same as `session_id` / `inputs["id"]`) |
 | `messages` | `list` of `{role, content}` for LLM history |
 | `last_user_message` | Latest user line for this turn |
 | `last_intent` | Route label after classification (if used) |
@@ -139,26 +148,27 @@ class MyChatState(ChatState):
 
 ## `Flow` conversational API
 
-### `handle_turn` parameters
+### `kickoff` / `kickoff_async` parameters
 
 | Parameter | Purpose |
 |-----------|---------|
-| `message` | This turn’s text |
+| `user_message` | This turn’s text (or `{"role": "user", "content": "..."}`) |
 | `session_id` | Conversation UUID → `inputs["id"]` / `state.id` |
 | `intents` | Outcome labels for pre-kickoff `classify_intent` |
 | `intent_llm` | LLM for classification (required with `intents`) |
-| `**kickoff_kwargs` | Forwarded to `kickoff()` for options like `input_files`, `from_checkpoint`, and `restore_from_state_id` |
-
-### `kickoff` parameters
-
-`Flow.kickoff()` accepts `inputs`, `input_files`, `from_checkpoint`, and `restore_from_state_id`. Pass `inputs={"id": session_id}` when you need raw flow execution, but use `handle_turn()` when the call represents a chat message.
+| `interactive` | CLI loop via `ask()` (local demos only) |
+| `interactive_prompt` | Override prompt in interactive mode |
+| `interactive_timeout` | Per-line `ask()` timeout |
+| `exit_commands` | Words that end interactive mode |
+| `inputs` | Additional state fields (merged with conversational keys) |
+| `restore_from_state_id` | Fork hydration from another persisted flow |
 
 ### Instance attributes
 
 | Attribute | Purpose |
 |-----------|---------|
-| `conversational` | Set to `True` to enable the conversational graph and `handle_turn()` |
-| `defer_trace_finalization` | Instance flag; set automatically from config on `handle_turn()` |
+| `conversational_config` | Class-level `ConversationalConfig` defaults |
+| `defer_trace_finalization` | Instance flag; set automatically from config on kickoff |
 | `suppress_flow_events` | Hides console flow panels; **tracing still records** method/flow events |
 | `stream` | Enable streaming; use with `ChatSession.handle_turn(..., stream=True)` |
 
@@ -166,8 +176,7 @@ class MyChatState(ChatState):
 
 | Name | Description |
 |------|-------------|
-| `append_assistant_message(content)` | Append a user-visible assistant reply to `state.messages` |
-| `append_message(role, content, **extra)` | Lower-level append to `state.messages` |
+| `append_message(role, content, **extra)` | Append to `state.messages` (roles: `user`, `assistant`, `system`, `tool`) |
 | `conversation_messages` | Read-only history for LLM calls |
 | `classify_intent(text, outcomes, *, llm, context=None)` | Map text to one outcome (same collapse logic as `@human_feedback`) |
 | `receive_user_message(text, *, outcomes=None, llm=None)` | Append user message; optionally set `last_intent` |
@@ -184,7 +193,7 @@ Importable for tests or custom orchestration:
 | `normalize_kickoff_inputs(inputs, user_message=..., session_id=...)` | Merge conversational kwargs into `inputs` |
 | `get_conversation_messages(flow)` | Read messages from state or internal buffer |
 | `append_message(flow, role, content, **extra)` | Same as instance method |
-| `prepare_conversational_turn(flow, user_message=..., intents=..., intent_llm=..., config=...)` | Lower-level turn hydration for custom wrappers |
+| `prepare_conversational_turn(flow, user_message=..., intents=..., intent_llm=..., config=...)` | Turn hydration (usually called by kickoff) |
 | `receive_user_message(flow, text, ...)` | Same as instance method |
 | `set_state_field(flow, name, value)` | Set a field on dict or Pydantic state |
 | `get_conversational_config(flow)` | Read class `conversational_config` |
@@ -192,20 +201,21 @@ Importable for tests or custom orchestration:
 
 ## Intent routing patterns
 
-### A. Pre-classify via `ConversationConfig` (simplest)
+### A. Pre-classify via `ConversationalConfig` (simplest)
 
-Set `default_intents` and `intent_llm`. Each `handle_turn()` runs classification before routing; read `self.state.last_intent` in `route_turn()`.
+Set `default_intents` and `intent_llm`. Each kickoff runs classification before your `@router`; read `self.state.last_intent` in `route()`.
 
-### B. Classify inside `route_turn` (richer prompts)
+### B. Classify inside `@router` (richer prompts)
 
-Set `default_intents=None` so `handle_turn()` only appends the user message. In `route_turn()`, call `classify_intent` with a custom prompt or descriptions:
+Set `default_intents=None` so kickoff only appends the user message. In `route()`, call `classify_intent` with a custom prompt or descriptions:
 
 ```python
-def route_turn(self, context):
+@router(bootstrap)
+def route(self):
     intent = self.classify_intent(
-        self._routing_prompt(self.state.current_user_message),
+        self._routing_prompt(self.state.last_user_message),
         ("GREETING", "ORDER", "RESEARCH", "GOODBYE"),
-        llm="gpt-4o-mini",
+        llm=self.conversational_config.intent_llm or "gpt-4o-mini",
     )
     self.state.last_intent = intent
     return intent
@@ -215,7 +225,7 @@ Use **`@listen("RESEARCH")`** (or similar) for steps that run `Agent.kickoff()`
 
 ## When the flow finishes but the user keeps chatting
 
-`FlowFinished` means **this graph run** completed. The conversation continues with another `handle_turn()` and the same `session_id`. `@persist` restores `messages`, flags, and context.
+`FlowFinished` means **this graph run** completed. The conversation continues with another `kickoff` and the same `session_id`. `@persist` restores `messages`, flags, and context.
 
 **Persist pattern:** prefer `@persist` on a **single terminal step** (for example `finalize`) rather than on the whole `Flow` class. Class-level persist saves after every method; `load_state` uses the latest row, which may be a mid-run snapshot (for example right after `bootstrap`) and miss handler updates from the same turn.
 
@@ -232,66 +242,57 @@ Do **not** use `@human_feedback` for follow-up chat lines unless a human must ap
   changelog for breaking updates. Open issues / feedback welcome.
 </Warning>
 
-Opt into the conversational chat graph by setting `conversational = True` on a `Flow` subclass. The base `Flow` then ships a built-in `@start` / `@router` / `converse_turn` / `end_conversation` graph, manages `state.messages`, can drive a router LLM, and keeps the trace batch open across turns. You write the **custom routes**; the framework owns the rest.
+Opt into the conversational chat graph by setting `conversational = True` on a `Flow` subclass. The base `Flow` then ships a built-in `@start` / `@router` / `converse_turn` / `end_conversation` graph, manages `state.messages`, drives the router LLM, and keeps the trace batch open across turns. You write the **custom routes**; the framework owns the rest.
 
-Use this when you want a multi-turn chat with a router and per-route handlers without wiring the lifecycle yourself. Use `Flow[ChatState]` (the lower-level pattern above) when you need full control.
+Use this when you want a multi-turn chat with an LLM-driven router and per-route handlers without wiring the lifecycle yourself. Use `Flow[ChatState]` (the lower-level pattern above) when you need full control.
 
 ### Quick example
 
 ```python
-from crewai import Flow
+from crewai import LLM, Flow
 from crewai.flow import listen
 from crewai.experimental.conversational import (
     ConversationConfig,
     ConversationState,
+    RouterConfig,
 )
 
 
-@ConversationConfig(defer_trace_finalization=True)
+ROUTER_LLM = LLM(model="gpt-4o-mini")
+
+
+@ConversationConfig(
+    system_prompt="A multi-agent assistant for ordinary chat and tool-backed tasks.",
+    llm=ROUTER_LLM,
+    router=RouterConfig(),  # routes + descriptions auto-discovered from @listen handlers
+)
 class SupportFlow(Flow[ConversationState]):
     conversational = True
 
-    def route_turn(self, context: dict) -> str | None:
-        message = (self.state.current_user_message or "").lower()
-        if "search" in message or "news" in message:
-            return "INTERNET_SEARCH"
-        if "docs" in message or "crewai" in message:
-            return "CREWAI_DOCS"
-        return "converse"
-
     @listen("INTERNET_SEARCH")
     def handle_internet_search(self) -> str:
         """Fresh web research, current news, real-time lookups."""
-        reply = "I would run the web research route here."
+        ...
         self.append_assistant_message(reply)
         return reply
 
     @listen("CREWAI_DOCS")
     def handle_crewai_docs(self) -> str:
         """Look up the CrewAI documentation for framework/API questions."""
-        reply = "I would look up the CrewAI docs here."
+        ...
         self.append_assistant_message(reply)
         return reply
 
 
 flow = SupportFlow()
 try:
-    flow.handle_turn("What can you do?")              # routes to converse
+    flow.handle_turn("What can you do?")              # routes to converse (built-in)
     flow.handle_turn("Search the web for AI news.")   # routes to INTERNET_SEARCH
-    flow.handle_turn("Check the CrewAI docs.")         # routes to CREWAI_DOCS
+    flow.handle_turn("Summarize the first result.")   # routes back to converse
 finally:
     flow.finalize_session_traces()
 ```
 
-For a local terminal chat, use `chat()`:
-
-```python
-def kickoff() -> None:
-    SupportFlow().chat()
-```
-
-`chat()` wraps `handle_turn()` in a REPL, exits on `exit` / `quit`, skips blank lines by default, and calls `finalize_session_traces()` when the session ends.
-
 ### `ConversationConfig`
 
 Class decorator that attaches per-class chat defaults.
@@ -311,21 +312,7 @@ Class decorator that attaches per-class chat defaults.
 ### `RouterConfig` and the auto-built route catalog
 
 ```python
-from typing import Literal
-
-from pydantic import BaseModel
-
-from crewai import LLM
-from crewai.experimental.conversational import RouterConfig
-
-
-class MyRoute(BaseModel):
-    intent: Literal["INTERNET_SEARCH", "CREWAI_DOCS", "converse"]
-
-
-ROUTER_LLM = LLM(model="gpt-4o-mini")
-
-router_config = RouterConfig(
+RouterConfig(
     prompt="Optional domain framing (policy, voice, persona).",
     response_format=MyRoute,        # optional; auto-generated otherwise
     llm=ROUTER_LLM,                  # falls back to ConversationConfig.llm
@@ -349,9 +336,6 @@ The router prompt that gets sent to the LLM is built automatically. For each rou
 So in practice, **adding a new route is `@listen("X")` + a one-line docstring**:
 
 ```python
-from crewai.flow import listen
-
-
 @listen("INTERNET_SEARCH")
 def handle_internet_search(self) -> str:
     """Fresh web research, current news, real-time lookups."""
@@ -390,49 +374,13 @@ You can override any of these by defining a same-named handler in your subclass.
 4. The router stores its decision in `state.last_intent` (visible to the next turn's router context).
 5. If your handler returned a string and didn't already call `append_assistant_message`, `handle_turn` appends it for you.
 
-Call `handle_turn()` for chat messages. Calling `kickoff(inputs={"id": ...})` directly runs the flow graph without applying the conversational turn wrapper.
-
-### `chat()` for local REPLs
-
-`flow.chat()` is the batteries-included terminal wrapper around `handle_turn()`:
-
-```python
-flow = SupportFlow()
-flow.chat()
-```
-
-It handles the common local loop:
-
-1. Prompts for a user message.
-2. Stops on `exit` / `quit`, `EOFError`, or `KeyboardInterrupt`.
-3. Calls `handle_turn(message, session_id=...)`.
-4. Prints the assistant result.
-5. Finalizes deferred session traces in a `finally` block.
-
-Customize the terminal behavior with injectable I/O:
-
-```python
-flow.chat(
-    session_id="demo-session",
-    prompt="You: ",
-    assistant_prefix="Assistant: ",
-    exit_commands=("exit", "quit", "bye"),
-)
-```
-
-For web apps, background workers, tests, and custom transports, keep using `handle_turn()` directly.
+You can also call `flow.kickoff(user_message=..., session_id=...)` directly — the same reset/run logic fires. `handle_turn` is the ergonomic wrapper.
 
 ### Custom router behavior
 
 To run side effects (event bus setup, telemetry) on every routing decision, override `route_turn`:
 
 ```python
-from typing import Any
-
-from crewai import Flow
-from crewai.experimental.conversational import ConversationState
-
-
 class SupportFlow(Flow[ConversationState]):
     conversational = True
 
@@ -454,7 +402,7 @@ Inside a `@listen(label)` handler, choose:
 
 ## Tracing across turns
 
-With `defer_trace_finalization=True` (default in `ConversationConfig`):
+With `defer_trace_finalization=True` (default in `ConversationalConfig`):
 
 - **One trace batch** for the whole chat session.
 - **`flow_started`** on the first turn only; **`flow_finished`** once in `finalize_session_traces()`.
@@ -462,12 +410,17 @@ With `defer_trace_finalization=True` (default in `ConversationConfig`):
 - **Nested work** (`Agent.kickoff()`, crews, Exa tools) appends to the **parent** batch; inner `AgentExecutor` flows do not close the session batch early.
 
 ```python
-flow.chat(session_id=session_id)
+try:
+    while True:
+        line = input("You: ").strip()
+        if not line:
+            break
+        flow.kickoff(user_message=line, session_id=session_id)
+finally:
+    flow.finalize_session_traces()
 ```
 
-`flow.chat()` calls `finalize_session_traces()` for you. When you own the loop
-with `handle_turn()`, call `finalize_session_traces()` when
-the session ends.
+`ChatSession.close()` calls `finalize_session_traces()` when deferral is enabled.
 
 `suppress_flow_events=True` only hides Rich console panels; trace and method events still emit for observability.
 

docs/ko/changelog.mdx

@@ -4,178 +4,6 @@ description: "CrewAI의 제품 업데이트, 개선 사항 및 버그 수정"
 icon: "clock"
 mode: "wide"
 ---
-<Update label="2026년 6월 11일">
-  ## v1.14.7
-
-  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7)
-
-  ## 변경 사항
-
-  ### 기능
-  - 메모리, 지식, RAG 및 흐름에 대한 플러그 가능한 기본 백엔드를 추가했습니다.
-  - LLM 이벤트에서 실제 finish_reason, 샘플링 매개변수 및 response.id를 표시합니다.
-  - 경로 인식 장식자로서의 타입 DSL 트리거를 설정합니다.
-  - 대화 흐름을 위한 채팅 API를 추가했습니다.
-  - 잠금 백엔드를 재정의 가능하도록 만듭니다.
-  - Flow DSL 메타데이터에서 FlowDefinition을 빌드합니다.
-  - 네이티브 Snowflake Cortex LLM 공급자를 추가했습니다.
-  - 훈련된 에이전트 파일 지원을 추가했습니다.
-
-  ### 버그 수정
-  - 복원 시 사용자 정의 BaseLLM을 구체적인 LLM으로 재구성하도록 체크포인트를 수정했습니다.
-  - 라이브 스냅샷이 재개로 재생되지 않도록 플래그를 사용하여 복원을 제한합니다.
-  - 실행마다 런타임 상태의 범위를 설정하여 성장을 제한하고 동시 실행을 격리합니다.
-  - crewai-login에서 텔레메트리 설정을 수정했습니다.
-  - 메서드 실행 이벤트에 대해 suppress_flow_events를 존중합니다.
-  - uv 도구 설치를 위해 crewai 패키지에서 [project.scripts]를 복원합니다.
-  - aiohttp, docling 및 docling-core에 대한 pip-audit CVE를 해결합니다.
-  - 파일 입력이 신뢰할 수 없게 작동하는 문제를 수정했습니다.
-  - Snowflake Claude의 불완전한 도구 결과 기록을 수정했습니다.
-
-  ### 문서
-  - v1.14.7에 대한 변경 로그 및 버전을 업데이트했습니다.
-  - OpenTelemetry 수집기 문서를 업데이트했습니다.
-  - NVIDIA Nemotron LLM 가이드를 업데이트했습니다.
-  - Databricks 통합 가이드를 추가했습니다.
-  - Snowflake 통합 가이드를 추가했습니다.
-
-  ### 성능
-  - docling 가져오기를 지연 로딩하여 crewai 가져오기 속도를 개선했습니다.
-
-  ### 리팩토링
-  - 흐름 조건 평가를 이벤트별로 상태 비저장으로 단순화했습니다.
-  - 대화 논리를 런타임에서 분리하고 conversational_definition을 추가했습니다.
-  - `flow.py`를 DSL, 정의 및 런타임으로 분리했습니다.
-
-  ## 기여자
-
-  @Luzk, @alex-clawd, @devin-ai-integration[bot], @greysonlalonde, @gvieira, @jessemiller, @lorenzejay, @lucasgomide, @mattatcha, @vinibrsl
-
-</Update>
-
-<Update label="2026년 6월 10일">
-  ## v1.14.7rc2
-
-  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7rc2)
-
-  ## 변경 사항
-
-  ### 버그 수정
-  - 라이브 스냅샷이 재개로 재생되는 것을 방지하기 위한 플래그에서 게이트 복원
-
-  ### 문서
-  - v1.14.7rc1에 대한 변경 로그 및 버전 업데이트
-
-  ## 기여자
-
-  @greysonlalonde
-
-</Update>
-
-<Update label="2026년 6월 10일">
-  ## v1.14.7rc1
-
-  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7rc1)
-
-  ## 변경 사항
-
-  ### 기능
-  - 누적된 버스 상태를 해제하기 위해 `reset_runtime_state` 추가
-  - 사용자 정의 프롬프트를 모두 지원하도록 처리
-  - 대화 논리를 런타임과 분리하고 `conversational_definition` 추가
-
-  ### 버그 수정
-  - 실행당 런타임 상태의 범위를 수정하여 성장 제한 및 동시 실행 격리
-  - `crewai-login`에서 원격 측정 설정 수정
-  - 메서드 실행 이벤트에 대한 `suppress_flow_events` 존중 수정
-
-  ### 문서
-  - OpenTelemetry 이미지 업데이트
-  - OpenTelemetry 수집기의 새로운 상태를 반영하도록 문서 업데이트
-  - v1.14.7a4에 대한 변경 로그 및 버전 업데이트
-
-  ### 리팩토링
-  - 이벤트당 상태 비저장 방식으로 흐름 조건 평가 단순화
-  - 경로를 하나 줄여 대화 라우팅 사이클 개선
-
-  ## 기여자
-
-  @greysonlalonde, @lorenzejay, @lucasgomide, @vinibrsl
-
-</Update>
-
-<Update label="2026년 6월 9일">
-  ## v1.14.7a4
-
-  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7a4)
-
-  ## 변경 사항
-
-  ### 기능
-  - @listen/@router 런타임을 FlowDefinition에서 읽도록 마이그레이션
-  - 메모리, 지식, rag 및 flow에 대한 플러그형 기본 백엔드 추가
-
-  ### 문서
-  - v1.14.7a3에 대한 변경 로그 및 버전 업데이트
-
-  ## 기여자
-
-  @greysonlalonde, @mattatcha, @vinibrsl
-
-</Update>
-
-<Update label="2026년 6월 8일">
-  ## v1.14.7a3
-
-  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7a3)
-
-  ## 변경 사항
-
-  ### 버그 수정
-  - 실험적인 `AgentExecutor`에서 `ask_for_human_input` 노출 문제 수정
-  - `aiohttp`, `docling`, `docling-core`, 및 `pip`에 대한 pip-audit CVE 해결
-
-  ### 리팩토링
-  - `@start`를 `FlowDefinition`에서 읽도록 마이그레이션
-
-  ### 문서화
-  - v1.14.7a2에 대한 변경 로그 및 버전 업데이트
-
-  ## 기여자
-
-  @greysonlalonde, @lorenzejay, @vinibrsl
-
-</Update>
-
-<Update label="2026년 6월 5일">
-  ## v1.14.7a2
-
-  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7a2)
-
-  ## 변경 사항
-
-  ### 기능
-  - 대화 흐름 추적 지원 추가.
-  - `handle_turn`을 활용하도록 대화 흐름 문서 업데이트.
-  - LLM 이벤트에서 실제 `finish_reason`, 샘플링 매개변수 및 `response.id` 표시.
-  - 라우트 인식 데코레이터로서 DSL 트리거 유형 지정.
-  - 대화 흐름을 위한 채팅 API 구현.
-  - 잠금 저장소에서 백엔드 잠금 오버라이드 가능하게 설정.
-  - 흐름 DSL 모놀리스를 집중된 데코레이터 모듈로 분할.
-  - `_usage_to_dict`에서 LiteLLM 캐시/추론 사용 하위 카운트 평탄화.
-  - 흐름 DSL 메타데이터에서 `FlowDefinition` 구축.
-
-  ### 문서
-  - NVIDIA Nemotron LLM 가이드 추가.
-  - 모노레포 배포 문서화.
-  - v1.14.7a1에 대한 변경 로그 및 버전 업데이트.
-
-  ## 기여자
-
-  @alex-clawd, @gvieira, @lorenzejay, @lucasgomide, @mattatcha, @vinibrsl
-
-</Update>
-
 <Update label="2026년 6월 3일">
   ## v1.14.7a1
 

docs/ko/concepts/flows.mdx

@@ -221,48 +221,6 @@ Flow가 실행된 후, 이러한 메소드들에 의해 수행된 업데이트
 최종 메소드의 출력이 반환되고 상태에 접근할 수 있도록 함으로써, CrewAI Flow는 AI 워크플로우의 결과를 더 큰 애플리케이션이나 시스템에 쉽게 통합할 수 있게 하며,
 Flow 실행 과정 전반에 걸쳐 상태를 유지하고 접근하면서도 이를 용이하게 만듭니다.
 
-## 플로우 사용 메트릭
-
-Flow 실행이 완료된 후, `usage_metrics` 속성에 접근하여 실행 동안 발생한 **모든 LLM 호출**의 토큰 사용량 집계를 확인할 수 있습니다. 여기에는 Flow가 오케스트레이션한 모든 Crew의 호출, Agent의 도구 내부에서 발생한 호출, 그리고 Flow 메서드에서 직접 호출한 `LLM.call(...)`이 모두 포함됩니다. 이는 CrewAI Enterprise UI에 표시되는 총량과 동등한 SDK 측 값입니다.
-
-```python Code
-from crewai import LLM
-from crewai.flow.flow import Flow, listen, start
-
-class UsageMetricsFlow(Flow):
-    @start()
-    def run_first_crew(self):
-        self.state.first_result = FirstCrew().crew().kickoff()
-
-    @listen(run_first_crew)
-    def call_llm_directly(self):
-        # 직접 LLM 호출 — flow.usage_metrics에서도 집계됩니다
-        llm = LLM(model="openai/gpt-4o-mini")
-        self.state.summary = llm.call("핵심 내용을 요약해 주세요.")
-
-    @listen(call_llm_directly)
-    def run_second_crew(self):
-        self.state.second_result = SecondCrew().crew().kickoff()
-
-flow = UsageMetricsFlow()
-flow.kickoff()
-
-print(flow.usage_metrics)
-# UsageMetrics(total_tokens=8579, prompt_tokens=6210, completion_tokens=2369,
-#              cached_prompt_tokens=0, reasoning_tokens=0,
-#              cache_creation_tokens=0, successful_requests=5)
-```
-
-<Note>
-  `flow.usage_metrics`는 `flow.kickoff().token_usage`와 **동일하지 않습니다**.
-  후자는 `CrewOutput`을 반환한 **마지막** `@listen` 메서드의
-  `CrewOutput.token_usage`만 반환하므로, 이전에 실행된 Crew들과 Flow 메서드에서
-  직접 호출한 `LLM.call(...)`은 전혀 포함되지 않습니다. Flow 실행에 대한
-  **전체** 토큰 집계가 필요할 때는 항상 `flow.usage_metrics`를 사용하십시오.
-</Note>
-
-반환되는 [`UsageMetrics`](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/types/usage_metrics.py)의 각 항목은 단일 `flow.kickoff()` 실행 동안 발생한 모든 LLM 호출의 합계입니다. 다음 `kickoff()` 호출(및 `kickoff_for_each`의 각 반복)에서 카운터가 초기화되므로 연속 실행이 이중으로 집계되지 않습니다. 이 속성은 `kickoff()` 완료 후 언제든지 안전하게 읽을 수 있으며, 실행 중에 읽으면 그 시점까지 누적된 부분 합계를 반환합니다.
-
 ## 플로우 상태 관리
 
 상태를 효과적으로 관리하는 것은 신뢰할 수 있고 유지 보수가 용이한 AI 워크플로를 구축하는 데 매우 중요합니다. CrewAI 플로우는 비정형 및 정형 상태 관리를 위한 강력한 메커니즘을 제공하여, 개발자가 자신의 애플리케이션에 가장 적합한 접근 방식을 선택할 수 있도록 합니다.

docs/ko/enterprise/guides/capture_telemetry_logs.mdx

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

docs/ko/guides/advanced/customizing-prompts.mdx

@@ -161,18 +161,6 @@ crew = Crew(
 )
 ```
 
-<Note>
-`agent.i18n`은 이전 버전과의 호환성을 위해서만 유지되며 사용이 중단될 예정입니다. 런타임 프롬프트 커스터마이징에는 `Crew`에 `prompt_file`을 전달하세요. 프롬프트 슬라이스를 코드에서 직접 읽어야 한다면 i18n 유틸리티를 직접 사용하세요:
-</Note>
-
-```python
-from crewai.utilities.i18n import get_i18n
-
-i18n = get_i18n("custom_prompts.json")
-format_slice = i18n.slice("format")
-tool_prompt = i18n.tools("ask_question")
-```
-
 #### 옵션 3: o1 모델에 대한 시스템 프롬프트 비활성화
 ```python
 agent = Agent(
@@ -220,8 +208,6 @@ agent = Agent(
 
 그러면 CrewAI가 기본값과 사용자가 지정한 내용을 병합하므로, 모든 프롬프트를 다시 정의할 필요가 없습니다. 방법은 다음과 같습니다:
 
-프롬프트 슬라이스를 코드에서 직접 읽어야 하는 경우에는 `agent.i18n`을 읽는 대신 동일한 프롬프트 파일로 `crewai.utilities.i18n.get_i18n()`을 사용하세요.
-
 ### 예시: 기본 프롬프트 커스터마이징
 
 수정하고 싶은 프롬프트를 포함하는 `custom_prompts.json` 파일을 생성하세요. 변경 사항만이 아니라 포함해야 하는 모든 최상위 프롬프트를 반드시 나열해야 합니다:
@@ -328,4 +314,4 @@ CrewAI에서의 저수준 prompt 커스터마이제이션은 매우 맞춤화되
 
 <Check>
 이제 CrewAI에서 고급 prompt 커스터마이징을 위한 기초를 갖추었습니다. 모델별 구조나 도메인별 제약에 맞춰 적용하든, 이러한 저수준 접근 방식은 agent 상호작용을 매우 전문적으로 조정할 수 있게 해줍니다.
-</Check>
+</Check>

docs/ko/guides/flows/conversational-flows.mdx

@@ -7,87 +7,98 @@ mode: "wide"
 
 ## 개요
 
-대화형 앱은 각 사용자 입력을 **동일한 세션 id**로 **새 flow 실행**으로 처리합니다. CrewAI는 메시지 기록, 선택적 의도 분류, 지연 트레이싱, UI 브리지, 그리고 대화형 flow용 로컬 `flow.chat()` REPL을 제공합니다.
+대화형 앱은 각 사용자 입력을 **동일한 세션 id**로 **새 flow 실행**으로 처리합니다. CrewAI는 메시지 기록, 선택적 의도 분류, 지연 트레이싱, UI 브리지를 제공하며, `Flow`에 별도 `chat()` API는 없습니다.
 
 | 개념 | 구현 |
 |------|------|
-| 세션 id | `handle_turn(..., session_id=...)` → `kickoff(inputs={"id": ...})` → `state.id` |
-| 사용자 입력 | `handle_turn(message)`가 그래프 실행 전 `state.messages`에 추가 |
-| 턴 완료 | `FlowFinished`는 **이번 실행**만 의미; 다음 `handle_turn`로 대화 계속 |
-| 세션 전체 트레이스 | `ConversationConfig(defer_trace_finalization=True)` + `finalize_session_traces()` |
+| 세션 id | `kickoff(session_id=...)` → `inputs["id"]` → `state.id` |
+| 사용자 입력 | `kickoff(user_message=...)`가 그래프 실행 전 `state.messages`에 추가 |
+| 턴 완료 | `FlowFinished`는 **이번 실행**만 의미; 다음 `kickoff`로 대화 계속 |
+| 세션 전체 트레이스 | `ConversationalConfig(defer_trace_finalization=True)` + `finalize_session_traces()` |
 
-## 턴 API
+## 단일 진입점: `kickoff`
 
-REST, WebSocket, 테스트, 커스텀 UI에서 오는 모든 사용자 메시지에는 **`flow.handle_turn(message, session_id=...)`**를 사용하세요. 대화형 `Flow`를 로컬 터미널 채팅 루프로 실행하고 싶을 때는 **`flow.chat()`**을 사용하세요.
-
-`Flow.kickoff()`는 `user_message=` 또는 `session_id=` 키워드 인자를 받지 않습니다. 대화형 flow에서는 `handle_turn()`이 보류 중인 메시지를 저장하고 내부적으로 `kickoff(inputs={"id": session_id})`를 호출합니다.
+모든 사용자 메시지에 **`flow.kickoff(user_message=..., session_id=...)`**를 사용하세요 (REST, WebSocket, CLI). `Flow`에 커스텀 `chat()` 래퍼를 만들지 마세요.
 
 | API | 용도 |
 |-----|------|
-| `handle_turn(message, session_id=...)` | 대화형 `Flow`용 한 턴 편의 래퍼 |
-| `chat()` | 대화형 `Flow`용 로컬 터미널 REPL |
-| `kickoff(inputs={...})` | 대화형 턴 처리 없이 flow를 직접 실행 |
+| `kickoff(user_message=..., session_id=...)` | 각 사용자 메시지 |
+| `kickoff_async(...)` | 동일 파라미터; 네이티브 async 진입 |
 | `ask()` | 한 스텝 **내부** 블로킹 프롬프트 (마법사, 확인) |
 | `@human_feedback` | **스텝 출력** 승인/거부 — 다음 채팅 줄이 아님 |
-| `ChatSession.handle_turn(...)` | `handle_turn` 위의 전송 계층 (SSE / WebSocket) |
+| `ChatSession.handle_turn(...)` | `kickoff` 위의 전송 계층 (SSE / WebSocket) |
 
 ## 빠른 시작
 
 ```python
 from uuid import uuid4
 
-from crewai import Flow
-from crewai.flow import listen
-from crewai.experimental.conversational import (
-    ConversationConfig,
-    ConversationState,
+from crewai.flow import (
+    ChatState,
+    ConversationalConfig,
+    Flow,
+    listen,
+    or_,
+    persist,
+    router,
+    start,
 )
+from crewai.flow.persistence import SQLiteFlowPersistence
 
 
-@ConversationConfig(defer_trace_finalization=True)
-class SupportFlow(Flow[ConversationState]):
-    conversational = True
+class SupportFlow(Flow[ChatState]):
+    conversational_config = ConversationalConfig(
+        default_intents=["order", "help", "goodbye"],
+        intent_llm="gpt-4o-mini",
+        defer_trace_finalization=True,
+    )
 
-    def route_turn(self, context):
-        message = self.state.current_user_message or ""
-        if "주문" in message or "order" in message.lower():
-            return "order"
-        if "안녕" in message or "goodbye" in message.lower():
-            return "goodbye"
-        return "help"
+    @start()
+    def bootstrap(self):
+        if not self.state.session_ready:
+            self.state.session_ready = True
+        return "ready"
+
+    @router(bootstrap)
+    def route(self):
+        # default_intents 설정 시 prepare_conversational_turn에서 last_intent 설정
+        return self.state.last_intent or "help"
 
     @listen("order")
     def handle_order(self):
         reply = "주문이 배송 중입니다."
-        self.append_assistant_message(reply)
+        self.append_message("assistant", reply)
         return reply
 
     @listen("help")
     def handle_help(self):
         reply = "무엇을 도와드릴까요?"
-        self.append_assistant_message(reply)
+        self.append_message("assistant", reply)
         return reply
 
     @listen("goodbye")
     def handle_goodbye(self):
         reply = "안녕히 가세요!"
-        self.append_assistant_message(reply)
+        self.append_message("assistant", reply)
         return reply
 
+    @persist(SQLiteFlowPersistence("support.db"))
+    @listen(or_(handle_order, handle_help, handle_goodbye))
+    def finalize(self):
+        return self.state.model_dump()
+
 
 session_id = str(uuid4())
 flow = SupportFlow()
 
-try:
-    flow.handle_turn("주문 어디까지 왔나요?", session_id=session_id)
-    flow.handle_turn("반품은 어떻게 하나요?", session_id=session_id)
-finally:
-    flow.finalize_session_traces()  # 전체 대화에 대한 단일 trace 링크
+flow.kickoff(user_message="주문 어디까지 왔나요?", session_id=session_id)
+flow.kickoff(user_message="반품은 어떻게 하나요?", session_id=session_id)
+flow.finalize_session_traces()  # 전체 대화에 대한 단일 trace 링크
 ```
 
 ## 턴 생명주기
 
-각 `handle_turn`은 다음 파이프라인을 실행합니다:
+`user_message`가 있는 각 `kickoff`는 다음 파이프라인을 실행합니다:
 
 1. **`_configure_conversational_kickoff`** — `session_id` / `user_message`를 `inputs`에 병합, `ConversationalConfig` 적용, 설정 시 지연 트레이싱 활성화.
 2. **상태 복원** — `inputs["id"]`가 있고 `@persist`가 설정되면 최신 스냅샷 로드.
@@ -96,7 +107,7 @@ finally:
 5. **그래프 실행** — `@start` → `@router` → `@listen` 핸들러.
 6. **실행 종료** — 지연 활성화 시 턴별 `flow_finished` 및 trace 종료 **건너뜀**; 중첩 `Agent.kickoff()` / crew도 부모 batch를 닫지 않음.
 
-핸들러는 **`append_assistant_message(reply)`**를 호출해 다음 턴의 `conversation_messages`에 어시스턴트 응답이 포함되게 하세요. 사용자 입력은 `handle_turn`이 이미 저장합니다 — 핸들러에서 다시 추가하지 마세요.
+핸들러는 **`append_message("assistant", reply)`**를 호출해 다음 턴의 `conversation_messages`에 어시스턴트 응답이 포함되게 하세요. 사용자 입력은 kickoff 시 이미 저장됩니다 — 핸들러에서 다시 추가하지 마세요.
 
 ## `ConversationalConfig` (클래스 수준 기본값)
 
@@ -281,15 +292,6 @@ finally:
     flow.finalize_session_traces()
 ```
 
-로컬 터미널 채팅에는 `chat()`을 사용하세요:
-
-```python
-def kickoff() -> None:
-    SupportFlow().chat()
-```
-
-`chat()`은 `handle_turn()`을 REPL로 감싸고, `exit` / `quit`에서 종료하며, 기본적으로 빈 줄을 건너뛰고, 세션이 끝날 때 `finalize_session_traces()`를 호출합니다.
-
 ### `ConversationConfig`
 
 클래스 단위의 챗 기본값을 부착하는 클래스 데코레이터입니다.
@@ -371,37 +373,7 @@ Routes:
 4. router는 결정을 `state.last_intent`에 저장합니다 (다음 턴의 router 컨텍스트에서 보입니다).
 5. 핸들러가 문자열을 반환했지만 `append_assistant_message`를 직접 호출하지 않았다면, `handle_turn`이 대신 추가해 줍니다.
 
-채팅 메시지에는 `handle_turn()`을 호출하세요. `kickoff(inputs={"id": ...})`를 직접 호출하면 대화형 턴 래퍼 없이 flow 그래프가 실행됩니다.
-
-### 로컬 REPL용 `chat()`
-
-`flow.chat()`은 `handle_turn()` 위에 얹은 바로 쓸 수 있는 터미널 래퍼입니다:
-
-```python
-flow = SupportFlow()
-flow.chat()
-```
-
-일반적인 로컬 루프를 처리합니다:
-
-1. 사용자 메시지를 입력받습니다.
-2. `exit` / `quit`, `EOFError`, `KeyboardInterrupt`에서 멈춥니다.
-3. `handle_turn(message, session_id=...)`를 호출합니다.
-4. 어시스턴트 결과를 출력합니다.
-5. `finally` 블록에서 지연된 세션 trace를 finalize합니다.
-
-주입 가능한 I/O로 터미널 동작을 커스터마이즈할 수 있습니다:
-
-```python
-flow.chat(
-    session_id="demo-session",
-    prompt="You: ",
-    assistant_prefix="Assistant: ",
-    exit_commands=("exit", "quit", "bye"),
-)
-```
-
-웹 앱, 백그라운드 worker, 테스트, 커스텀 transport에서는 계속 `handle_turn()`을 직접 사용하세요.
+`flow.kickoff(user_message=..., session_id=...)`를 직접 호출해도 동일한 reset/run 로직이 동작합니다. `handle_turn`은 그 위에 얹은 편의 래퍼입니다.
 
 ### 커스텀 router 동작
 
@@ -437,10 +409,17 @@ LLM router를 우회해 프로그램적으로 라우트를 선택하려면 `rout
 - **중첩 작업** (`Agent.kickoff()`, crew, Exa tool)은 **부모** batch에 추가; 내부 `AgentExecutor` flow가 세션 batch를 조기 종료하지 않음.
 
 ```python
-flow.chat(session_id=session_id)
+try:
+    while True:
+        line = input("You: ").strip()
+        if not line:
+            break
+        flow.kickoff(user_message=line, session_id=session_id)
+finally:
+    flow.finalize_session_traces()
 ```
 
-`flow.chat()`이 `finalize_session_traces()`를 대신 호출합니다. `handle_turn()`이나 `kickoff(...)`로 직접 루프를 소유하는 경우, 세션이 끝날 때 `finalize_session_traces()`를 호출하세요.
+지연 활성화 시 `ChatSession.close()`가 `finalize_session_traces()`를 호출합니다.
 
 `suppress_flow_events=True`는 Rich 콘솔 패널만 숨깁니다. trace 및 method 이벤트는 계속 발생합니다.
 

docs/pt-BR/changelog.mdx

@@ -4,178 +4,6 @@ description: "Atualizações de produto, melhorias e correções do CrewAI"
 icon: "clock"
 mode: "wide"
 ---
-<Update label="11 jun 2026">
-  ## v1.14.7
-
-  [Ver release no GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7)
-
-  ## O que Mudou
-
-  ### Recursos
-  - Adicionar backends padrão plugáveis para memória, conhecimento, rag e fluxo.
-  - Exibir o verdadeiro finish_reason, parâmetros de amostragem e response.id em eventos LLM.
-  - Tipar os gatilhos DSL como decoradores cientes de rotas.
-  - Adicionar API de chat para fluxos de conversa.
-  - Tornar o backend de bloqueio substituível.
-  - Construir FlowDefinition a partir de metadados Flow DSL.
-  - Adicionar provedor nativo Snowflake Cortex LLM.
-  - Adicionar suporte a arquivos de agentes treinados pela equipe.
-
-  ### Correções de Bugs
-  - Corrigir checkpoint para reconstruir BaseLLM personalizado como LLM concreto na restauração.
-  - Controlar a restauração com uma flag para evitar que snapshots ao vivo sejam reproduzidos como retomar.
-  - Escopar o estado de execução por execução para limitar o crescimento e isolar execuções concorrentes.
-  - Corrigir configuração de telemetria no crewai-login.
-  - Respeitar suppress_flow_events para eventos de execução de método.
-  - Restaurar [project.scripts] no pacote crewai para instalação da ferramenta uv.
-  - Resolver CVEs de pip-audit para aiohttp, docling e docling-core.
-  - Corrigir entrada de arquivo que não estava funcionando de forma confiável.
-  - Corrigir histórias de resultados de ferramentas incompletas do Snowflake Claude.
-
-  ### Documentação
-  - Atualizar changelog e versão para v1.14.7.
-  - Atualizar documentação do coletor OpenTelemetry.
-  - Atualizar guia do LLM NVIDIA Nemotron.
-  - Adicionar guia de integração do Databricks.
-  - Adicionar guia de integração do Snowflake.
-
-  ### Desempenho
-  - Melhorar a velocidade de importação do crewai através do carregamento preguiçoso de imports do docling.
-
-  ### Refatoração
-  - Simplificar a avaliação de condições de fluxo para ser sem estado por evento.
-  - Desacoplar a lógica de conversa da execução e adicionar uma conversational_definition.
-  - Dividir `flow.py` em DSL, definição e execução.
-
-  ## Contribuidores
-
-  @Luzk, @alex-clawd, @devin-ai-integration[bot], @greysonlalonde, @gvieira, @jessemiller, @lorenzejay, @lucasgomide, @mattatcha, @vinibrsl
-
-</Update>
-
-<Update label="10 jun 2026">
-  ## v1.14.7rc2
-
-  [Ver release no GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7rc2)
-
-  ## O que Mudou
-
-  ### Correções de Bugs
-  - Restauração de portão em uma flag para evitar que snapshots ao vivo sejam reproduzidos como retomar
-
-  ### Documentação
-  - Atualizar changelog e versão para v1.14.7rc1
-
-  ## Contributors
-
-  @greysonlalonde
-
-</Update>
-
-<Update label="10 jun 2026">
-  ## v1.14.7rc1
-
-  [Ver release no GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7rc1)
-
-  ## O que Mudou
-
-  ### Recursos
-  - Adicionar `reset_runtime_state` para liberar o estado acumulado do barramento
-  - Lidar com suporte a ambos os prompts personalizados
-  - Desacoplar a lógica de conversa do tempo de execução e adicionar uma `conversational_definition`
-
-  ### Correções de Bugs
-  - Corrigir o escopo do estado de tempo de execução por execução para limitar o crescimento e isolar execuções concorrentes
-  - Corrigir a configuração de telemetria em `crewai-login`
-  - Corrigir o respeito a `suppress_flow_events` para eventos de execução de método
-
-  ### Documentação
-  - Atualizar imagens do OpenTelemetry
-  - Atualizar a documentação para refletir o novo estado do coletor OpenTelemetry
-  - Atualizar o changelog e a versão para v1.14.7a4
-
-  ### Refatoração
-  - Simplificar a avaliação da condição de fluxo para ser sem estado por evento
-  - Melhorar o ciclo de roteamento de conversas com uma rota a menos
-
-  ## Contribuidores
-
-  @greysonlalonde, @lorenzejay, @lucasgomide, @vinibrsl
-
-</Update>
-
-<Update label="09 jun 2026">
-  ## v1.14.7a4
-
-  [Ver release no GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7a4)
-
-  ## O Que Mudou
-
-  ### Funcionalidades
-  - Migrar a execução @listen/@router para ler a partir de FlowDefinition
-  - Adicionar backends padrão plugáveis para memória, conhecimento, rag e flow
-
-  ### Documentação
-  - Atualizar changelog e versão para v1.14.7a3
-
-  ## Contributors
-
-  @greysonlalonde, @mattatcha, @vinibrsl
-
-</Update>
-
-<Update label="08 jun 2026">
-  ## v1.14.7a3
-
-  [Ver release no GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7a3)
-
-  ## O que Mudou
-
-  ### Correções de Bugs
-  - Corrigir a exposição de `ask_for_human_input` no `AgentExecutor` experimental
-  - Resolver CVEs do pip-audit para `aiohttp`, `docling`, `docling-core` e `pip`
-
-  ### Refatoração
-  - Migrar `@start` para ler de `FlowDefinition`
-
-  ### Documentação
-  - Atualizar o changelog e a versão para v1.14.7a2
-
-  ## Contribuidores
-
-  @greysonlalonde, @lorenzejay, @vinibrsl
-
-</Update>
-
-<Update label="05 jun 2026">
-  ## v1.14.7a2
-
-  [Ver release no GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7a2)
-
-  ## O que Mudou
-
-  ### Recursos
-  - Adicionar suporte a rastreamentos de fluxo de conversa.
-  - Atualizar a documentação do fluxo de conversa para utilizar `handle_turn`.
-  - Exibir o real `finish_reason`, parâmetros de amostragem e `response.id` em eventos LLM.
-  - Tipar os gatilhos DSL como decoradores cientes de rota.
-  - Implementar API de chat para fluxos de conversa.
-  - Tornar o backend de bloqueio substituível no armazenamento de bloqueios.
-  - Dividir o monólito DSL de fluxo em módulos de decoradores focados.
-  - Achatar os subcontagens de uso de cache/razão do LiteLLM em `_usage_to_dict`.
-  - Construir `FlowDefinition` a partir dos metadados do Flow DSL.
-
-  ### Documentação
-  - Adicionar guia do LLM NVIDIA Nemotron.
-  - Documentar implantações de monorepo.
-  - Atualizar changelog e versão para v1.14.7a1.
-
-  ## Contribuidores
-
-  @alex-clawd, @gvieira, @lorenzejay, @lucasgomide, @mattatcha, @vinibrsl
-
-</Update>
-
 <Update label="03 jun 2026">
   ## v1.14.7a1
 

docs/pt-BR/concepts/flows.mdx

@@ -219,49 +219,6 @@ Após o término da execução, é possível acessar o estado final e observar a
 Ao garantir que a saída do método final seja retornada e oferecer acesso ao estado, o CrewAI Flows facilita a integração dos resultados dos seus workflows de IA em aplicações maiores,
 além de permitir o gerenciamento e o acesso ao estado durante toda a execução do Flow.
 
-## Métricas de Uso do Flow
-
-Após a execução de um Flow, você pode acessar a propriedade `usage_metrics` para visualizar o consumo agregado de tokens em **todas as chamadas de LLM** realizadas durante a execução — incluindo chamadas das Crews orquestradas pelo Flow, chamadas dentro de tools de Agents, e invocações diretas de `LLM.call(...)` feitas a partir de métodos do Flow. Esse é o equivalente, do lado do SDK, ao total exibido na interface do CrewAI Enterprise.
-
-```python Code
-from crewai import LLM
-from crewai.flow.flow import Flow, listen, start
-
-class UsageMetricsFlow(Flow):
-    @start()
-    def run_first_crew(self):
-        self.state.first_result = FirstCrew().crew().kickoff()
-
-    @listen(run_first_crew)
-    def call_llm_directly(self):
-        # Chamada direta de LLM — também contabilizada por flow.usage_metrics
-        llm = LLM(model="openai/gpt-4o-mini")
-        self.state.summary = llm.call("Resuma os principais pontos.")
-
-    @listen(call_llm_directly)
-    def run_second_crew(self):
-        self.state.second_result = SecondCrew().crew().kickoff()
-
-flow = UsageMetricsFlow()
-flow.kickoff()
-
-print(flow.usage_metrics)
-# UsageMetrics(total_tokens=8579, prompt_tokens=6210, completion_tokens=2369,
-#              cached_prompt_tokens=0, reasoning_tokens=0,
-#              cache_creation_tokens=0, successful_requests=5)
-```
-
-<Note>
-  `flow.usage_metrics` **não** é o mesmo que `flow.kickoff().token_usage`. Este
-  último retorna apenas o `CrewOutput.token_usage` do **último** método
-  `@listen` que retornou um `CrewOutput`, ou seja, reflete somente a Crew
-  final e ignora completamente as Crews anteriores e quaisquer chamadas
-  diretas de `LLM.call(...)`. Use `flow.usage_metrics` sempre que precisar do
-  rollup **completo** de tokens da execução do Flow.
-</Note>
-
-Cada campo do [`UsageMetrics`](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/types/usage_metrics.py) retornado representa a soma de todas as chamadas de LLM feitas em uma única invocação de `flow.kickoff()`. Os contadores são resetados a cada novo `kickoff()` (e em cada iteração de `kickoff_for_each`), de modo que execuções sucessivas não duplicam o total. A propriedade é segura para ser lida em qualquer momento após o `kickoff()`; lê-la durante a execução retorna o total parcial acumulado até aquele instante.
-
 ## Gerenciamento de Estado em Flows
 
 Gerenciar o estado de forma eficaz é fundamental para construir fluxos de trabalho de IA confiáveis e de fácil manutenção. O CrewAI Flows oferece mecanismos robustos para o gerenciamento de estado tanto não estruturado quanto estruturado,

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

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

docs/pt-BR/guides/advanced/customizing-prompts.mdx

@@ -161,18 +161,6 @@ crew = Crew(
 )
 ```
 
-<Note>
-`agent.i18n` é mantido apenas para compatibilidade retroativa e está obsoleto. Para customização de prompts em tempo de execução, passe `prompt_file` para `Crew`. Para acesso programático aos slices de prompt, use diretamente o utilitário de i18n:
-</Note>
-
-```python
-from crewai.utilities.i18n import get_i18n
-
-i18n = get_i18n("custom_prompts.json")
-format_slice = i18n.slice("format")
-tool_prompt = i18n.tools("ask_question")
-```
-
 #### Opção 3: Desativar Prompts de Sistema para Modelos o1
 ```python
 agent = Agent(
@@ -220,8 +208,6 @@ Uma abordagem direta é criar um arquivo JSON para os prompts que deseja sobresc
 
 O CrewAI então mescla suas customizações com os padrões, assim você não precisa redefinir todos os prompts. Veja como:
 
-Para código que precisa ler slices de prompt diretamente, use `crewai.utilities.i18n.get_i18n()` com o mesmo arquivo de prompts em vez de ler `agent.i18n`.
-
 ### Exemplo: Customização Básica de Prompt
 
 Crie um arquivo `custom_prompts.json` com os prompts que deseja modificar. Certifique-se de listar todos os prompts de nível superior que ele deve conter, não apenas suas alterações:

docs/pt-BR/guides/flows/conversational-flows.mdx

@@ -7,87 +7,98 @@ mode: "wide"
 
 ## Visão geral
 
-Apps conversacionais tratam cada linha do usuário como uma **nova execução do flow** com o **mesmo id de sessão**. A CrewAI oferece helpers para histórico de mensagens, classificação opcional de intenção, tracing adiado, pontes para UI e um REPL local `flow.chat()` para flows conversacionais.
+Apps conversacionais tratam cada linha do usuário como uma **nova execução do flow** com o **mesmo id de sessão**. A CrewAI oferece helpers para histórico de mensagens, classificação opcional de intenção, tracing adiado e pontes para UI — sem uma API `chat()` separada em `Flow`.
 
 | Conceito | Implementação |
 |---------|----------------|
-| Id de sessão | `handle_turn(..., session_id=...)` → `kickoff(inputs={"id": ...})` → `state.id` |
-| Linha do usuário | `handle_turn(message)` acrescenta em `state.messages` antes do grafo rodar |
-| Fim do turno | `FlowFinished` só para **esta execução**; o chat segue no próximo `handle_turn` |
-| Trace da sessão | `ConversationConfig(defer_trace_finalization=True)` + `finalize_session_traces()` |
+| Id de sessão | `kickoff(session_id=...)` → `inputs["id"]` → `state.id` |
+| Linha do usuário | `kickoff(user_message=...)` acrescenta em `state.messages` antes do grafo rodar |
+| Fim do turno | `FlowFinished` só para **esta execução**; o chat segue no próximo `kickoff` |
+| Trace da sessão | `ConversationalConfig(defer_trace_finalization=True)` + `finalize_session_traces()` |
 
-## APIs de turno
+## Um ponto de entrada: `kickoff`
 
-Use **`flow.handle_turn(message, session_id=...)`** para cada mensagem de usuário em REST, WebSocket, testes e UIs customizadas. Use **`flow.chat()`** quando quiser um loop de chat local no terminal para um `Flow` conversacional.
-
-`Flow.kickoff()` não aceita os argumentos nomeados `user_message=` ou `session_id=`. Para flows conversacionais, `handle_turn()` guarda a mensagem pendente e chama `kickoff(inputs={"id": session_id})` internamente.
+Use **`flow.kickoff(user_message=..., session_id=...)`** para cada mensagem (REST, WebSocket, CLI). Não crie um wrapper `chat()` customizado em `Flow`.
 
 | API | Uso |
 |-----|-----|
-| `handle_turn(message, session_id=...)` | Wrapper ergonômico de um turno para `Flow` conversacional |
-| `chat()` | REPL local no terminal para `Flow` conversacional |
-| `kickoff(inputs={...})` | Execução avançada do flow sem tratamento de turno conversacional |
+| `kickoff(user_message=..., session_id=...)` | Cada mensagem do usuário |
+| `kickoff_async(...)` | Mesmos parâmetros; entrada async nativa |
 | `ask()` | Prompt bloqueante **dentro** de um passo (wizard, esclarecimento) |
 | `@human_feedback` | Aprovar/rejeitar **saída de um passo** — não a próxima linha do chat |
-| `ChatSession.handle_turn(...)` | Camada de transporte sobre `handle_turn` (SSE / WebSocket) |
+| `ChatSession.handle_turn(...)` | Camada de transporte sobre `kickoff` (SSE / WebSocket) |
 
 ## Início rápido
 
 ```python
 from uuid import uuid4
 
-from crewai import Flow
-from crewai.flow import listen
-from crewai.experimental.conversational import (
-    ConversationConfig,
-    ConversationState,
+from crewai.flow import (
+    ChatState,
+    ConversationalConfig,
+    Flow,
+    listen,
+    or_,
+    persist,
+    router,
+    start,
 )
+from crewai.flow.persistence import SQLiteFlowPersistence
 
 
-@ConversationConfig(defer_trace_finalization=True)
-class SupportFlow(Flow[ConversationState]):
-    conversational = True
+class SupportFlow(Flow[ChatState]):
+    conversational_config = ConversationalConfig(
+        default_intents=["order", "help", "goodbye"],
+        intent_llm="gpt-4o-mini",
+        defer_trace_finalization=True,
+    )
 
-    def route_turn(self, context):
-        message = (self.state.current_user_message or "").lower()
-        if "pedido" in message or "order" in message:
-            return "order"
-        if "tchau" in message or "goodbye" in message:
-            return "goodbye"
-        return "help"
+    @start()
+    def bootstrap(self):
+        if not self.state.session_ready:
+            self.state.session_ready = True
+        return "ready"
+
+    @router(bootstrap)
+    def route(self):
+        # last_intent definido em prepare_conversational_turn quando default_intents está setado
+        return self.state.last_intent or "help"
 
     @listen("order")
     def handle_order(self):
         reply = "Seu pedido está a caminho."
-        self.append_assistant_message(reply)
+        self.append_message("assistant", reply)
         return reply
 
     @listen("help")
     def handle_help(self):
         reply = "Como posso ajudar?"
-        self.append_assistant_message(reply)
+        self.append_message("assistant", reply)
         return reply
 
     @listen("goodbye")
     def handle_goodbye(self):
         reply = "Até logo!"
-        self.append_assistant_message(reply)
+        self.append_message("assistant", reply)
         return reply
 
+    @persist(SQLiteFlowPersistence("support.db"))
+    @listen(or_(handle_order, handle_help, handle_goodbye))
+    def finalize(self):
+        return self.state.model_dump()
+
 
 session_id = str(uuid4())
 flow = SupportFlow()
 
-try:
-    flow.handle_turn("Onde está meu pedido?", session_id=session_id)
-    flow.handle_turn("E as devoluções?", session_id=session_id)
-finally:
-    flow.finalize_session_traces()  # um link de trace para o chat inteiro
+flow.kickoff(user_message="Onde está meu pedido?", session_id=session_id)
+flow.kickoff(user_message="E as devoluções?", session_id=session_id)
+flow.finalize_session_traces()  # um link de trace para o chat inteiro
 ```
 
 ## Ciclo de vida do turno
 
-Cada `handle_turn` executa este pipeline:
+Cada `kickoff` com `user_message` executa este pipeline:
 
 1. **`_configure_conversational_kickoff`** — mescla `session_id` / `user_message` em `inputs`, aplica `ConversationalConfig`, habilita tracing adiado quando configurado.
 2. **Restauração de estado** — se `inputs["id"]` existe e `@persist` está configurado, carrega o snapshot mais recente.
@@ -96,7 +107,7 @@ Cada `handle_turn` executa este pipeline:
 5. **Execução do grafo** — `@start` → `@router` → handlers `@listen`.
 6. **Fim da execução** — `flow_finished` por turno e finalização de trace são **ignorados** com adiamento; `Agent.kickoff()` / crews aninhados também não fecham o batch pai.
 
-Os handlers devem chamar **`append_assistant_message(reply)`** para que o próximo turno inclua a resposta do assistente. A linha do usuário já é salva por `handle_turn` — não acrescente de novo nos handlers.
+Os handlers devem chamar **`append_message("assistant", reply)`** para que o próximo turno inclua a resposta do assistente. A linha do usuário já é salva no kickoff — não acrescente de novo nos handlers.
 
 ## `ConversationalConfig` (padrões em nível de classe)
 
@@ -282,15 +293,6 @@ finally:
     flow.finalize_session_traces()
 ```
 
-Para um chat local no terminal, use `chat()`:
-
-```python
-def kickoff() -> None:
-    SupportFlow().chat()
-```
-
-`chat()` envolve `handle_turn()` em um REPL, sai com `exit` / `quit`, ignora linhas em branco por padrão e chama `finalize_session_traces()` quando a sessão termina.
-
 ### `ConversationConfig`
 
 Decorador de classe que anexa os defaults de chat por classe.
@@ -372,37 +374,7 @@ Você pode sobrescrever qualquer uma definindo um handler com o mesmo nome na su
 4. O router grava sua decisão em `state.last_intent` (visível para o contexto de routing do próximo turno).
 5. Se seu handler retornou uma string e ainda não chamou `append_assistant_message`, `handle_turn` anexa para você.
 
-Chame `handle_turn()` para mensagens de chat. Chamar `kickoff(inputs={"id": ...})` diretamente executa o grafo sem aplicar o wrapper de turno conversacional.
-
-### `chat()` para REPLs locais
-
-`flow.chat()` é o wrapper de terminal pronto para uso em cima de `handle_turn()`:
-
-```python
-flow = SupportFlow()
-flow.chat()
-```
-
-Ele cobre o loop local comum:
-
-1. Solicita uma mensagem do usuário.
-2. Para com `exit` / `quit`, `EOFError` ou `KeyboardInterrupt`.
-3. Chama `handle_turn(message, session_id=...)`.
-4. Imprime o resultado do assistente.
-5. Finaliza traces de sessão adiados em um bloco `finally`.
-
-Customize o comportamento do terminal com I/O injetável:
-
-```python
-flow.chat(
-    session_id="demo-session",
-    prompt="You: ",
-    assistant_prefix="Assistant: ",
-    exit_commands=("exit", "quit", "bye"),
-)
-```
-
-Para apps web, workers em background, testes e transportes customizados, continue usando `handle_turn()` diretamente.
+Você também pode chamar `flow.kickoff(user_message=..., session_id=...)` diretamente — a mesma lógica de reset/run é acionada. `handle_turn` é o wrapper ergonômico.
 
 ### Comportamento customizado do router
 
@@ -438,10 +410,17 @@ Com `defer_trace_finalization=True` (padrão em `ConversationalConfig`):
 - **Trabalho aninhado** (`Agent.kickoff()`, crews, tools Exa) acrescenta ao batch **pai**; flows internos de `AgentExecutor` não fecham o batch da sessão cedo.
 
 ```python
-flow.chat(session_id=session_id)
+try:
+    while True:
+        line = input("You: ").strip()
+        if not line:
+            break
+        flow.kickoff(user_message=line, session_id=session_id)
+finally:
+    flow.finalize_session_traces()
 ```
 
-`flow.chat()` chama `finalize_session_traces()` para você. Quando você controla o loop com `handle_turn()` ou `kickoff(...)`, chame `finalize_session_traces()` quando a sessão terminar.
+`ChatSession.close()` chama `finalize_session_traces()` quando o adiamento está habilitado.
 
 `suppress_flow_events=True` só oculta painéis do console; eventos de trace e método ainda são emitidos.
 

lib/cli/pyproject.toml

@@ -8,7 +8,7 @@ authors = [
 ]
 requires-python = ">=3.10, <3.14"
 dependencies = [
-    "crewai-core==1.14.7",
+    "crewai-core==1.14.7a1",
     "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.7"
+__version__ = "1.14.7a1"

lib/cli/src/crewai_cli/cli.py

@@ -26,7 +26,6 @@ from crewai_cli.remote_template.main import TemplateCommand
 from crewai_cli.replay_from_task import replay_task_command
 from crewai_cli.reset_memories_command import reset_memories_command
 from crewai_cli.run_crew import run_crew
-from crewai_cli.run_flow_definition import run_flow_definition
 from crewai_cli.settings.main import SettingsCommand
 from crewai_cli.task_outputs import load_task_outputs
 from crewai_cli.tools.main import ToolCommand
@@ -399,36 +398,8 @@ def install(context: click.Context) -> None:
         "CREWAI_TRAINED_AGENTS_FILE."
     ),
 )
-@click.option(
-    "--definition",
-    type=str,
-    default=None,
-    help=(
-        "Experimental: path to a Flow Definition YAML/JSON file, "
-        "or an inline YAML/JSON string."
-    ),
-)
-@click.option(
-    "--inputs",
-    type=str,
-    default=None,
-    help='Experimental: JSON object passed to flow.kickoff(), e.g. \'{"topic":"AI"}\'.',
-)
-def run(
-    trained_agents_file: str | None, definition: str | None, inputs: str | None
-) -> None:
-    """Run the Crew or Flow."""
-    if inputs is not None and definition is None:
-        raise click.UsageError("--inputs requires --definition")
-
-    if definition is not None:
-        click.secho(
-            "Warning: `crewai run --definition` is experimental and may change without notice.",
-            fg="yellow",
-        )
-        run_flow_definition(definition=definition, inputs=inputs)
-        return
-
+def run(trained_agents_file: str | None) -> None:
+    """Run the Crew."""
     run_crew(trained_agents_file=trained_agents_file)
 
 

lib/cli/src/crewai_cli/run_flow_definition.py

@@ -1,113 +0,0 @@
-from __future__ import annotations
-
-import json
-from pathlib import Path
-from typing import Any
-
-import click
-
-
-def run_flow_definition(definition: str, inputs: str | None = None) -> None:
-    """Run a flow from a Flow Definition YAML/JSON string or file path."""
-    try:
-        from crewai.flow.flow import Flow
-        from crewai.flow.flow_definition import FlowDefinition
-    except ImportError as exc:
-        click.echo(
-            "Running flows from definitions requires the full crewai package.",
-            err=True,
-        )
-        raise SystemExit(1) from exc
-
-    parsed_inputs = _parse_inputs(inputs)
-    definition_source = _read_definition_source(definition)
-
-    try:
-        flow_definition = _parse_flow_definition(FlowDefinition, definition_source)
-        flow = Flow.from_definition(flow_definition)
-        result = flow.kickoff(inputs=parsed_inputs)
-    except Exception as exc:
-        click.echo(
-            f"An error occurred while running the flow definition: {exc}", err=True
-        )
-        raise SystemExit(1) from exc
-
-    click.echo(_format_result(result))
-
-
-def _parse_inputs(inputs: str | None) -> dict[str, Any] | None:
-    if inputs is None:
-        return None
-
-    try:
-        parsed = json.loads(inputs)
-    except json.JSONDecodeError as exc:
-        click.echo(f"Invalid --inputs JSON: {exc}", err=True)
-        raise SystemExit(1) from exc
-
-    if not isinstance(parsed, dict):
-        click.echo("Invalid --inputs JSON: expected an object.", err=True)
-        raise SystemExit(1)
-
-    return parsed
-
-
-def _read_definition_source(definition: str) -> str:
-    path = Path(definition).expanduser()
-    try:
-        is_file = path.is_file()
-    except OSError as exc:
-        if _looks_like_inline_definition(definition):
-            return definition
-        click.echo(f"Invalid --definition path: {definition} ({exc})", err=True)
-        raise SystemExit(1) from exc
-
-    if is_file:
-        try:
-            return path.read_text(encoding="utf-8")
-        except (OSError, UnicodeError) as exc:
-            click.echo(
-                f"Unable to read --definition path {path}: {exc}",
-                err=True,
-            )
-            raise SystemExit(1) from exc
-
-    try:
-        if path.exists():
-            click.echo(
-                f"Invalid --definition path: {definition} is not a file.", err=True
-            )
-            raise SystemExit(1)
-    except OSError as exc:
-        click.echo(f"Invalid --definition path: {definition} ({exc})", err=True)
-        raise SystemExit(1) from exc
-
-    return definition
-
-
-def _looks_like_inline_definition(definition: str) -> bool:
-    stripped = definition.lstrip()
-    return "\n" in definition or stripped.startswith(("{", "---")) or ":" in stripped
-
-
-def _parse_flow_definition(flow_definition_cls: type[Any], source: str) -> Any:
-    if _looks_like_json(source):
-        return flow_definition_cls.from_json(source)
-
-    return flow_definition_cls.from_yaml(source)
-
-
-def _looks_like_json(source: str) -> bool:
-    stripped = source.lstrip()
-    return stripped.startswith("{")
-
-
-def _format_result(result: Any) -> str:
-    raw_result = getattr(result, "raw", result)
-    if isinstance(raw_result, str):
-        return raw_result
-
-    try:
-        return json.dumps(raw_result, default=str)
-    except TypeError:
-        return str(raw_result)

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.7"
+    "crewai[tools]==1.14.7a1"
 ]
 
 [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.7"
+    "crewai[tools]==1.14.7a1"
 ]
 
 [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.7"
+    "crewai[tools]==1.14.7a1"
 ]
 
 [tool.crewai]

lib/cli/tests/test_cli.py

@@ -13,7 +13,6 @@ from crewai_cli.cli import (
     flow_add_crew,
     login,
     reset_memories,
-    run,
     test,
     train,
     version,
@@ -120,43 +119,6 @@ def test_test_invalid_string_iterations(evaluate_crew, runner):
     )
 
 
-@mock.patch("crewai_cli.cli.run_crew")
-def test_run_uses_project_runner_by_default(run_crew, runner):
-    result = runner.invoke(run)
-
-    assert result.exit_code == 0
-    run_crew.assert_called_once_with(trained_agents_file=None)
-    assert "experimental" not in result.output.lower()
-
-
-@mock.patch("crewai_cli.cli.run_flow_definition")
-def test_run_with_definition_uses_definition_runner(run_flow_definition, runner):
-    result = runner.invoke(
-        run,
-        ["--definition", "flow.yaml", "--inputs", '{"topic":"AI"}'],
-    )
-
-    assert result.exit_code == 0
-    assert (
-        "Warning: `crewai run --definition` is experimental and may change without notice."
-        in result.output
-    )
-    run_flow_definition.assert_called_once_with(
-        definition="flow.yaml", inputs='{"topic":"AI"}'
-    )
-
-
-@mock.patch("crewai_cli.cli.run_crew")
-@mock.patch("crewai_cli.cli.run_flow_definition")
-def test_run_rejects_inputs_without_definition(run_flow_definition, run_crew, runner):
-    result = runner.invoke(run, ["--inputs", '{"topic":"AI"}'])
-
-    assert result.exit_code == 2
-    assert "Error: --inputs requires --definition" in result.output
-    run_flow_definition.assert_not_called()
-    run_crew.assert_not_called()
-
-
 @mock.patch("crewai_cli.cli.AuthenticationCommand")
 def test_login(command, runner):
     mock_auth = command.return_value

lib/cli/tests/test_run_flow_definition.py

@@ -1,156 +0,0 @@
-from __future__ import annotations
-
-import json
-import sys
-import types
-
-import pytest
-import yaml
-
-from crewai_cli.run_flow_definition import run_flow_definition
-
-
-class _FakeFlow:
-    def __init__(self, definition):
-        self.definition = definition
-
-    def kickoff(self, inputs=None):
-        return {
-            "flow": self.definition["name"],
-            "inputs": inputs or {},
-        }
-
-
-class _FakeFlowFactory:
-    @classmethod
-    def from_definition(cls, definition):
-        return _FakeFlow(definition)
-
-
-class _FakeFlowDefinition:
-    @classmethod
-    def from_yaml(cls, source):
-        return yaml.safe_load(source)
-
-    @classmethod
-    def from_json(cls, source):
-        return json.loads(source)
-
-
-@pytest.fixture
-def fake_flow_runtime(monkeypatch):
-    crewai_module = types.ModuleType("crewai")
-    flow_package = types.ModuleType("crewai.flow")
-    flow_module = types.ModuleType("crewai.flow.flow")
-    flow_definition_module = types.ModuleType("crewai.flow.flow_definition")
-
-    flow_module.Flow = _FakeFlowFactory
-    flow_definition_module.FlowDefinition = _FakeFlowDefinition
-
-    monkeypatch.setitem(sys.modules, "crewai", crewai_module)
-    monkeypatch.setitem(sys.modules, "crewai.flow", flow_package)
-    monkeypatch.setitem(sys.modules, "crewai.flow.flow", flow_module)
-    monkeypatch.setitem(
-        sys.modules, "crewai.flow.flow_definition", flow_definition_module
-    )
-
-
-def _captured_json(capsys):
-    return json.loads(capsys.readouterr().out)
-
-
-def test_run_flow_definition_reads_definition_file(
-    tmp_path, capsys, fake_flow_runtime
-):
-    definition_path = tmp_path / "flow.yaml"
-    definition_path.write_text("schema: crewai.flow/v1\nname: TestFlow\n")
-
-    run_flow_definition(str(definition_path), '{"topic":"AI"}')
-
-    assert _captured_json(capsys) == {
-        "flow": "TestFlow",
-        "inputs": {"topic": "AI"},
-    }
-
-
-@pytest.mark.parametrize(
-    ("definition_source", "expected_flow_name"),
-    [
-        pytest.param(
-            "schema: crewai.flow/v1\nname: InlineFlow\n",
-            "InlineFlow",
-            id="inline-yaml",
-        ),
-        pytest.param(
-            '{"schema":"crewai.flow/v1","name":"InlineJsonFlow"}',
-            "InlineJsonFlow",
-            id="inline-json",
-        ),
-        pytest.param(
-            '{"schema":"crewai.flow/v1","name":"' + ("JsonFlow" * 500) + '"}',
-            "JsonFlow" * 500,
-            id="large-inline-json",
-        ),
-    ],
-)
-def test_run_flow_definition_accepts_inline_definitions(
-    definition_source, expected_flow_name, capsys, fake_flow_runtime
-):
-    run_flow_definition(definition_source)
-
-    assert _captured_json(capsys) == {"flow": expected_flow_name, "inputs": {}}
-
-
-@pytest.mark.parametrize(
-    ("filename", "definition_source", "expected_flow_name"),
-    [
-        pytest.param(
-            "flow.yaml",
-            "schema: crewai.flow/v1\nname: YamlFileFlow\n",
-            "YamlFileFlow",
-            id="yaml-file",
-        ),
-        pytest.param(
-            "flow.json",
-            '{"schema":"crewai.flow/v1","name":"JsonFlow"}',
-            "JsonFlow",
-            id="json-file",
-        ),
-    ],
-)
-def test_run_flow_definition_accepts_definition_files(
-    filename, definition_source, expected_flow_name, tmp_path, capsys, fake_flow_runtime
-):
-    definition_path = tmp_path / filename
-    definition_path.write_text(definition_source)
-
-    run_flow_definition(str(definition_path))
-
-    assert _captured_json(capsys) == {"flow": expected_flow_name, "inputs": {}}
-
-
-def test_run_flow_definition_rejects_non_object_inputs(fake_flow_runtime, capsys):
-    with pytest.raises(SystemExit):
-        run_flow_definition("name: TestFlow", '["not", "an", "object"]')
-
-    assert "Invalid --inputs JSON: expected an object." in capsys.readouterr().err
-
-
-def test_run_flow_definition_reports_unreadable_file(
-    monkeypatch, tmp_path, capsys, fake_flow_runtime
-):
-    definition_path = tmp_path / "flow.yaml"
-    definition_path.write_text("schema: crewai.flow/v1\nname: TestFlow\n")
-
-    def raise_permission_error(self, *args, **kwargs):
-        raise PermissionError("no access")
-
-    monkeypatch.setattr("pathlib.Path.read_text", raise_permission_error)
-
-    with pytest.raises(SystemExit):
-        run_flow_definition(str(definition_path))
-
-    err = capsys.readouterr().err
-    assert "Unable to read --definition path" in err
-    assert str(definition_path) in err
-    assert "no access" in err

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

@@ -1 +1 @@
-__version__ = "1.14.7"
+__version__ = "1.14.7a1"

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

@@ -1,18 +1,14 @@
 """Centralised lock factory.
 
-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).
+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.
 """
 
 from __future__ import annotations
 
-from collections.abc import Callable, Iterator
-from contextlib import AbstractContextManager, contextmanager
+from collections.abc import Iterator
+from contextlib import contextmanager
 from functools import lru_cache
 from hashlib import md5
 import logging
@@ -34,25 +30,6 @@ _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."""
@@ -81,19 +58,10 @@ 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"``). The
-              built-in default namespaces it to avoid collisions; a custom
-              backend receives it verbatim.
+        name: A human-readable lock name (e.g. ``"chromadb_init"``).
+              Automatically namespaced to avoid collisions.
         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-core/src/crewai_core/telemetry.py

@@ -17,7 +17,7 @@ import contextlib
 import logging
 import os
 import threading
-from typing import Any, ClassVar, Final
+from typing import Any, Final
 
 from opentelemetry import trace
 from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
@@ -27,7 +27,7 @@ from opentelemetry.sdk.trace.export import (
     BatchSpanProcessor,
     SpanExportResult,
 )
-from opentelemetry.trace import ProxyTracerProvider, Span, Status, StatusCode
+from opentelemetry.trace import Span, Status, StatusCode
 from typing_extensions import Self
 
 
@@ -72,8 +72,8 @@ class Telemetry:
     and event-bus signal handlers (see ``crewai.telemetry.telemetry``).
     """
 
-    _instance: ClassVar[Self | None] = None
-    _lock: ClassVar[threading.Lock] = threading.Lock()
+    _instance = None
+    _lock = threading.Lock()
 
     def __new__(cls) -> Self:
         if cls._instance is None:
@@ -149,10 +149,6 @@ class Telemetry:
         if self.ready and not self.trace_set:
             try:
                 with suppress_warnings():
-                    existing_provider = trace.get_tracer_provider()
-                    if not isinstance(existing_provider, ProxyTracerProvider):
-                        self.trace_set = True
-                        return
                     trace.set_tracer_provider(self.provider)
                     self.trace_set = True
             except Exception as e:

lib/crewai-core/tests/test_smoke.py

@@ -13,7 +13,6 @@ from crewai_core import (
     user_data,
     version,
 )
-from opentelemetry.sdk.trace import TracerProvider
 import pytest
 
 
@@ -95,36 +94,3 @@ def test_user_data_decline_blocks(
 def test_unused_var_warning_silenced() -> None:
     # Touch os to keep the import (used by env-var fixtures above)
     assert os.environ is not None
-
-
-def test_core_telemetry_skips_duplicate_tracer_provider(
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    from crewai_core.telemetry import Telemetry
-
-    Telemetry._instance = None
-    monkeypatch.delenv("OTEL_SDK_DISABLED", raising=False)
-    monkeypatch.delenv("CREWAI_DISABLE_TELEMETRY", raising=False)
-    monkeypatch.delenv("CREWAI_DISABLE_TRACKING", raising=False)
-
-    monkeypatch.setattr(
-        "crewai_core.telemetry.trace.get_tracer_provider",
-        lambda: TracerProvider(),
-    )
-
-    called = False
-
-    def fail_if_called(provider: object) -> None:
-        nonlocal called
-        called = True
-
-    monkeypatch.setattr(
-        "crewai_core.telemetry.trace.set_tracer_provider",
-        fail_if_called,
-    )
-
-    telemetry = Telemetry()
-    telemetry.set_tracer()
-
-    assert called is False
-    assert telemetry.trace_set is True

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

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

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.7",
+    "crewai==1.14.7a1",
     "tiktoken>=0.8.0,<0.13",
     "beautifulsoup4~=4.13.4",
     "python-docx~=1.2.0",
@@ -63,7 +63,7 @@ spider-client = [
     "spider-client>=0.1.25",
 ]
 scrapegraph-py = [
-    "scrapegraph-py>=1.9.0,<2",
+    "scrapegraph-py>=1.9.0",
 ]
 linkup-sdk = [
     "linkup-sdk>=0.2.2",

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

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

lib/crewai-tools/src/crewai_tools/security/safe_path.py

@@ -22,31 +22,6 @@ logger = logging.getLogger(__name__)
 _UNSAFE_PATHS_ENV = "CREWAI_TOOLS_ALLOW_UNSAFE_PATHS"
 
 
-def format_path_for_display(path: str, base_dir: str | None = None) -> str:
-    """Return a path label that does not expose absolute directory prefixes."""
-    if base_dir is None:
-        base_dir = os.getcwd()
-
-    try:
-        resolved_base = os.path.realpath(base_dir)
-        resolved_path = os.path.realpath(
-            os.path.join(resolved_base, path) if not os.path.isabs(path) else path
-        )
-        if os.path.commonpath([resolved_base, resolved_path]) == resolved_base:
-            return os.path.relpath(resolved_path, resolved_base)
-    except (OSError, ValueError) as exc:
-        logger.debug("Falling back to basename for display path formatting: %s", exc)
-
-    return os.path.basename(os.path.realpath(path)) or "[redacted path]"
-
-
-def format_error_for_display(error: Exception) -> str:
-    """Return exception details without OS-added absolute path context."""
-    if isinstance(error, OSError):
-        return error.strerror or error.__class__.__name__
-    return str(error)
-
-
 def _is_escape_hatch_enabled() -> bool:
     """Check if the unsafe paths escape hatch is enabled."""
     return os.environ.get(_UNSAFE_PATHS_ENV, "").lower() in ("true", "1", "yes")
@@ -91,8 +66,8 @@ def validate_file_path(path: str, base_dir: str | None = None) -> str:
     prefix = resolved_base if resolved_base.endswith(os.sep) else resolved_base + os.sep
     if not resolved_path.startswith(prefix) and resolved_path != resolved_base:
         raise ValueError(
-            f"Path '{format_path_for_display(resolved_path, resolved_base)}' is "
-            f"outside the allowed directory. "
+            f"Path '{path}' resolves to '{resolved_path}' which is outside "
+            f"the allowed directory '{resolved_base}'. "
             f"Set {_UNSAFE_PATHS_ENV}=true to bypass this check."
         )
 

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

@@ -3,11 +3,7 @@ from typing import Any
 from crewai.tools import BaseTool
 from pydantic import BaseModel, Field
 
-from crewai_tools.security.safe_path import (
-    format_error_for_display,
-    format_path_for_display,
-    validate_file_path,
-)
+from crewai_tools.security.safe_path import validate_file_path
 
 
 class FileReadToolSchema(BaseModel):
@@ -62,9 +58,8 @@ class FileReadTool(BaseTool):
             **kwargs: Additional keyword arguments passed to BaseTool.
         """
         if file_path is not None:
-            display_path = format_path_for_display(file_path)
             kwargs["description"] = (
-                f"A tool that reads file content. The default file is {display_path}, but you can provide a different 'file_path' parameter to read another file. You can also specify 'start_line' and 'line_count' to read specific parts of the file."
+                f"A tool that reads file content. The default file is {file_path}, but you can provide a different 'file_path' parameter to read another file. You can also specify 'start_line' and 'line_count' to read specific parts of the file."
             )
 
         super().__init__(**kwargs)
@@ -83,12 +78,7 @@ class FileReadTool(BaseTool):
         if file_path is None:
             return "Error: No file path provided. Please provide a file path either in the constructor or as an argument."
 
-        try:
-            file_path = validate_file_path(file_path)
-        except ValueError as e:
-            return f"Error: Invalid file path: {e!s}"
-
-        display_path = format_path_for_display(file_path)
+        file_path = validate_file_path(file_path)
         try:
             with open(file_path, "r") as file:
                 if start_line == 1 and line_count is None:
@@ -108,11 +98,8 @@ class FileReadTool(BaseTool):
 
                 return "".join(selected_lines)
         except FileNotFoundError:
-            return f"Error: File not found at path: {display_path}"
+            return f"Error: File not found at path: {file_path}"
         except PermissionError:
-            return f"Error: Permission denied when trying to read file: {display_path}"
+            return f"Error: Permission denied when trying to read file: {file_path}"
         except Exception as e:
-            return (
-                f"Error: Failed to read file {display_path}. "
-                f"{format_error_for_display(e)}"
-            )
+            return f"Error: Failed to read file {file_path}. {e!s}"

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

@@ -5,11 +5,6 @@ from typing import Any
 from crewai.tools import BaseTool
 from pydantic import BaseModel
 
-from crewai_tools.security.safe_path import (
-    format_error_for_display,
-    format_path_for_display,
-)
-
 
 def strtobool(val: str | bool) -> bool:
     if isinstance(val, bool):
@@ -49,9 +44,6 @@ class FileWriterTool(BaseTool):
             # itself, since that is not a valid file target.
             real_directory = Path(directory).resolve()
             real_filepath = Path(filepath).resolve()
-            display_filepath = format_path_for_display(
-                str(real_filepath), str(real_directory)
-            )
             if (
                 not real_filepath.is_relative_to(real_directory)
                 or real_filepath == real_directory
@@ -64,18 +56,15 @@ class FileWriterTool(BaseTool):
             kwargs["overwrite"] = strtobool(kwargs["overwrite"])
 
             if os.path.exists(real_filepath) and not kwargs["overwrite"]:
-                return f"File {display_filepath} already exists and overwrite option was not passed."
+                return f"File {real_filepath} already exists and overwrite option was not passed."
 
             mode = "w" if kwargs["overwrite"] else "x"
             with open(real_filepath, mode) as file:
                 file.write(kwargs["content"])
-            return f"Content successfully written to {display_filepath}"
+            return f"Content successfully written to {real_filepath}"
         except FileExistsError:
-            return f"File {display_filepath} already exists and overwrite option was not passed."
+            return f"File {real_filepath} already exists and overwrite option was not passed."
         except KeyError as e:
             return f"An error occurred while accessing key: {e!s}"
         except Exception as e:
-            return (
-                "An error occurred while writing to the file: "
-                f"{format_error_for_display(e)}"
-            )
+            return f"An error occurred while writing to the file: {e!s}"

lib/crewai-tools/tests/file_read_tool_test.py

@@ -1,3 +1,4 @@
+import os
 from unittest.mock import mock_open, patch
 
 from crewai_tools import FileReadTool
@@ -5,16 +6,21 @@ from crewai_tools import FileReadTool
 
 def test_file_read_tool_constructor():
     """Test FileReadTool initialization with file_path."""
-    test_file = "test_file.txt"
+    test_file = "/tmp/test_file.txt"
+    test_content = "Hello, World!"
+    with open(test_file, "w") as f:
+        f.write(test_content)
 
     tool = FileReadTool(file_path=test_file)
     assert tool.file_path == test_file
     assert "test_file.txt" in tool.description
 
+    os.remove(test_file)
+
 
 def test_file_read_tool_run():
     """Test FileReadTool _run method with file_path at runtime."""
-    test_file = "test_file.txt"
+    test_file = "/tmp/test_file.txt"
     test_content = "Hello, World!"
 
     # Use mock_open to mock file operations
@@ -30,18 +36,18 @@ def test_file_read_tool_error_handling():
     result = tool._run()
     assert "Error: No file path provided" in result
 
-    result = tool._run(file_path="nonexistent/file.txt")
+    result = tool._run(file_path="/nonexistent/file.txt")
     assert "Error: File not found at path:" in result
 
     with patch("builtins.open", side_effect=PermissionError()):
-        result = tool._run(file_path="no_permission.txt")
+        result = tool._run(file_path="/tmp/no_permission.txt")
         assert "Error: Permission denied" in result
 
 
 def test_file_read_tool_constructor_and_run():
     """Test FileReadTool using both constructor and runtime file paths."""
-    test_file1 = "test1.txt"
-    test_file2 = "test2.txt"
+    test_file1 = "/tmp/test1.txt"
+    test_file2 = "/tmp/test2.txt"
     content1 = "File 1 content"
     content2 = "File 2 content"
 
@@ -58,7 +64,7 @@ def test_file_read_tool_constructor_and_run():
 
 def test_file_read_tool_chunk_reading():
     """Test FileReadTool reading specific chunks of a file."""
-    test_file = "multiline_test.txt"
+    test_file = "/tmp/multiline_test.txt"
     lines = [
         "Line 1\n",
         "Line 2\n",
@@ -98,7 +104,7 @@ def test_file_read_tool_chunk_reading():
 
 def test_file_read_tool_chunk_error_handling():
     """Test error handling for chunk reading."""
-    test_file = "short_test.txt"
+    test_file = "/tmp/short_test.txt"
     lines = ["Line 1\n", "Line 2\n", "Line 3\n"]
     file_content = "".join(lines)
 
@@ -116,7 +122,7 @@ def test_file_read_tool_chunk_error_handling():
 
 def test_file_read_tool_zero_or_negative_start_line():
     """Test that start_line values of 0 or negative read from the start of the file."""
-    test_file = "negative_test.txt"
+    test_file = "/tmp/negative_test.txt"
     lines = ["Line 1\n", "Line 2\n", "Line 3\n", "Line 4\n", "Line 5\n"]
     file_content = "".join(lines)
 
@@ -144,45 +150,3 @@ def test_file_read_tool_zero_or_negative_start_line():
         result = tool._run(file_path=test_file, start_line=-10, line_count=2)
         expected = "".join(lines[0:2])  # Should read first 2 lines
         assert result == expected
-
-
-def test_file_read_tool_error_messages_do_not_disclose_absolute_paths(
-    tmp_path, monkeypatch
-):
-    """FileReadTool should redact absolute prefixes from user-visible errors."""
-    monkeypatch.chdir(tmp_path)
-    tool = FileReadTool()
-    target = tmp_path / "secret.txt"
-
-    result = tool._run(file_path=str(target))
-    assert "secret.txt" in result
-    assert str(tmp_path) not in result
-
-    target.touch()
-    with patch("builtins.open", side_effect=PermissionError()):
-        result = tool._run(file_path=str(target))
-    assert "secret.txt" in result
-    assert str(tmp_path) not in result
-
-    with patch(
-        "builtins.open",
-        side_effect=OSError(5, "Input/output error", str(target)),
-    ):
-        result = tool._run(file_path=str(target))
-    assert "secret.txt" in result
-    assert str(tmp_path) not in result
-
-
-def test_file_read_tool_invalid_path_error_does_not_disclose_workspace(
-    tmp_path, monkeypatch
-):
-    """Validation errors should not echo the resolved workspace path."""
-    monkeypatch.chdir(tmp_path)
-    outside = tmp_path.parent / "outside.txt"
-
-    result = FileReadTool()._run(file_path=str(outside))
-
-    assert "Invalid file path" in result
-    assert "outside.txt" in result
-    assert str(tmp_path) not in result
-    assert str(tmp_path.parent) not in result

lib/crewai-tools/tests/tools/test_file_writer_tool.py

@@ -47,8 +47,6 @@ def test_basic_file_write(tool, temp_env):
     assert os.path.exists(path)
     assert read_file(path) == temp_env["test_content"]
     assert "successfully written" in result
-    assert temp_env["test_file"] in result
-    assert temp_env["temp_dir"] not in result
 
 
 def test_directory_creation(tool, temp_env):
@@ -64,8 +62,6 @@ def test_directory_creation(tool, temp_env):
     assert os.path.exists(new_dir)
     assert os.path.exists(path)
     assert "successfully written" in result
-    assert temp_env["test_file"] in result
-    assert new_dir not in result
 
 
 @pytest.mark.parametrize(
@@ -138,8 +134,6 @@ def test_file_exists_error_handling(tool, temp_env, overwrite):
     )
 
     assert "already exists and overwrite option was not passed" in result
-    assert temp_env["test_file"] in result
-    assert temp_env["temp_dir"] not in result
     assert read_file(path) == "Pre-existing content"
 
 

lib/crewai-tools/tests/utilities/test_safe_path.py

@@ -7,7 +7,6 @@ import os
 import pytest
 
 from crewai_tools.security.safe_path import (
-    format_path_for_display,
     validate_directory_path,
     validate_file_path,
     validate_url,
@@ -67,37 +66,6 @@ class TestValidateFilePath:
         result = validate_file_path("/etc/passwd", str(tmp_path))
         assert result == os.path.realpath("/etc/passwd")
 
-    def test_rejection_message_redacts_absolute_prefixes(self, tmp_path):
-        outside = tmp_path.parent / "outside.txt"
-
-        with pytest.raises(ValueError) as exc_info:
-            validate_file_path(str(outside), str(tmp_path))
-
-        message = str(exc_info.value)
-        assert "outside.txt" in message
-        assert str(tmp_path) not in message
-        assert str(tmp_path.parent) not in message
-
-
-class TestFormatPathForDisplay:
-    """Tests for user-visible path labels."""
-
-    def test_returns_relative_path_inside_base(self, tmp_path):
-        nested_file = tmp_path / "nested" / "file.txt"
-        nested_file.parent.mkdir()
-        nested_file.touch()
-
-        result = format_path_for_display(str(nested_file), str(tmp_path))
-
-        assert result == os.path.join("nested", "file.txt")
-
-    def test_redacts_absolute_prefix_outside_base(self, tmp_path):
-        outside_file = tmp_path.parent / "outside.txt"
-
-        result = format_path_for_display(str(outside_file), str(tmp_path))
-
-        assert result == "outside.txt"
-
 
 class TestValidateDirectoryPath:
     """Tests for validate_directory_path."""

lib/crewai/pyproject.toml

@@ -8,8 +8,8 @@ authors = [
 ]
 requires-python = ">=3.10, <3.14"
 dependencies = [
-    "crewai-core==1.14.7",
-    "crewai-cli==1.14.7",
+    "crewai-core==1.14.7a1",
+    "crewai-cli==1.14.7a1",
     # Core Dependencies
     "pydantic>=2.11.9,<2.13",
     "openai>=2.30.0,<3",
@@ -33,12 +33,11 @@ dependencies = [
     "appdirs~=1.4.4",
     "jsonref~=1.1.0",
     "json-repair~=0.25.2",
-    "cel-python>=0.5.0,<0.6",
     "tomli-w~=1.1.0",
     "tomli~=2.0.2",
     "json5~=0.10.0",
     "portalocker~=2.7.0",
-    "pydantic-settings>=2.10.1,<3",
+    "pydantic-settings~=2.10.1",
     "httpx~=0.28.1",
     "mcp~=1.26.0",
     "aiosqlite~=0.21.0",
@@ -55,7 +54,7 @@ Repository = "https://github.com/crewAIInc/crewAI"
 
 [project.optional-dependencies]
 tools = [
-    "crewai-tools==1.14.7",
+    "crewai-tools==1.14.7a1",
 ]
 embeddings = [
     "tiktoken>=0.8.0,<0.13"
@@ -68,11 +67,7 @@ openpyxl = [
 ]
 mem0 = ["mem0ai>=2.0.0,<3"]
 docling = [
-    "docling~=2.97.0",
-    # docling 2.97 split into docling-slim; the chunker package (HierarchicalChunker)
-    # now eagerly imports code-chunking submodules that need tree-sitter/semchunk,
-    # which only the docling-core[chunking] extra provides.
-    "docling-core[chunking]>=2.74.1",
+    "docling~=2.84.0",
 ]
 qdrant = [
     "qdrant-client[fastembed]~=1.14.3",

lib/crewai/src/crewai/__init__.py

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

lib/crewai/src/crewai/agents/agent_builder/base_agent.py

@@ -46,7 +46,6 @@ from crewai.state.checkpoint_config import CheckpointConfig, _coerce_checkpoint
 from crewai.tools.base_tool import BaseTool, Tool
 from crewai.types.callback import SerializableCallable
 from crewai.utilities.config import process_config
-from crewai.utilities.i18n import I18N, get_i18n
 from crewai.utilities.logger import Logger
 from crewai.utilities.rpm_controller import RPMController
 from crewai.utilities.string_utils import interpolate_only
@@ -82,7 +81,6 @@ _LLM_TYPE_REGISTRY: dict[str, str] = {
 def _validate_llm_ref(value: Any) -> Any:
     if isinstance(value, dict):
         import importlib
-        import inspect
 
         llm_type = value.get("llm_type")
         if not llm_type or llm_type not in _LLM_TYPE_REGISTRY:
@@ -93,12 +91,6 @@ def _validate_llm_ref(value: Any) -> Any:
         dotted = _LLM_TYPE_REGISTRY[llm_type]
         mod_path, cls_name = dotted.rsplit(".", 1)
         cls = getattr(importlib.import_module(mod_path), cls_name)
-        if inspect.isabstract(cls):
-            from crewai.llm import LLM
-
-            return LLM(
-                **{k: v for k, v in value.items() if v is not None and k != "llm_type"}
-            )
         return cls(**value)
     return value
 
@@ -194,7 +186,6 @@ class BaseAgent(BaseModel, ABC, metaclass=AgentMeta):
         tools (list[Any] | None): Tools at the agent's disposal.
         max_iter (int): Maximum iterations for an agent to execute a task.
         agent_executor: An instance of the CrewAgentExecutor class.
-        i18n (I18N): Internationalization settings.
         llm (Any): Language model that will run the agent.
         crew (Any): Crew to which the agent belongs.
 
@@ -274,14 +265,6 @@ class BaseAgent(BaseModel, ABC, metaclass=AgentMeta):
             _serialize_executor_ref, return_type=dict | None, when_used="json"
         ),
     ] = Field(default=None, description="An instance of the CrewAgentExecutor class.")
-    i18n: I18N = Field(
-        default_factory=get_i18n,
-        description="Internationalization settings.",
-        deprecated=(
-            "Agent.i18n is deprecated and will be removed in a future release. "
-            "Use crewai.utilities.i18n.get_i18n() or Crew(prompt_file=...) instead."
-        ),
-    )
 
     llm: Annotated[
         str | BaseLLM | None,

lib/crewai/src/crewai/context.py

@@ -117,10 +117,8 @@ def capture_execution_context(
     )
 
 
-def apply_execution_context(ctx: ExecutionContext | dict[str, Any]) -> None:
+def apply_execution_context(ctx: ExecutionContext) -> None:
     """Write an ExecutionContext back into the ContextVars."""
-    if isinstance(ctx, dict):
-        ctx = ExecutionContext.model_validate(ctx)
     _current_task_id.set(ctx.current_task_id)
     current_flow_request_id.set(ctx.flow_request_id)
     current_flow_id.set(ctx.flow_id)

lib/crewai/src/crewai/crew.py

@@ -1013,7 +1013,6 @@ class Crew(FlowTrackable, BaseModel):
         )
         token = attach(baggage_ctx)
 
-        runtime_scope = crewai_event_bus._enter_runtime_scope()
         try:
             inputs = prepare_kickoff(self, inputs, input_files)
 
@@ -1049,7 +1048,6 @@ class Crew(FlowTrackable, BaseModel):
                 self._memory.drain_writes()
             clear_files(self.id)
             detach(token)
-            crewai_event_bus._exit_runtime_scope(runtime_scope)
 
     def _post_kickoff(self, result: CrewOutput) -> CrewOutput:
         return result
@@ -1225,7 +1223,6 @@ class Crew(FlowTrackable, BaseModel):
         )
         token = attach(baggage_ctx)
 
-        runtime_scope = crewai_event_bus._enter_runtime_scope()
         try:
             inputs = prepare_kickoff(self, inputs, input_files)
 
@@ -1259,7 +1256,6 @@ class Crew(FlowTrackable, BaseModel):
         finally:
             clear_files(self.id)
             detach(token)
-            crewai_event_bus._exit_runtime_scope(runtime_scope)
 
     async def akickoff_for_each(
         self,

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

@@ -61,8 +61,6 @@ if TYPE_CHECKING:
         CrewTrainStartedEvent,
     )
     from crewai.events.types.flow_events import (
-        ConversationMessageAddedEvent,
-        ConversationRouteSelectedEvent,
         FlowCreatedEvent,
         FlowEvent,
         FlowFinishedEvent,
@@ -178,8 +176,6 @@ _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",
@@ -295,8 +291,6 @@ __all__ = [
     "CheckpointRestoreStartedEvent",
     "CheckpointStartedEvent",
     "CircularDependencyError",
-    "ConversationMessageAddedEvent",
-    "ConversationRouteSelectedEvent",
     "CrewKickoffCompletedEvent",
     "CrewKickoffFailedEvent",
     "CrewKickoffStartedEvent",

lib/crewai/src/crewai/events/event_bus.py

@@ -80,17 +80,6 @@ def is_replaying() -> bool:
     return _replaying.get()
 
 
-_runtime_state_var: contextvars.ContextVar[RuntimeState | None] = (
-    contextvars.ContextVar("crewai_runtime_state", default=None)
-)
-_registered_entity_ids_var: contextvars.ContextVar[set[int] | None] = (
-    contextvars.ContextVar("crewai_registered_entity_ids", default=None)
-)
-_runtime_scope_depth: contextvars.ContextVar[int] = contextvars.ContextVar(
-    "crewai_runtime_scope_depth", default=0
-)
-
-
 class CrewAIEventsBus:
     """Singleton event bus for handling events in CrewAI.
 
@@ -127,6 +116,7 @@ class CrewAIEventsBus:
     _futures_lock: threading.Lock
     _executor_initialized: bool
     _has_pending_events: bool
+    _runtime_state: RuntimeState | None
 
     def __new__(cls) -> Self:
         """Create or return the singleton instance.
@@ -161,6 +151,8 @@ class CrewAIEventsBus:
         self._console = ConsoleFormatter()
         self._executor_initialized = False
         self._has_pending_events = False
+        self._runtime_state: RuntimeState | None = None
+        self._registered_entity_ids: set[int] = set()
 
     def _ensure_executor_initialized(self) -> None:
         """Lazily initialize the thread pool executor and event loop.
@@ -289,51 +281,6 @@ class CrewAIEventsBus:
         """The RuntimeState currently attached to the bus, if any."""
         return self._runtime_state
 
-    @property
-    def _runtime_state(self) -> RuntimeState | None:
-        return _runtime_state_var.get()
-
-    @_runtime_state.setter
-    def _runtime_state(self, value: RuntimeState | None) -> None:
-        _runtime_state_var.set(value)
-
-    @property
-    def _registered_entity_ids(self) -> set[int]:
-        ids = _registered_entity_ids_var.get()
-        if ids is None:
-            ids = set()
-            _registered_entity_ids_var.set(ids)
-        return ids
-
-    @_registered_entity_ids.setter
-    def _registered_entity_ids(self, value: set[int]) -> None:
-        _registered_entity_ids_var.set(value)
-
-    def reset_runtime_state(self) -> None:
-        """Detach the RuntimeState and clear the entity registry."""
-        self._runtime_state = None
-        self._registered_entity_ids = set()
-
-    def _enter_runtime_scope(self) -> bool:
-        depth = _runtime_scope_depth.get()
-        _runtime_scope_depth.set(depth + 1)
-        if depth != 0:
-            return False
-        if _runtime_state_var.get() is None:
-            from crewai import RuntimeState
-
-            if RuntimeState is not None:
-                _runtime_state_var.set(RuntimeState(root=[]))
-            _registered_entity_ids_var.set(set())
-        return True
-
-    def _exit_runtime_scope(self, outermost: bool) -> None:
-        depth = _runtime_scope_depth.get()
-        _runtime_scope_depth.set(depth - 1 if depth > 0 else 0)
-        if outermost:
-            _runtime_state_var.set(None)
-            _registered_entity_ids_var.set(None)
-
     def register_entity(self, entity: Any) -> None:
         """Add an entity to the RuntimeState, creating it if needed.
 
@@ -402,7 +349,6 @@ class CrewAIEventsBus:
         source: Any,
         event: BaseEvent,
         handlers: SyncHandlerSet,
-        state: RuntimeState | None,
     ) -> None:
         """Call provided synchronous handlers.
 
@@ -410,8 +356,8 @@ class CrewAIEventsBus:
             source: The emitting object
             event: The event instance
             handlers: Frozenset of sync handlers to call
-            state: The RuntimeState captured on the emitting context
         """
+        state = self._runtime_state
         errors: list[tuple[SyncHandler, Exception]] = [
             (handler, error)
             for handler in handlers
@@ -430,7 +376,6 @@ class CrewAIEventsBus:
         source: Any,
         event: BaseEvent,
         handlers: AsyncHandlerSet,
-        state: RuntimeState | None,
     ) -> None:
         """Asynchronously call provided async handlers.
 
@@ -438,8 +383,8 @@ class CrewAIEventsBus:
             source: The object that emitted the event
             event: The event instance
             handlers: Frozenset of async handlers to call
-            state: The RuntimeState captured on the emitting context
         """
+        state = self._runtime_state
 
         async def _call(handler: AsyncHandler) -> Any:
             if _get_param_count(handler) >= 3:
@@ -454,9 +399,7 @@ class CrewAIEventsBus:
                     f"[CrewAIEventsBus] Async handler error in {getattr(handler, '__name__', handler)}: {result}"
                 )
 
-    async def _emit_with_dependencies(
-        self, source: Any, event: BaseEvent, state: RuntimeState | None
-    ) -> None:
+    async def _emit_with_dependencies(self, source: Any, event: BaseEvent) -> None:
         """Emit an event with dependency-aware handler execution.
 
         Handlers are grouped into execution levels based on their dependencies.
@@ -507,18 +450,18 @@ class CrewAIEventsBus:
 
             if level_sync:
                 if event_type is LLMStreamChunkEvent:
-                    self._call_handlers(source, event, level_sync, state)
+                    self._call_handlers(source, event, level_sync)
                 else:
                     ctx = contextvars.copy_context()
                     future = self._sync_executor.submit(
-                        ctx.run, self._call_handlers, source, event, level_sync, state
+                        ctx.run, self._call_handlers, source, event, level_sync
                     )
                     await asyncio.get_running_loop().run_in_executor(
                         None, future.result
                     )
 
             if level_async:
-                await self._acall_handlers(source, event, level_async, state)
+                await self._acall_handlers(source, event, level_async)
 
     def _register_source(self, source: Any) -> None:
         """Register the source entity in RuntimeState if applicable."""
@@ -613,23 +556,21 @@ class CrewAIEventsBus:
         self._ensure_executor_initialized()
         self._has_pending_events = True
 
-        state = self._runtime_state
-
         if has_dependencies:
             return self._track_future(
                 asyncio.run_coroutine_threadsafe(
-                    self._emit_with_dependencies(source, event, state),
+                    self._emit_with_dependencies(source, event),
                     self._loop,
                 )
             )
 
         if sync_handlers:
             if event_type is LLMStreamChunkEvent:
-                self._call_handlers(source, event, sync_handlers, state)
+                self._call_handlers(source, event, sync_handlers)
             else:
                 ctx = contextvars.copy_context()
                 sync_future = self._sync_executor.submit(
-                    ctx.run, self._call_handlers, source, event, sync_handlers, state
+                    ctx.run, self._call_handlers, source, event, sync_handlers
                 )
                 if not async_handlers:
                     return self._track_future(sync_future)
@@ -637,7 +578,7 @@ class CrewAIEventsBus:
         if async_handlers:
             return self._track_future(
                 asyncio.run_coroutine_threadsafe(
-                    self._acall_handlers(source, event, async_handlers, state),
+                    self._acall_handlers(source, event, async_handlers),
                     self._loop,
                 )
             )
@@ -649,22 +590,21 @@ class CrewAIEventsBus:
         source: Any,
         event: BaseEvent,
         handlers: AsyncHandlerSet,
-        state: RuntimeState | None,
     ) -> None:
         """Call async handlers with the replaying flag set on the loop thread."""
         token = _replaying.set(True)
         try:
-            await self._acall_handlers(source, event, handlers, state)
+            await self._acall_handlers(source, event, handlers)
         finally:
             _replaying.reset(token)
 
     async def _emit_with_dependencies_replaying(
-        self, source: Any, event: BaseEvent, state: RuntimeState | None
+        self, source: Any, event: BaseEvent
     ) -> None:
         """Dependency-aware dispatch with the replaying flag set."""
         token = _replaying.set(True)
         try:
-            await self._emit_with_dependencies(source, event, state)
+            await self._emit_with_dependencies(source, event)
         finally:
             _replaying.reset(token)
 
@@ -698,13 +638,12 @@ class CrewAIEventsBus:
         self._ensure_executor_initialized()
         self._has_pending_events = True
 
-        state = self._runtime_state
         token = _replaying.set(True)
         try:
             if has_dependencies:
                 return self._track_future(
                     asyncio.run_coroutine_threadsafe(
-                        self._emit_with_dependencies_replaying(source, event, state),
+                        self._emit_with_dependencies_replaying(source, event),
                         self._loop,
                     )
                 )
@@ -712,7 +651,7 @@ class CrewAIEventsBus:
             if sync_handlers:
                 ctx = contextvars.copy_context()
                 sync_future = self._sync_executor.submit(
-                    ctx.run, self._call_handlers, source, event, sync_handlers, state
+                    ctx.run, self._call_handlers, source, event, sync_handlers
                 )
                 self._track_future(sync_future)
                 if not async_handlers:
@@ -720,9 +659,7 @@ class CrewAIEventsBus:
 
             return self._track_future(
                 asyncio.run_coroutine_threadsafe(
-                    self._acall_handlers_replaying(
-                        source, event, async_handlers, state
-                    ),
+                    self._acall_handlers_replaying(source, event, async_handlers),
                     self._loop,
                 )
             )
@@ -790,9 +727,7 @@ class CrewAIEventsBus:
             async_handlers = self._async_handlers.get(event_type, frozenset())
 
         if async_handlers:
-            await self._acall_handlers(
-                source, event, async_handlers, self._runtime_state
-            )
+            await self._acall_handlers(source, event, async_handlers)
 
     def register_handler(
         self,

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

@@ -158,6 +158,7 @@ class EventListener(BaseEventListener):
             trace_listener.formatter = self.formatter
 
     def setup_listeners(self, crewai_event_bus: CrewAIEventsBus) -> None:
+
         @crewai_event_bus.on(CCEnvEvent)
         def on_cc_env(_: Any, event: CCEnvEvent) -> None:
             self._telemetry.env_context_span(event.type)

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

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

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

@@ -62,8 +62,6 @@ from crewai.events.types.crew_events import (
     CrewKickoffStartedEvent,
 )
 from crewai.events.types.flow_events import (
-    ConversationMessageAddedEvent,
-    ConversationRouteSelectedEvent,
     FlowCreatedEvent,
     FlowFinishedEvent,
     FlowPlotEvent,
@@ -257,18 +255,6 @@ 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)
@@ -292,7 +278,7 @@ class TraceCollectionListener(BaseEventListener):
         @event_bus.on(CrewKickoffCompletedEvent)
         def on_crew_completed(source: Any, event: CrewKickoffCompletedEvent) -> None:
             self._handle_trace_event("crew_kickoff_completed", source, event)
-            if self._should_defer_session_finalization():
+            if self.batch_manager.defer_session_finalization:
                 return
             if self._nested_in_flow_execution():
                 return
@@ -306,7 +292,7 @@ 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._should_defer_session_finalization():
+            if self.batch_manager.defer_session_finalization:
                 return
             if self._nested_in_flow_execution():
                 return
@@ -734,7 +720,7 @@ class TraceCollectionListener(BaseEventListener):
             if not self.batch_manager.is_batch_initialized():
                 return
             # Multi-turn flows defer batch finalization to finalize_session_traces().
-            if self._should_defer_session_finalization():
+            if self.batch_manager.defer_session_finalization:
                 return
             self.batch_manager.finalize_batch()
 
@@ -745,15 +731,6 @@ class TraceCollectionListener(BaseEventListener):
 
         return current_flow_id.get() is not None
 
-    def _should_defer_session_finalization(self) -> bool:
-        """True when the active trace belongs to a deferred flow session."""
-        from crewai.flow.flow_context import current_flow_defer_trace_finalization
-
-        return (
-            self.batch_manager.defer_session_finalization
-            or current_flow_defer_trace_finalization.get()
-        )
-
     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":
@@ -789,17 +766,12 @@ class TraceCollectionListener(BaseEventListener):
     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`` (infrastructure flows such as
-        ``AgentExecutor`` and the memory flows), flow and method lifecycle
-        events are not emitted, so the batch is claimed from the flow context
-        (``current_flow_id``) to keep LLM/tool events from falling back to an
-        implicit crew batch.
+        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_defer_trace_finalization,
-            current_flow_id,
-            current_flow_name,
-        )
+        from crewai.flow.flow_context import current_flow_id, current_flow_name
 
         flow_id = current_flow_id.get()
         if flow_id is None:
@@ -815,8 +787,6 @@ class TraceCollectionListener(BaseEventListener):
         }
         self.batch_manager.batch_owner_type = "flow"
         self.batch_manager.batch_owner_id = flow_id
-        if current_flow_defer_trace_finalization.get():
-            self.batch_manager.defer_session_finalization = True
         self._initialize_batch(user_context, execution_metadata)
         return True
 

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

@@ -1,6 +1,6 @@
 from typing import Any, Literal
 
-from pydantic import BaseModel, ConfigDict, field_serializer
+from pydantic import BaseModel, ConfigDict
 
 from crewai.events.base_events import BaseEvent
 
@@ -57,10 +57,6 @@ class MethodExecutionFailedEvent(FlowEvent):
 
     model_config = ConfigDict(arbitrary_types_allowed=True)
 
-    @field_serializer("error")
-    def _serialize_error(self, error: Exception) -> str:
-        return str(error)
-
 
 class MethodExecutionPausedEvent(FlowEvent):
     """Event emitted when a flow method is paused waiting for human feedback.
@@ -170,31 +166,6 @@ 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, field_validator
+from pydantic import BaseModel
 
 from crewai.events.base_events import BaseEvent
 
@@ -48,43 +48,6 @@ 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):
@@ -95,23 +58,6 @@ 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/agent_executor.py

@@ -279,16 +279,6 @@ class AgentExecutor(Flow[AgentExecutorState], BaseAgentExecutor):
         """Set state messages."""
         self._state.messages = value
 
-    @property
-    def ask_for_human_input(self) -> bool:
-        """Compatibility property - returns state ask_for_human_input."""
-        return self._state.ask_for_human_input  # type: ignore[no-any-return]
-
-    @ask_for_human_input.setter
-    def ask_for_human_input(self, value: bool) -> None:
-        """Set state ask_for_human_input."""
-        self._state.ask_for_human_input = value
-
     @start()
     def generate_plan(self) -> None:
         """Generate execution plan if planning is enabled.

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

@@ -1,36 +1,29 @@
-"""Conversational graph + helpers as an experimental Flow extension.
+"""Conversational graph + helpers as a mixin for ``Flow`` (experimental).
 
-The conversational chat surface remains experimental and may change before the
-v2 graduation path. It lives here so ``crewai.flow.runtime`` can stay focused
-on the execution engine. ``crewai.flow.flow`` composes this mixin onto the
-public ``Flow`` class for backwards compatibility.
-
-The built-in conversational graph only registers for subclasses that opt in
-with ``conversational = True``. Static conversational metadata is projected
-into ``FlowDefinition.conversational`` via the Python DSL builder.
+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; the public ``Flow`` class
-      composes it in. Users don't import it directly.
+    - :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 collections.abc import Mapping, Sequence
 from enum import Enum
 import json
 import logging
-from typing import TYPE_CHECKING, Any, ClassVar, Literal, TypeVar, cast
+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,
@@ -46,69 +39,26 @@ from crewai.flow.conversation import (
     get_conversation_messages,
     receive_user_message as _receive_user_message,
 )
-from crewai.flow.dsl import listen, start
-from crewai.flow.dsl._utils import _method_action, _set_flow_method_definition
-from crewai.flow.flow_definition import FlowMethodDefinition
+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__)
 
 
-def _iter_condition_labels(condition: Any) -> set[str]:
-    if isinstance(condition, str):
-        return {condition}
-    if isinstance(condition, dict):
-        labels: set[str] = set()
-        for value in condition.values():
-            if isinstance(value, list):
-                for item in value:
-                    labels.update(_iter_condition_labels(item))
-            else:
-                labels.update(_iter_condition_labels(value))
-        return labels
-    return set()
-
-
-def _conversation_start_router(func: Callable[..., Any]) -> Any:
-    wrapper = start()(func)
-    _set_flow_method_definition(
-        cast(Any, wrapper),
-        FlowMethodDefinition(do=_method_action(func), start=True, router=True),
-    )
-    return wrapper
-
-
 class _ConversationalMixin:
-    """Experimental conversational graph for ``Flow``.
+    """Built-in conversational graph for ``Flow`` (gated on ``conversational``).
 
-    This mixin owns chat behavior and runtime hooks. Non-chat flows see these
-    methods as inert attributes unless they opt in with ``conversational = True``.
+    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.
     """
 
-    # === EXPERIMENTAL: conversational mode ===
-    # When ``conversational = True`` on a Flow subclass, this mixin's built-in
-    # graph registers and ``handle_turn`` / ``chat`` become chat entry points.
-    conversational: ClassVar[bool] = False
-    conversational_config: ClassVar[ConversationConfig | None] = None
-    builtin_routes: ClassVar[tuple[str, ...]] = ("converse", "end")
-    internal_routes: ClassVar[tuple[str, ...]] = ("answer_from_history",)
-    builtin_route_descriptions: ClassVar[dict[str, str]] = {
-        "converse": (
-            "Ordinary chat, follow-ups, summaries, clarifications, and "
-            "questions answerable from prior conversation history."
-        ),
-        "end": ("User signals the conversation is finished (goodbye, exit, done)."),
-        "answer_from_history": (
-            "Answer directly from prior conversation history without invoking "
-            "tools, agents, or custom routes."
-        ),
-    }
-
     # The metaclass + state attributes referenced below live on ``Flow`` —
     # this mixin is never instantiated standalone. These type-only
     # declarations exist so static analyzers don't flag attribute access.
@@ -116,15 +66,22 @@ class _ConversationalMixin:
     # (otherwise mypy flags "Cannot override instance variable with class
     # variable" when Flow declares them as ``ClassVar``).
     if TYPE_CHECKING:
+        conversational: ClassVar[bool]
+        conversational_config: ClassVar[ConversationConfig | None]
+        builtin_routes: ClassVar[tuple[str, ...]]
+        internal_routes: ClassVar[tuple[str, ...]]
+        builtin_route_descriptions: ClassVar[dict[str, str]]
+        # Registry ClassVars populated by ``FlowMeta`` at class creation.
+        _listeners: ClassVar[dict[Any, Any]]
+
         # Instance attrs from ``Flow``.
         state: Any
         name: str | None
         _completed_methods: set[Any]
         _method_outputs: list[Any]
-        _pending_events: dict[Any, Any]
+        _pending_and_listeners: dict[Any, Any]
         _method_call_counts: dict[Any, int]
         _is_execution_resuming: bool
-        _conversation_messages: list[LLMMessage]
         _pending_user_message: str | dict[str, Any] | None
         _pending_intents: Sequence[str] | None
         _pending_intent_llm: str | BaseLLM | None
@@ -135,8 +92,8 @@ class _ConversationalMixin:
         def _collapse_to_outcome(
             self,
             feedback: str,
-            outcomes: Sequence[str],
-            llm: str | BaseLLM,
+            outcomes: tuple[str, ...],
+            llm: str | BaseLLM | Any,
         ) -> str:
             pass
 
@@ -146,60 +103,38 @@ class _ConversationalMixin:
         def kickoff(self, *args: Any, **kwargs: Any) -> Any:
             pass
 
-        @property
-        def method_outputs(self) -> list[Any]:
-            pass
-
+    @start()
+    @_conversational_only
     def conversation_start(self) -> str | None:
-        """Return the current user message for conversational route selection.
+        """Internal Flow entrypoint that hands the user message to the router.
 
-        This remains as a plain overridable helper for compatibility. It is not
-        registered as a Flow method; ``route_conversation`` is the synthetic
-        built-in start/router that begins a conversational turn.
+        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
 
-    @_conversation_start_router
+    @router(conversation_start)
     @_conversational_only
     def route_conversation(self) -> str:
         """Route the current turn to a listener label."""
-        if "conversation_start" not in {
-            str(method_name) for method_name in self._completed_methods
-        }:
-            self.conversation_start()
         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")
@@ -281,8 +216,8 @@ class _ConversationalMixin:
         state = cast(ConversationState, self.state)
         sid = session_id or state.id
 
-        # Stash the pending turn so the kickoff extension hook picks it up
-        # after persist restore.
+        # 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
@@ -308,59 +243,6 @@ class _ConversationalMixin:
             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 self._is_conversational_enabled():
-            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)
@@ -471,61 +353,13 @@ class _ConversationalMixin:
         metadata: dict[str, Any] | None = None,
     ) -> None:
         """Append a final user-visible assistant message."""
-        state = cast(ConversationState, self.state)
-        state.messages.append(
+        cast(ConversationState, self.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,
@@ -534,14 +368,14 @@ class _ConversationalMixin:
         **extra: Any,
     ) -> None:
         """Append a message to conversation history (legacy ChatState path)."""
-        _append_conversation_message(cast(Any, self), role, content, **extra)
+        _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(Any, self))
+            for message in get_conversation_messages(cast("Flow[Any]", self))
         ]
 
     def receive_user_message(
@@ -557,14 +391,9 @@ class _ConversationalMixin:
         ``state.messages`` and preserve ``last_intent`` across turns.
         Non-conversational flows fall through to the legacy helper.
         """
-        if self._is_conversational_enabled():
+        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:
@@ -578,7 +407,9 @@ class _ConversationalMixin:
                 return intent
             return text
 
-        return _receive_user_message(cast(Any, self), text, outcomes=outcomes, llm=llm)
+        return _receive_user_message(
+            cast("Flow[Any]", self), text, outcomes=outcomes, llm=llm
+        )
 
     def classify_intent(
         self,
@@ -602,104 +433,27 @@ class _ConversationalMixin:
     def _conversation_config(self) -> ConversationConfig | None:
         return getattr(type(self), "conversational_config", None)
 
-    @property
-    def _conversation_definition(self) -> Any | None:
-        return self._conversation_flow_definition().conversational
-
-    def _conversation_flow_definition(self) -> Any:
-        flow_definition = getattr(type(self), "flow_definition", None)
-        if not callable(flow_definition):
-            raise AttributeError(
-                f"{type(self).__name__} does not expose flow_definition()"
-            )
-        return flow_definition()
-
-    @classmethod
-    def _conversational_definition(cls) -> Any | None:
-        flow_definition = getattr(cls, "flow_definition", None)
-        if not callable(flow_definition):
-            return None
-        return flow_definition().conversational
-
-    @classmethod
-    def _is_conversational(cls) -> bool:
-        definition = cls._conversational_definition()
-        return bool(definition and definition.enabled)
-
-    def _is_conversational_enabled(self) -> bool:
-        definition = self._conversation_definition
-        return bool(definition and definition.enabled)
-
-    def _initialize_runtime_extension_attrs(self) -> None:
-        if not isinstance(getattr(self, "_conversation_messages", None), list):
-            object.__setattr__(self, "_conversation_messages", [])
-        if not hasattr(self, "_pending_user_message"):
-            object.__setattr__(self, "_pending_user_message", None)
-        if not hasattr(self, "_pending_intents"):
-            object.__setattr__(self, "_pending_intents", None)
-        if not hasattr(self, "_pending_intent_llm"):
-            object.__setattr__(self, "_pending_intent_llm", None)
-
-    def _create_default_extension_state(self) -> ConversationState | None:
-        initial_state_t = getattr(self, "_initial_state_t", None)
-        if type(self)._is_conversational() and (
-            not hasattr(self, "_initial_state_t")
-            or isinstance(initial_state_t, TypeVar)
-        ):
-            return ConversationState()
-        return None
-
-    def _should_apply_pending_kickoff_context(self) -> bool:
-        return (
-            type(self)._is_conversational() and self._pending_user_message is not None
-        )
-
-    def _apply_pending_kickoff_context(self) -> None:
-        self._apply_pending_conversational_turn()
-
-    def _order_start_methods_for_kickoff(
-        self,
-        start_methods: list[Any],
-    ) -> tuple[list[Any], bool]:
-        if not type(self)._is_conversational():
-            return start_methods, False
-
-        route_conversation = "route_conversation"
-        if route_conversation not in {str(method) for method in start_methods}:
-            return start_methods, False
-
-        ordered_starts = [
-            method for method in start_methods if str(method) != route_conversation
-        ]
-        ordered_starts.append(
-            next(
-                method for method in start_methods if str(method) == route_conversation
-            )
-        )
-        return ordered_starts, True
-
     def _should_defer_trace_finalization(self) -> bool:
         """Whether per-turn ``FlowFinished`` + ``finalize_batch`` should be skipped.
 
         True when either:
           - ``flow.defer_trace_finalization`` is set on the instance, OR
-          - the static conversational definition enables deferred finalization.
+          - 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
-        definition = self._conversation_definition
-        return bool(
-            definition and definition.enabled and definition.defer_trace_finalization
-        )
+        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_events.clear()
+        self._pending_and_listeners.clear()
         self._method_call_counts.clear()
         self._clear_or_listeners()
         self._is_execution_resuming = False
@@ -851,12 +605,11 @@ class _ConversationalMixin:
         router_config: RouterConfig | None,
     ) -> dict[str, str]:
         label_to_method: dict[str, str] = {}
-        flow_definition = self._conversation_flow_definition()
-        for listener_name, method_definition in flow_definition.methods.items():
-            if method_definition.listen is None or method_definition.router:
-                continue
-            for trigger_label in _iter_condition_labels(method_definition.listen):
-                label_to_method.setdefault(trigger_label, listener_name)
+        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 = (
@@ -907,31 +660,21 @@ class _ConversationalMixin:
 
     def _valid_route_labels(self) -> set[str]:
         labels: set[str] = set()
-        flow_definition = self._conversation_flow_definition()
-        for method_definition in flow_definition.methods.values():
-            if method_definition.listen is None or method_definition.router:
-                continue
-            labels.update(_iter_condition_labels(method_definition.listen))
+        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()
-        definition = self._conversation_definition
-        builtin_routes = (
-            tuple(definition.builtin_routes)
-            if definition is not None
-            else self.builtin_routes
-        )
-        internal_routes = (
-            tuple(definition.internal_routes)
-            if definition is not None
-            else self.internal_routes
-        )
         if not custom_routes:
             custom_routes = (
-                self._valid_route_labels() - set(builtin_routes) - set(internal_routes)
+                self._valid_route_labels()
+                - set(self.builtin_routes)
+                - set(self.internal_routes)
             )
-        return custom_routes | set(builtin_routes)
+        return custom_routes | set(self.builtin_routes)
 
     def _default_conversation_llm(self) -> Any | None:
         config = self._conversation_config
@@ -1037,8 +780,7 @@ class _ConversationalMixin:
         # of warning about an empty scope stack.
         started_id = getattr(self, "_deferred_flow_started_event_id", None)
         if started_id:
-            method_outputs = self.method_outputs
-            last_output = method_outputs[-1] if method_outputs else None
+            last_output = self._method_outputs[-1] if self._method_outputs else None
             restore_event_scope(((started_id, "flow_started"),))
             try:
                 crewai_event_bus.emit(
@@ -1061,15 +803,12 @@ class _ConversationalMixin:
 
         trace_listener = TraceCollectionListener()
         batch_manager = trace_listener.batch_manager
-        try:
-            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()
-        finally:
-            batch_manager.defer_session_finalization = False
+        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

@@ -9,9 +9,9 @@ from crewai.flow.conversation import (
     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.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 (

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

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

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

@@ -1,29 +0,0 @@
-"""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
-
-
-__all__ = [
-    "HumanFeedbackResult",
-    "and_",
-    "human_feedback",
-    "listen",
-    "or_",
-    "router",
-    "start",
-]

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

@@ -1,86 +0,0 @@
-"""Flow DSL condition primitives."""
-
-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,
-    FlowConditionType,
-)
-
-
-_CONDITION_TYPES = (AND_CONDITION, OR_CONDITION)
-
-
-def or_(*triggers: FlowTrigger) -> FlowCondition:
-    """Return a condition that fires when any trigger fires."""
-    return _condition_tree(OR_CONDITION, triggers)
-
-
-def and_(*triggers: FlowTrigger) -> FlowCondition:
-    """Return a condition that fires after all triggers fire."""
-    return _condition_tree(AND_CONDITION, triggers)
-
-
-def _trigger_name(value: Any) -> str | None:
-    if isinstance(value, str):
-        return value
-
-    name = getattr(value, "__name__", None)
-    if callable(value) and isinstance(name, str):
-        return name
-
-    return None
-
-
-def _is_condition(value: Any) -> TypeIs[FlowCondition]:
-    return (
-        isinstance(value, dict)
-        and set(value) == {"type", "conditions"}
-        and value["type"] in _CONDITION_TYPES
-        and isinstance(value["conditions"], list)
-        and all(
-            _trigger_name(condition) is not None or _is_condition(condition)
-            for condition in value["conditions"]
-        )
-    )
-
-
-def _coerce_trigger(trigger: FlowTrigger) -> str | FlowCondition:
-    name = _trigger_name(trigger)
-    if name is not None:
-        return name
-    if _is_condition(trigger):
-        return trigger
-    raise ValueError("Invalid condition")
-
-
-def _condition_tree(
-    condition_type: FlowConditionType,
-    triggers: Sequence[FlowTrigger],
-) -> FlowCondition:
-    return {
-        "type": condition_type,
-        "conditions": [_coerce_trigger(trigger) for trigger in triggers],
-    }
-
-
-def _to_definition_condition(condition: FlowTrigger) -> FlowDefinitionCondition:
-    trigger = _coerce_trigger(condition)
-    if isinstance(trigger, str):
-        return trigger
-
-    key = trigger["type"].lower()
-    return {
-        key: [
-            _to_definition_condition(sub_condition)
-            for sub_condition in trigger["conditions"]
-        ]
-    }

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

@@ -1,59 +0,0 @@
-from __future__ import annotations
-
-from collections.abc import Callable, Sequence
-from typing import TYPE_CHECKING, Any, TypeVar
-
-from crewai.flow.human_feedback import (
-    HumanFeedbackConfig,
-    HumanFeedbackResult,
-    _validate_human_feedback_options,
-)
-
-
-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 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.
-
-    The decorator is a pure metadata stamper: it records the feedback
-    configuration on the method, and the Flow engine collects and routes
-    feedback after the method completes, driven by the flow's definition.
-    """
-    _validate_human_feedback_options(
-        emit=emit, llm=llm, default_outcome=default_outcome
-    )
-    config = HumanFeedbackConfig(
-        message=message,
-        emit=list(emit) if emit is not None else None,
-        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:
-        func.__human_feedback_config__ = config  # type: ignore[attr-defined]
-        return func
-
-    return decorator

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

@@ -1,57 +0,0 @@
-from __future__ import annotations
-
-from collections.abc import Callable
-from typing import cast
-
-from crewai.flow.dsl._conditions import _to_definition_condition
-from crewai.flow.dsl._types import FlowMethodDecorator, FlowTrigger
-from crewai.flow.dsl._utils import (
-    P,
-    R,
-    _method_action,
-    _set_flow_method_definition,
-)
-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(
-                do=_method_action(func),
-                listen=_to_definition_condition(condition),
-            ),
-        )
-        return wrapper
-
-    return cast(FlowMethodDecorator, decorator)

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

@@ -1,160 +0,0 @@
-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 _to_definition_condition
-from crewai.flow.dsl._types import FlowMethodDecorator, FlowTrigger
-from crewai.flow.dsl._utils import (
-    P,
-    R,
-    _method_action,
-    _set_flow_method_definition,
-)
-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(
-                do=_method_action(func),
-                listen=_to_definition_condition(condition),
-                router=True,
-                emit=router_events or None,
-            ),
-        )
-        return wrapper
-
-    return cast(FlowMethodDecorator, decorator)

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

@@ -1,70 +0,0 @@
-from __future__ import annotations
-
-from collections.abc import Callable
-from typing import cast
-
-from crewai.flow.dsl._conditions import _to_definition_condition
-from crewai.flow.dsl._types import FlowMethodDecorator, FlowTrigger
-from crewai.flow.dsl._utils import (
-    P,
-    R,
-    _method_action,
-    _set_flow_method_definition,
-)
-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)
-
-        _set_flow_method_definition(
-            wrapper,
-            FlowMethodDefinition(
-                do=_method_action(func),
-                start=(
-                    _to_definition_condition(condition)
-                    if condition is not None
-                    else True
-                ),
-            ),
-        )
-        return wrapper
-
-    return cast(FlowMethodDecorator, decorator)

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

@@ -1,27 +0,0 @@
-"""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

@@ -1,485 +0,0 @@
-from __future__ import annotations
-
-import json
-import logging
-from typing import Any, ParamSpec, TypeVar
-
-from pydantic import BaseModel
-from typing_extensions import TypeIs
-
-from crewai.flow.flow_definition import (
-    FlowActionDefinition,
-    FlowCodeActionDefinition,
-    FlowConfigDefinition,
-    FlowConversationalDefinition,
-    FlowConversationalRouterDefinition,
-    FlowDefinition,
-    FlowDefinitionDiagnostic,
-    FlowHumanFeedbackDefinition,
-    FlowMethodDefinition,
-    FlowPersistenceDefinition,
-    FlowStateDefinition,
-    _object_ref,
-)
-from crewai.flow.flow_wrappers import (
-    FlowMethod,
-)
-
-
-P = ParamSpec("P")
-R = TypeVar("R")
-
-logger = logging.getLogger(__name__)
-
-_FLOW_METHOD_DEFINITION_ATTR = "__flow_method_definition__"
-_FLOW_METHOD_METADATA_ATTRS = [
-    "__conversational_only__",
-    "__flow_method_definition__",
-    "__flow_persistence_config__",
-    "__human_feedback_config__",
-]
-
-
-def is_flow_method(obj: Any) -> TypeIs[FlowMethod[Any, Any]]:
-    """Check if the object carries Flow method wrapper metadata."""
-    return 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 _is_conversational_flow(flow_class: type) -> bool:
-    return bool(getattr(flow_class, "conversational", False))
-
-
-def _get_inherited_conversational_method(
-    flow_class: type,
-    attr_name: str,
-) -> Any | None:
-    if not _is_conversational_flow(flow_class):
-        return None
-
-    for base in flow_class.__mro__[1:]:
-        inherited = base.__dict__.get(attr_name)
-        if inherited is None:
-            continue
-        if getattr(inherited, "__conversational_only__", False) and is_flow_method(
-            inherited
-        ):
-            return inherited
-    return None
-
-
-def _stamp_inherited_conversational_metadata(
-    method: Any,
-    inherited: Any,
-) -> Any:
-    for attr in _FLOW_METHOD_METADATA_ATTRS:
-        if hasattr(inherited, attr):
-            setattr(method, attr, getattr(inherited, attr))
-    return method
-
-
-def _method_action(method: Any) -> FlowActionDefinition:
-    return FlowCodeActionDefinition(ref=f"{method.__module__}:{method.__qualname__}")
-
-
-def _set_flow_method_definition(
-    wrapper: FlowMethod[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 _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)
-    if isinstance(state_value, TypeVar):
-        state_value = None
-    initial_state = getattr(flow_class, "initial_state", None)
-    if initial_state is not None:
-        state_value = initial_state
-
-    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.get_default(call_default_factory=True)
-        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)
-        if field_name == "input_provider":
-            # A string value is already a ref; only live objects degrade.
-            values[field_name] = (
-                value if value is None or isinstance(value, str) else _object_ref(value)
-            )
-        else:
-            values[field_name] = _serialize_static_value(
-                value, diagnostics, f"config.{field_name}"
-            )
-    return FlowConfigDefinition(**values)
-
-
-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 and provider stay live: the engine consumes them in-process and
-        # the contract degrades them to serializable forms at JSON dump time.
-        llm=getattr(config, "llm", None),
-        default_outcome=getattr(config, "default_outcome", None),
-        metadata=_serialize_static_value(
-            getattr(config, "metadata", None), diagnostics, f"{path}.metadata"
-        ),
-        provider=getattr(config, "provider", None),
-        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) -> FlowPersistenceDefinition | None:
-    config = getattr(value, "__flow_persistence_config__", None)
-    if config is None:
-        return None
-    return FlowPersistenceDefinition(
-        enabled=True,
-        verbose=bool(getattr(config, "verbose", False)),
-        # The backend stays live: the engine persists through the exact
-        # instance the user configured; the contract degrades it to a
-        # serialized config at JSON dump time.
-        persistence=getattr(config, "persistence", None),
-    )
-
-
-def _build_conversational_router_definition(
-    router_config: Any,
-    diagnostics: list[FlowDefinitionDiagnostic],
-    path: str,
-) -> FlowConversationalRouterDefinition | None:
-    if router_config is None:
-        return None
-
-    routes = getattr(router_config, "routes", None)
-    return FlowConversationalRouterDefinition(
-        prompt=getattr(router_config, "prompt", None),
-        response_format=_serialize_static_value(
-            getattr(router_config, "response_format", None),
-            diagnostics,
-            f"{path}.response_format",
-        ),
-        llm=_serialize_static_value(
-            getattr(router_config, "llm", None), diagnostics, f"{path}.llm"
-        ),
-        routes=[str(route) for route in routes] if routes is not None else None,
-        route_descriptions=getattr(router_config, "route_descriptions", None),
-        default_intent=getattr(router_config, "default_intent", "converse"),
-        fallback_intent=getattr(router_config, "fallback_intent", "converse"),
-        intent_field=str(getattr(router_config, "intent_field", "intent")),
-    )
-
-
-def _build_conversational_definition(
-    flow_class: type,
-    diagnostics: list[FlowDefinitionDiagnostic],
-) -> FlowConversationalDefinition | None:
-    if not _is_conversational_flow(flow_class):
-        return None
-
-    config = getattr(flow_class, "conversational_config", None)
-    builtin_routes = getattr(flow_class, "builtin_routes", ("converse", "end"))
-    internal_routes = getattr(
-        flow_class,
-        "internal_routes",
-        ("answer_from_history",),
-    )
-    if config is None:
-        return FlowConversationalDefinition(
-            enabled=True,
-            builtin_routes=[str(route) for route in builtin_routes],
-            internal_routes=[str(route) for route in internal_routes],
-        )
-
-    default_intents = getattr(config, "default_intents", None)
-    visible_agent_outputs = getattr(config, "visible_agent_outputs", None)
-    return FlowConversationalDefinition(
-        enabled=True,
-        system_prompt=getattr(config, "system_prompt", None),
-        llm=_serialize_static_value(
-            getattr(config, "llm", None), diagnostics, "conversational.llm"
-        ),
-        router=_build_conversational_router_definition(
-            getattr(config, "router", None),
-            diagnostics,
-            "conversational.router",
-        ),
-        answer_from_history_prompt=getattr(config, "answer_from_history_prompt", None),
-        default_intents=(
-            [str(intent) for intent in default_intents]
-            if default_intents is not None
-            else None
-        ),
-        intent_llm=_serialize_static_value(
-            getattr(config, "intent_llm", None),
-            diagnostics,
-            "conversational.intent_llm",
-        ),
-        answer_from_history_llm=_serialize_static_value(
-            getattr(config, "answer_from_history_llm", None),
-            diagnostics,
-            "conversational.answer_from_history_llm",
-        ),
-        visible_agent_outputs=(
-            "all"
-            if visible_agent_outputs == "all"
-            else [str(output) for output in visible_agent_outputs]
-            if visible_agent_outputs is not None
-            else None
-        ),
-        defer_trace_finalization=bool(
-            getattr(config, "defer_trace_finalization", True)
-        ),
-        builtin_routes=[str(route) for route in builtin_routes],
-        internal_routes=[str(route) for route in internal_routes],
-    )
-
-
-def _build_method_definition(
-    method: Any,
-    diagnostics: list[FlowDefinitionDiagnostic],
-    path: str,
-) -> FlowMethodDefinition:
-    fragment = _get_flow_method_definition(method)
-    if fragment is None:
-        method_definition = FlowMethodDefinition(do=_method_action(method))
-    else:
-        method_definition = fragment.model_copy(
-            deep=True, update={"do": _method_action(method)}
-        )
-
-    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)
-
-    return method_definition
-
-
-def _iter_flow_methods(flow_class: type) -> dict[str, Any]:
-    methods: dict[str, Any] = {}
-    for attr_name in flow_class.__dict__:
-        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
-            continue
-
-        inherited = _get_inherited_conversational_method(flow_class, attr_name)
-        if inherited is not None and callable(attr_value):
-            methods[attr_name] = _stamp_inherited_conversational_metadata(
-                attr_value, inherited
-            )
-
-    if _is_conversational_flow(flow_class):
-        for base in reversed(flow_class.__mro__[1:]):
-            for attr_name, raw_value in base.__dict__.items():
-                if attr_name.startswith("_") or attr_name in methods:
-                    continue
-                if not getattr(raw_value, "__conversational_only__", False):
-                    continue
-                try:
-                    attr_value = getattr(flow_class, attr_name)
-                except AttributeError:
-                    continue
-                if is_flow_method(attr_value) and _should_include_flow_method(
-                    flow_class, attr_value
-                ):
-                    methods[attr_name] = attr_value
-
-    # A wrapped method whose name collides with a base Flow model field
-    # (e.g. ``checkpoint``) is absorbed by Pydantic as a field; the underlying
-    # 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),
-        conversational=_build_conversational_definition(flow_class, diagnostics),
-        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)

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

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

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

@@ -15,10 +15,6 @@ current_flow_id: contextvars.ContextVar[str | None] = contextvars.ContextVar(
     "flow_id", default=None
 )
 
-current_flow_defer_trace_finalization: contextvars.ContextVar[bool] = (
-    contextvars.ContextVar("flow_defer_trace_finalization", default=False)
-)
-
 current_flow_method_name: contextvars.ContextVar[str] = contextvars.ContextVar(
     "flow_method_name", default="unknown"
 )

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

@@ -11,58 +11,28 @@ from __future__ import annotations
 
 import json
 import logging
-import re
 from typing import Any, Literal as TypingLiteral
 
-from pydantic import (
-    BaseModel,
-    ConfigDict,
-    Field,
-    RootModel,
-    field_serializer,
-    model_validator,
-)
+from pydantic import BaseModel, ConfigDict, Field
 import yaml
 
-from crewai.flow.conversational_definition import (
-    FlowConversationalDefinition,
-    FlowConversationalRouterDefinition,
-)
-
 
 logger = logging.getLogger(__name__)
 
 FlowDefinitionCondition = str | dict[str, Any]
-_STEP_NAME_PATTERN = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
 
 __all__ = [
-    "FlowActionDefinition",
-    "FlowCodeActionDefinition",
     "FlowConfigDefinition",
-    "FlowConversationalDefinition",
-    "FlowConversationalRouterDefinition",
     "FlowDefinition",
     "FlowDefinitionCondition",
     "FlowDefinitionDiagnostic",
-    "FlowEachActionDefinition",
-    "FlowEachInnerActionDefinition",
-    "FlowExpressionActionDefinition",
     "FlowHumanFeedbackDefinition",
     "FlowMethodDefinition",
     "FlowPersistenceDefinition",
     "FlowStateDefinition",
-    "FlowToolActionDefinition",
 ]
 
 
-def _object_ref(value: Any) -> str:
-    """Format a class or instance as the canonical ``module:qualname`` ref."""
-    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)
-
-
 class FlowDefinitionDiagnostic(BaseModel):
     """A non-fatal Flow Definition build or validation diagnostic."""
 
@@ -75,10 +45,9 @@ class FlowDefinitionDiagnostic(BaseModel):
 class FlowStateDefinition(BaseModel):
     """Static description of a Flow state contract."""
 
-    type: TypingLiteral["dict", "pydantic", "json_schema", "unknown"] = "dict"
+    type: TypingLiteral["dict", "pydantic", "unknown"] = "dict"
     ref: str | None = None
-    json_schema: dict[str, Any] | None = None
-    default: dict[str, Any] | None = None
+    default: Any = None
 
 
 class FlowConfigDefinition(BaseModel):
@@ -86,50 +55,22 @@ class FlowConfigDefinition(BaseModel):
 
     tracing: bool | None = None
     stream: bool = False
-    memory: dict[str, Any] | None = None
-    input_provider: str | None = None
+    memory: Any = None
+    input_provider: Any = None
     suppress_flow_events: bool = False
     max_method_calls: int = 100
-    defer_trace_finalization: bool = False
-    checkpoint: bool | dict[str, Any] | None = None
 
 
 class FlowPersistenceDefinition(BaseModel):
-    """Static persistence configuration.
-
-    ``persistence`` may hold a live backend when the definition is built from
-    a decorated class — the engine then persists through the exact instance
-    the user configured; the JSON/YAML projection degrades it to its
-    serialized config.
-    """
+    """Static persistence configuration."""
 
     enabled: bool = False
     verbose: bool = False
     persistence: Any = None
 
-    @field_serializer("persistence", when_used="json")
-    def _serialize_persistence(self, value: Any) -> Any:
-        if value is None or isinstance(value, dict):
-            return value
-        if isinstance(value, BaseModel):
-            try:
-                return value.model_dump(mode="json")
-            except Exception:
-                logger.warning(
-                    "Persistence backend %s is not fully serializable; "
-                    "preserved import reference only.",
-                    _object_ref(value),
-                )
-        return {"ref": _object_ref(value)}
-
 
 class FlowHumanFeedbackDefinition(BaseModel):
-    """Static human feedback configuration.
-
-    ``llm`` and ``provider`` may hold live Python objects when the definition
-    is built from a decorated class; the JSON/YAML projection degrades them to
-    a serialized config (``llm``) or a ``module:qualname`` ref (``provider``).
-    """
+    """Static human feedback configuration."""
 
     message: str
     emit: list[str] | None = None
@@ -141,120 +82,10 @@ class FlowHumanFeedbackDefinition(BaseModel):
     learn_source: str = "hitl"
     learn_strict: bool = False
 
-    @field_serializer("llm", when_used="json")
-    def _serialize_llm(self, value: Any) -> dict[str, Any] | str | None:
-        if value is None or isinstance(value, (str, dict)):
-            return value
-        from crewai.flow.human_feedback import _serialize_llm_for_context
-
-        return _serialize_llm_for_context(value)
-
-    @field_serializer("provider", when_used="json")
-    def _serialize_provider(self, value: Any) -> str | None:
-        if value is None or isinstance(value, str):
-            return value
-        return _object_ref(value)
-
-
-class FlowCodeActionDefinition(BaseModel):
-    """A Flow method action that executes importable Python code."""
-
-    model_config = ConfigDict(populate_by_name=True, extra="forbid")
-
-    call: TypingLiteral["code"] = "code"
-    ref: str
-    with_: dict[str, Any] | None = Field(default=None, alias="with")
-
-
-class FlowToolActionDefinition(BaseModel):
-    """A Flow method action that invokes a CrewAI tool."""
-
-    model_config = ConfigDict(populate_by_name=True, extra="forbid")
-
-    call: TypingLiteral["tool"]
-    ref: str
-    with_: dict[str, Any] | None = Field(default=None, alias="with")
-
-
-class FlowExpressionActionDefinition(BaseModel):
-    """A Flow method action that evaluates a CEL expression."""
-
-    model_config = ConfigDict(extra="forbid")
-
-    call: TypingLiteral["expression"]
-    expr: str
-
-
-FlowInnerActionDefinition = (
-    FlowCodeActionDefinition | FlowToolActionDefinition | FlowExpressionActionDefinition
-)
-
-
-class FlowEachInnerActionDefinition(RootModel[dict[str, FlowInnerActionDefinition]]):
-    """One named action inside an ``each`` composite action."""
-
-    @property
-    def name(self) -> str:
-        return next(iter(self.root))
-
-    @property
-    def action(self) -> FlowInnerActionDefinition:
-        return next(iter(self.root.values()))
-
-
-class FlowEachActionDefinition(BaseModel):
-    """A composite action that runs a sequential mini-pipeline for each item."""
-
-    model_config = ConfigDict(populate_by_name=True, extra="forbid")
-
-    call: TypingLiteral["each"]
-    in_: str = Field(alias="in")
-    do: list[FlowEachInnerActionDefinition]
-
-    @model_validator(mode="before")
-    @classmethod
-    def _validate_inner_action_list(cls, data: Any) -> Any:
-        if not isinstance(data, dict) or "do" not in data:
-            return data
-
-        inner_actions = data["do"]
-        if not isinstance(inner_actions, list) or not inner_actions:
-            raise ValueError("each.do must contain at least one action")
-
-        seen: set[str] = set()
-        for inner_action in inner_actions:
-            if isinstance(inner_action, FlowEachInnerActionDefinition):
-                action_mapping = inner_action.root
-            elif isinstance(inner_action, dict):
-                action_mapping = inner_action
-            else:
-                raise ValueError("each.do entries must be one-key mappings")
-
-            if len(action_mapping) != 1:
-                raise ValueError("each.do entries must be one-key mappings")
-
-            name = next(iter(action_mapping))
-            _validate_step_name(name, field="each.do action names")
-            if name in seen:
-                raise ValueError(f"each.do action names must be unique: {name!r}")
-            seen.add(name)
-
-        return data
-
-
-FlowActionDefinition = (
-    FlowCodeActionDefinition
-    | FlowToolActionDefinition
-    | FlowExpressionActionDefinition
-    | FlowEachActionDefinition
-)
-
 
 class FlowMethodDefinition(BaseModel):
     """Static definition of one Flow method and its execution roles."""
 
-    description: str | None = None
-    do: FlowActionDefinition
     start: bool | FlowDefinitionCondition | None = None
     listen: FlowDefinitionCondition | None = None
     router: bool = False
@@ -262,16 +93,6 @@ class FlowMethodDefinition(BaseModel):
     human_feedback: FlowHumanFeedbackDefinition | None = None
     persist: FlowPersistenceDefinition | None = None
 
-    @model_validator(mode="after")
-    def _canonicalize_human_feedback_routing(self) -> FlowMethodDefinition:
-        # Canonical shape: a method whose human_feedback declares emit
-        # outcomes routes like a router, regardless of how the definition
-        # was authored.
-        if self.human_feedback is not None and self.human_feedback.emit:
-            self.router = True
-            self.emit = None
-        return self
-
     @property
     def is_start(self) -> bool:
         """Whether this method is a start method.
@@ -288,24 +109,15 @@ class FlowDefinition(BaseModel):
 
     model_config = ConfigDict(populate_by_name=True, arbitrary_types_allowed=True)
 
-    schema_: TypingLiteral["crewai.flow/v1"] = Field(
-        default="crewai.flow/v1", alias="schema"
-    )
+    schema_: str = Field(default="crewai.flow/v1", alias="schema")
     name: str
     description: str | None = None
     state: FlowStateDefinition | None = None
     config: FlowConfigDefinition = Field(default_factory=FlowConfigDefinition)
     persist: FlowPersistenceDefinition | None = None
-    conversational: FlowConversationalDefinition | None = None
     methods: dict[str, FlowMethodDefinition] = Field(default_factory=dict)
     diagnostics: list[FlowDefinitionDiagnostic] = Field(default_factory=list)
 
-    @model_validator(mode="after")
-    def _validate_method_names(self) -> FlowDefinition:
-        for method_name in self.methods:
-            _validate_step_name(method_name, field="Flow method names")
-        return self
-
     def to_dict(self, *, exclude_none: bool = True) -> dict[str, Any]:
         """Serialize the definition to a JSON/YAML-ready dictionary."""
         return self.model_dump(by_alias=True, exclude_none=exclude_none, mode="json")
@@ -448,11 +260,6 @@ def _deserialize_diagnostics(value: Any) -> list[FlowDefinitionDiagnostic]:
     return [FlowDefinitionDiagnostic.model_validate(item) for item in value or []]
 
 
-def _validate_step_name(name: str, *, field: str) -> None:
-    if not isinstance(name, str) or not _STEP_NAME_PATTERN.fullmatch(name):
-        raise ValueError(f"{field} must match {_STEP_NAME_PATTERN.pattern}")
-
-
 def _merge_diagnostics(
     *diagnostic_groups: list[FlowDefinitionDiagnostic],
 ) -> list[FlowDefinitionDiagnostic]:

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

@@ -16,6 +16,7 @@ P = ParamSpec("P")
 R = TypeVar("R")
 
 FlowConditionType: TypeAlias = Literal["OR", "AND"]
+SimpleFlowCondition: TypeAlias = tuple[FlowConditionType, list[FlowMethodName]]
 
 __all__ = [
     "FlowCondition",
@@ -24,6 +25,7 @@ __all__ = [
     "FlowMethod",
     "ListenMethod",
     "RouterMethod",
+    "SimpleFlowCondition",
     "StartMethod",
 ]
 
@@ -35,14 +37,16 @@ class FlowCondition(TypedDict, total=False):
 
     Attributes:
         type: The type of the condition.
-        conditions: A sequence of route labels, method names, or nested conditions.
+        conditions: A list of conditions types.
+        methods: A list of methods.
     """
 
     type: Required[FlowConditionType]
-    conditions: Sequence[str | FlowCondition]
+    conditions: Sequence[FlowMethodName | FlowCondition]
+    methods: list[FlowMethodName]
 
 
-FlowConditions: TypeAlias = Sequence[str | FlowCondition]
+FlowConditions: TypeAlias = list[FlowMethodName | FlowCondition]
 
 
 class FlowMethod(Generic[P, R]):
@@ -79,10 +83,13 @@ class FlowMethod(Generic[P, R]):
 
         # Preserve flow-related attributes from wrapped method (e.g., from @human_feedback)
         for attr in [
+            "__is_router__",
+            "__router_emit__",
             "__human_feedback_config__",
             "__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))
@@ -151,10 +158,25 @@ class FlowMethod(Generic[P, R]):
 class StartMethod(FlowMethod[P, R]):
     """Wrapper for methods marked as flow start points."""
 
+    __is_start_method__: bool = True
+    __trigger_methods__: list[FlowMethodName] | None = None
+    __condition_type__: FlowConditionType | None = None
+    __trigger_condition__: FlowCondition | None = None
+
 
 class ListenMethod(FlowMethod[P, R]):
     """Wrapper for methods marked as flow listeners."""
 
+    __trigger_methods__: list[FlowMethodName] | None = None
+    __condition_type__: FlowConditionType | None = None
+    __trigger_condition__: FlowCondition | None = None
+
 
 class RouterMethod(FlowMethod[P, R]):
     """Wrapper for methods marked as flow routers."""
+
+    __is_router__: bool = True
+    __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

@@ -1,11 +1,8 @@
-"""Human feedback support for Flow methods.
+"""Human feedback decorator for Flow methods.
 
-This module backs the @human_feedback decorator that enables human-in-the-loop
-workflows within CrewAI Flows. The decorator is a pure metadata stamper: it
-records a :class:`HumanFeedbackConfig` on the method, the Flow definition
-builder lifts it into ``FlowHumanFeedbackDefinition``, and the Flow engine
-collects feedback after each decorated method completes, driven by the flow's
-definition.
+This module provides the @human_feedback decorator that enables human-in-the-loop
+workflows within CrewAI Flows. It allows collecting human feedback on method outputs
+and optionally routing to different listeners based on the feedback.
 
 Supports both synchronous (blocking) and asynchronous (non-blocking) feedback
 collection through the provider parameter.
@@ -58,18 +55,23 @@ Example (asynchronous with custom provider):
 
 from __future__ import annotations
 
+import asyncio
 from collections.abc import Callable, Sequence
 from dataclasses import dataclass, field
 from datetime import datetime
+from functools import wraps
 import logging
 from typing import TYPE_CHECKING, Any, TypeVar
 
 from pydantic import BaseModel, Field
 
+from crewai.flow.flow_definition import FlowMethodDefinition
+from crewai.flow.flow_wrappers import FlowMethod
+
 
 if TYPE_CHECKING:
     from crewai.flow.async_feedback.types import HumanFeedbackProvider
-    from crewai.flow.runtime import Flow
+    from crewai.flow.flow import Flow
     from crewai.llms.base_llm import BaseLLM
 
 
@@ -159,8 +161,8 @@ class HumanFeedbackResult:
 class HumanFeedbackConfig:
     """Configuration for the @human_feedback decorator.
 
-    Stores the parameters passed to the decorator for later use by the
-    Flow definition builder and for introspection by visualization tools.
+    Stores the parameters passed to the decorator for later use during
+    method execution and for introspection by visualization tools.
 
     Attributes:
         message: The message shown to the human when requesting feedback.
@@ -182,6 +184,23 @@ class HumanFeedbackConfig:
     learn_strict: bool = False
 
 
+class HumanFeedbackMethod(FlowMethod[Any, Any]):
+    """Wrapper for methods decorated with @human_feedback.
+
+    This wrapper extends FlowMethod to add human feedback specific attributes
+    that are used by FlowMeta for routing and by visualization tools.
+
+    Attributes:
+        __is_router__: True when emit is specified, enabling router behavior.
+        __router_emit__: List of possible outcomes when acting as a router.
+        __human_feedback_config__: The HumanFeedbackConfig for this method.
+    """
+
+    __is_router__: bool = False
+    __router_emit__: list[str] | None = None
+    __human_feedback_config__: HumanFeedbackConfig | None = None
+
+
 class PreReviewResult(BaseModel):
     """Structured output from the HITL pre-review LLM call."""
 
@@ -203,11 +222,113 @@ class DistilledLessons(BaseModel):
     )
 
 
-def _validate_human_feedback_options(
-    emit: Sequence[str] | None,
-    llm: Any,
-    default_outcome: str | None,
-) -> None:
+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.
+
+    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(
@@ -224,163 +345,341 @@ def _validate_human_feedback_options(
     elif default_outcome is not None:
         raise ValueError("default_outcome requires emit to be specified.")
 
+    def decorator(func: F) -> F:
+        def _get_hitl_prompt(key: str) -> str:
+            from crewai.utilities.i18n import I18N_DEFAULT
 
-def _get_hitl_prompt(key: str) -> str:
-    from crewai.utilities.i18n import I18N_DEFAULT
+            return I18N_DEFAULT.slice(key)
 
-    return I18N_DEFAULT.slice(key)
+        def _resolve_llm_instance() -> Any:
+            if llm is None:
+                from crewai.llm import LLM
 
+                return LLM(model="gpt-4o-mini")
+            if isinstance(llm, str):
+                from crewai.llm import LLM
 
-def _resolve_llm_instance(llm: Any) -> Any:
-    from crewai.llm import LLM
+                return LLM(model=llm)
+            return llm  # already a BaseLLM instance
 
-    if llm is None:
-        return LLM(model="gpt-4o-mini")
-    if isinstance(llm, str):
-        return LLM(model=llm)
-    if isinstance(llm, dict):
-        deserialized = _deserialize_llm_from_context(llm)
-        return deserialized if deserialized is not None else LLM(model="gpt-4o-mini")
-    return llm  # already a BaseLLM instance
+        def _pre_review_with_lessons(
+            flow_instance: Flow[Any], method_output: Any
+        ) -> Any:
+            try:
+                mem = flow_instance.memory
+                if mem is None:
+                    return method_output
+                query = f"human feedback lessons for {func.__name__}: {method_output!s}"
+                matches = mem.recall(query, source=learn_source)
+                if not matches:
+                    return method_output
 
+                lessons = "\n".join(f"- {m.record.content}" for m in matches)
+                llm_inst = _resolve_llm_instance()
+                prompt = _get_hitl_prompt("hitl_pre_review_user").format(
+                    output=str(method_output),
+                    lessons=lessons,
+                )
+                messages = [
+                    {
+                        "role": "system",
+                        "content": _get_hitl_prompt("hitl_pre_review_system"),
+                    },
+                    {"role": "user", "content": prompt},
+                ]
+                if getattr(llm_inst, "supports_function_calling", lambda: False)():
+                    response = llm_inst.call(messages, response_model=PreReviewResult)
+                    if isinstance(response, PreReviewResult):
+                        return response.improved_output
+                    return PreReviewResult.model_validate(response).improved_output
+                reviewed = llm_inst.call(messages)
+                return reviewed if isinstance(reviewed, str) else str(reviewed)
+            except Exception:
+                if learn_strict:
+                    logger.warning(
+                        "HITL pre-review failed for %s; re-raising (learn_strict=True)",
+                        func.__name__,
+                        exc_info=True,
+                    )
+                    raise
+                logger.warning(
+                    "HITL pre-review failed for %s; falling back to raw output",
+                    func.__name__,
+                    exc_info=True,
+                )
+                return method_output
 
-def _pre_review_with_lessons(
-    flow_instance: Flow[Any],
-    method_name: str,
-    method_output: Any,
-    *,
-    llm: Any,
-    learn_source: str,
-    learn_strict: bool,
-) -> Any:
-    try:
-        mem = flow_instance.memory
-        if mem is None:
-            return method_output
-        query = f"human feedback lessons for {method_name}: {method_output!s}"
-        matches = mem.recall(query, source=learn_source)
-        if not matches:
-            return method_output
-
-        lessons = "\n".join(f"- {m.record.content}" for m in matches)
-        llm_inst = _resolve_llm_instance(llm)
-        prompt = _get_hitl_prompt("hitl_pre_review_user").format(
-            output=str(method_output),
-            lessons=lessons,
-        )
-        messages = [
-            {
-                "role": "system",
-                "content": _get_hitl_prompt("hitl_pre_review_system"),
-            },
-            {"role": "user", "content": prompt},
-        ]
-        if getattr(llm_inst, "supports_function_calling", lambda: False)():
-            response = llm_inst.call(messages, response_model=PreReviewResult)
-            if isinstance(response, PreReviewResult):
-                return response.improved_output
-            return PreReviewResult.model_validate(response).improved_output
-        reviewed = llm_inst.call(messages)
-        return reviewed if isinstance(reviewed, str) else str(reviewed)
-    except Exception:
-        if learn_strict:
-            logger.warning(
-                "HITL pre-review failed for %s; re-raising (learn_strict=True)",
-                method_name,
-                exc_info=True,
-            )
-            raise
-        logger.warning(
-            "HITL pre-review failed for %s; falling back to raw output",
-            method_name,
-            exc_info=True,
-        )
-        return method_output
-
-
-def _distill_and_store_lessons(
-    flow_instance: Flow[Any],
-    method_name: str,
-    method_output: Any,
-    raw_feedback: str,
-    *,
-    llm: Any,
-    learn_source: str,
-    learn_strict: bool,
-) -> None:
-    try:
-        mem = flow_instance.memory
-        if mem is None:
-            return
-        llm_inst = _resolve_llm_instance(llm)
-        prompt = _get_hitl_prompt("hitl_distill_user").format(
-            method_name=method_name,
-            output=str(method_output),
-            feedback=raw_feedback,
-        )
-        messages = [
-            {
-                "role": "system",
-                "content": _get_hitl_prompt("hitl_distill_system"),
-            },
-            {"role": "user", "content": prompt},
-        ]
-
-        lessons: list[str] = []
-        if getattr(llm_inst, "supports_function_calling", lambda: False)():
-            response = llm_inst.call(messages, response_model=DistilledLessons)
-            if isinstance(response, DistilledLessons):
-                lessons = response.lessons
-            else:
-                lessons = DistilledLessons.model_validate(response).lessons
-        else:
-            response = llm_inst.call(messages)
-            if isinstance(response, str):
-                lessons = [
-                    line.strip("- ").strip()
-                    for line in response.strip().split("\n")
-                    if line.strip() and line.strip() != "NONE"
+        def _distill_and_store_lessons(
+            flow_instance: Flow[Any], method_output: Any, raw_feedback: str
+        ) -> None:
+            try:
+                mem = flow_instance.memory
+                if mem is None:
+                    return
+                llm_inst = _resolve_llm_instance()
+                prompt = _get_hitl_prompt("hitl_distill_user").format(
+                    method_name=func.__name__,
+                    output=str(method_output),
+                    feedback=raw_feedback,
+                )
+                messages = [
+                    {
+                        "role": "system",
+                        "content": _get_hitl_prompt("hitl_distill_system"),
+                    },
+                    {"role": "user", "content": prompt},
                 ]
 
-        if lessons:
-            mem.remember_many(lessons, source=learn_source)  # type: ignore[union-attr]
-    except Exception:
-        if learn_strict:
-            logger.warning(
-                "HITL lesson distillation failed for %s; re-raising (learn_strict=True)",
-                method_name,
-                exc_info=True,
+                lessons: list[str] = []
+                if getattr(llm_inst, "supports_function_calling", lambda: False)():
+                    response = llm_inst.call(messages, response_model=DistilledLessons)
+                    if isinstance(response, DistilledLessons):
+                        lessons = response.lessons
+                    else:
+                        lessons = DistilledLessons.model_validate(response).lessons
+                else:
+                    response = llm_inst.call(messages)
+                    if isinstance(response, str):
+                        lessons = [
+                            line.strip("- ").strip()
+                            for line in response.strip().split("\n")
+                            if line.strip() and line.strip() != "NONE"
+                        ]
+
+                if lessons:
+                    mem.remember_many(lessons, source=learn_source)  # type: ignore[union-attr]
+            except Exception:
+                if learn_strict:
+                    logger.warning(
+                        "HITL lesson distillation failed for %s; re-raising (learn_strict=True)",
+                        func.__name__,
+                        exc_info=True,
+                    )
+                    raise
+                logger.warning(
+                    "HITL lesson distillation failed for %s; no lessons stored",
+                    func.__name__,
+                    exc_info=True,
+                )
+
+        def _build_feedback_context(
+            flow_instance: Flow[Any], method_output: Any
+        ) -> tuple[Any, Any]:
+            from crewai.flow.async_feedback.types import PendingFeedbackContext
+
+            context = PendingFeedbackContext(
+                flow_id=flow_instance.flow_id or "unknown",
+                flow_class=f"{flow_instance.__class__.__module__}.{flow_instance.__class__.__name__}",
+                method_name=func.__name__,
+                method_output=method_output,
+                message=message,
+                emit=list(emit) if emit else None,
+                default_outcome=default_outcome,
+                metadata=metadata or {},
+                llm=llm if isinstance(llm, str) else _serialize_llm_for_context(llm),
             )
-            raise
-        logger.warning(
-            "HITL lesson distillation failed for %s; no lessons stored",
-            method_name,
-            exc_info=True,
+
+            effective_provider = provider
+            if effective_provider is None:
+                from crewai.flow.flow_config import flow_config
+
+                effective_provider = flow_config.hitl_provider
+
+            return context, effective_provider
+
+        def _request_feedback(flow_instance: Flow[Any], method_output: Any) -> str:
+            context, effective_provider = _build_feedback_context(
+                flow_instance, method_output
+            )
+
+            if effective_provider is not None:
+                feedback_result = effective_provider.request_feedback(
+                    context, flow_instance
+                )
+                if asyncio.iscoroutine(feedback_result):
+                    raise TypeError(
+                        f"Provider {type(effective_provider).__name__}.request_feedback() "
+                        "returned a coroutine in a sync flow method. Use an async flow "
+                        "method or a synchronous provider."
+                    )
+                return str(feedback_result)
+            return flow_instance._request_human_feedback(
+                message=message,
+                output=method_output,
+                metadata=metadata,
+                emit=emit,
+            )
+
+        async def _request_feedback_async(
+            flow_instance: Flow[Any], method_output: Any
+        ) -> str:
+            context, effective_provider = _build_feedback_context(
+                flow_instance, method_output
+            )
+
+            if effective_provider is not None:
+                feedback_result = effective_provider.request_feedback(
+                    context, flow_instance
+                )
+                if asyncio.iscoroutine(feedback_result):
+                    return str(await feedback_result)
+                return str(feedback_result)
+            return flow_instance._request_human_feedback(
+                message=message,
+                output=method_output,
+                metadata=metadata,
+                emit=emit,
+            )
+
+        def _process_feedback(
+            flow_instance: Flow[Any],
+            method_output: Any,
+            raw_feedback: str,
+        ) -> HumanFeedbackResult | str:
+            collapsed_outcome: str | None = None
+
+            if not raw_feedback.strip():
+                if default_outcome:
+                    collapsed_outcome = default_outcome
+                elif emit:
+                    collapsed_outcome = emit[0]
+            elif emit:
+                if llm is not None:
+                    collapsed_outcome = flow_instance._collapse_to_outcome(
+                        feedback=raw_feedback,
+                        outcomes=emit,
+                        llm=llm,
+                    )
+                else:
+                    collapsed_outcome = emit[0]
+
+            result = HumanFeedbackResult(
+                output=method_output,
+                feedback=raw_feedback,
+                outcome=collapsed_outcome,
+                timestamp=datetime.now(),
+                method_name=func.__name__,
+                metadata=metadata or {},
+            )
+
+            flow_instance.human_feedback_history.append(result)
+            flow_instance.last_human_feedback = result
+
+            if emit:
+                if collapsed_outcome is None:
+                    collapsed_outcome = default_outcome or emit[0]
+                    result.outcome = collapsed_outcome
+                return collapsed_outcome
+            return result
+
+        if asyncio.iscoroutinefunction(func):
+
+            @wraps(func)
+            async def async_wrapper(self: Flow[Any], *args: Any, **kwargs: Any) -> Any:
+                method_output = await func(self, *args, **kwargs)
+
+                if learn and getattr(self, "memory", None) is not None:
+                    method_output = _pre_review_with_lessons(self, method_output)
+
+                raw_feedback = await _request_feedback_async(self, method_output)
+                result = _process_feedback(self, method_output, raw_feedback)
+
+                if (
+                    learn
+                    and getattr(self, "memory", None) is not None
+                    and raw_feedback.strip()
+                ):
+                    _distill_and_store_lessons(self, method_output, raw_feedback)
+
+                # Stash the real method output for final flow result when emit is set:
+                # result is the collapsed outcome string for routing, but we preserve the
+                # actual method output as the flow's final result. Uses per-method dict for
+                # concurrency safety and to handle None returns.
+                if emit:
+                    self._human_feedback_method_outputs[func.__name__] = method_output
+
+                return result
+
+            wrapper: Any = async_wrapper
+        else:
+
+            @wraps(func)
+            def sync_wrapper(self: Flow[Any], *args: Any, **kwargs: Any) -> Any:
+                method_output = func(self, *args, **kwargs)
+
+                if learn and getattr(self, "memory", None) is not None:
+                    method_output = _pre_review_with_lessons(self, method_output)
+
+                raw_feedback = _request_feedback(self, method_output)
+                result = _process_feedback(self, method_output, raw_feedback)
+
+                if (
+                    learn
+                    and getattr(self, "memory", None) is not None
+                    and raw_feedback.strip()
+                ):
+                    _distill_and_store_lessons(self, method_output, raw_feedback)
+
+                # Stash the real method output for final flow result when emit is set:
+                # result is the collapsed outcome string for routing, but we preserve the
+                # actual method output as the flow's final result. Uses per-method dict for
+                # concurrency safety and to handle None returns.
+                if emit:
+                    self._human_feedback_method_outputs[func.__name__] = method_output
+
+                return result
+
+            wrapper = sync_wrapper
+
+        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))
+
+        # 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_emit__ = list(emit)
+            # Keep the definition fragment in sync: emit promotes the method to
+            # a router and the feedback outcomes replace any emit recorded by an
+            # inner @router. Copy before updating so the wrapped method's own
+            # fragment (shared by reference) is left untouched.
+            fragment = getattr(wrapper, "__flow_method_definition__", None)
+            if isinstance(fragment, FlowMethodDefinition):
+                wrapper.__flow_method_definition__ = fragment.model_copy(
+                    update={"router": True, "emit": list(emit)}
+                )
 
-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
+        # 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._human_feedback_llm = llm
 
-    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,
-    )
+        return wrapper  # type: ignore[no-any-return]
+
+    return decorator

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

@@ -24,20 +24,22 @@ Example:
 
 from __future__ import annotations
 
+import asyncio
 from collections.abc import Callable
+import functools
 import logging
 from types import SimpleNamespace
-from typing import TYPE_CHECKING, Any, Final, TypeVar
+from typing import TYPE_CHECKING, Any, Final, TypeVar, cast
 
 from crewai_core.printer import PRINTER
 from pydantic import BaseModel
 
 from crewai.flow.persistence.base import FlowPersistence
-from crewai.flow.persistence.factory import default_flow_persistence
+from crewai.flow.persistence.sqlite import SQLiteFlowPersistence
 
 
 if TYPE_CHECKING:
-    from crewai.flow.runtime import Flow
+    from crewai.flow.flow import Flow
 
 
 logger = logging.getLogger(__name__)
@@ -64,6 +66,20 @@ def _stamp_persistence_metadata(
     )
 
 
+_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."""
 
@@ -154,15 +170,9 @@ def persist(
     states. When applied at the method level, it persists only that method's
     state.
 
-    The decorator is a pure metadata stamper: it records the persistence
-    configuration on the class or method, and the Flow engine saves state
-    after each persisted method completes, driven by the flow's definition.
-
     Args:
         persistence: Optional FlowPersistence implementation to use.
-                    If not provided, uses ``default_flow_persistence()`` (the
-                    registered factory when present, else the built-in SQLite
-                    fallback).
+                    If not provided, uses SQLiteFlowPersistence.
         verbose: Whether to log persistence operations. Defaults to False.
 
     Returns:
@@ -181,11 +191,127 @@ def persist(
     """
 
     def decorator(target: type | Callable[..., T]) -> type | Callable[..., T]:
-        actual_persistence = (
-            persistence if persistence is not None else default_flow_persistence()
-        )
+        actual_persistence = persistence or SQLiteFlowPersistence()
 
-        _stamp_persistence_metadata(target, actual_persistence, verbose)
-        return target
+        if isinstance(target, type):
+            _stamp_persistence_metadata(target, actual_persistence, verbose)
+            original_init = target.__init__  # type: ignore[misc]
+
+            @functools.wraps(original_init)
+            def new_init(self: Any, *args: Any, **kwargs: Any) -> None:
+                if "persistence" not in kwargs:
+                    kwargs["persistence"] = actual_persistence
+                original_init(self, *args, **kwargs)
+
+            target.__init__ = new_init  # type: ignore[misc]
+
+            # Preserve original methods' decorators
+            original_methods = {
+                name: method
+                for name, method in target.__dict__.items()
+                if callable(method)
+                and (
+                    hasattr(method, "__is_start_method__")
+                    or hasattr(method, "__trigger_methods__")
+                    or hasattr(method, "__condition_type__")
+                    or hasattr(method, "__is_flow_method__")
+                    or hasattr(method, "__is_router__")
+                )
+            }
+
+            for name, method in original_methods.items():
+                if asyncio.iscoroutinefunction(method):
+                    # Closure captures the current name and method
+                    def create_async_wrapper(
+                        method_name: str, original_method: Callable[..., Any]
+                    ) -> Callable[..., Any]:
+                        @functools.wraps(original_method)
+                        async def method_wrapper(
+                            self: Any, *args: Any, **kwargs: Any
+                        ) -> Any:
+                            result = await original_method(self, *args, **kwargs)
+                            PersistenceDecorator.persist_state(
+                                self, method_name, actual_persistence, verbose
+                            )
+                            return result
+
+                        return method_wrapper
+
+                    wrapped = create_async_wrapper(name, method)
+
+                    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]
+
+                    setattr(target, name, wrapped)
+                else:
+
+                    def create_sync_wrapper(
+                        method_name: str, original_method: Callable[..., Any]
+                    ) -> Callable[..., Any]:
+                        @functools.wraps(original_method)
+                        def method_wrapper(self: Any, *args: Any, **kwargs: Any) -> Any:
+                            result = original_method(self, *args, **kwargs)
+                            PersistenceDecorator.persist_state(
+                                self, method_name, actual_persistence, verbose
+                            )
+                            return result
+
+                        return method_wrapper
+
+                    wrapped = create_sync_wrapper(name, method)
+
+                    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]
+
+                    setattr(target, name, wrapped)
+
+            return target
+        method = target
+        method.__is_flow_method__ = True  # type: ignore[attr-defined]
+        _stamp_persistence_metadata(method, actual_persistence, verbose)
+
+        if asyncio.iscoroutinefunction(method):
+
+            @functools.wraps(method)
+            async def method_async_wrapper(
+                flow_instance: Any, *args: Any, **kwargs: Any
+            ) -> T:
+                method_coro = method(flow_instance, *args, **kwargs)
+                if asyncio.iscoroutine(method_coro):
+                    result = await method_coro
+                else:
+                    result = method_coro
+                PersistenceDecorator.persist_state(
+                    flow_instance, method.__name__, actual_persistence, verbose
+                )
+                return cast(T, result)
+
+            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)
+        def method_sync_wrapper(flow_instance: Any, *args: Any, **kwargs: Any) -> T:
+            result = method(flow_instance, *args, **kwargs)
+            PersistenceDecorator.persist_state(
+                flow_instance, method.__name__, actual_persistence, verbose
+            )
+            return result
+
+        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/persistence/factory.py

@@ -1,60 +0,0 @@
-"""Pluggable default persistence backend for flows.
-
-By default, ``@persist`` and the flow runtime persist state with
-:class:`~crewai.flow.persistence.sqlite.SQLiteFlowPersistence` when no explicit
-``persistence=`` is given. Registering a factory via
-:func:`set_flow_persistence_factory` lets an application back flow state with a
-custom :class:`~crewai.flow.persistence.base.FlowPersistence` -- a database, a
-remote service, an in-memory fake for tests -- without passing a
-``persistence=`` instance at every ``@persist`` / kickoff site.
-
-This mirrors :func:`crewai_core.lock_store.set_lock_backend`: a one-time,
-process-wide setter intended for application startup. Pass ``None`` to restore
-the built-in SQLite default. Call :func:`default_flow_persistence` to build the
-default backend (the registered factory if any, else SQLite).
-"""
-
-from __future__ import annotations
-
-from collections.abc import Callable
-from typing import TYPE_CHECKING
-
-
-if TYPE_CHECKING:
-    from crewai.flow.persistence.base import FlowPersistence
-
-FlowPersistenceFactory = Callable[[], "FlowPersistence"]
-
-_factory: FlowPersistenceFactory | None = None
-
-
-def set_flow_persistence_factory(factory: FlowPersistenceFactory | None) -> None:
-    """Replace the process-wide default flow persistence factory.
-
-    Intended for one-time setup at startup. Pass ``None`` to restore the
-    built-in ``SQLiteFlowPersistence``. Only affects flows that fall back to
-    the default; an explicit ``persistence=`` instance always wins.
-
-    The default is resolved at each fall-back site (``@persist`` and the
-    runtime's pause/resume paths), so the factory may be called more than once
-    for a single flow. Return instances backed by shared durable state (or a
-    singleton) so state saved on one call is visible to the next -- the
-    built-in SQLite default satisfies this by sharing one on-disk file.
-    """
-    global _factory
-    _factory = factory
-
-
-def default_flow_persistence() -> FlowPersistence:
-    """Build the default flow persistence backend.
-
-    Returns the result of the registered factory if one is set, otherwise a
-    built-in :class:`~crewai.flow.persistence.sqlite.SQLiteFlowPersistence`.
-    """
-    factory = _factory
-    if factory is not None:
-        return factory()
-
-    from crewai.flow.persistence.sqlite import SQLiteFlowPersistence
-
-    return SQLiteFlowPersistence()

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

@@ -1,48 +0,0 @@
-"""Build FlowDefinition actions into live runtime callables."""
-
-from __future__ import annotations
-
-from collections.abc import Callable
-from typing import TYPE_CHECKING, Any
-
-from crewai.flow.flow_definition import (
-    FlowActionDefinition,
-    FlowInnerActionDefinition,
-)
-from crewai.flow.runtime._actions._base import ActionHandlerRegistry
-from crewai.flow.runtime._actions._code import CodeActionHandler
-from crewai.flow.runtime._actions._each import EachActionHandler
-from crewai.flow.runtime._actions._expression import ExpressionActionHandler
-from crewai.flow.runtime._actions._tool import ToolActionHandler
-
-
-if TYPE_CHECKING:
-    from crewai.flow.runtime import Flow
-
-
-__all__ = [
-    "build_action",
-]
-
-
-_SIMPLE_ACTION_HANDLERS = (
-    CodeActionHandler(),
-    ToolActionHandler(),
-    ExpressionActionHandler(),
-)
-
-_SIMPLE_ACTION_REGISTRY = ActionHandlerRegistry[FlowInnerActionDefinition](
-    _SIMPLE_ACTION_HANDLERS
-)
-
-_ACTION_REGISTRY = ActionHandlerRegistry[FlowActionDefinition](
-    (
-        *_SIMPLE_ACTION_HANDLERS,
-        EachActionHandler(_SIMPLE_ACTION_REGISTRY),
-    )
-)
-
-
-def build_action(flow: Flow[Any], action: FlowActionDefinition) -> Callable[..., Any]:
-    """Turn one `do:` action into the callable the flow runs for that node."""
-    return _ACTION_REGISTRY.build(flow, action)

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

@@ -1,39 +0,0 @@
-"""Shared action handler contracts."""
-
-from __future__ import annotations
-
-from collections.abc import Callable, Iterable
-from typing import TYPE_CHECKING, Any, Generic, Protocol, TypeVar
-
-from pydantic import BaseModel
-
-
-if TYPE_CHECKING:
-    from crewai.flow.runtime import Flow
-
-
-ActionT = TypeVar("ActionT", bound=BaseModel)
-ResolvedAction = Callable[..., Any]
-
-
-class ActionHandler(Protocol[ActionT]):
-    """Handler for one concrete FlowDefinition action type."""
-
-    action_type: type[ActionT]
-
-    def build(self, flow: Flow[Any], action: ActionT) -> ResolvedAction:
-        """Build the callable executed by the flow."""
-
-
-class ActionHandlerRegistry(Generic[ActionT]):
-    """Build action callables with an ordered set of typed handlers."""
-
-    def __init__(self, handlers: Iterable[ActionHandler[Any]]) -> None:
-        self._handlers = tuple(handlers)
-
-    def build(self, flow: Flow[Any], action: ActionT) -> ResolvedAction:
-        for handler in self._handlers:
-            if isinstance(action, handler.action_type):
-                return handler.build(flow, action)
-        call = getattr(action, "call", None)
-        raise ValueError(f"unknown call type {call!r}")

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

@@ -1,51 +0,0 @@
-"""Handler for ``call: code`` FlowDefinition actions."""
-
-from __future__ import annotations
-
-from collections.abc import Callable
-import functools
-from typing import TYPE_CHECKING, Any, cast
-
-from crewai.flow.flow_definition import FlowCodeActionDefinition
-from crewai.flow.runtime._actions._base import ResolvedAction
-from crewai.flow.runtime._actions._runtime import LOCAL_CONTEXT_KWARG
-from crewai.flow.runtime._expressions import render_with_block
-from crewai.flow.runtime._refs import InvalidRefError, resolve_ref
-
-
-if TYPE_CHECKING:
-    from crewai.flow.runtime import Flow
-
-
-class CodeActionHandler:
-    """Build importable Python callables and bind them to the running flow."""
-
-    action_type = FlowCodeActionDefinition
-
-    def build(
-        self, flow: Flow[Any], action: FlowCodeActionDefinition
-    ) -> ResolvedAction:
-        handler = _resolve_code_handler(flow, action)
-
-        def run_code(*args: Any, **kwargs: Any) -> Any:
-            local_context = kwargs.pop(LOCAL_CONTEXT_KWARG, None)
-            if action.with_ is None:
-                return handler(*args, **kwargs)
-            return handler(
-                **render_with_block(flow, action.with_, local_context=local_context)
-            )
-
-        return functools.update_wrapper(run_code, handler)
-
-
-def _resolve_code_handler(
-    flow: Flow[Any], action: FlowCodeActionDefinition
-) -> Callable[..., Any]:
-    ref = action.ref
-    target = resolve_ref(ref, field="do")
-    if not callable(target):
-        raise InvalidRefError(f"invalid do ref {ref!r}; object is not callable")
-    handler = cast(Callable[..., Any], target)
-    if getattr(handler, "__self__", None) is None:
-        handler = handler.__get__(flow, type(flow))
-    return handler

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

@@ -1,73 +0,0 @@
-"""Handler for ``call: each`` FlowDefinition actions."""
-
-from __future__ import annotations
-
-from collections.abc import Callable
-from typing import TYPE_CHECKING, Any
-
-from crewai.flow.flow_definition import (
-    FlowEachActionDefinition,
-    FlowEachInnerActionDefinition,
-    FlowInnerActionDefinition,
-)
-from crewai.flow.runtime._actions._base import (
-    ActionHandlerRegistry,
-    ResolvedAction,
-)
-from crewai.flow.runtime._actions._runtime import (
-    LOCAL_CONTEXT_KWARG,
-    ensure_array,
-    invoke_callable,
-)
-from crewai.flow.runtime._expressions import evaluate_expression
-
-
-if TYPE_CHECKING:
-    from crewai.flow.runtime import Flow
-
-
-class EachActionHandler:
-    """Build a sequential mini-pipeline for every item in an array."""
-
-    action_type = FlowEachActionDefinition
-
-    def __init__(
-        self, inner_registry: ActionHandlerRegistry[FlowInnerActionDefinition]
-    ) -> None:
-        self._inner_registry = inner_registry
-
-    def build(
-        self, flow: Flow[Any], action: FlowEachActionDefinition
-    ) -> ResolvedAction:
-        inner_actions = [
-            (inner_action.name, self._resolve_inner_action(flow, inner_action))
-            for inner_action in action.do
-        ]
-
-        async def run_each(*_args: Any, **_kwargs: Any) -> list[Any]:
-            items = ensure_array(evaluate_expression(flow, action.in_))
-            results: list[Any] = []
-            for item in items:
-                local_outputs: dict[str, Any] = {}
-                last_output: Any = None
-                for name, run_inner_action in inner_actions:
-                    last_output = await run_inner_action(
-                        {"item": item, "outputs": local_outputs}
-                    )
-                    local_outputs[name] = last_output
-                results.append(last_output)
-            return results
-
-        return run_each
-
-    def _resolve_inner_action(
-        self, flow: Flow[Any], inner_action: FlowEachInnerActionDefinition
-    ) -> Callable[[dict[str, Any]], Any]:
-        run_action = self._inner_registry.build(flow, inner_action.action)
-
-        async def run_inner_action(local_context: dict[str, Any]) -> Any:
-            return await invoke_callable(
-                run_action, **{LOCAL_CONTEXT_KWARG: local_context}
-            )
-
-        return run_inner_action

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

@@ -1,29 +0,0 @@
-"""Handler for ``call: expression`` FlowDefinition actions."""
-
-from __future__ import annotations
-
-from typing import TYPE_CHECKING, Any
-
-from crewai.flow.flow_definition import FlowExpressionActionDefinition
-from crewai.flow.runtime._actions._base import ResolvedAction
-from crewai.flow.runtime._actions._runtime import LOCAL_CONTEXT_KWARG
-from crewai.flow.runtime._expressions import evaluate_expression
-
-
-if TYPE_CHECKING:
-    from crewai.flow.runtime import Flow
-
-
-class ExpressionActionHandler:
-    """Build CEL expression actions."""
-
-    action_type = FlowExpressionActionDefinition
-
-    def build(
-        self, flow: Flow[Any], action: FlowExpressionActionDefinition
-    ) -> ResolvedAction:
-        def run_expression(*_args: Any, **kwargs: Any) -> Any:
-            local_context = kwargs.pop(LOCAL_CONTEXT_KWARG, None)
-            return evaluate_expression(flow, action.expr, local_context=local_context)
-
-        return run_expression

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

@@ -1,28 +0,0 @@
-"""Runtime helpers shared by action resolvers."""
-
-from __future__ import annotations
-
-from collections.abc import Callable
-import inspect
-from typing import Any
-
-
-LOCAL_CONTEXT_KWARG = "__flow_definition_local_context"
-
-
-async def invoke_callable(
-    handler: Callable[..., Any], *args: Any, **kwargs: Any
-) -> Any:
-    if inspect.iscoroutinefunction(handler):
-        result = await handler(*args, **kwargs)
-    else:
-        result = handler(*args, **kwargs)
-    if inspect.isawaitable(result):
-        result = await result
-    return result
-
-
-def ensure_array(value: Any) -> list[Any]:
-    if isinstance(value, list):
-        return value
-    raise ValueError("each.in must evaluate to an array")

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

@@ -1,52 +0,0 @@
-"""Handler for ``call: tool`` FlowDefinition actions."""
-
-from __future__ import annotations
-
-from collections.abc import Callable
-import inspect
-from typing import TYPE_CHECKING, Any, cast
-
-from crewai.flow.flow_definition import FlowToolActionDefinition
-from crewai.flow.runtime._actions._base import ResolvedAction
-from crewai.flow.runtime._actions._runtime import LOCAL_CONTEXT_KWARG
-from crewai.flow.runtime._expressions import render_with_block
-from crewai.flow.runtime._refs import InvalidRefError, resolve_ref
-
-
-if TYPE_CHECKING:
-    from crewai.flow.runtime import Flow
-
-
-class ToolActionHandler:
-    """Build and instantiate CrewAI tool actions."""
-
-    action_type = FlowToolActionDefinition
-
-    def build(
-        self, flow: Flow[Any], action: FlowToolActionDefinition
-    ) -> ResolvedAction:
-        target = resolve_ref(action.ref, field="do")
-        from crewai.tools import BaseTool
-
-        if not (inspect.isclass(target) and issubclass(target, BaseTool)):
-            raise InvalidRefError(
-                f"invalid tool ref {action.ref!r}; expected a BaseTool class"
-            )
-
-        try:
-            tool_cls = cast(Callable[[], BaseTool], target)
-            tool = tool_cls()
-        except Exception as e:
-            raise InvalidRefError(
-                f"cannot instantiate tool ref {action.ref!r} without arguments: {e}"
-            ) from e
-
-        tool_kwargs = action.with_ or {}
-
-        def run_tool(*_args: Any, **kwargs: Any) -> Any:
-            local_context = kwargs.pop(LOCAL_CONTEXT_KWARG, None)
-            return tool.run(
-                **render_with_block(flow, tool_kwargs, local_context=local_context)
-            )
-
-        return run_tool

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

@@ -1,163 +0,0 @@
-"""Runtime expression support for FlowDefinition CEL expressions."""
-
-from __future__ import annotations
-
-import dataclasses
-from itertools import pairwise
-import json
-import re
-from typing import TYPE_CHECKING, Any, cast
-
-from pydantic import BaseModel
-
-
-if TYPE_CHECKING:
-    from crewai.flow.runtime import Flow
-
-
-_EXPRESSION_PATTERN = re.compile(r"\$\{([^{}]*)\}")
-
-__all__ = ["FlowExpressionError", "evaluate_expression", "render_with_block"]
-
-
-class FlowExpressionError(ValueError):
-    """A FlowDefinition expression failed to parse or evaluate."""
-
-
-def render_with_block(
-    flow: Flow[Any], value: Any, local_context: dict[str, Any] | None = None
-) -> Any:
-    """Render CEL expressions inside a FlowDefinition ``with:`` payload."""
-    context = _expression_context(flow, local_context=local_context)
-    return _render_value(value, context)
-
-
-def evaluate_expression(
-    flow: Flow[Any], expression: str, local_context: dict[str, Any] | None = None
-) -> Any:
-    """Evaluate a FlowDefinition CEL expression against runtime context."""
-    expression = expression.strip()
-    if not expression:
-        raise FlowExpressionError("empty CEL expression")
-    return _eval_cel(expression, _expression_context(flow, local_context=local_context))
-
-
-def _expression_context(
-    flow: Flow[Any], local_context: dict[str, Any] | None = None
-) -> dict[str, Any]:
-    context = {
-        "state": flow._copy_and_serialize_state(),
-        "outputs": _outputs_by_name(flow._method_outputs),
-    }
-    if local_context:
-        context.update(
-            {key: _to_json_safe(value) for key, value in local_context.items()}
-        )
-    return context
-
-
-def _outputs_by_name(method_outputs: list[Any]) -> dict[str, Any]:
-    outputs: dict[str, Any] = {}
-    for entry in method_outputs:
-        method = ""
-        output = entry
-        if isinstance(entry, dict) and "output" in entry:
-            method = str(entry.get("method", ""))
-            output = entry["output"]
-        outputs[method] = _to_json_safe(output)
-    return outputs
-
-
-def _to_json_safe(value: Any) -> Any:
-    if isinstance(value, BaseModel):
-        return value.model_dump(mode="json")
-    if dataclasses.is_dataclass(value) and not isinstance(value, type):
-        return dataclasses.asdict(value)
-    if isinstance(value, dict):
-        return {key: _to_json_safe(item) for key, item in value.items()}
-    if isinstance(value, list):
-        return [_to_json_safe(item) for item in value]
-    if isinstance(value, tuple):
-        return [_to_json_safe(item) for item in value]
-    return value
-
-
-def _render_value(value: Any, context: dict[str, Any]) -> Any:
-    if isinstance(value, str):
-        return _render_string(value, context)
-    if isinstance(value, dict):
-        return {key: _render_value(item, context) for key, item in value.items()}
-    if isinstance(value, list):
-        return [_render_value(item, context) for item in value]
-    return value
-
-
-def _render_string(value: str, context: dict[str, Any]) -> Any:
-    matches = list(_EXPRESSION_PATTERN.finditer(value))
-    if not matches:
-        _raise_for_invalid_interpolation(value)
-        return value
-
-    _raise_for_literal_braces(value[: matches[0].start()])
-    for previous, current in pairwise(matches):
-        _raise_for_literal_braces(value[previous.end() : current.start()])
-    _raise_for_literal_braces(value[matches[-1].end() :])
-
-    if len(matches) == 1 and matches[0].span() == (0, len(value)):
-        expression = matches[0].group(1).strip()
-        if not expression:
-            raise FlowExpressionError("empty CEL expression in with block")
-        return _eval_cel(expression, context)
-
-    rendered: list[str] = []
-    position = 0
-    for match in matches:
-        start, end = match.span()
-        literal = value[position:start]
-        rendered.append(literal)
-
-        expression = match.group(1).strip()
-        if not expression:
-            raise FlowExpressionError("empty CEL expression in with block")
-        result = _eval_cel(expression, context)
-        rendered.append(result if isinstance(result, str) else json.dumps(result))
-        position = end
-
-    literal = value[position:]
-    rendered.append(literal)
-
-    return "".join(rendered)
-
-
-def _raise_for_invalid_interpolation(value: str) -> None:
-    if "${" not in value:
-        return
-    raise FlowExpressionError(
-        "invalid CEL interpolation in with block: expressions must be enclosed "
-        "as ${...} and cannot contain braces"
-    )
-
-
-def _raise_for_literal_braces(value: str) -> None:
-    if "{" not in value and "}" not in value:
-        return
-    raise FlowExpressionError(
-        "invalid CEL interpolation in with block: expressions must be enclosed "
-        "as ${...} and cannot contain braces"
-    )
-
-
-def _eval_cel(expression: str, context: dict[str, Any]) -> Any:
-    try:
-        from celpy import Environment
-        from celpy.adapter import CELJSONEncoder, json_to_cel
-        from celpy.evaluation import Context
-
-        environment = Environment()
-        program = environment.program(environment.compile(expression))
-        result = program.evaluate(cast(Context, json_to_cel(context)))
-        return json.loads(json.dumps(result, cls=CELJSONEncoder))
-    except Exception as e:
-        raise FlowExpressionError(
-            f"failed to evaluate CEL expression {expression!r}: {e}"
-        ) from e

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

@@ -1,38 +0,0 @@
-"""Resolution of ``module:qualname`` refs into live Python objects."""
-
-from __future__ import annotations
-
-import importlib
-import inspect
-from operator import attrgetter
-from typing import Any
-
-
-class InvalidRefError(ValueError):
-    """A definition ref that cannot be resolved to a live object."""
-
-
-def resolve_ref(ref: str, *, field: str) -> Any:
-    """Import the object a definition's `module:qualname` ref points to."""
-    module_name, _, qualname = ref.partition(":")
-    if "<" in ref or not module_name or not qualname:
-        raise InvalidRefError(
-            f"invalid {field} ref {ref!r}; expected 'module:qualname'"
-        )
-    try:
-        return attrgetter(qualname)(importlib.import_module(module_name))
-    except (ImportError, AttributeError) as e:
-        raise InvalidRefError(f"unresolvable {field} ref {ref!r}") from e
-
-
-def resolve_instance_ref(ref: str, *, field: str) -> Any:
-    """Resolve a ref, auto-instantiating a no-arg class into an instance."""
-    target = resolve_ref(ref, field=field)
-    if not inspect.isclass(target):
-        return target
-    try:
-        return target()
-    except Exception as e:
-        raise InvalidRefError(
-            f"cannot instantiate {field} ref {ref!r} without arguments: {e}"
-        ) from e

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

@@ -5,7 +5,15 @@ the Flow system.
 """
 
 from datetime import datetime
-from typing import Annotated, Any, NewType, ParamSpec, Protocol, TypeVar, TypedDict
+from typing import (
+    Annotated,
+    Any,
+    NewType,
+    ParamSpec,
+    Protocol,
+    TypeVar,
+    TypedDict,
+)
 
 from typing_extensions import NotRequired, Required
 
@@ -16,14 +24,14 @@ R = TypeVar("R", covariant=True)
 FlowMethodName = NewType("FlowMethodName", str)
 PendingListenerKey = NewType(
     "PendingListenerKey",
-    Annotated[str, "listener method name, or 'start:<method>' for conditional starts"],
+    Annotated[str, "nested flow conditions use 'listener_name:object_id'"],
 )
 
 
 class FlowMethodCallable(Protocol[P, R]):
     """A callable that can be used as a flow method reference."""
 
-    __name__: str
+    __name__: FlowMethodName
 
     def __call__(self, *args: P.args, **kwargs: P.kwargs) -> R: ...
 

lib/crewai/src/crewai/knowledge/knowledge.py

@@ -13,7 +13,6 @@ from crewai.knowledge.source.string_knowledge_source import StringKnowledgeSourc
 from crewai.knowledge.source.text_file_knowledge_source import (
     TextFileKnowledgeSource,
 )
-from crewai.knowledge.storage.base_knowledge_storage import BaseKnowledgeStorage
 from crewai.knowledge.storage.knowledge_storage import KnowledgeStorage
 from crewai.rag.core.base_embeddings_provider import BaseEmbeddingsProvider
 from crewai.rag.embeddings.types import EmbedderConfig
@@ -90,7 +89,7 @@ class Knowledge(BaseModel):
     Knowledge is a collection of sources and setup for the vector store to save and query relevant context.
     Args:
         sources: list[BaseKnowledgeSource] = Field(default_factory=list)
-        storage: BaseKnowledgeStorage | None = Field(default=None)
+        storage: KnowledgeStorage | None = Field(default=None)
         embedder: EmbedderConfig | None = None
     """
 
@@ -99,7 +98,7 @@ class Knowledge(BaseModel):
         BeforeValidator(_resolve_knowledge_sources),
     ] = Field(default_factory=list)
     model_config = ConfigDict(arbitrary_types_allowed=True)
-    storage: BaseKnowledgeStorage | None = Field(default=None)
+    storage: KnowledgeStorage | None = Field(default=None)
     embedder: Annotated[
         EmbedderConfig | None,
         PlainSerializer(
@@ -113,22 +112,15 @@ class Knowledge(BaseModel):
         collection_name: str,
         sources: list[BaseKnowledgeSource],
         embedder: EmbedderConfig | None = None,
-        storage: BaseKnowledgeStorage | None = None,
+        storage: KnowledgeStorage | None = None,
         **data: object,
     ) -> None:
         super().__init__(**data)
-        if storage is not None:
+        if storage:
             self.storage = storage
         else:
-            from crewai.knowledge.storage.factory import resolve_knowledge_storage
-
-            custom = resolve_knowledge_storage(embedder, collection_name)
-            self.storage = (
-                custom
-                if custom is not None
-                else KnowledgeStorage(
-                    embedder=embedder, collection_name=collection_name
-                )
+            self.storage = KnowledgeStorage(
+                embedder=embedder, collection_name=collection_name
             )
         self.sources = sources
 
@@ -160,9 +152,10 @@ class Knowledge(BaseModel):
             raise e
 
     def reset(self) -> None:
-        if self.storage is None:
+        if self.storage:
+            self.storage.reset()
+        else:
             raise ValueError("Storage is not initialized.")
-        self.storage.reset()
 
     async def aquery(
         self, query: list[str], results_limit: int = 5, score_threshold: float = 0.6
@@ -200,6 +193,7 @@ class Knowledge(BaseModel):
 
     async def areset(self) -> None:
         """Reset the knowledge base asynchronously."""
-        if self.storage is None:
+        if self.storage:
+            await self.storage.areset()
+        else:
             raise ValueError("Storage is not initialized.")
-        await self.storage.areset()

lib/crewai/src/crewai/knowledge/source/base_file_knowledge_source.py

@@ -5,7 +5,7 @@ from typing import Any
 from pydantic import Field, field_validator
 
 from crewai.knowledge.source.base_knowledge_source import BaseKnowledgeSource
-from crewai.knowledge.storage.base_knowledge_storage import BaseKnowledgeStorage
+from crewai.knowledge.storage.knowledge_storage import KnowledgeStorage
 from crewai.utilities.constants import KNOWLEDGE_DIRECTORY
 from crewai.utilities.logger import Logger
 
@@ -22,7 +22,7 @@ class BaseFileKnowledgeSource(BaseKnowledgeSource, ABC):
         default_factory=list, description="The path to the file"
     )
     content: dict[Path, str] = Field(init=False, default_factory=dict)
-    storage: BaseKnowledgeStorage | None = Field(default=None)
+    storage: KnowledgeStorage | None = Field(default=None)
     safe_file_paths: list[Path] = Field(default_factory=list)
 
     @field_validator("file_path", "file_paths", mode="before")
@@ -70,14 +70,14 @@ class BaseFileKnowledgeSource(BaseKnowledgeSource, ABC):
 
     def _save_documents(self) -> None:
         """Save the documents to the storage."""
-        if self.storage is not None:
+        if self.storage:
             self.storage.save(self.chunks)
         else:
             raise ValueError("No storage found to save documents.")
 
     async def _asave_documents(self) -> None:
         """Save the documents to the storage asynchronously."""
-        if self.storage is not None:
+        if self.storage:
             await self.storage.asave(self.chunks)
         else:
             raise ValueError("No storage found to save documents.")

lib/crewai/src/crewai/knowledge/source/base_knowledge_source.py

@@ -4,15 +4,9 @@ from typing import Any
 import numpy as np
 from pydantic import BaseModel, ConfigDict, Field
 
-from crewai.knowledge.storage.base_knowledge_storage import BaseKnowledgeStorage
 from crewai.knowledge.storage.knowledge_storage import KnowledgeStorage
 
 
-# ``KnowledgeStorage`` is re-exported for backwards compatibility; the ``storage``
-# field below is typed to the base interface so any backend plugs in.
-__all__ = ["BaseKnowledgeSource", "KnowledgeStorage"]
-
-
 class BaseKnowledgeSource(BaseModel, ABC):
     """Abstract base class for knowledge sources."""
 
@@ -24,7 +18,7 @@ class BaseKnowledgeSource(BaseModel, ABC):
     )
 
     model_config = ConfigDict(arbitrary_types_allowed=True)
-    storage: BaseKnowledgeStorage | None = Field(default=None)
+    storage: KnowledgeStorage | None = Field(default=None)
     metadata: dict[str, Any] = Field(default_factory=dict)  # Currently unused
     collection_name: str | None = Field(default=None)
 
@@ -55,7 +49,7 @@ class BaseKnowledgeSource(BaseModel, ABC):
         Raises:
             ValueError: If no storage is configured.
         """
-        if self.storage is not None:
+        if self.storage:
             self.storage.save(self.chunks)
         else:
             raise ValueError("No storage found to save documents.")
@@ -72,7 +66,7 @@ class BaseKnowledgeSource(BaseModel, ABC):
         Raises:
             ValueError: If no storage is configured.
         """
-        if self.storage is not None:
+        if self.storage:
             await self.storage.asave(self.chunks)
         else:
             raise ValueError("No storage found to save documents.")

lib/crewai/src/crewai/knowledge/storage/factory.py

@@ -1,56 +0,0 @@
-"""Pluggable default storage backend for knowledge collections.
-
-By default, :class:`~crewai.knowledge.knowledge.Knowledge` builds a
-:class:`~crewai.knowledge.storage.knowledge_storage.KnowledgeStorage` when no
-explicit ``storage=`` is given. Registering a factory via
-:func:`set_knowledge_storage_factory` lets an application back knowledge with a
-custom :class:`~crewai.knowledge.storage.base_knowledge_storage.BaseKnowledgeStorage`
-without subclassing ``Knowledge`` or passing a ``storage=`` instance at every
-call site.
-
-This mirrors :func:`crewai_core.lock_store.set_lock_backend`: a one-time,
-process-wide setter intended for application startup. Pass ``None`` to restore
-the built-in default.
-"""
-
-from __future__ import annotations
-
-from collections.abc import Callable
-from typing import TYPE_CHECKING
-
-
-if TYPE_CHECKING:
-    from crewai.knowledge.storage.base_knowledge_storage import BaseKnowledgeStorage
-    from crewai.rag.embeddings.types import EmbedderConfig
-
-# Receives the same inputs as the built-in default -- the embedder config and
-# collection name -- and returns a storage backend, or ``None`` to defer to the
-# built-in ``KnowledgeStorage``.
-KnowledgeStorageFactory = Callable[
-    ["EmbedderConfig | None", "str | None"], "BaseKnowledgeStorage | None"
-]
-
-_factory: KnowledgeStorageFactory | None = None
-
-
-def set_knowledge_storage_factory(factory: KnowledgeStorageFactory | None) -> None:
-    """Replace the process-wide default knowledge storage factory.
-
-    Intended for one-time setup at startup. Pass ``None`` to restore the
-    built-in ``KnowledgeStorage``. Only affects ``Knowledge`` instances
-    constructed afterwards; an explicit ``storage=`` instance always wins.
-    """
-    global _factory
-    _factory = factory
-
-
-def resolve_knowledge_storage(
-    embedder: EmbedderConfig | None, collection_name: str | None
-) -> BaseKnowledgeStorage | None:
-    """Return the registered factory's backend, or ``None`` for the built-in.
-
-    ``None`` means no factory is registered or it declined; the caller then
-    falls back to the built-in ``KnowledgeStorage``.
-    """
-    factory = _factory
-    return factory(embedder, collection_name) if factory is not None else None

lib/crewai/src/crewai/llm.py

@@ -23,6 +23,7 @@ from crewai.events.event_bus import crewai_event_bus
 from crewai.events.types.llm_events import (
     LLMCallCompletedEvent,
     LLMCallFailedEvent,
+    LLMCallStartedEvent,
     LLMCallType,
     LLMStreamChunkEvent,
 )
@@ -31,7 +32,6 @@ 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,11 +732,6 @@ 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
@@ -755,16 +750,6 @@ 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
@@ -937,11 +922,6 @@ 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(
@@ -959,8 +939,6 @@ 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
 
@@ -972,8 +950,6 @@ 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
 
@@ -989,8 +965,6 @@ 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
 
@@ -1004,10 +978,6 @@ 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,
@@ -1015,8 +985,6 @@ 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
 
@@ -1201,10 +1169,6 @@ 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):
@@ -1216,8 +1180,6 @@ class LLM(BaseLLM):
                     from_agent=from_agent,
                     messages=params["messages"],
                     usage=response_usage,
-                    finish_reason=finish_reason,
-                    response_id=response_id,
                 )
                 return structured_response
 
@@ -1254,8 +1216,6 @@ class LLM(BaseLLM):
                 from_agent=from_agent,
                 messages=params["messages"],
                 usage=response_usage,
-                finish_reason=finish_reason,
-                response_id=response_id,
             )
             return text_response
 
@@ -1273,8 +1233,6 @@ class LLM(BaseLLM):
             from_agent=from_agent,
             messages=params["messages"],
             usage=response_usage,
-            finish_reason=finish_reason,
-            response_id=response_id,
         )
         return text_response
 
@@ -1352,10 +1310,6 @@ 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()
@@ -1366,8 +1320,6 @@ class LLM(BaseLLM):
                     from_agent=from_agent,
                     messages=params["messages"],
                     usage=response_usage,
-                    finish_reason=finish_reason,
-                    response_id=response_id,
                 )
                 return structured_response
 
@@ -1406,8 +1358,6 @@ class LLM(BaseLLM):
                 from_agent=from_agent,
                 messages=params["messages"],
                 usage=response_usage,
-                finish_reason=finish_reason,
-                response_id=response_id,
             )
             return text_response
 
@@ -1425,8 +1375,6 @@ class LLM(BaseLLM):
             from_agent=from_agent,
             messages=params["messages"],
             usage=response_usage,
-            finish_reason=finish_reason,
-            response_id=response_id,
         )
         return text_response
 
@@ -1464,29 +1412,12 @@ 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
-                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
+                response_id = chunk.id if isinstance(chunk, ModelResponseBase) else None
 
                 try:
                     choices = None
@@ -1594,10 +1525,6 @@ 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,
@@ -1605,8 +1532,6 @@ 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
 
@@ -1620,10 +1545,6 @@ 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,
@@ -1631,8 +1552,6 @@ 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
@@ -1759,14 +1678,19 @@ class LLM(BaseLLM):
             ValueError: If response format is not supported
             LLMContextLengthExceededError: If input exceeds model's context limit
         """
-        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,
+        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,
+                ),
             )
 
             self._validate_call_params()
@@ -1898,14 +1822,19 @@ class LLM(BaseLLM):
             ValueError: If response format is not supported
             LLMContextLengthExceededError: If input exceeds model's context limit
         """
-        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,
+        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,
+                ),
             )
 
             self._validate_call_params()
@@ -2061,8 +1990,6 @@ 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.
 
@@ -2073,10 +2000,6 @@ 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,
@@ -2089,24 +2012,9 @@ 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

@@ -1,55 +0,0 @@
-"""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,13 +150,6 @@ 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")
@@ -471,16 +464,6 @@ 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],
@@ -489,38 +472,10 @@ 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(
@@ -532,15 +487,6 @@ 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,
             ),
         )
 
@@ -552,8 +498,6 @@ 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
@@ -569,8 +513,6 @@ class BaseLLM(BaseModel, ABC):
                 model=self.model,
                 call_id=get_current_call_id(),
                 usage=usage,
-                finish_reason=finish_reason,
-                response_id=response_id,
             ),
         )
 
@@ -890,17 +832,41 @@ class BaseLLM(BaseModel, ABC):
         Args:
             usage_data: Token usage data from the API response
         """
-        metrics = UsageMetrics.from_provider_dict(usage_data)
-        if metrics is None:
-            return
+        prompt_tokens = (
+            usage_data.get("prompt_tokens")
+            or usage_data.get("prompt_token_count")
+            or usage_data.get("input_tokens")
+            or 0
+        )
 
-        self._token_usage["prompt_tokens"] += metrics.prompt_tokens
-        self._token_usage["completion_tokens"] += metrics.completion_tokens
-        self._token_usage["total_tokens"] += metrics.total_tokens
-        self._token_usage["successful_requests"] += metrics.successful_requests
-        self._token_usage["cached_prompt_tokens"] += metrics.cached_prompt_tokens
-        self._token_usage["reasoning_tokens"] += metrics.reasoning_tokens
-        self._token_usage["cache_creation_tokens"] += metrics.cache_creation_tokens
+        completion_tokens = (
+            usage_data.get("completion_tokens")
+            or usage_data.get("candidates_token_count")
+            or usage_data.get("output_tokens")
+            or 0
+        )
+
+        cached_tokens = (
+            usage_data.get("cached_tokens")
+            or usage_data.get("cached_prompt_tokens")
+            or usage_data.get("cache_read_input_tokens")
+            or 0
+        )
+        if not cached_tokens:
+            prompt_details = usage_data.get("prompt_tokens_details")
+            if isinstance(prompt_details, dict):
+                cached_tokens = prompt_details.get("cached_tokens", 0) or 0
+
+        reasoning_tokens = usage_data.get("reasoning_tokens", 0) or 0
+        cache_creation_tokens = usage_data.get("cache_creation_tokens", 0) or 0
+
+        self._token_usage["prompt_tokens"] += prompt_tokens
+        self._token_usage["completion_tokens"] += completion_tokens
+        self._token_usage["total_tokens"] += prompt_tokens + completion_tokens
+        self._token_usage["successful_requests"] += 1
+        self._token_usage["cached_prompt_tokens"] += cached_tokens
+        self._token_usage["reasoning_tokens"] += reasoning_tokens
+        self._token_usage["cache_creation_tokens"] += cache_creation_tokens
 
     def get_token_usage_summary(self) -> UsageMetrics:
         """Get summary of token usage for this LLM instance.

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

@@ -923,8 +923,6 @@ 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:
@@ -937,8 +935,6 @@ class AnthropicCompletion(BaseLLM):
                             from_agent=from_agent,
                             messages=params["messages"],
                             usage=usage,
-                            finish_reason=finish_reason,
-                            response_id=response_id,
                         )
                         return structured_data
             else:
@@ -955,8 +951,6 @@ class AnthropicCompletion(BaseLLM):
                             from_agent=from_agent,
                             messages=params["messages"],
                             usage=usage,
-                            finish_reason=finish_reason,
-                            response_id=response_id,
                         )
                         return structured_data
 
@@ -979,8 +973,6 @@ class AnthropicCompletion(BaseLLM):
                         from_agent=from_agent,
                         messages=params["messages"],
                         usage=usage,
-                        finish_reason=finish_reason,
-                        response_id=response_id,
                     )
                     return list(tool_uses)
 
@@ -1013,8 +1005,6 @@ 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:
@@ -1157,10 +1147,6 @@ 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)
@@ -1171,8 +1157,6 @@ 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:
@@ -1188,8 +1172,6 @@ class AnthropicCompletion(BaseLLM):
                         from_agent=from_agent,
                         messages=params["messages"],
                         usage=usage,
-                        finish_reason=finish_reason,
-                        response_id=final_response_id,
                     )
                     return structured_data
 
@@ -1219,8 +1201,6 @@ 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(
@@ -1381,10 +1361,6 @@ 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,
@@ -1392,8 +1368,6 @@ 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 = {
@@ -1473,8 +1447,6 @@ 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:
@@ -1487,8 +1459,6 @@ class AnthropicCompletion(BaseLLM):
                             from_agent=from_agent,
                             messages=params["messages"],
                             usage=usage,
-                            finish_reason=finish_reason,
-                            response_id=response_id,
                         )
                         return structured_data
             else:
@@ -1505,8 +1475,6 @@ class AnthropicCompletion(BaseLLM):
                             from_agent=from_agent,
                             messages=params["messages"],
                             usage=usage,
-                            finish_reason=finish_reason,
-                            response_id=response_id,
                         )
                         return structured_data
 
@@ -1527,8 +1495,6 @@ class AnthropicCompletion(BaseLLM):
                         from_agent=from_agent,
                         messages=params["messages"],
                         usage=usage,
-                        finish_reason=finish_reason,
-                        response_id=response_id,
                     )
                     return list(tool_uses)
 
@@ -1553,8 +1519,6 @@ 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:
@@ -1683,10 +1647,6 @@ 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)
@@ -1697,8 +1657,6 @@ 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:
@@ -1714,8 +1672,6 @@ class AnthropicCompletion(BaseLLM):
                         from_agent=from_agent,
                         messages=params["messages"],
                         usage=usage,
-                        finish_reason=finish_reason,
-                        response_id=final_response_id,
                     )
                     return structured_data
 
@@ -1745,8 +1701,6 @@ class AnthropicCompletion(BaseLLM):
             from_agent=from_agent,
             messages=params["messages"],
             usage=usage,
-            finish_reason=finish_reason,
-            response_id=final_response_id,
         )
 
         return full_response
@@ -1799,10 +1753,6 @@ 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,
@@ -1810,8 +1760,6 @@ 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 = {
@@ -1865,20 +1813,6 @@ 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,