Checkpointing

Checkpointing saves a snapshot of execution state during a run so a crew, flow, or agent can resume after a failure or be forked into an alternate branch.

Explanation

How checkpointing works: events, storage, and inheritance.

Tutorial

A 5-minute walkthrough: run, interrupt, resume.

How-to guides

Task-focused recipes for common workflows.

Reference

CheckpointConfig, events, providers, and CLI.

Explanation

What a checkpoint is

A checkpoint captures the state CrewAI needs to recreate a run mid-flight: the full state of the crew, flow, or agent — configuration, agent memory and knowledge sources, task progress, intermediate outputs, internal state and attributes — alongside the kickoff inputs, the event history up to that point, and a lineage ID that ties the checkpoint to the run it came from. Callbacks are saved only as references to named functions; see What a restore does not bring back. Restoring rebuilds that state and continues. Completed tasks are skipped, memory and knowledge are rehydrated, and downstream work runs against the same outputs the original run produced. Forking does the same restore under a new lineage, so the new branch and the original run can write checkpoints side by side without overwriting each other.

When checkpoints are written

Checkpointing is event-driven. The runtime subscribes to events you select via on_events and writes a checkpoint each time one fires. The default task_completed produces one checkpoint per finished task — a sensible tradeoff between granularity and disk use. Higher-frequency events like llm_call_completed are available for fine-grained recovery but write far more files.

Storage

Two providers ship with CrewAI:

JsonProvider writes one file per checkpoint. Human-readable and easy to inspect.
SqliteProvider writes to a single SQLite database. Better for high-frequency checkpointing.

Both prune oldest checkpoints when max_checkpoints is set.

Auto-checkpoint writes (event-driven) are best-effort: a failed write is logged and the run continues. Manual state.checkpoint() and state.acheckpoint() calls re-raise on failure.

Inheritance model

Crew, Flow, and Agent all accept a checkpoint argument. Children inherit from their parent unless they set their own value or pass False to opt out. Enable checkpointing once on the crew and every agent participates, or selectively exclude one agent.

What a restore does not bring back

A restore builds the crew, flow, or agent from the checkpoint file, not from the object you call kickoff() on. crew.kickoff(from_checkpoint=...) runs the crew stored in the file, so callables you set on crew are not copied over. A checkpoint saves a callback as the dotted path of a module-level function, such as "my_project.hooks.on_task_done", and imports it again on restore. A checkpoint is data, so CrewAI imports these paths only when the CREWAI_DESERIALIZE_CALLBACKS=1 environment variable is set. Without it, restoring a checkpoint that names a callback raises a ValueError. Set it only for checkpoint files you trust. These are not saved and do not run after a restore:

Lambdas, closures, bound methods such as notifier.on_task_done, functools.partial objects, and callable instances. CrewAI warns A ... callback cannot be saved in a checkpoint when you pass one to a Task, Agent, Crew, or tool; setting the attribute afterwards does not warn. A tool cache_function of this kind is restored as one that never caches.
Callable guardrails. CrewAI warns when it writes the checkpoint. String guardrails are saved.
@before_kickoff and @after_kickoff hooks on a @CrewBase class.

To keep a callback that cannot be saved, restore with Crew.from_checkpoint() and assign it again before kickoff():

from crewai import CheckpointConfig, Crew


class Notifier:
    def on_task_done(self, output):
        print(f"Finished: {output.description}")


notifier = Notifier()
crew = Crew.from_checkpoint(
    CheckpointConfig(restore_from="./.checkpoints/<timestamp>_<uuid>.json")
)
crew.tasks[-1].callback = notifier.on_task_done
result = crew.kickoff()

Tutorial: Resume a failing crew

This walkthrough takes ~5 minutes. You will run a two-task crew, kill it midway, and resume from the saved checkpoint.

Create the crew with checkpointing enabled

from crewai import Agent, Crew, Task

researcher = Agent(role="Researcher", goal="Research", backstory="Expert")
writer = Agent(role="Writer", goal="Write", backstory="Expert")

