---
title: "Handoff and checkpoints"
canonical: https://guavaindex.com/specs/handoff
modified: 2026-11-10T08:36:22Z
lang: en
---

# Handoff and checkpoints

Status: draft 0.1 (`agent-checkpoint/0.1`). Fixes friction #19 (no checkpoints on long tasks) and #20 (handoffs pass free text). Reference implementation: `agent_index/checkpoint.py`.

A checkpoint is the smallest record that lets a task resume after a failure. The same record is what one agent should hand to another, in place of a long free-text summary.

## Record

```json
{
  "format": "agent-checkpoint/0.1",
  "task_id": "tide-report-2026-11",
  "goal": "Write a one-page tide pool report for the newsletter",
  "done": ["Found 6 sources", "Drafted sections 1 and 2"],
  "next": ["Draft section 3", "Check every figure against its source"],
  "state": {"sources": ["https://coast.example/tide-pools"], "word_count": 540},
  "artifacts": ["drafts/tide-report.md"],
  "notes": "The marine station data is from summer 2025 only.",
  "step": 4,
  "saved_at": "2026-11-09T08:02:11Z"
}
```

| Field | Meaning |
|---|---|
| `goal` | The outcome, in the requester's words. Never rewritten by later steps. |
| `done` | Steps finished, oldest first. |
| `next` | Steps left, in the order the agent plans to do them. |
| `state` | Small structured data the next step needs: ids, URLs, counts, decisions. Not page text. |
| `artifacts` | Files or URLs produced so far. |
| `notes` | Caveats the next agent must know. |

## Rules

- Save after every step that would be expensive to redo.
- Writes are atomic (write to a temp file, then rename), so a crash never leaves half a checkpoint.
- A receiving agent reads `goal`, `next` and `notes` first and does not need the sender's transcript.
- Page content goes in the shared cache, referenced by URL in `state`, never pasted into the record. The receiving agent fetches it from agent-index for free.