Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.
feat: add from_checkpoint parameter to kickoff methods
Greyson LaLonde84b1b0a0b0e7
diff --git a/lib/crewai/src/crewai/agents/agent_builder/base_agent.py b/lib/crewai/src/crewai/agents/agent_builder/base_agent.pyindex c55f5e417..9d37373e8 100644--- a/lib/crewai/src/crewai/agents/agent_builder/base_agent.py+++ b/lib/crewai/src/crewai/agents/agent_builder/base_agent.py@@ -51,7 +51,6 @@ from crewai.utilities.string_utils import interpolate_onlyif TYPE_CHECKING:from crewai.context import ExecutionContextfrom crewai.crew import Crew- from crewai.state.provider.core import BaseProviderdef _validate_crew_ref(value: Any) -> Any:@@ -338,19 +337,16 @@ class BaseAgent(BaseModel, ABC, metaclass=AgentMeta):execution_context: ExecutionContext | None = Field(default=None)@classmethod- def from_checkpoint(- cls, path: str, *, provider: BaseProvider | None = None- ) -> Self:- """Restore an Agent from a checkpoint file."""+ def from_checkpoint(cls, config: CheckpointConfig) -> Self:+ """Restore an Agent from a checkpoint.++ Args:+ config: Checkpoint configuration with ``restore_from`` set.+ """from crewai.context import apply_execution_context- from crewai.state.provider.json_provider import JsonProviderfrom crewai.state.runtime import RuntimeState- state = RuntimeState.from_checkpoint(- path,- provider=provider or JsonProvider(),- context={"from_checkpoint": True},- )+ state = RuntimeState.from_checkpoint(config, context={"from_checkpoint": True})for entity in state.root:if isinstance(entity, cls):if entity.execution_context is not None:@@ -359,7 +355,9 @@ class BaseAgent(BaseModel, ABC, metaclass=AgentMeta):entity.agent_executor.agent = entityentity.agent_executor._resuming = Truereturn entity- raise ValueError(f"No {cls.__name__} found in checkpoint: {path}")+ raise ValueError(+ f"No {cls.__name__} found in checkpoint: {config.restore_from}"+ )@model_validator(mode="before")@classmethoddiff --git a/lib/crewai/src/crewai/cli/checkpoint_tui.py b/lib/crewai/src/crewai/cli/checkpoint_tui.pyindex 5f81d5fad..c58ed2ea6 100644--- a/lib/crewai/src/crewai/cli/checkpoint_tui.py+++ b/lib/crewai/src/crewai/cli/checkpoint_tui.py@@ -353,8 +353,9 @@ async def _run_checkpoint_tui_async(location: str) -> None:click.echo(f"\nResuming from: {selected}\n")from crewai.crew import Crew+ from crewai.state.checkpoint_config import CheckpointConfig- crew = Crew.from_checkpoint(selected)+ crew = Crew.from_checkpoint(CheckpointConfig(restore_from=selected))result = await crew.akickoff()click.echo(f"\nResult: {getattr(result, 'raw', result)}")diff --git a/lib/crewai/src/crewai/crew.py b/lib/crewai/src/crewai/crew.pyindex d279a265d..111babbf3 100644--- a/lib/crewai/src/crewai/crew.py+++ b/lib/crewai/src/crewai/crew.py@@ -42,7 +42,6 @@ if TYPE_CHECKING:from opentelemetry.trace import Spanfrom crewai.context import ExecutionContext- from crewai.state.provider.core import BaseProvidertry:from crewai_files import get_supported_content_types@@ -104,7 +103,11 @@ from crewai.rag.types import SearchResultfrom crewai.security.fingerprint import Fingerprintfrom crewai.security.security_config import SecurityConfigfrom crewai.skills.models import Skill-from crewai.state.checkpoint_config import CheckpointConfig, _coerce_checkpoint+from crewai.state.checkpoint_config import (+ CheckpointConfig,+ _coerce_checkpoint,+ apply_checkpoint,+)from crewai.task import Taskfrom crewai.tasks.conditional_task import ConditionalTaskfrom crewai.tasks.task_output import TaskOutput@@ -365,32 +368,21 @@ class Crew(FlowTrackable, BaseModel):checkpoint_kickoff_event_id: str | None = Field(default=None)@classmethod- def from_checkpoint(- cls, path: str, *, provider: BaseProvider | None = None- ) -> Crew:- """Restore a Crew from a checkpoint file, ready to resume via kickoff().+ def from_checkpoint(cls, config: CheckpointConfig) -> Crew:+ """Restore a Crew from a checkpoint, ready to resume via kickoff().Args:- path: Path to a checkpoint JSON file.- provider: Storage backend to read from. Defaults to JsonProvider.+ config: Checkpoint configuration with ``restore_from`` set to+ the path of the checkpoint to load.Returns:A Crew instance. Call kickoff() to resume from the last completed task."""from crewai.context import apply_execution_contextfrom crewai.events.event_bus import crewai_event_bus- from crewai.state.provider.json_provider import JsonProvider- from crewai.state.provider.utils import detect_providerfrom crewai.state.runtime import RuntimeState- if provider is None:- provider = detect_provider(path)-- state = RuntimeState.from_checkpoint(- path,- provider=provider or JsonProvider(),- context={"from_checkpoint": True},- )+ state = RuntimeState.from_checkpoint(config, context={"from_checkpoint": True})crewai_event_bus.set_runtime_state(state)for entity in state.root:if isinstance(entity, cls):@@ -398,27 +390,24 @@ class Crew(FlowTrackable, BaseModel):apply_execution_context(entity.execution_context)entity._restore_runtime()return entity- raise ValueError(f"No Crew found in checkpoint: {path}")+ raise ValueError(f"No Crew found in checkpoint: {config.restore_from}")@classmethoddef fork(cls,- path: str,- *,+ config: CheckpointConfig,branch: str | None = None,- provider: BaseProvider | None = None,) -> Crew:"""Fork a Crew from a checkpoint, creating a new execution branch.Args:- path: Path to a checkpoint file.+ config: Checkpoint configuration with ``restore_from`` set.branch: Branch label for the fork. Auto-generated if not provided.- provider: Storage backend to read from. Defaults to auto-detect.Returns:A Crew instance on the new branch. Call kickoff() to run."""- crew = cls.from_checkpoint(path, provider=provider)+ crew = cls.from_checkpoint(config)state = crewai_event_bus._runtime_stateif state is None:raise RuntimeError(@@ -882,16 +871,23 @@ class Crew(FlowTrackable, BaseModel):self,inputs: dict[str, Any] | None = None,input_files: dict[str, FileInput] | None = None,+ from_checkpoint: CheckpointConfig | None = None,) -> CrewOutput | CrewStreamingOutput:"""Execute the crew's workflow.Args:inputs: Optional input dictionary for task interpolation.input_files: Optional dict of named file inputs for the crew.+ from_checkpoint: Optional checkpoint config. If ``restore_from``+ is set, the crew resumes from that checkpoint. Remaining+ config fields enable checkpointing for the run.Returns:CrewOutput or CrewStreamingOutput if streaming is enabled."""+ restored = apply_checkpoint(self, from_checkpoint)+ if restored is not None:+ return restored.kickoff(inputs=inputs, input_files=input_files) # type: ignore[no-any-return]get_env_context()if self.stream:enable_agent_streaming(self.agents)@@ -1004,12 +1000,15 @@ class Crew(FlowTrackable, BaseModel):self,inputs: dict[str, Any] | None = None,input_files: dict[str, FileInput] | None = None,+ from_checkpoint: CheckpointConfig | None = None,) -> CrewOutput | CrewStreamingOutput:"""Asynchronous kickoff method to start the crew execution.Args:inputs: Optional input dictionary for task interpolation.input_files: Optional dict of named file inputs for the crew.+ from_checkpoint: Optional checkpoint config. If ``restore_from``+ is set, the crew resumes from that checkpoint.Returns:CrewOutput or CrewStreamingOutput if streaming is enabled.@@ -1018,6 +1017,9 @@ class Crew(FlowTrackable, BaseModel):to get stream chunks. After iteration completes, access the final resultvia .result."""+ restored = apply_checkpoint(self, from_checkpoint)+ if restored is not None:+ return await restored.kickoff_async(inputs=inputs, input_files=input_files) # type: ignore[no-any-return]inputs = inputs or {}if self.stream:@@ -1078,6 +1080,7 @@ class Crew(FlowTrackable, BaseModel):self,inputs: dict[str, Any] | None = None,input_files: dict[str, FileInput] | None = None,+ from_checkpoint: CheckpointConfig | None = None,) -> CrewOutput | CrewStreamingOutput:"""Native async kickoff method using async task execution throughout.@@ -1088,10 +1091,15 @@ class Crew(FlowTrackable, BaseModel):Args:inputs: Optional input dictionary for task interpolation.input_files: Optional dict of named file inputs for the crew.+ from_checkpoint: Optional checkpoint config. If ``restore_from``+ is set, the crew resumes from that checkpoint.Returns:CrewOutput or CrewStreamingOutput if streaming is enabled."""+ restored = apply_checkpoint(self, from_checkpoint)+ if restored is not None:+ return await restored.akickoff(inputs=inputs, input_files=input_files) # type: ignore[no-any-return]if self.stream:enable_agent_streaming(self.agents)ctx = StreamingContext(use_async=True)diff --git a/lib/crewai/src/crewai/flow/flow.py b/lib/crewai/src/crewai/flow/flow.pyindex a85885bd9..057f60ffb 100644--- a/lib/crewai/src/crewai/flow/flow.py+++ b/lib/crewai/src/crewai/flow/flow.py@@ -113,7 +113,11 @@ from crewai.flow.utils import ()from crewai.memory.memory_scope import MemoryScope, MemorySlicefrom crewai.memory.unified_memory import Memory-from crewai.state.checkpoint_config import CheckpointConfig, _coerce_checkpoint+from crewai.state.checkpoint_config import (+ CheckpointConfig,+ _coerce_checkpoint,+ apply_checkpoint,+)if TYPE_CHECKING:@@ -122,7 +126,6 @@ if TYPE_CHECKING:from crewai.context import ExecutionContextfrom crewai.flow.async_feedback.types import PendingFeedbackContextfrom crewai.llms.base_llm import BaseLLM- from crewai.state.provider.core import BaseProviderfrom crewai.flow.visualization import build_flow_structure, render_interactivefrom crewai.types.streaming import CrewStreamingOutput, FlowStreamingOutput@@ -928,20 +931,21 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):] = Field(default=None)@classmethod- def from_checkpoint(- cls, path: str, *, provider: BaseProvider | None = None- ) -> Flow: # type: ignore[type-arg]- """Restore a Flow from a checkpoint file."""+ def from_checkpoint(cls, config: CheckpointConfig) -> Flow: # type: ignore[type-arg]+ """Restore a Flow from a checkpoint.++ Args:+ config: Checkpoint configuration with ``restore_from`` set to+ the path of the checkpoint to load.++ Returns:+ A Flow instance ready to resume.+ """from crewai.context import apply_execution_contextfrom crewai.events.event_bus import crewai_event_bus- from crewai.state.provider.json_provider import JsonProviderfrom crewai.state.runtime import RuntimeState- state = RuntimeState.from_checkpoint(- path,- provider=provider or JsonProvider(),- context={"from_checkpoint": True},- )+ state = RuntimeState.from_checkpoint(config, context={"from_checkpoint": True})crewai_event_bus.set_runtime_state(state)for entity in state.root:if not isinstance(entity, Flow):@@ -958,27 +962,24 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):instance.checkpoint_state = entity.checkpoint_stateinstance._restore_from_checkpoint()return instance- raise ValueError(f"No Flow found in checkpoint: {path}")+ raise ValueError(f"No Flow found in checkpoint: {config.restore_from}")@classmethoddef fork(cls,- path: str,- *,+ config: CheckpointConfig,branch: str | None = None,- provider: BaseProvider | None = None,) -> Flow: # type: ignore[type-arg]"""Fork a Flow from a checkpoint, creating a new execution branch.Args:- path: Path to a checkpoint file.+ config: Checkpoint configuration with ``restore_from`` set.branch: Branch label for the fork. Auto-generated if not provided.- provider: Storage backend to read from. Defaults to auto-detect.Returns:A Flow instance on the new branch. Call kickoff() to run."""- flow = cls.from_checkpoint(path, provider=provider)+ flow = cls.from_checkpoint(config)state = crewai_event_bus._runtime_stateif state is None:raise RuntimeError(@@ -1984,6 +1985,7 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):self,inputs: dict[str, Any] | None = None,input_files: dict[str, FileInput] | None = None,+ from_checkpoint: CheckpointConfig | None = None,) -> Any | FlowStreamingOutput:"""Start the flow execution in a synchronous context.@@ -1993,10 +1995,15 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):Args:inputs: Optional dictionary containing input values and/or a state ID.input_files: Optional dict of named file inputs for the flow.+ from_checkpoint: Optional checkpoint config. If ``restore_from``+ is set, the flow resumes from that checkpoint.Returns:The final output from the flow or FlowStreamingOutput if streaming."""+ restored = apply_checkpoint(self, from_checkpoint)+ if restored is not None:+ return restored.kickoff(inputs=inputs, input_files=input_files)get_env_context()if self.stream:result_holder: list[Any] = []@@ -2053,6 +2060,7 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):self,inputs: dict[str, Any] | None = None,input_files: dict[str, FileInput] | None = None,+ from_checkpoint: CheckpointConfig | None = None,) -> Any | FlowStreamingOutput:"""Start the flow execution asynchronously.@@ -2064,10 +2072,15 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):Args:inputs: Optional dictionary containing input values and/or a state ID for restoration.input_files: Optional dict of named file inputs for the flow.+ from_checkpoint: Optional checkpoint config. If ``restore_from``+ is set, the flow resumes from that checkpoint.Returns:The final output from the flow, which is the result of the last executed method."""+ restored = apply_checkpoint(self, from_checkpoint)+ if restored is not None:+ return await restored.kickoff_async(inputs=inputs, input_files=input_files)if self.stream:result_holder: list[Any] = []current_task_info: TaskInfo = {@@ -2326,17 +2339,20 @@ class Flow(BaseModel, Generic[T], metaclass=FlowMeta):self,inputs: dict[str, Any] | None = None,input_files: dict[str, FileInput] | None = None,+ from_checkpoint: CheckpointConfig | None = None,) -> Any | FlowStreamingOutput:"""Native async method to start the flow execution. Alias for kickoff_async.Args:inputs: Optional dictionary containing input values and/or a state ID for restoration.input_files: Optional dict of named file inputs for the flow.+ from_checkpoint: Optional checkpoint config. If ``restore_from``+ is set, the flow resumes from that checkpoint.Returns:The final output from the flow, which is the result of the last executed method."""- return await self.kickoff_async(inputs, input_files)+ return await self.kickoff_async(inputs, input_files, from_checkpoint)async def _execute_start_method(self, start_method_name: FlowMethodName) -> None:"""Executes a flow's start method and its triggered listeners.diff --git a/lib/crewai/src/crewai/state/checkpoint_config.py b/lib/crewai/src/crewai/state/checkpoint_config.pyindex 38c6b0490..bd24ef8eb 100644--- a/lib/crewai/src/crewai/state/checkpoint_config.py+++ b/lib/crewai/src/crewai/state/checkpoint_config.py@@ -2,6 +2,7 @@from __future__ import annotations+from pathlib import Pathfrom typing import Annotated, Any, Literalfrom pydantic import BaseModel, Field, model_validator@@ -201,6 +202,12 @@ class CheckpointConfig(BaseModel):description="Maximum checkpoints to keep. Oldest are pruned after ""each write. None means keep all.",)+ restore_from: Path | str | None = Field(+ default=None,+ description="Path or location of a checkpoint to restore from. "+ "When passed via a kickoff method's from_checkpoint parameter, "+ "the crew or flow resumes from this checkpoint.",+ )@model_validator(mode="after")def _register_handlers(self) -> CheckpointConfig:@@ -216,3 +223,25 @@ class CheckpointConfig(BaseModel):@propertydef trigger_events(self) -> set[str]:return set(self.on_events)+++def apply_checkpoint(instance: Any, from_checkpoint: CheckpointConfig | None) -> Any:+ """Handle checkpoint config for a kickoff method.++ If *from_checkpoint* carries a ``restore_from`` path, builds and returns a+ restored instance (with ``restore_from`` cleared). The caller should+ dispatch into its own kickoff variant on that restored instance.++ If *from_checkpoint* is present but has no ``restore_from``, sets+ ``instance.checkpoint`` and returns ``None`` (proceed normally).++ If *from_checkpoint* is ``None``, returns ``None`` immediately.+ """+ if from_checkpoint is None:+ return None+ if from_checkpoint.restore_from is not None:+ restored = type(instance).from_checkpoint(from_checkpoint)+ restored.checkpoint = from_checkpoint.model_copy(update={"restore_from": None})+ return restored+ instance.checkpoint = from_checkpoint+ return Nonediff --git a/lib/crewai/src/crewai/state/runtime.py b/lib/crewai/src/crewai/state/runtime.pyindex 79c836e1e..3f32457bb 100644--- a/lib/crewai/src/crewai/state/runtime.py+++ b/lib/crewai/src/crewai/state/runtime.py@@ -23,6 +23,7 @@ from pydantic import ()from crewai.context import capture_execution_context+from crewai.state.checkpoint_config import CheckpointConfigfrom crewai.state.event_record import EventRecordfrom crewai.state.provider.core import BaseProviderfrom crewai.state.provider.json_provider import JsonProvider@@ -208,19 +209,22 @@ class RuntimeState(RootModel): # type: ignore[type-arg]self._branch = f"fork/{uuid.uuid4().hex[:8]}"@classmethod- def from_checkpoint(- cls, location: str, provider: BaseProvider, **kwargs: Any- ) -> RuntimeState:+ def from_checkpoint(cls, config: CheckpointConfig, **kwargs: Any) -> RuntimeState:"""Restore a RuntimeState from a checkpoint.Args:- location: The identifier returned by a previous ``checkpoint`` call.- provider: The storage backend to read from.+ config: Checkpoint configuration with ``restore_from`` set.**kwargs: Passed to ``model_validate_json``.Returns:A restored RuntimeState."""+ from crewai.state.provider.utils import detect_provider++ if config.restore_from is None:+ raise ValueError("CheckpointConfig.restore_from must be set")+ location = str(config.restore_from)+ provider = detect_provider(location)raw = provider.from_checkpoint(location)state = cls.model_validate_json(raw, **kwargs)checkpoint_id = provider.extract_id(location)@@ -230,18 +234,23 @@ class RuntimeState(RootModel): # type: ignore[type-arg]@classmethodasync def afrom_checkpoint(- cls, location: str, provider: BaseProvider, **kwargs: Any+ cls, config: CheckpointConfig, **kwargs: Any) -> RuntimeState:"""Async version of :meth:`from_checkpoint`.Args:- location: The identifier returned by a previous ``acheckpoint`` call.- provider: The storage backend to read from.+ config: Checkpoint configuration with ``restore_from`` set.**kwargs: Passed to ``model_validate_json``.Returns:A restored RuntimeState."""+ from crewai.state.provider.utils import detect_provider++ if config.restore_from is None:+ raise ValueError("CheckpointConfig.restore_from must be set")+ location = str(config.restore_from)+ provider = detect_provider(location)raw = await provider.afrom_checkpoint(location)state = cls.model_validate_json(raw, **kwargs)checkpoint_id = provider.extract_id(location)diff --git a/lib/crewai/tests/test_checkpoint.py b/lib/crewai/tests/test_checkpoint.pyindex 0a0c00027..1f1541790 100644--- a/lib/crewai/tests/test_checkpoint.py+++ b/lib/crewai/tests/test_checkpoint.py@@ -172,6 +172,14 @@ class TestCheckpointConfig:cfg = CheckpointConfig(on_events=["*"])assert cfg.trigger_all+ def test_restore_from_field(self) -> None:+ cfg = CheckpointConfig(restore_from="/path/to/checkpoint.json")+ assert cfg.restore_from == "/path/to/checkpoint.json"++ def test_restore_from_default_none(self) -> None:+ cfg = CheckpointConfig()+ assert cfg.restore_from is None+def test_trigger_events(self) -> None:cfg = CheckpointConfig(on_events=["task_completed", "crew_kickoff_completed"]@@ -269,9 +277,9 @@ class TestRuntimeStateLineage:loc = state.checkpoint(d)written_id = state._checkpoint_id- provider = JsonProvider()+ cfg = CheckpointConfig(restore_from=loc)restored = RuntimeState.from_checkpoint(- loc, provider, context={"from_checkpoint": True}+ cfg, context={"from_checkpoint": True})assert restored._checkpoint_id == written_idassert restored._parent_id == written_id@@ -480,3 +488,51 @@ class TestSqliteProviderFork:agent = Agent(role="r", goal="g", backstory="b", llm="gpt-4o-mini")crew = Crew(agents=[agent], tasks=[], verbose=False)return RuntimeState(root=[crew])+++# ---------- Kickoff from_checkpoint parameter ----------+++class TestKickoffFromCheckpoint:+ def test_crew_kickoff_delegates_to_from_checkpoint(self) -> None:+ mock_restored = MagicMock(spec=Crew)+ mock_restored.kickoff.return_value = "result"++ cfg = CheckpointConfig(restore_from="/path/to/cp.json")+ with patch.object(Crew, "from_checkpoint", return_value=mock_restored):+ agent = Agent(role="r", goal="g", backstory="b", llm="gpt-4o-mini")+ crew = Crew(agents=[agent], tasks=[], verbose=False)+ result = crew.kickoff(inputs={"k": "v"}, from_checkpoint=cfg)++ mock_restored.kickoff.assert_called_once_with(+ inputs={"k": "v"}, input_files=None+ )+ assert mock_restored.checkpoint.restore_from is None+ assert result == "result"++ def test_crew_kickoff_config_only_sets_checkpoint(self) -> None:+ cfg = CheckpointConfig(on_events=["task_completed"])+ agent = Agent(role="r", goal="g", backstory="b", llm="gpt-4o-mini")+ crew = Crew(agents=[agent], tasks=[], verbose=False)+ assert crew.checkpoint is None+ with patch("crewai.crew.get_env_context"), \+ patch("crewai.crew.prepare_kickoff", side_effect=RuntimeError("stop")):+ with pytest.raises(RuntimeError, match="stop"):+ crew.kickoff(from_checkpoint=cfg)+ assert isinstance(crew.checkpoint, CheckpointConfig)+ assert crew.checkpoint.on_events == ["task_completed"]++ def test_flow_kickoff_delegates_to_from_checkpoint(self) -> None:+ mock_restored = MagicMock(spec=Flow)+ mock_restored.kickoff.return_value = "flow_result"++ cfg = CheckpointConfig(restore_from="/path/to/flow_cp.json")+ with patch.object(Flow, "from_checkpoint", return_value=mock_restored):+ flow = Flow()+ result = flow.kickoff(from_checkpoint=cfg)++ mock_restored.kickoff.assert_called_once_with(+ inputs=None, input_files=None+ )+ assert mock_restored.checkpoint.restore_from is None+ assert result == "flow_result"