How it works
Resumable state turns an agent run from an in-memory conversation into a recoverable execution. The harness persists the facts required to restart the control loop at a defined boundary. Those facts usually include the current workflow step, accepted outputs, outstanding work, attempt identifiers, tool-call status, relevant context references, and the policy under which the work was authorized.
A typical resume path is:
- Load the latest valid state record and verify its version and integrity.
- Reconcile that record with external effects, such as files written, jobs submitted, or messages sent.
- Classify incomplete operations as safe to retry, unsafe to retry, or requiring investigation.
- Reassemble only the context needed for the next step.
- Revalidate permissions, limits, and stop conditions before execution continues.
- Persist the next transition before releasing ownership of the run.
The important property is not persistence alone. A transcript can survive a crash yet still leave the harness unable to decide what happened. Resumable state must encode execution meaning: which transition committed, which result became authoritative, and what recovery action applies when an outcome is unknown.
Why it matters in an agent harness
Long-running agent work crosses unreliable boundaries. Processes restart. Models time out. Operators interrupt runs. Tool providers accept a request but fail before returning a response. Without resumable state, the harness must either discard useful work or replay an uncertain sequence. Both choices can be costly, and replay can be dangerous when tools produce external effects.
The first benefit is failure containment. A failed extraction step should not force the system to repeat approved research, model evaluations, or completed exports. Recovery remains local to the smallest step whose outcome is unresolved. That reduces both wasted work and the number of actions exposed to another non-deterministic model pass.
The second benefit is control. An interrupt becomes a supported transition rather than an accidental crash. The operator can stop a run, inspect its state, change an allowed input, and resume from a known boundary. This only works when the stored state is authoritative. If the harness reconstructs progress from logs or model prose, recovery depends on inference where it needs a definite answer.
Resumable state also improves observability. A useful state record can answer practical questions: What completed? What is pending? Which attempt owns the run? Which external effects were confirmed? Which policy allowed the next action? An execution trace can explain the path, but resumable state identifies the current operational truth.
Permissions need special treatment during recovery. Persisting an earlier authorization decision does not necessarily make it valid forever. Credentials may expire, scopes may change, and an approval may apply only to one attempt or payload. The harness should preserve the decision record while rechecking any condition that must still hold at resume time.
The hardest case is an unknown outcome. Suppose a tool call timed out after submission. Marking it failed and retrying may duplicate the effect. Marking it complete may skip required work. The state model needs an explicit unresolved status plus a recovery rule, such as querying the provider with an idempotency key, inspecting the target system, or requiring a compensating action.
Resumable state vs checkpoint
A checkpoint is a saved boundary. Resumable state is the complete operational representation used to continue safely from that boundary. The distinction changes what you must persist and validate.
| Concern | Checkpoint | Resumable state |
|---|---|---|
| Primary purpose | Mark or capture a recovery point | Determine the next safe transition |
| Typical contents | Snapshot, cursor, or completed-step marker | Workflow state, accepted outputs, attempts, effects, policies, and recovery status |
| External effects | May record that a step ran | Must distinguish confirmed, absent, and unknown outcomes |
| Resume behavior | Restores saved data | Reconciles reality, revalidates controls, and continues |
A checkpoint can be part of resumable state, but the checkpoint alone may be insufficient. Saving “step 4 started” does not tell the harness whether step 4 sent a payment, created a ticket, or failed before invoking its tool. The resume decision depends on that distinction.
The Rifty take
We optimize for explicit recovery semantics, not merely durable storage. We accept extra state transitions and reconciliation work because duplicate or unauthorized effects are more expensive than a slower restart. If the harness cannot distinguish completed, pending, and unknown work, it should not claim that a run is safely resumable.
Implementation checks
- Define the exact boundaries at which a run may resume.
- Store workflow state separately from conversational narration.
- Give every attempt and side-effecting operation a stable identifier.
- Record whether each effect is planned, submitted, confirmed, failed, or unknown.
- Make retries idempotent where possible; otherwise define reconciliation or compensation.
- Use leases or ownership tokens so two workers cannot resume the same run concurrently.
- Version the state schema and reject incompatible records visibly.
- Revalidate permission scope, approval conditions, budgets, and stop conditions on resume.
- Persist references to required context rather than assuming one process retains it.
- Test crashes before dispatch, after dispatch, and after effect confirmation.
- Expose recovery decisions in the audit trail, including any deterministic fallback used.
- Fail loudly when state is missing, corrupt, contradictory, or too old to interpret safely.
Frequently asked questions
What information must resumable state contain?
Resumable state must contain enough authoritative data to choose the next safe transition. At minimum, record the workflow position, accepted outputs, attempt identifiers, pending operations, confirmed and unknown side effects, relevant context references, and applicable recovery rules. Include permissions or approvals when they affect whether execution may continue.
Is an agent transcript sufficient for resumption?
No. A transcript records what participants said or attempted, but it rarely proves which workflow transition committed or which external effect occurred. It can help rebuild context and explain decisions. The harness still needs structured state that identifies authoritative outputs, operation status, ownership, and the next permitted action.
How should a harness handle a tool call with an unknown outcome?
Mark the outcome as unknown and reconcile it before retrying. Query the target system using a stable request identifier, inspect the intended effect, or apply a defined compensation procedure. Do not silently classify a timeout as failure, because the provider may have completed the action before the response was lost.
Should approvals remain valid after a run resumes?
Only when the approval contract says they do. Preserve the original decision for auditability, then revalidate conditions that may have changed, including payload, permission scope, credentials, budgets, and time limits. An approval for one attempt or action should not silently become standing authority for a resumed run.
How do you test whether state is genuinely resumable?
Inject failures at each execution boundary and verify the resulting transition. Test interruption before tool dispatch, after dispatch but before acknowledgment, after effect confirmation, and during state persistence. A successful test resumes without duplicating confirmed effects, skipping required work, widening permissions, or relying on unrecorded process memory.