crew = Crew(
    agents=[researcher, writer],
    tasks=[
        Task(description="Research AI trends", agent=researcher, expected_output="bullets"),
        Task(description="Write a summary", agent=writer, expected_output="paragraph"),
    ],
    checkpoint=True,
)

Run it and interrupt after the first task

result = crew.kickoff()

Press Ctrl+C after the first task finishes. Look in ./.checkpoints/ — a file named <timestamp>_<uuid>.json is the checkpoint.

Resume from the checkpoint

from crewai import CheckpointConfig

result = crew.kickoff(
    from_checkpoint=CheckpointConfig(
        restore_from="./.checkpoints/<timestamp>_<uuid>.json",
    ),
)

The research task is skipped, the writer runs against the saved research output, and the crew finishes.

The resumed crew is built from the checkpoint file, not from crew. If your tasks use callbacks, read What a restore does not bring back.

How-to guides

Enable checkpointing with defaults

crew = Crew(agents=[...], tasks=[...], checkpoint=True)

Writes to ./.checkpoints/ on every task_completed.

Customize storage and frequency

from crewai import Crew, CheckpointConfig

crew = Crew(
    agents=[...],
    tasks=[...],
    checkpoint=CheckpointConfig(
        location="./my_checkpoints",
        on_events=["task_completed", "crew_kickoff_completed"],
        max_checkpoints=5,
    ),
)

Choose a storage provider

from crewai import Crew, CheckpointConfig
from crewai.state import JsonProvider

crew = Crew(
    agents=[...],
    tasks=[...],
    checkpoint=CheckpointConfig(
        location="./my_checkpoints",
        provider=JsonProvider(),
        max_checkpoints=5,
    ),
)

from crewai import Crew, CheckpointConfig
from crewai.state import SqliteProvider

crew = Crew(
    agents=[...],
    tasks=[...],
    checkpoint=CheckpointConfig(
        location="./.checkpoints.db",
        provider=SqliteProvider(),
        max_checkpoints=50,
    ),
)

SQLite enables WAL journal mode for concurrent reads. Prefer it for high-frequency checkpointing.

Opt one agent out

crew = Crew(
    agents=[
        Agent(role="Researcher", ...),
        Agent(role="Writer", ..., checkpoint=False),
    ],
    tasks=[...],
    checkpoint=True,
)

Fork into a new branch

fork() restores a checkpoint under a fresh lineage so the new run does not collide with the original.

config = CheckpointConfig(restore_from="./my_checkpoints/<file>.json")
crew = Crew.fork(config, branch="experiment-a")
result = crew.kickoff(inputs={"strategy": "aggressive"})

The branch label is optional; one is generated if omitted.

Checkpoint a Crew, Flow, or Agent

Crew
Flow
Agent

crew = Crew(
    agents=[researcher, writer],
    tasks=[research_task, write_task, review_task],
    checkpoint=CheckpointConfig(location="./crew_cp"),
)

Default trigger: task_completed.

from crewai.flow.flow import Flow, start, listen
from crewai import CheckpointConfig

class MyFlow(Flow):
    @start()
    def step_one(self):
        return "data"

    @listen(step_one)
    def step_two(self, data):
        return process(data)

flow = MyFlow(
    checkpoint=CheckpointConfig(
        location="./flow_cp",
        on_events=["method_execution_finished"],
    ),
)
result = flow.kickoff()

agent = Agent(
    role="Researcher",
    goal="Research topics",
    backstory="Expert researcher",
    checkpoint=CheckpointConfig(
        location="./agent_cp",
        on_events=["lite_agent_execution_completed"],
    ),
)
result = agent.kickoff(messages=[{"role": "user", "content": "Research AI trends"}])

Write a checkpoint manually

from __future__ import annotations

from typing import TYPE_CHECKING, Any

from crewai.events.event_bus import crewai_event_bus
from crewai.events.types.llm_events import LLMCallCompletedEvent

