Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.
feat: embed crewai_version in checkpoints with migration framework
Greyson LaLonde56cf8a4384e4
diff --git a/lib/crewai/src/crewai/cli/crew_chat.py b/lib/crewai/src/crewai/cli/crew_chat.pyindex ad1c65894..61d9b4d9e 100644--- a/lib/crewai/src/crewai/cli/crew_chat.py+++ b/lib/crewai/src/crewai/cli/crew_chat.py@@ -13,7 +13,6 @@ from packaging import versionimport tomlifrom crewai.cli.utils import read_toml-from crewai.cli.version import get_crewai_versionfrom crewai.crew import Crewfrom crewai.llm import LLMfrom crewai.llms.base_llm import BaseLLM@@ -21,6 +20,7 @@ from crewai.types.crew_chat import ChatInputField, ChatInputsfrom crewai.utilities.llm_utils import create_llmfrom crewai.utilities.printer import PRINTERfrom crewai.utilities.types import LLMMessage+from crewai.utilities.version import get_crewai_versionMIN_REQUIRED_VERSION: Final[Literal["0.98.0"]] = "0.98.0"diff --git a/lib/crewai/src/crewai/cli/enterprise/main.py b/lib/crewai/src/crewai/cli/enterprise/main.pyindex 395de418b..2977868f2 100644--- a/lib/crewai/src/crewai/cli/enterprise/main.py+++ b/lib/crewai/src/crewai/cli/enterprise/main.py@@ -7,7 +7,7 @@ from rich.console import Consolefrom crewai.cli.authentication.main import Oauth2Settings, ProviderFactoryfrom crewai.cli.command import BaseCommandfrom crewai.cli.settings.main import SettingsCommand-from crewai.cli.version import get_crewai_version+from crewai.utilities.version import get_crewai_versionconsole = Console()diff --git a/lib/crewai/src/crewai/cli/plus_api.py b/lib/crewai/src/crewai/cli/plus_api.pyindex ac7acfda9..862ab81e8 100644--- a/lib/crewai/src/crewai/cli/plus_api.py+++ b/lib/crewai/src/crewai/cli/plus_api.py@@ -6,7 +6,7 @@ import httpxfrom crewai.cli.config import Settingsfrom crewai.cli.constants import DEFAULT_CREWAI_ENTERPRISE_URL-from crewai.cli.version import get_crewai_version+from crewai.utilities.version import get_crewai_versionclass PlusAPI:diff --git a/lib/crewai/src/crewai/cli/run_crew.py b/lib/crewai/src/crewai/cli/run_crew.pyindex 6f031f245..ba2202032 100644--- a/lib/crewai/src/crewai/cli/run_crew.py+++ b/lib/crewai/src/crewai/cli/run_crew.py@@ -5,7 +5,7 @@ import clickfrom packaging import versionfrom crewai.cli.utils import build_env_with_all_tool_credentials, read_toml-from crewai.cli.version import get_crewai_version+from crewai.utilities.version import get_crewai_versionclass CrewType(Enum):diff --git a/lib/crewai/src/crewai/cli/version.py b/lib/crewai/src/crewai/cli/version.pyindex 60eb3a95a..232aa2423 100644--- a/lib/crewai/src/crewai/cli/version.py+++ b/lib/crewai/src/crewai/cli/version.py@@ -3,7 +3,6 @@from collections.abc import Mappingfrom datetime import datetime, timedeltafrom functools import lru_cache-import importlib.metadataimport jsonfrom pathlib import Pathfrom typing import Any@@ -13,6 +12,8 @@ from urllib.error import URLErrorimport appdirsfrom packaging.version import InvalidVersion, Version, parse+from crewai.utilities.version import get_crewai_version+@lru_cache(maxsize=1)def _get_cache_file() -> Path:@@ -25,11 +26,6 @@ def _get_cache_file() -> Path:return cache_dir / "version_cache.json"-def get_crewai_version() -> str:- """Get the version number of CrewAI running the CLI."""- return importlib.metadata.version("crewai")--def _is_cache_valid(cache_data: Mapping[str, Any]) -> bool:"""Check if the cache is still valid, less than 24 hours old."""if "timestamp" not in cache_data:diff --git a/lib/crewai/src/crewai/events/listeners/tracing/trace_batch_manager.py b/lib/crewai/src/crewai/events/listeners/tracing/trace_batch_manager.pyindex 1a25b68a9..d2a0912f6 100644--- a/lib/crewai/src/crewai/events/listeners/tracing/trace_batch_manager.py+++ b/lib/crewai/src/crewai/events/listeners/tracing/trace_batch_manager.py@@ -13,13 +13,13 @@ from crewai.cli.authentication.token import AuthError, get_auth_tokenfrom crewai.cli.config import Settingsfrom crewai.cli.constants import DEFAULT_CREWAI_ENTERPRISE_URLfrom crewai.cli.plus_api import PlusAPI-from crewai.cli.version import get_crewai_versionfrom crewai.events.listeners.tracing.types import TraceEventfrom crewai.events.listeners.tracing.utils import (get_user_id,is_tracing_enabled_in_context,should_auto_collect_first_time_traces,)+from crewai.utilities.version import get_crewai_versionlogger = getLogger(__name__)diff --git a/lib/crewai/src/crewai/events/listeners/tracing/trace_listener.py b/lib/crewai/src/crewai/events/listeners/tracing/trace_listener.pyindex 0e3b284c0..c4cc6cb71 100644--- a/lib/crewai/src/crewai/events/listeners/tracing/trace_listener.py+++ b/lib/crewai/src/crewai/events/listeners/tracing/trace_listener.py@@ -7,7 +7,6 @@ import uuidfrom typing_extensions import Selffrom crewai.cli.authentication.token import AuthError, get_auth_token-from crewai.cli.version import get_crewai_versionfrom crewai.events.base_event_listener import BaseEventListenerfrom crewai.events.base_events import BaseEventfrom crewai.events.event_bus import CrewAIEventsBus@@ -127,6 +126,7 @@ from crewai.events.types.tool_usage_events import (ToolUsageStartedEvent,)from crewai.events.utils.console_formatter import ConsoleFormatter+from crewai.utilities.version import get_crewai_versionclass TraceCollectionListener(BaseEventListener):diff --git a/lib/crewai/src/crewai/state/runtime.py b/lib/crewai/src/crewai/state/runtime.pyindex b4293ad39..79c836e1e 100644--- a/lib/crewai/src/crewai/state/runtime.py+++ b/lib/crewai/src/crewai/state/runtime.py@@ -9,9 +9,11 @@ via ``RuntimeState.model_rebuild()``.from __future__ import annotations+import loggingfrom typing import TYPE_CHECKING, Anyimport uuid+from packaging.version import Versionfrom pydantic import (ModelWrapValidatorHandler,PrivateAttr,@@ -24,6 +26,10 @@ from crewai.context import capture_execution_contextfrom crewai.state.event_record import EventRecordfrom crewai.state.provider.core import BaseProviderfrom crewai.state.provider.json_provider import JsonProvider+from crewai.utilities.version import get_crewai_version+++logger = logging.getLogger(__name__)if TYPE_CHECKING:@@ -61,6 +67,39 @@ def _sync_checkpoint_fields(entity: object) -> None:entity.checkpoint_kickoff_event_id = entity._kickoff_event_id+def _migrate(data: dict[str, Any]) -> dict[str, Any]:+ """Apply version-based migrations to checkpoint data.++ Each block handles checkpoints older than a specific version,+ transforming them forward to the current format. Blocks run in+ version order so migrations compose.++ Args:+ data: The raw deserialized checkpoint dict.++ Returns:+ The migrated checkpoint dict.+ """+ raw = data.get("crewai_version")+ current = Version(get_crewai_version())+ stored = Version(raw) if raw else Version("0.0.0")++ if raw is None:+ logger.warning("Checkpoint has no crewai_version — treating as 0.0.0")+ elif stored != current:+ logger.debug(+ "Migrating checkpoint from crewAI %s to %s",+ stored,+ current,+ )++ # --- migrations in version order ---+ # if stored < Version("X.Y.Z"):+ # data.setdefault("some_field", "default")++ return data++class RuntimeState(RootModel): # type: ignore[type-arg]root: list[Entity]_provider: BaseProvider = PrivateAttr(default_factory=JsonProvider)@@ -77,6 +116,7 @@ class RuntimeState(RootModel): # type: ignore[type-arg]@model_serializer(mode="plain")def _serialize(self) -> dict[str, Any]:return {+ "crewai_version": get_crewai_version(),"parent_id": self._parent_id,"branch": self._branch,"entities": [e.model_dump(mode="json") for e in self.root],@@ -89,6 +129,7 @@ class RuntimeState(RootModel): # type: ignore[type-arg]cls, data: Any, handler: ModelWrapValidatorHandler[RuntimeState]) -> RuntimeState:if isinstance(data, dict) and "entities" in data:+ data = _migrate(data)record_data = data.get("event_record")state = handler(data["entities"])if record_data:diff --git a/lib/crewai/src/crewai/utilities/version.py b/lib/crewai/src/crewai/utilities/version.pynew file mode 100644index 000000000..57a5c562d--- /dev/null+++ b/lib/crewai/src/crewai/utilities/version.py@@ -0,0 +1,12 @@+"""Version utilities for crewAI."""++from __future__ import annotations++from functools import cache+import importlib.metadata+++@cache+def get_crewai_version() -> str:+ """Get the installed crewAI version string."""+ return importlib.metadata.version("crewai")diff --git a/lib/crewai/tests/test_checkpoint.py b/lib/crewai/tests/test_checkpoint.pyindex cbea4b562..0a0c00027 100644--- a/lib/crewai/tests/test_checkpoint.py+++ b/lib/crewai/tests/test_checkpoint.py@@ -196,6 +196,39 @@ class TestRuntimeStateLineage:assert state._parent_id is Noneassert state._branch == "main"+ def test_serialize_includes_version(self) -> None:+ from crewai.utilities.version import get_crewai_version++ state = self._make_state()+ dumped = json.loads(state.model_dump_json())+ assert dumped["crewai_version"] == get_crewai_version()++ def test_deserialize_migrates_on_version_mismatch(self, caplog: Any) -> None:+ import logging++ state = self._make_state()+ raw = state.model_dump_json()+ data = json.loads(raw)+ data["crewai_version"] = "0.1.0"+ with caplog.at_level(logging.DEBUG):+ RuntimeState.model_validate_json(+ json.dumps(data), context={"from_checkpoint": True}+ )+ assert "Migrating checkpoint from crewAI 0.1.0" in caplog.text++ def test_deserialize_warns_on_missing_version(self, caplog: Any) -> None:+ import logging++ state = self._make_state()+ raw = state.model_dump_json()+ data = json.loads(raw)+ data.pop("crewai_version", None)+ with caplog.at_level(logging.WARNING):+ RuntimeState.model_validate_json(+ json.dumps(data), context={"from_checkpoint": True}+ )+ assert "treating as 0.0.0" in caplog.text+def test_serialize_includes_lineage(self) -> None:state = self._make_state()state._parent_id = "parent456"