Checkpoints

A checkpointer owns private state for an active invocation. It is separate from the session store, which owns committed conversation history and application session data. When Harnest owns portable checkpoint storage, it keeps:

Harnest-owned checkpoint state	Purpose
Run status	Coordinate running, waiting, completed, failed, and cancelled transitions
Framework snapshots	Resume ADK or LangGraph execution through the selected adapter
Pending writes	Preserve parallel framework work until it commits
Wait metadata	Resume durable tools and external continuations

Native LangGraphStore and ADKStore authorities expose their framework’s narrower checkpoint contract. They do not provide every Harnest-owned capability in this table. Every application resolves exactly one checkpoint factory across its root and Runtime Plugin extensions. This example assumes the shared PostgresStore from lib/state.py in the storage overview:

extensions/checkpoints.py

from harnest.lib.state import state
from harnest.lifecycle import lifecycle


@lifecycle.storage.checkpoints
def checkpoints():
    """Provide the application's private checkpoint authority."""

    return state

Harnest-owned checkpoint operations are scoped by application, authenticated user, session, and run. Knowing a run ID alone does not grant access. Agent code should not read or mutate framework checkpoint state directly.

Run multiple replicas

Point every replica at the same Harnest checkpointer. Atomic run and continuation transitions allow one replica to claim a resume while another safely observes it.

MemoryStore cannot recover a durable tool across processes. Queued or external waits need a Harnest-owned checkpointer; an opaque native advanced-mode saver is insufficient.

See Durable execution for replica recovery and response polling.

Configure advanced framework ownership

Advanced LangGraph can compile with a Harnest adapter:

agent.py

from harnest.agent import Agent
from harnest.lib.state import state

graph = builder.compile(
    checkpointer=state.as_langgraph_checkpointer(),
)
root_agent = Agent.advanced(graph)

If LangGraph owns a native saver, wrap that saver in LangGraphStore, use the wrapper to compile the graph, and return the same wrapper from @lifecycle.storage.checkpoints. Keep a separate SessionStore factory for committed conversation state. For ADK-native ownership, create one ADKStore(session_service) in lib/state.py. Return that same object from the session and checkpoint factories so Harnest does not create a second session authority.

Switch frameworks safely

Framework checkpoints are opaque and cannot be translated between ADK and LangGraph. Finish or cancel active runs before switching. Committed session state remains portable when the new application uses compatible session storage. Harnest records privacy-safe OTEL mutation events, never checkpoint payloads, prompts, arguments, credentials, or results.

Configure sessions separately

Persist committed conversation history and application data through the session authority.

Overview

Get started

Guides

Run multiple replicas

Configure advanced framework ownership

Switch frameworks safely

Configure sessions separately

​Run multiple replicas

​Configure advanced framework ownership

​Switch frameworks safely

Configure sessions separately

Run multiple replicas

Configure advanced framework ownership

Switch frameworks safely