if TYPE_CHECKING:
    from crewai.state.runtime import RuntimeState


@crewai_event_bus.on(LLMCallCompletedEvent)
def on_llm_done(source: Any, event: LLMCallCompletedEvent, state: RuntimeState) -> None:
    path = state.checkpoint("./my_checkpoints")
    print(f"Saved checkpoint: {path}")

from __future__ import annotations

from typing import TYPE_CHECKING, Any

from crewai.events.event_bus import crewai_event_bus
from crewai.events.types.llm_events import LLMCallCompletedEvent

if TYPE_CHECKING:
    from crewai.state.runtime import RuntimeState


@crewai_event_bus.on(LLMCallCompletedEvent)
async def on_llm_done_async(source: Any, event: LLMCallCompletedEvent, state: RuntimeState) -> None:
    path = await state.acheckpoint("./my_checkpoints")
    print(f"Saved checkpoint: {path}")

A state argument is supplied automatically when the handler takes three parameters. See Event Listeners for the full event catalog.

Browse, resume, and fork from the CLI

crewai checkpoint
crewai checkpoint --location ./my_checkpoints
crewai checkpoint --location ./.checkpoints.db

Checkpoint TUI tree view — Checkpoint tree — branches and forks nest under their parent.

The left panel groups checkpoints by branch; forks nest under their parent. Selecting a checkpoint opens the detail panel with metadata, entity state, and task progress. Resume continues the run; Fork starts a new branch.

Checkpoint detail overview tab — Overview tab — metadata, entity state, and run summary.

The detail panel exposes two editable areas:

Inputs — original kickoff inputs, pre-filled and editable.
Task outputs — outputs of completed tasks. Editing an output and hitting Fork invalidates downstream tasks so they re-run against the modified context.

Fork confirmation panel — Fork view — confirm a new branch from the selected checkpoint.

Useful for “what if” exploration: fork, tweak, observe.

Inspect checkpoints without the TUI

crewai checkpoint list ./my_checkpoints
crewai checkpoint info ./my_checkpoints/<file>.json
crewai checkpoint info ./.checkpoints.db

Reference

`CheckpointConfig`

str

default:"\"./.checkpoints\""

Storage destination. A directory for JsonProvider, a database file path for SqliteProvider.

list[CheckpointEventType | Literal["*"]]

default:"[\"task_completed\"]"

Event types that trigger a checkpoint. CheckpointEventType is a Literal — your type checker will autocomplete and reject unsupported values. See event types for the full list.

BaseProvider

default:"JsonProvider()"

Storage backend. Either JsonProvider or SqliteProvider.

int | None

default:"None"

Maximum checkpoints to retain. Oldest are pruned after each write.

Path | str | None

default:"None"

Checkpoint to restore from when passed via from_checkpoint.

`checkpoint` field values

Accepted by Crew, Flow, and Agent.

default

Inherit from parent.

bool

Enable with defaults.

bool

Explicit opt-out. Stops inheritance.

CheckpointConfig

Custom configuration.

Event types

on_events accepts any combination of CheckpointEventType values. The default ["task_completed"] writes one checkpoint per finished task; ["*"] matches every event.

["*"] and high-frequency events like llm_call_completed write many checkpoints and can degrade performance. Pair them with max_checkpoints.

Show All supported events

