Appearance
Checkpoint API
Thin ReAct-loop bookmarks persisted under an agent session. See Checkpoints for usage and resume semantics.
python
from elsai.checkpoint import Checkpoint, CheckpointConfig, CheckpointExceptionDeprecated import path
from elsai.experimental.checkpoint import ... still works but emits a deprecation warning. Use elsai.checkpoint.
CheckpointConfig
python
from elsai.checkpoint import CheckpointConfigSelects which loop boundaries write a bookmark. Pass on AgentConfig.checkpoint (requires a session_manager).
python
from elsai.agent import AgentConfig
from elsai.checkpoint import CheckpointConfig
from elsai.session import FileSessionManager
config = AgentConfig(
agent_id="worker",
session_manager=FileSessionManager(session_id="job-1", storage_dir="./sessions"),
checkpoint=CheckpointConfig(position="both"),
)| Field | Type | Default | Description |
|---|---|---|---|
position | "after_tools" | "after_model" | "both" | "after_tools" | Boundaries at which to save |
Methods
| Method | Returns | Description |
|---|---|---|
saves_after_tools() | bool | True when position is "after_tools" or "both" |
saves_after_model() | bool | True when position is "after_model" or "both" |
TIP
Pass CheckpointConfig, not a Checkpoint instance. Wrong types raise TypeError at Agent construction.
Checkpoint
python
from elsai.checkpoint import CheckpointFrozen, JSON-serializable bookmark written to checkpoint.json. Schema version: 1.0.
Users normally do not construct this for day-to-day usage — the event loop writes it. Treat it as a read model when inspecting disk or writing tests.
| Field | Type | Description |
|---|---|---|
position | "after_model" | "after_tools" | Boundary just completed (never "both") |
cycle_index | int ≥ 0 | 0-based ReAct cycle index at save |
schema_version | str | Must match SDK version on load |
created_at | str | ISO-8601 UTC (...Z); auto-filled if empty |
message_count | int | None | len(messages) at save (used by resume gate) |
agent_id | str | None | Disambiguation / consistency |
execution_status | "active" | "completed" | Auto-resume only if "active" |
Methods
| Method | Description |
|---|---|
validate() | Raises CheckpointException if invalid |
to_dict() | JSON-compatible dict |
Checkpoint.from_dict(data) | Reconstruct and validate |
CheckpointException
python
from elsai.types.exceptions import CheckpointException
# or
from elsai.checkpoint import CheckpointExceptionRaised for schema, I/O, or validation failures on checkpoint load/serialize. Distinct from SessionException.
Session manager methods
FileSessionManager and S3SessionManager (via the repository façade) expose:
| Method | Description |
|---|---|
write_checkpoint(agent, checkpoint) | Persist / overwrite checkpoint.json |
read_checkpoint(agent) | Load bookmark or None if missing |
delete_checkpoint(agent) | Remove the bookmark file |
Prefer letting the agent loop manage writes. Manual writes are mainly for tests or crash simulation.
AgentResult resume fields
Set when an invoke acts on an allowed loaded bookmark (not merely loads one):
| Field | Type | Description |
|---|---|---|
resumed_from_checkpoint | bool | True if this invoke resumed from a checkpoint |
resume_position | "after_model" | "after_tools" | None | Boundary that was resumed |
Related
- Checkpoints — concepts and copy-paste recipes
- Sessions — conversation persistence
- Sessions API — session managers
- Agent API —
AgentConfig.checkpoint