DS DevShelfHub Projects · AI tools
Tutorials / CrewAI / Reference / Classes / JsonProvider
Class flows

JsonProvider: Reference Guide

By DevShelfHub

Stores Flow state as JSON files under db_storage_path — readable, debuggable backend.

See the CrewAI API reference index, CrewAI introduction, and core concepts for surrounding context.

What is JsonProvider?

JsonProvider is the human-readable counterpart to SqliteProvider for @persist Flow checkpoints. Each write serializes the Flow's state snapshot to JSON on disk (layout depends on CrewAI version but stays plain text friendly), which makes diffing two checkpoints in git-style tools or attaching artifacts to incident tickets trivial during development.

Because JSON writes are typically whole-file rewrites without SQLite's WAL concurrency story, JsonProvider best fits single-writer processes, local laptops, and CI fixtures where you want deterministic files under tmp_path. Parallel flows hammering the same directory can interleave corrupt partial writes — switch to SqliteProvider or a networked StorageProvider when multiple workers share persistence.

Treat JsonProvider like a developer convenience: it trades throughput and locking sophistication for inspectability. Promote the same CheckpointConfig shape to SqliteProvider unchanged when you graduate to staging or single-host production.

When to Use

Local dev, low-traffic flows.

Use Cases

  • • Local dev
  • • Debugging persisted state

Key Features

  • ✓ Human-readable
  • ✓ File-per-flow

When NOT to Use

High concurrency — use SqliteProvider.

Notes

Secrets in JSON blobs

Flow state often mirrors prompts or API tokens during debugging. Scrub sensitive fields before persisting or restrict file permissions on the storage directory.

Concurrent writers

Two processes writing the same JsonProvider path can clobber each other. Use one writer per path or move to SqliteProvider for file-level locking.

CI cleanup

Remember to delete fixture directories between pytest runs — leftover JSON can make tests order-dependent.

Migration path

CheckpointConfig accepts either provider; plan a one-time copy when moving from JsonProvider folders to Sqlite .db files for production.

Import

python 
from crewai.state import JsonProvider

Code Examples

Swap JsonProvider into CheckpointConfig

python 
from crewai.state import JsonProvider
from crewai.state.checkpoint_config import CheckpointConfig

cfg = CheckpointConfig(storage=JsonProvider())

Inspect serialized checkpoints interactively

python 
from pathlib import Path
import json

root = Path.home() / '.crewai' / 'flows'
for path in sorted(root.glob('*.json'))[:10]:
    data = json.loads(path.read_text())
    print(path.name, 'keys=', list(data)[:8])

Pair with @persist on a Flow class

python 
from crewai.flow.flow import Flow, start
from crewai.state.checkpoint_config import CheckpointConfig, persist
from crewai.state import JsonProvider

@persist(config=CheckpointConfig(storage=JsonProvider()))
class DemoFlow(Flow):
    @start()
    def begin(self):
        self.state['counter'] = self.state.get('counter', 0) + 1
        return self.state['counter']

Common Mistakes

❌ Pointing production multi-worker traffic at JsonProvider

✅ Use SqliteProvider on a single host or a networked backend for concurrent writers.

JsonProvider FAQ

What is JsonProvider in CrewAI?

Stores Flow state as JSON files under db_storage_path — readable, debuggable backend. JsonProvider is the human-readable counterpart to SqliteProvider for @persist Flow checkpoints. Each write serializes the Flow's state snapshot to JSON on disk (layout depends on CrewAI version but stays plain text friendly), which makes diffing two checkpoints in git-style tools or attaching artifacts to incident tickets trivial during development. Because JSON writes are typically whole-file rewrites without SQLite's WAL concurrency story, JsonProvider best fits single-wri…

Which package defines the CrewAI class JsonProvider?

DevShelfHub maps JsonProvider to Python module crewai.state (package path crewai.state in this reference). Pin your installed crewai version and match imports to the snippet on this page.

When should I use JsonProvider?

Local dev, low-traffic flows.

When should I avoid using JsonProvider?

High concurrency — use SqliteProvider.

How do I import JsonProvider in Python?

from crewai.state import JsonProvider

Where can I explore more CrewAI API reference pages?

Open the CrewAI API reference index on DevShelfHub to search 58 classes, 30 methods, and 16 decorators, each with runnable examples, parameters, common mistakes, and cross-links.