Task — task_started, task_completed, task_failed, task_evaluation
Crew — crew_kickoff_started, crew_kickoff_completed, crew_kickoff_failed, crew_train_started, crew_train_completed, crew_train_failed, crew_test_started, crew_test_completed, crew_test_failed, crew_test_result
Agent — agent_execution_started, agent_execution_completed, agent_execution_error, lite_agent_execution_started, lite_agent_execution_completed, lite_agent_execution_error, agent_evaluation_started, agent_evaluation_completed, agent_evaluation_failed
Flow — flow_created, flow_started, flow_finished, flow_paused, method_execution_started, method_execution_finished, method_execution_failed, method_execution_paused, human_feedback_requested, human_feedback_received, flow_input_requested, flow_input_received
LLM — llm_call_started, llm_call_completed, llm_call_failed, llm_stream_chunk, llm_thinking_chunk
LLM Guardrail — llm_guardrail_started, llm_guardrail_completed, llm_guardrail_failed
Tool — tool_usage_started, tool_usage_finished, tool_usage_error, tool_validate_input_error, tool_selection_error, tool_execution_error
Memory — memory_save_started, memory_save_completed, memory_save_failed, memory_query_started, memory_query_completed, memory_query_failed, memory_retrieval_started, memory_retrieval_completed, memory_retrieval_failed
Knowledge — knowledge_search_query_started, knowledge_search_query_completed, knowledge_query_started, knowledge_query_completed, knowledge_query_failed, knowledge_search_query_failed
Reasoning — agent_reasoning_started, agent_reasoning_completed, agent_reasoning_failed
MCP — mcp_connection_started, mcp_connection_completed, mcp_connection_failed, mcp_tool_execution_started, mcp_tool_execution_completed, mcp_tool_execution_failed, mcp_config_fetch_failed
Observation — step_observation_started, step_observation_completed, step_observation_failed, plan_refinement, plan_replan_triggered, goal_achieved_early
Skill — skill_discovery_started, skill_discovery_completed, skill_loaded, skill_activated, skill_load_failed
Logging — agent_logs_started, agent_logs_execution
A2A — a2a_delegation_started, a2a_delegation_completed, a2a_conversation_started, a2a_conversation_completed, a2a_message_sent, a2a_response_received, a2a_polling_started, a2a_polling_status, a2a_push_notification_registered, a2a_push_notification_received, a2a_push_notification_sent, a2a_push_notification_timeout, a2a_streaming_started, a2a_streaming_chunk, a2a_agent_card_fetched, a2a_authentication_failed, a2a_artifact_received, a2a_connection_error, a2a_server_task_started, a2a_server_task_completed, a2a_server_task_canceled, a2a_server_task_failed, a2a_parallel_delegation_started, a2a_parallel_delegation_completed, a2a_transport_negotiated, a2a_content_type_negotiated, a2a_context_created, a2a_context_expired, a2a_context_idle, a2a_context_completed, a2a_context_pruned
System signals — SIGTERM, SIGINT, SIGHUP, SIGTSTP, SIGCONT
Wildcard — "*" matches every event.

Storage providers

provider

One file per checkpoint, named <timestamp>_<uuid>.json inside location.

provider

Single database file at location with WAL journaling.

CLI

Command	Purpose
`crewai checkpoint`	Launch the TUI; auto-detect storage.
`crewai checkpoint --location <path>`	Launch the TUI against a specific location.
`crewai checkpoint list <path>`	List checkpoints.
`crewai checkpoint info <path>`	Inspect a checkpoint file or the latest entry in a SQLite database.

Get Started

Guides

Core Concepts

MCP Integration

Tools

Observability

Learn

Telemetry

Explanation

Tutorial

How-to guides

Reference

Explanation

What a checkpoint is

When checkpoints are written

Storage

Inheritance model

What a restore does not bring back

Tutorial: Resume a failing crew

How-to guides

Reference

`CheckpointConfig`

`checkpoint` field values

Event types

Storage providers

CLI

Explanation

Tutorial

How-to guides

Reference

​Explanation

​What a checkpoint is

​When checkpoints are written

​Storage

​Inheritance model

​What a restore does not bring back

​Tutorial: Resume a failing crew

​How-to guides

​Reference

​CheckpointConfig

​checkpoint field values

​Event types

​Storage providers

​CLI

Explanation

What a checkpoint is

When checkpoints are written

Storage

Inheritance model

What a restore does not bring back

Tutorial: Resume a failing crew

How-to guides

Reference

`CheckpointConfig`

`checkpoint` field values

Event types

Storage providers

CLI