Skip to content

Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.

Update conversational flow docs to use handle_turn (#6053)

Lorenze Jay3723f0db768a
diff --git a/docs/ar/guides/flows/conversational-flows.mdx b/docs/ar/guides/flows/conversational-flows.mdx
index 9d397d73e..371de79be 100644
--- a/docs/ar/guides/flows/conversational-flows.mdx
+++ b/docs/ar/guides/flows/conversational-flows.mdx
@@ -11,95 +11,83 @@ mode: "wide"
| المفهوم | التنفيذ |
|---------|---------|
-| معرّف الجلسة | `kickoff(session_id=...)` → `inputs["id"]` → `state.id` |
-| سطر المستخدم | `kickoff(user_message=...)` يُضاف إلى `state.messages` قبل تشغيل الرسم |
-| اكتمال الجولة | `FlowFinished` لهذا **التشغيل** فقط؛ تستمر المحادثة في `kickoff` التالي |
-| تتبع الجلسة | `ConversationalConfig(defer_trace_finalization=True)` + `finalize_session_traces()` |
+| معرّف الجلسة | `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()` |
## واجهات الجولات
-استخدم **`flow.kickoff(user_message=..., session_id=...)`** أو **`flow.handle_turn(...)`** لكل رسالة مستخدم من REST أو WebSocket أو الاختبارات أو الواجهات المخصصة. استخدم **`flow.chat()`** عندما تريد حلقة دردشة محلية في الطرفية لـ `Flow` محادثي.
+استخدم **`flow.handle_turn(message, session_id=...)`** لكل رسالة مستخدم من REST أو WebSocket أو الاختبارات أو الواجهات المخصصة. استخدم **`flow.chat()`** عندما تريد حلقة دردشة محلية في الطرفية لـ `Flow` محادثي.
+
+لا يقبل `Flow.kickoff()` الوسيطين `user_message=` أو `session_id=`. في التدفقات المحادثية، يخزن `handle_turn()` الرسالة المعلقة ويستدعي داخلياً `kickoff(inputs={"id": session_id})`.
| API | الاستخدام |
|-----|-----------|
-| `kickoff(user_message=..., session_id=...)` | كل رسالة مستخدم |
| `handle_turn(message, session_id=...)` | غلاف مريح لجولة واحدة في `Flow` محادثي |
| `chat()` | REPL محلي في الطرفية لـ `Flow` محادثي |
-| `kickoff_async(...)` | نفس المعاملات؛ دخول async أصلي |
+| `kickoff(inputs={...})` | تشغيل متقدم للـ flow بدون معالجة جولة محادثية |
| `ask()` | مطالبة حاجزة **داخل** خطوة واحدة |
| `@human_feedback` | الموافقة/الرفض على **مخرجات خطوة** — وليس السطر التالي |
-| `ChatSession.handle_turn(...)` | طبقة نقل فوق `kickoff` |
+| `ChatSession.handle_turn(...)` | طبقة نقل فوق `handle_turn` |
## بداية سريعة
```python
from uuid import uuid4
-from crewai.flow import (
- ChatState,
- ConversationalConfig,
- Flow,
- listen,
- or_,
- persist,
- router,
- start,
+from crewai import Flow
+from crewai.flow import listen
+from crewai.experimental.conversational import (
+ ConversationConfig,
+ ConversationState,
)
-from crewai.flow.persistence import SQLiteFlowPersistence
-
-class SupportFlow(Flow[ChatState]):
- conversational_config = ConversationalConfig(
- default_intents=["order", "help", "goodbye"],
- intent_llm="gpt-4o-mini",
- defer_trace_finalization=True,
- )
- @start()
- def bootstrap(self):
- if not self.state.session_ready:
- self.state.session_ready = True
- return "ready"
+@ConversationConfig(defer_trace_finalization=True)
+class SupportFlow(Flow[ConversationState]):
+ conversational = True
- @router(bootstrap)
- def route(self):
- return self.state.last_intent or "help"
+ 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"
@listen("order")
def handle_order(self):
reply = "طلبك في الطريق."
- self.append_message("assistant", reply)
+ self.append_assistant_message(reply)
return reply
@listen("help")
def handle_help(self):
reply = "كيف يمكنني المساعدة؟"
- self.append_message("assistant", reply)
+ self.append_assistant_message(reply)
return reply
@listen("goodbye")
def handle_goodbye(self):
reply = "وداعاً!"
- self.append_message("assistant", reply)
+ self.append_assistant_message(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()
-flow.kickoff(user_message="أين طلبي؟", session_id=session_id)
-flow.kickoff(user_message="وماذا عن الإرجاع؟", session_id=session_id)
-flow.finalize_session_traces()
+try:
+ flow.handle_turn("أين طلبي؟", session_id=session_id)
+ flow.handle_turn("وماذا عن الإرجاع؟", session_id=session_id)
+finally:
+ flow.finalize_session_traces()
```
## دورة حياة الجولة
-كل `kickoff` مع `user_message` يشغّل:
+كل `handle_turn` يشغّل:
1. **`_configure_conversational_kickoff`** — دمج `session_id` / `user_message` في `inputs` وتطبيق `ConversationalConfig`.
2. **استعادة الحالة** — عند وجود `inputs["id"]` و`@persist`.
@@ -108,7 +96,7 @@ flow.finalize_session_traces()
5. **تنفيذ الرسم** — `@start` → `@router` → معالجات `@listen`.
6. **نهاية التشغيل** — يُتخطى `flow_finished` والتتبع لكل جولة عند التأجيل؛ `Agent.kickoff()` / crews لا تغلق دفعة الأب.
-استدعِ **`append_message("assistant", reply)`** في المعالجات. سطر المستخدم محفوظ عند kickoff — لا تُضفه مرة أخرى.
+استدعِ **`append_assistant_message(reply)`** في المعالجات. سطر المستخدم محفوظ عبر `handle_turn` — لا تُضفه مرة أخرى.
## `ConversationalConfig` (افتراضيات على مستوى الصنف)
@@ -382,7 +370,7 @@ Routes:
4. يخزّن الموجّه قراره في `state.last_intent` (يكون مرئياً لسياق التوجيه في الجولة التالية).
5. إذا أعاد معالجك سلسلة نصية ولم يستدعِ `append_assistant_message`، فإن `handle_turn` يُلحقها نيابةً عنك.
-يمكنك أيضاً استدعاء `flow.kickoff(user_message=..., session_id=...)` مباشرةً — نفس منطق الإعادة والتشغيل يعمل. `handle_turn` هو الغلاف المريح.
+استدعِ `handle_turn()` لرسائل الدردشة. استدعاء `kickoff(inputs={"id": ...})` مباشرةً يشغل الرسم بدون غلاف الجولة المحادثية.
### `chat()` للـ REPL المحلي
diff --git a/docs/en/guides/flows/conversational-flows.mdx b/docs/en/guides/flows/conversational-flows.mdx
index 00084cae7..c231fe010 100644
--- a/docs/en/guides/flows/conversational-flows.mdx
+++ b/docs/en/guides/flows/conversational-flows.mdx
@@ -1,132 +1,121 @@
---
title: Conversational Flows
-description: Build multi-turn chat apps with kickoff per turn, message history, intent routing, tracing, and WebSocket bridges.
+description: Build multi-turn chat apps with handle_turn 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 classification, 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 routing, deferred tracing, UI bridges, and a local `flow.chat()` REPL for conversational flows.
| Concept | Implementation |
|---------|----------------|
-| 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()` |
+| 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()` |
## Turn APIs
-Use **`flow.kickoff(user_message=..., session_id=...)`** or **`flow.handle_turn(...)`** 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`.
+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.
| API | Use for |
|-----|---------|
-| `kickoff(user_message=..., session_id=...)` | Each user message |
| `handle_turn(message, session_id=...)` | Ergonomic one-turn wrapper for conversational `Flow` |
| `chat()` | Local terminal REPL for conversational `Flow` |
-| `kickoff_async(...)` | Same parameters; native async entry |
+| `kickoff(inputs={...})` | Advanced flow execution without conversational turn handling |
| `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 `kickoff` (SSE / WebSocket) |
+| `ChatSession.handle_turn(...)` | Transport layer over `handle_turn` (SSE / WebSocket) |
## Quick start
```python
from uuid import uuid4
-from crewai.flow import (
- ChatState,
- ConversationalConfig,
- Flow,
- listen,
- or_,
- persist,
- router,
- start,
+from crewai import Flow
+from crewai.flow import listen
+from crewai.experimental.conversational import (
+ ConversationConfig,
+ ConversationState,
)
-from crewai.flow.persistence import SQLiteFlowPersistence
-
-class SupportFlow(Flow[ChatState]):
- conversational_config = ConversationalConfig(
- default_intents=["order", "help", "goodbye"],
- intent_llm="gpt-4o-mini",
- defer_trace_finalization=True,
- )
- @start()
- def bootstrap(self):
- if not self.state.session_ready:
- self.state.session_ready = True
- return "ready"
+@ConversationConfig(defer_trace_finalization=True)
+class SupportFlow(Flow[ConversationState]):
+ conversational = True
- @router(bootstrap)
- def route(self):
- # last_intent set in prepare_conversational_turn when default_intents is set
- return self.state.last_intent or "help"
+ 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"
@listen("order")
def handle_order(self):
reply = "Your order is on the way."
- self.append_message("assistant", reply)
+ self.append_assistant_message(reply)
return reply
@listen("help")
def handle_help(self):
reply = "How can I help?"
- self.append_message("assistant", reply)
+ self.append_assistant_message(reply)
return reply
@listen("goodbye")
def handle_goodbye(self):
reply = "Goodbye!"
- self.append_message("assistant", reply)
+ self.append_assistant_message(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()
-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
+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
```
## Turn lifecycle
-Each `kickoff` with `user_message` runs this pipeline:
+Each `handle_turn` runs this pipeline:
-1. **`_configure_conversational_kickoff`** — merges `session_id` / `user_message` into `inputs`, applies `ConversationalConfig`, enables deferred tracing when configured.
+1. **Turn setup** — stores the pending user message, resolves the session id, resets per-turn execution tracking, and calls `kickoff(inputs={"id": session_id})`.
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. **`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.
+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.
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_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.
+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.
-## `ConversationalConfig` (class-level defaults)
+## `ConversationConfig` (class-level defaults)
-Set on your `Flow` subclass as `conversational_config: ClassVar[ConversationalConfig | None]`.
+Decorate your conversational `Flow` subclass with `ConversationConfig`.
| Field | Default | Purpose |
|-------|---------|---------|
-| `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 |
+| `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. |
+
+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` (recommended persisted shape)
+`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()`.
```python
from crewai.flow import ChatState
@@ -140,7 +129,7 @@ class MyChatState(ChatState):
| Field | Role |
|-------|------|
-| `id` | Session UUID (same as `session_id` / `inputs["id"]`) |
+| `id` | Session UUID (same as `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) |
@@ -150,27 +139,26 @@ class MyChatState(ChatState):
## `Flow` conversational API
-### `kickoff` / `kickoff_async` parameters
+### `handle_turn` parameters
| Parameter | Purpose |
|-----------|---------|
-| `user_message` | This turn’s text (or `{"role": "user", "content": "..."}`) |
+| `message` | This turn’s text |
| `session_id` | Conversation UUID → `inputs["id"]` / `state.id` |
| `intents` | Outcome labels for pre-kickoff `classify_intent` |
| `intent_llm` | LLM for classification (required with `intents`) |
-| `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 |
+| `**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.
### Instance attributes
| Attribute | Purpose |
|-----------|---------|
-| `conversational_config` | Class-level `ConversationalConfig` defaults |
-| `defer_trace_finalization` | Instance flag; set automatically from config on kickoff |
+| `conversational` | Set to `True` to enable the conversational graph and `handle_turn()` |
+| `defer_trace_finalization` | Instance flag; set automatically from config on `handle_turn()` |
| `suppress_flow_events` | Hides console flow panels; **tracing still records** method/flow events |
| `stream` | Enable streaming; use with `ChatSession.handle_turn(..., stream=True)` |
@@ -178,7 +166,8 @@ class MyChatState(ChatState):
| Name | Description |
|------|-------------|
-| `append_message(role, content, **extra)` | Append to `state.messages` (roles: `user`, `assistant`, `system`, `tool`) |
+| `append_assistant_message(content)` | Append a user-visible assistant reply to `state.messages` |
+| `append_message(role, content, **extra)` | Lower-level append to `state.messages` |
| `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` |
@@ -195,7 +184,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=...)` | Turn hydration (usually called by kickoff) |
+| `prepare_conversational_turn(flow, user_message=..., intents=..., intent_llm=..., config=...)` | Lower-level turn hydration for custom wrappers |
| `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` |
@@ -203,21 +192,20 @@ Importable for tests or custom orchestration:
## Intent routing patterns
-### A. Pre-classify via `ConversationalConfig` (simplest)
+### A. Pre-classify via `ConversationConfig` (simplest)
-Set `default_intents` and `intent_llm`. Each kickoff runs classification before your `@router`; read `self.state.last_intent` in `route()`.
+Set `default_intents` and `intent_llm`. Each `handle_turn()` runs classification before routing; read `self.state.last_intent` in `route_turn()`.
-### B. Classify inside `@router` (richer prompts)
+### B. Classify inside `route_turn` (richer prompts)
-Set `default_intents=None` so kickoff only appends the user message. In `route()`, call `classify_intent` with a custom prompt or descriptions:
+Set `default_intents=None` so `handle_turn()` only appends the user message. In `route_turn()`, call `classify_intent` with a custom prompt or descriptions:
```python
-@router(bootstrap)
-def route(self):
+def route_turn(self, context):
intent = self.classify_intent(
- self._routing_prompt(self.state.last_user_message),
+ self._routing_prompt(self.state.current_user_message),
("GREETING", "ORDER", "RESEARCH", "GOODBYE"),
- llm=self.conversational_config.intent_llm or "gpt-4o-mini",
+ llm="gpt-4o-mini",
)
self.state.last_intent = intent
return intent
@@ -227,7 +215,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 `kickoff` and the same `session_id`. `@persist` restores `messages`, flags, and context.
+`FlowFinished` means **this graph run** completed. The conversation continues with another `handle_turn()` 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.
@@ -244,53 +232,53 @@ 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`, drives the 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`, can drive a 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 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.
+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.
### Quick example
```python
-from crewai import LLM, Flow
+from crewai import Flow
from crewai.flow import listen
from crewai.experimental.conversational import (
ConversationConfig,
ConversationState,
- RouterConfig,
)
-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
-)
+@ConversationConfig(defer_trace_finalization=True)
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 (built-in)
+ flow.handle_turn("What can you do?") # routes to converse
flow.handle_turn("Search the web for AI news.") # routes to INTERNET_SEARCH
- flow.handle_turn("Summarize the first result.") # routes back to converse
+ flow.handle_turn("Check the CrewAI docs.") # routes to CREWAI_DOCS
finally:
flow.finalize_session_traces()
```
@@ -323,7 +311,21 @@ Class decorator that attaches per-class chat defaults.
### `RouterConfig` and the auto-built route catalog
```python
-RouterConfig(
+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(
prompt="Optional domain framing (policy, voice, persona).",
response_format=MyRoute, # optional; auto-generated otherwise
llm=ROUTER_LLM, # falls back to ConversationConfig.llm
@@ -347,6 +349,9 @@ 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."""
@@ -385,7 +390,7 @@ 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.
-You can also call `flow.kickoff(user_message=..., session_id=...)` directly — the same reset/run logic fires. `handle_turn` is the ergonomic wrapper.
+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
@@ -422,6 +427,12 @@ For web apps, background workers, tests, and custom transports, keep using `hand
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
@@ -443,7 +454,7 @@ Inside a `@listen(label)` handler, choose:
## Tracing across turns
-With `defer_trace_finalization=True` (default in `ConversationalConfig`):
+With `defer_trace_finalization=True` (default in `ConversationConfig`):
- **One trace batch** for the whole chat session.
- **`flow_started`** on the first turn only; **`flow_finished`** once in `finalize_session_traces()`.
@@ -455,7 +466,7 @@ flow.chat(session_id=session_id)
```
`flow.chat()` calls `finalize_session_traces()` for you. When you own the loop
-with `handle_turn()` or `kickoff(...)`, call `finalize_session_traces()` when
+with `handle_turn()`, call `finalize_session_traces()` when
the session ends.
`suppress_flow_events=True` only hides Rich console panels; trace and method events still emit for observability.
diff --git a/docs/ko/guides/flows/conversational-flows.mdx b/docs/ko/guides/flows/conversational-flows.mdx
index 35c63cacc..3a18cd1da 100644
--- a/docs/ko/guides/flows/conversational-flows.mdx
+++ b/docs/ko/guides/flows/conversational-flows.mdx
@@ -11,96 +11,83 @@ mode: "wide"
| 개념 | 구현 |
|------|------|
-| 세션 id | `kickoff(session_id=...)` → `inputs["id"]` → `state.id` |
-| 사용자 입력 | `kickoff(user_message=...)`가 그래프 실행 전 `state.messages`에 추가 |
-| 턴 완료 | `FlowFinished`는 **이번 실행**만 의미; 다음 `kickoff`로 대화 계속 |
-| 세션 전체 트레이스 | `ConversationalConfig(defer_trace_finalization=True)` + `finalize_session_traces()` |
+| 세션 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()` |
## 턴 API
-REST, WebSocket, 테스트, 커스텀 UI에서 오는 모든 사용자 메시지에는 **`flow.kickoff(user_message=..., session_id=...)`** 또는 **`flow.handle_turn(...)`**를 사용하세요. 대화형 `Flow`를 로컬 터미널 채팅 루프로 실행하고 싶을 때는 **`flow.chat()`**을 사용하세요.
+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})`를 호출합니다.
| API | 용도 |
|-----|------|
-| `kickoff(user_message=..., session_id=...)` | 각 사용자 메시지 |
| `handle_turn(message, session_id=...)` | 대화형 `Flow`용 한 턴 편의 래퍼 |
| `chat()` | 대화형 `Flow`용 로컬 터미널 REPL |
-| `kickoff_async(...)` | 동일 파라미터; 네이티브 async 진입 |
+| `kickoff(inputs={...})` | 대화형 턴 처리 없이 flow를 직접 실행 |
| `ask()` | 한 스텝 **내부** 블로킹 프롬프트 (마법사, 확인) |
| `@human_feedback` | **스텝 출력** 승인/거부 — 다음 채팅 줄이 아님 |
-| `ChatSession.handle_turn(...)` | `kickoff` 위의 전송 계층 (SSE / WebSocket) |
+| `ChatSession.handle_turn(...)` | `handle_turn` 위의 전송 계층 (SSE / WebSocket) |
## 빠른 시작
```python
from uuid import uuid4
-from crewai.flow import (
- ChatState,
- ConversationalConfig,
- Flow,
- listen,
- or_,
- persist,
- router,
- start,
+from crewai import Flow
+from crewai.flow import listen
+from crewai.experimental.conversational import (
+ ConversationConfig,
+ ConversationState,
)
-from crewai.flow.persistence import SQLiteFlowPersistence
-
-class SupportFlow(Flow[ChatState]):
- conversational_config = ConversationalConfig(
- default_intents=["order", "help", "goodbye"],
- intent_llm="gpt-4o-mini",
- defer_trace_finalization=True,
- )
- @start()
- def bootstrap(self):
- if not self.state.session_ready:
- self.state.session_ready = True
- return "ready"
+@ConversationConfig(defer_trace_finalization=True)
+class SupportFlow(Flow[ConversationState]):
+ conversational = True
- @router(bootstrap)
- def route(self):
- # default_intents 설정 시 prepare_conversational_turn에서 last_intent 설정
- return self.state.last_intent or "help"
+ 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"
@listen("order")
def handle_order(self):
reply = "주문이 배송 중입니다."
- self.append_message("assistant", reply)
+ self.append_assistant_message(reply)
return reply
@listen("help")
def handle_help(self):
reply = "무엇을 도와드릴까요?"
- self.append_message("assistant", reply)
+ self.append_assistant_message(reply)
return reply
@listen("goodbye")
def handle_goodbye(self):
reply = "안녕히 가세요!"
- self.append_message("assistant", reply)
+ self.append_assistant_message(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()
-flow.kickoff(user_message="주문 어디까지 왔나요?", session_id=session_id)
-flow.kickoff(user_message="반품은 어떻게 하나요?", session_id=session_id)
-flow.finalize_session_traces() # 전체 대화에 대한 단일 trace 링크
+try:
+ flow.handle_turn("주문 어디까지 왔나요?", session_id=session_id)
+ flow.handle_turn("반품은 어떻게 하나요?", session_id=session_id)
+finally:
+ flow.finalize_session_traces() # 전체 대화에 대한 단일 trace 링크
```
## 턴 생명주기
-`user_message`가 있는 각 `kickoff`는 다음 파이프라인을 실행합니다:
+각 `handle_turn`은 다음 파이프라인을 실행합니다:
1. **`_configure_conversational_kickoff`** — `session_id` / `user_message`를 `inputs`에 병합, `ConversationalConfig` 적용, 설정 시 지연 트레이싱 활성화.
2. **상태 복원** — `inputs["id"]`가 있고 `@persist`가 설정되면 최신 스냅샷 로드.
@@ -109,7 +96,7 @@ flow.finalize_session_traces() # 전체 대화에 대한 단일 trace 링크
5. **그래프 실행** — `@start` → `@router` → `@listen` 핸들러.
6. **실행 종료** — 지연 활성화 시 턴별 `flow_finished` 및 trace 종료 **건너뜀**; 중첩 `Agent.kickoff()` / crew도 부모 batch를 닫지 않음.
-핸들러는 **`append_message("assistant", reply)`**를 호출해 다음 턴의 `conversation_messages`에 어시스턴트 응답이 포함되게 하세요. 사용자 입력은 kickoff 시 이미 저장됩니다 — 핸들러에서 다시 추가하지 마세요.
+핸들러는 **`append_assistant_message(reply)`**를 호출해 다음 턴의 `conversation_messages`에 어시스턴트 응답이 포함되게 하세요. 사용자 입력은 `handle_turn`이 이미 저장합니다 — 핸들러에서 다시 추가하지 마세요.
## `ConversationalConfig` (클래스 수준 기본값)
@@ -384,7 +371,7 @@ Routes:
4. router는 결정을 `state.last_intent`에 저장합니다 (다음 턴의 router 컨텍스트에서 보입니다).
5. 핸들러가 문자열을 반환했지만 `append_assistant_message`를 직접 호출하지 않았다면, `handle_turn`이 대신 추가해 줍니다.
-`flow.kickoff(user_message=..., session_id=...)`를 직접 호출해도 동일한 reset/run 로직이 동작합니다. `handle_turn`은 그 위에 얹은 편의 래퍼입니다.
+채팅 메시지에는 `handle_turn()`을 호출하세요. `kickoff(inputs={"id": ...})`를 직접 호출하면 대화형 턴 래퍼 없이 flow 그래프가 실행됩니다.
### 로컬 REPL용 `chat()`
diff --git a/docs/pt-BR/guides/flows/conversational-flows.mdx b/docs/pt-BR/guides/flows/conversational-flows.mdx
index 905cdce3a..10ffdcbd6 100644
--- a/docs/pt-BR/guides/flows/conversational-flows.mdx
+++ b/docs/pt-BR/guides/flows/conversational-flows.mdx
@@ -11,96 +11,83 @@ Apps conversacionais tratam cada linha do usuário como uma **nova execução do
| Conceito | Implementação |
|---------|----------------|
-| 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()` |
+| 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()` |
## APIs de turno
-Use **`flow.kickoff(user_message=..., session_id=...)`** ou **`flow.handle_turn(...)`** 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.
+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.
| API | Uso |
|-----|-----|
-| `kickoff(user_message=..., session_id=...)` | Cada mensagem do usuário |
| `handle_turn(message, session_id=...)` | Wrapper ergonômico de um turno para `Flow` conversacional |
| `chat()` | REPL local no terminal para `Flow` conversacional |
-| `kickoff_async(...)` | Mesmos parâmetros; entrada async nativa |
+| `kickoff(inputs={...})` | Execução avançada do flow sem tratamento de turno conversacional |
| `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 `kickoff` (SSE / WebSocket) |
+| `ChatSession.handle_turn(...)` | Camada de transporte sobre `handle_turn` (SSE / WebSocket) |
## Início rápido
```python
from uuid import uuid4
-from crewai.flow import (
- ChatState,
- ConversationalConfig,
- Flow,
- listen,
- or_,
- persist,
- router,
- start,
+from crewai import Flow
+from crewai.flow import listen
+from crewai.experimental.conversational import (
+ ConversationConfig,
+ ConversationState,
)
-from crewai.flow.persistence import SQLiteFlowPersistence
-
-class SupportFlow(Flow[ChatState]):
- conversational_config = ConversationalConfig(
- default_intents=["order", "help", "goodbye"],
- intent_llm="gpt-4o-mini",
- defer_trace_finalization=True,
- )
- @start()
- def bootstrap(self):
- if not self.state.session_ready:
- self.state.session_ready = True
- return "ready"
+@ConversationConfig(defer_trace_finalization=True)
+class SupportFlow(Flow[ConversationState]):
+ conversational = True
- @router(bootstrap)
- def route(self):
- # last_intent definido em prepare_conversational_turn quando default_intents está setado
- return self.state.last_intent or "help"
+ 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"
@listen("order")
def handle_order(self):
reply = "Seu pedido está a caminho."
- self.append_message("assistant", reply)
+ self.append_assistant_message(reply)
return reply
@listen("help")
def handle_help(self):
reply = "Como posso ajudar?"
- self.append_message("assistant", reply)
+ self.append_assistant_message(reply)
return reply
@listen("goodbye")
def handle_goodbye(self):
reply = "Até logo!"
- self.append_message("assistant", reply)
+ self.append_assistant_message(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()
-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
+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
```
## Ciclo de vida do turno
-Cada `kickoff` com `user_message` executa este pipeline:
+Cada `handle_turn` 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.
@@ -109,7 +96,7 @@ Cada `kickoff` com `user_message` 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_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.
+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.
## `ConversationalConfig` (padrões em nível de classe)
@@ -385,7 +372,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ê.
-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.
+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