strands.experimental.checkpoint.checkpoint

Checkpoint system for durable agent execution.

A Checkpoint is a pause-point marker emitted at agent cycle boundaries. It captures the position (which boundary fired) and the cycle index. It does not capture conversation state — pair with a SessionManager for cross-process state continuity.

Positions per ReAct cycle:

• after_model: model returned tool_use; tools have not run yet.
• after_tools: tools finished; the next model call has not happened yet.

Per-tool granularity within a cycle is the ToolExecutor’s responsibility.

Usage (mirrors interrupts):

• Pause: AgentResult with stop_reason="checkpoint" and checkpoint populated.
• Resume: pass back \{"checkpointResume": \{"checkpoint": ckpt.to_dict()}}.

Precedence:

• Interrupt > checkpoint: an interrupt during a checkpointing cycle returns stop_reason="interrupt" and skips after_tools.
• Cancel > checkpoint: a cancel signal at either boundary returns stop_reason="cancelled".

Notes:

• Checkpoints are only emitted on tool_use cycles. A turn with no tool calls emits no checkpoint; use a SessionManager for durability of every turn.
• EventLoopMetrics resets per invocation; aggregate yourself if needed.
• BeforeInvocationEvent / AfterInvocationEvent fire on every resume, same as interrupts.

Checkpoint

@dataclass(frozen=True)
class Checkpoint()

Defined in: src/strands/experimental/checkpoint/checkpoint.py:46

Pause-point marker. Treat as opaque — pass back to resume.

Attributes:

• position - Which boundary fired (after_model or after_tools).
• cycle_index - ReAct loop cycle (0-based).
• snapshot - Reserved for forward extensibility (e.g. a future hook that lets callers attach agent state to the checkpoint). The SDK does not populate or read it today; it round-trips through serialization.
• app_data - Reserved for forward extensibility — caller metadata that round-trips through serialization. The SDK does not populate or read it.
• schema_version - Rejects incompatible checkpoints on resume.

to_dict

def to_dict() -> dict[str, Any]

Defined in: src/strands/experimental/checkpoint/checkpoint.py:66

Serialize for persistence.

from_dict

@classmethod
def from_dict(cls, data: dict[str, Any]) -> "Checkpoint"

Defined in: src/strands/experimental/checkpoint/checkpoint.py:71

Reconstruct from a dict produced by to_dict().

Arguments:

• data - Serialized checkpoint data.

Raises:

• CheckpointException - If schema_version doesn’t match the current version.