Snapshot and Restore Skill

Process steps in order. Do not skip ahead.

Step 1 — Confirm Snapshot Is the Right Tool

Persistence (add-persistence) writes checkpoints automatically on a configured schedule (every node, every N steps, every successful turn). Snapshot is caller-triggered — you call snapshot() when you decide it's a useful save point.

Use snapshot when:

• The interesting save points are semantic ("after the user approves the plan"), not periodic
• You want to fork — take a snapshot, try variant A, restore, try variant B
• You're building a debugger or replay tool that needs explicit save/load semantics

If the user's need is "agent should resume after a crash", invoke Skill(skill: "add-persistence"). If it's "save state at this specific point", continue.

Proceed immediately to Step 2.

Step 2 — Add the Dependency

implementation("ai.koog:agents-features-snapshot:1.0.0")

Proceed immediately to Step 3.

Step 3 — Install the Feature

import ai.koog.agents.features.snapshot.Snapshot

val agent = AIAgent(
    promptExecutor = ...,
    llmModel = ...,
    systemPrompt = "...",
) {
    install(Snapshot) {
        // optional: storage backend (in-memory, disk, JDBC)
    }
}

Proceed immediately to Step 4.

Step 4 — Call the Snapshot API from Code

Inside a node body (or from outside the run via the agent's API), call snapshot():

// inside a node body
val snapshotId = snapshot()        // returns an identifier you store
storeSnapshotId(snapshotId)

Restore by passing the snapshot ID to runFromSnapshot:

val snapshotId = loadSnapshotId()
val result = agent.runFromSnapshot(snapshotId, additionalInput = null)

Snapshots are the typed-storage half of persistence — AIAgentStorage rides along automatically (values must be @Serializable, see manage-state). Non-serializable types break snapshots silently, same as checkpoints.

Forking — take a snapshot, run one branch, restore, run another:

val branchPoint = snapshot()
val resultA = agent.runFromSnapshot(branchPoint, additionalInput = "variant A input")
val resultB = agent.runFromSnapshot(branchPoint, additionalInput = "variant B input")

Useful for A/B testing strategy variants without re-running the prefix.

Finish here.