docs: document SQLite storage location for flow persistence (#5372)

[NIK-TIGER-BILL]

Fixes #5372

Problem

The flow persistence documentation mentions that @persist uses SQLiteFlowPersistence by default, but does not specify where the SQLite database file is actually stored on disk. Users have asked for this information (see #5372).

Solution

Add explicit documentation about the default storage path for the SQLite database, including cross-platform paths and the CREWAI_STORAGE_DIR environment variable override.

Changes

• Documented default SQLite storage paths for Linux, macOS, and Windows
• Documented the CREWAI_STORAGE_DIR environment variable for customizing the storage location

Summary by CodeRabbit

• Documentation

  • Clarified Flow Persistence defaults and storage path behavior, plus improved flow state resumption examples for clarity.

• Bug Fixes

  • Improved tool execution error handling to avoid reporting results as successful when a tool emits an error.

• Tests

  • Added regression test covering tool error handling to ensure result reporting correctness.

[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: 4f3dad2e-7828-4ec1-945c-a12779662cf9

📥 Commits

Reviewing files that changed from the base of the PR and between a1e289c and 74986a1.

📒 Files selected for processing (1)

• docs/en/concepts/flows.mdx

✅ Files skipped from review due to trivial changes (1)

• docs/en/concepts/flows.mdx

---

📝 Walkthrough

Walkthrough

This PR enhances Flow Persistence documentation by specifying SQLite storage defaults and improving the @persist() resumption example. Additionally, it fixes tool error handling logic to prevent results from being treated as final answers when execution errors occur, validated by a regression test.

Changes

Persistence Documentation & Tool Error Handling

Layer / File(s)	Summary
Flow Persistence Documentation docs/en/concepts/flows.mdx	SQLite backend storage details added: filename is flow_states.db, platform-specific user data directory locations documented for Linux/macOS/Windows, and <project_name> derivation from current working directory name or CREWAI_STORAGE_DIR environment variable.
State Resumption Example docs/en/guides/flows/mastering-flow-state.mdx	Updated @persist() class-level example demonstrates explicit state resumption by passing state.id into kickoff(inputs={"id": flow1.state.id}) on subsequent runs.
Tool Error Handling Logic lib/crewai/src/crewai/utilities/agent_utils.py	result_as_answer flag in execute_single_native_tool_call now requires both the tool capability and not error_event_emitted, preventing tool results from being treated as final answers when errors occur.
Error Handling Regression Test lib/crewai/tests/utilities/test_agent_utils.py	New TestExecuteSingleNativeToolCall.test_result_as_answer_false_on_tool_error verifies that tool execution errors override result_as_answer=True capability, forcing the result flag to False and returning an error message containing "Error executing tool".

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant Executor as execute_single_native_tool_call
  participant Tool
  participant Emitter as ErrorEventEmitter
  Caller->>Executor: request tool execution
  Executor->>Tool: invoke tool
  Tool-->>Executor: returns result / raises exception
  alt exception or error event emitted
    Tool->>Emitter: emit error event
    Executor->>Caller: return NativeToolCallResult(result_as_answer=false, error message)
  else success without error event
    Executor->>Caller: return NativeToolCallResult(result_as_answer=true/false based on capability)
  end

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Suggested labels

size/M, enhancement

Suggested reviewers

• greysonlalonde
• vinibrsl

Poem

🐰 In flows where states persist with care,
We clarify where data rests secure—
SQLite keeps what's tucked in there,
While errors halt the answer's lure,
State resumes with ID so true! ✨

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Out of Scope Changes check	⚠️ Warning	The PR includes changes to agent_utils.py and test files that are unrelated to the flow persistence documentation objective stated in #5372.	Remove the unrelated changes to agent_utils.py and its tests, or clarify their connection to issue #5372 if intentional.
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title references issue #5372 about documenting SQLite storage location for flow persistence, which aligns with the main documentation changes in the PR.
Linked Issues check	✅ Passed	The PR addresses the core requirement from #5372 by documenting default SQLite storage paths and the CREWAI_STORAGE_DIR environment variable for overriding storage location.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

⚔️ Resolve merge conflicts

• Resolve merge conflict in branch fix-docs-persist-location

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

• Generate code and open pull requests
• Plan features and break down work
• Investigate incidents and troubleshoot customer tickets together
• Automate recurring tasks and respond to alerts with triggers
• Summarize progress and report instantly

Built for teams:

• Shared memory across your entire org—no repeating context
• Per-thread sandboxes to safely plan and execute work
• Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

---

_{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 `@docs/en/concepts/flows.mdx`:
- Line 433: The sentence currently implies CREWAI_STORAGE_DIR replaces
<project_name>; revise the wording to clearly separate project naming from
storage-location override by stating that <project_name> is still derived from
the current working directory name (or explicitly provided elsewhere) and that
CREWAI_STORAGE_DIR only overrides the base storage directory where the project
folder is created (i.e., CREWAI_STORAGE_DIR/<project_name>), not the project
name itself; update the line mentioning `<project_name>` and
`CREWAI_STORAGE_DIR` to reflect this explicit path semantics.

🪄 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: 5cd0a414-c1a9-4836-939b-1f8a2e484d35

📥 Commits

Reviewing files that changed from the base of the PR and between e4a91cd and a1e289c.

📒 Files selected for processing (4)

• docs/en/concepts/flows.mdx
• docs/en/guides/flows/mastering-flow-state.mdx
• lib/crewai/src/crewai/utilities/agent_utils.py
• lib/crewai/tests/utilities/test_agent_utils.py

[NIK-TIGER-BILL]

@coderabbitai Thanks for the suggestion — applied the wording tweak that separates <project_name> defaults from CREWAI_STORAGE_DIR semantics. Ready for another look.

[coderabbitai]

@NIK-TIGER-BILL Sure! Kicking off a fresh review of the updated changes now.

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.