Repository navigation
docs: add a runnable conversational Flow persistence and resume example - #8808
Felix Shi (shi-felix) wants to merge 3 commits into
Conversation
Preview approval requiredThis pull request comes from a fork, so Mintlify won't build a preview until someone with write access approves commit |
Strix Security ReviewWarning This pull request has 117 commits after the last Strix review ( ✅ No open security findings. PR summary: Adds a runnable SQLite-backed example to the conversational Flow docs showing how a fresh Flow instance resumes a persisted session versus starting a new one, in four locales, plus a test that runs the documented script. Review summaryThis PR adds a "Persisting and resuming a session" section to the conversational Flow guide in English, Arabic, Korean, and Brazilian Portuguese, together with a pytest class that runs the documented script against a temporary SQLite database. The change is documentation and test content only: no production modules, request paths, authentication logic, or persistence implementation are modified. The example uses a fixed session id purely to produce deterministic output, and the surrounding guide continues to document UUID-based session ids for real use; the new prose also states explicitly that a restart restores conversation state only. No security issues found in the changed lines. Ruled out (2)
Review 1 on this PR · Reviewed by Strix |
Summary
The conversational Flow guide explains session identity and persistence, but never shows a
complete runnable example, so "reuse the instance" and "resume persisted history" look the
same on paper. This adds one deterministic SQLite-backed example that runs without provider
credentials and proves the difference on a fresh instance.
Fixes #8070.
Changes
docs/edge/en/guides/flows/conversational-flows.mdx: a new "Persisting and resuming a session" section with the full script, the command, and its expected output. It usesSQLiteFlowPersistence("./notes.db")with a stable session id, shows a fresh instance restoring the first turn and appending the second, shows a different session id starting a separate conversation, and states that a restart restores persisted conversation state only — not running background work, in-flight method executions, or open resources. It also says when to callfinalize_session_traces()if deferral is on.docs/edge/{ar,ko,pt-BR}/guides/flows/conversational-flows.mdx: the same section in each locale.lib/crewai/tests/test_flow_conversation.py:TestDocumentedPersistenceExampleruns the documented flow against a temporary SQLite database and asserts the restored history for both the resumed session and the separate one.The example uses only existing APIs (
ConversationConfig,handle_turn(),@persist,SQLiteFlowPersistence) and a deterministicroute_turn/@listenpair, so no LLM is involved.Testing
The documented script prints exactly what the guide claims:
Python 3.13.14 on Windows. No credentials, no network calls.
AI assistance
Written with AI assistance (WorkBuddy) and reviewed before submission.
Note
Low Risk
Documentation and a deterministic test only; no runtime or API changes.
Overview
Adds a “Persisting and resuming a session” section to the conversational Flow guide in English, Arabic, Korean, and Portuguese, placed before the streaming section. The new content contrasts reusing an in-memory instance with resuming on a fresh
Flowviasession_idand@persist, walks through a deterministicNoteTakerexample withSQLiteFlowPersistence, expected console output, limits of what a restart restores (not in-flight work or open streams), and when to callfinalize_session_traces()with deferred tracing.Adds
TestDocumentedPersistenceExampleintest_flow_conversation.py, which mirrors the documented flow against a temp SQLite DB and asserts message history for resume and for a separate session id.Reviewed by Cursor Bugbot for commit b5b96f2. Bugbot is set up for automated code reviews on this repo. Configure here.