chat api for convo flows

[lorenzejay]

abstracts needing to setup a turn by turn experience for conversational flows

---

Note

Low Risk
Experimental conversational API only; changes are additive with docs and unit tests, no auth or production transport paths affected.

Overview
Adds flow.chat() on conversational flows: a terminal REPL that loops on user input, delegates each line to handle_turn(), prints assistant output, and always calls finalize_session_traces() in a finally block. The method rejects non-conversational flows, supports injectable input_fn/output_fn, customizable prompts and exit commands, optional blank-line skipping, and can temporarily enable defer_trace_finalization for the session.

Docs (en, ar, ko, pt-BR) are updated to document chat() alongside kickoff / handle_turn, replacing the old “kickoff-only / no custom chat wrapper” guidance and manual input() loop examples with flow.chat(session_id=...). runtime.py comments now list chat as an experimental conversational entry point.

Tests cover REPL behavior (skip empty, quit, trace finalization, output stringification) and the ValueError for plain flows.

^{Reviewed by Cursor Bugbot for commit 6d98513. Bugbot is set up for automated code reviews on this repo. Configure here.}

Summary by CodeRabbit

• New Features

  • Added flow.chat() — an interactive local terminal REPL for conversational flows with customizable prompt, assistant prefix, exit commands, optional skipping of empty input, and automatic session trace finalization.

• Documentation

  • Updated Conversational Flows guide (EN/AR/KO/PT-BR) with examples and guidance on using flow.chat() for local REPLs vs. per-message handling for web/workers/tests.

• Tests

  • Added tests validating REPL behavior and error on non-conversational flows.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
crewai	🟢 Ready	View Preview	Jun 3, 2026, 11:45 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 87fcaa1b-e3ab-456c-a81c-19533fe10d43

📥 Commits

Reviewing files that changed from the base of the PR and between ce63586 and 6d98513.

📒 Files selected for processing (2)

• lib/crewai/src/crewai/experimental/conversational_mixin.py
• lib/crewai/tests/test_flow_conversation.py

🚧 Files skipped from review as they are similar to previous changes (1)

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

---

📝 Walkthrough

Walkthrough

This PR adds a new _ConversationalMixin.chat() REPL for conversational Flows, associated tests, a small runtime doc reflow, and multi-language docs updating guidance to prefer flow.chat() for local terminal loops while keeping handle_turn()/kickoff() for external transports.

Changes

Implementation and Tests

Layer / File(s)	Summary
chat() method implementation lib/crewai/src/crewai/experimental/conversational_mixin.py	_ConversationalMixin.chat() provides an interactive REPL that enforces conversational, accepts injectable input_fn/output_fn, normalizes exit commands, optionally defers/restores trace finalization, routes each message to handle_turn() with session_id, prints assistant output with assistant_prefix, and ensures finalize_session_traces() runs in a finally block.
chat() method tests lib/crewai/tests/test_flow_conversation.py	Tests exercise the REPL loop (input/output routing, per-turn behavior, quit handling), validate stringification of listener raw results, and assert chat() raises ValueError for non-conversational Flows.
Runtime documentation comment update lib/crewai/src/crewai/flow/runtime.py	Reflowed the Flow conversational-mode comment to mention handle_turn/chat entry points; no behavior changes.

Conversational Flows Documentation (All Languages)

Layer / File(s)	Summary
Overview section: flow.chat() announcement docs/ar/guides/flows/conversational-flows.mdx, docs/en/guides/flows/conversational-flows.mdx, docs/ko/guides/flows/conversational-flows.mdx, docs/pt-BR/guides/flows/conversational-flows.mdx	Overview text now explicitly documents a local flow.chat() REPL for conversational flows in each language variant.
Turn APIs section: kickoff, handle_turn, and chat guidance docs/ar/guides/flows/conversational-flows.mdx, docs/en/guides/flows/conversational-flows.mdx, docs/ko/guides/flows/conversational-flows.mdx, docs/pt-BR/guides/flows/conversational-flows.mdx	"Turn APIs" sections and API tables updated: use kickoff(...)/handle_turn(...) per incoming message for external transports; use chat() for local terminal REPLs.
Experimental Flow usage examples: chat() vs handle_turn() docs/ar/guides/flows/conversational-flows.mdx, docs/en/guides/flows/conversational-flows.mdx, docs/ko/guides/flows/conversational-flows.mdx, docs/pt-BR/guides/flows/conversational-flows.mdx	Added concise SupportFlow().chat() examples showing REPL wrapping of handle_turn(), exit handling, blank-line skipping, and automatic trace finalization.
Detailed 'chat() for local REPLs' sections with customization docs/ar/guides/flows/conversational-flows.mdx, docs/en/guides/flows/conversational-flows.mdx, docs/ko/guides/flows/conversational-flows.mdx, docs/pt-BR/guides/flows/conversational-flows.mdx	New sections document REPL loop steps, I/O injection, session customization (prompt, assistant prefix, exit commands), and reiterate using handle_turn() for non-local transports.
Tracing section: chat() vs handle_turn() finalization responsibility docs/ar/guides/flows/conversational-flows.mdx, docs/en/guides/flows/conversational-flows.mdx, docs/ko/guides/flows/conversational-flows.mdx, docs/pt-BR/guides/flows/conversational-flows.mdx	Tracing guidance updated to show flow.chat(session_id=...) for terminal loops and to state that chat() finalizes deferred session traces automatically while manual handle_turn()/kickoff() loops must call finalize_session_traces() on session end.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Suggested labels

size/XL

Poem

🐰 A chat loop arrives in fluent grace,
REPL-bound conversational space,
Four tongues now sing of terminal cheer,
While traces finalize without fear—
One method wraps the turn, oh what delight! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 35.71% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'chat api for convo flows' directly summarizes the main change: introduction of a new chat() API for conversational flows, which is the primary feature addition in this PR.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch lorenze/feat/chat-api-for-convo-flows

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@lib/crewai/src/crewai/experimental/conversational_mixin.py`:
- Line 293: The REPL output in the chat() method prints result directly
(output_fn(f"{assistant_prefix}{result}")), bypassing the mixin's standard
coercion; update chat() to pass the value through the mixin's
_stringify_result() (e.g.,
output_fn(f"{assistant_prefix}{self._stringify_result(result)}")) so .raw
extraction and BaseModel JSON serialization are applied and terminal output
matches conversational history.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 4c2db877-c695-422c-aec2-631c8a1bb8db

📥 Commits

Reviewing files that changed from the base of the PR and between aed6923 and 9e057e6.

📒 Files selected for processing (7)

• docs/ar/guides/flows/conversational-flows.mdx
• docs/en/guides/flows/conversational-flows.mdx
• docs/ko/guides/flows/conversational-flows.mdx
• docs/pt-BR/guides/flows/conversational-flows.mdx
• lib/crewai/src/crewai/experimental/conversational_mixin.py
• lib/crewai/src/crewai/flow/runtime.py
• lib/crewai/tests/test_flow_conversation.py