feat: add checkpoint and fork support to standalone agents

[greysonlalonde]

Summary

• Add fork() classmethod to BaseAgent following the Crew/Flow pattern
• Fix from_checkpoint() to set runtime state on the event bus and restore event scopes
• Store kickoff event ID across checkpoints to skip re-emission on resume
• Handle agent entity type in checkpoint CLI and TUI resume/fork flows
• Sync checkpoint_kickoff_event_id in _sync_checkpoint_fields

Test plan

• pytest lib/crewai/tests/test_checkpoint.py — 54 passed
• Manual: agent with checkpoint=True, verify checkpoint written on kickoff
• Manual: resume and fork from agent checkpoint via CLI and TUI

---

Note

Medium Risk
Touches checkpoint restore/fork and event emission bookkeeping for agents, which can subtly affect resume behavior and observability even though the scope is limited and covered by new tests.

Overview
Standalone Agent checkpoints can now be resumed and forked similarly to Crew/Flow, including CLI (checkpoint_cli.py) and TUI (checkpoint_tui.py) flows that detect agent entities and run Agent.from_checkpoint() / Agent.fork().

Checkpoint restore now rehydrates runtime/event state: BaseAgent.from_checkpoint() sets the restored RuntimeState onto crewai_event_bus, rebuilds event scope/last event ID/emission counter, and persists/restores a kickoff event ID (checkpoint_kickoff_event_id) so Agent.kickoff()/kickoff_async() can skip re-emitting LiteAgentExecutionStartedEvent when resuming.

Agent._prepare_kickoff() now reuses a resuming AgentExecutor instance (updating tools/prompt/callbacks/etc.) instead of always creating a fresh executor, and runtime serialization now syncs agent kickoff event IDs via _sync_checkpoint_fields(); new tests cover these behaviors.

^{Reviewed by Cursor Bugbot for commit 683d88b. Bugbot is set up for automated code reviews on this repo. Configure here.}

[iris-clawd]

Approved ✅

Solid feature — extends checkpoint resume/fork to standalone agents, following the same patterns already established for Crew and Flow.

Key changes reviewed:

base_agent.py — Core of the PR:

• from_checkpoint() now properly sets runtime state on event bus and calls _restore_runtime() (previously just set executor resuming flag directly)
• fork() classmethod mirrors Crew/Flow pattern: restore → branch the RuntimeState
• _restore_runtime() handles executor wiring + kickoff event ID restoration
• _restore_event_scope() rebuilds scope stack + emission counter from event record — ensures resumed agents don't re-emit or misorder events

core.py — Both kickoff() and kickoff_async():

• Skip LiteAgentExecutionStartedEvent emission if checkpoint_kickoff_event_id is set (resumed agent)
• Otherwise capture the event ID for future checkpoint persistence

runtime.py — _sync_checkpoint_fields now syncs _kickoff_event_id → checkpoint_kickoff_event_id for agent entities

CLI/TUI — Agent entity type wired through:

• checkpoint_cli.py: resume path calls Agent.from_checkpoint() + akickoff()
• checkpoint_tui.py: entity type detection + resume/fork flows for agents

Tests — 5 new tests covering: runtime state setup, fork with explicit/auto branch, sync_checkpoint_fields, and kickoff event ID round-trip through checkpoint.

54 tests passing. LGTM.

💬 313

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 2 total unresolved issues (including 1 from previous review).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 7a8abfb. Configure here.}

[iris-clawd]

Re-approving after new commits since my last review.

New since last approval (2 commits):

1. 6cfdf062 — Restores the remaining non-serialized executor fields (stop_words, tools_handler, step_callback, function_calling_llm, respect_context_window, request_within_rpm_limit, callbacks) on the resuming-executor path in _prepare_kickoff. This was the gap from the previous commit that only set tools/prompt/response_model — now the resume path mirrors the fresh-executor constructor 1:1.

2. 683d88bc — Merge from main. No conflicts.

Everything else is the same as my previous review. LGTM ✅

💬 316