Skip to content

docs: add a runnable conversational Flow persistence and resume example - #8808

Open
Felix Shi (shi-felix) wants to merge 3 commits into
crewAIInc:mainfrom
shi-felix:docs/conversational-flow-persistence-example
Open

Felix Shi (shi-felix) wants to merge 3 commits into
crewAIInc:mainfrom
shi-felix:docs/conversational-flow-persistence-example

Conversation

@shi-felix

@shi-felix Felix Shi (shi-felix) commented Oct 30, 2026 •

Copy link
Copy Markdown

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 uses SQLiteFlowPersistence("./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 call finalize_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: TestDocumentedPersistenceExample runs 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 deterministic route_turn/@listen pair, so no LLM is involved.

Testing

The documented script prints exactly what the guide claims:

first: [('user', 'buy milk'), ('assistant', 'noted: buy milk')]
second: [('user', 'buy milk'), ('assistant', 'noted: buy milk'), ('user', 'and eggs'), ('assistant', 'noted: and eggs')]
other: [('user', 'different'), ('assistant', 'noted: different')]
python -m pytest lib/crewai/tests/test_flow_conversation.py -k "DocumentedPersistenceExample"
1 passed, 174 deselected in 24.51s

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 Flow via session_id and @persist, walks through a deterministic NoteTaker example with SQLiteFlowPersistence, expected console output, limits of what a restart restores (not in-flight work or open streams), and when to call finalize_session_traces() with deferred tracing.

Adds TestDocumentedPersistenceExample in test_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.

@mintlify

mintlify Bot commented Oct 30, 2026 •

Copy link
Copy Markdown

Preview approval required

This pull request comes from a fork, so Mintlify won't build a preview until someone with write access approves commit 9ddf040.

Approve preview

@strix-security

strix-security Bot commented Oct 30, 2026 •

Copy link
Copy Markdown

Strix Security Review

Warning

This pull request has 117 commits after the last Strix review (15cbbbf). Strix has not reviewed these changes.
Automatic review on push is off for this repository. To review the latest changes, tag @strix-security in a comment, or turn on re-review on push.

✅ 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 summary

This 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)
  • Does the fixed session id in the documented example teach cross-user session reuse that leaks conversation history?
    The id is a demo constant for deterministic output, it is not a credential, the same guide documents UUID-derived session ids for real callers, and the new prose explicitly explains that a different session id starts a separate conversation.
  • Does persisting conversation history to a local SQLite file without access-control guidance introduce an exploitable weakness?
    The only changed executable lines are a documentation snippet and a test that writes to a temporary directory, so no shipped code path performs this persistence.

Review 1 on this PR · 15cbbbf · requested Oct 30 05:55 UTC when the PR was opened


Reviewed by Strix
Re-run review · Configure security review settings

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[docs] Add a runnable conversational Flow persistence and restart example

1 participant