Skip to content

AI uses for records

Agent trajectory state diff dataset or full snapshots: what to store

By SourceX Editorial · Updated

9 sections

Short answer

An agent trajectory should store full state snapshots at the start, at fixed checkpoints, before any action with outside effects and at the end, with state diffs between them. Diffs alone work only when each names its base state and carries a hash of the result. Full snapshots win for screen-based tasks, systems you cannot re-execute and steps reviewed out of order.

Agent run

Agent trajectory state diff

This page covers agent trajectory state diff dataset or full snapshots: what to store.Illustrative

Key takeaways

  • Checkpoints plus diffs suit most business trajectories; full snapshots suit screens, short episodes and step-level training sets.
  • Every diff should name its base step, carry base and result hashes and open with a test operation.
  • JSON Patch records removals and nulls precisely; JSON Merge Patch cannot set a field to null.
  • Cap the number of diffs between checkpoints so one bad diff cannot corrupt a whole episode.
  • Acceptance means a second team rebuilds state, matches every hash and recomputes the outcome.

When should an agent trajectory contain state differences versus full snapshots?

Store a full snapshot of task state at the start of every episode, at fixed checkpoints, before any action with an effect outside the environment, and at the end; store diffs between those points. Use diffs alone only when every diff names the exact state it applies to and carries a hash of the result, so a second team can prove the chain is unbroken.

A full snapshot is the complete task state at one step: the records, files or screen the agent could act on. A state diff is the change one step made, expressed as operations against a known earlier state. A trajectory that keeps observations, actions and tool responses but no state at all is a third option, and it only works if the environment can be re-executed deterministically.

The choice is not about saving disk. It decides whether a reviewer can open step 40 without replaying steps 1 to 39, whether a single corrupted diff destroys the rest of an episode, and whether the dataset still means anything after the source system has changed.

The storage and reconstruction comparison

The table compares five storage designs for agent trajectory datasets: what each one stores, how state at an arbitrary step k is rebuilt, how it fails, and when it is the right choice.

For checkpoints plus diffs, two numbers define the design and both belong in the dataset card: the checkpoint interval and the maximum chain length. The interval sets how many diffs a reader applies in the worst case; the chain limit sets how far one corrupt diff can spread. Pick the interval from the slowest acceptable random-access read, then add mandatory checkpoints at events that matter more than position, such as a hand-off to another role, a call to a payment or messaging tool, or a status change to closed.

Whichever design you choose, record it per episode, not just per dataset. Capture tooling can change partway through a collection, and a buyer who assumes one design for every episode will misread the ones built the other way.

The storage and reconstruction comparison
DesignWhat is storedRebuilding state at step kTypical failureFits when
Full snapshot every stepComplete state after each stepRead one fileVolume grows with steps times state sizeState is small, or reviewers inspect steps out of order
Initial snapshot plus diffsState at step 0, then one diff per stepApply diffs 1 to k in orderOne bad or missing diff breaks every later stepShort episodes with small, structured changes
Checkpoints plus diffsSnapshots every N steps and before irreversible actions; diffs betweenLoad nearest earlier checkpoint, apply at most N diffsCheckpoint policy not recorded, so gaps go unnoticedMost business workflows with long episodes
Before and after pair per actionState immediately before and after each actionRead the pair for step kChanges between actions, such as background jobs, are invisibleScreen and browser tasks where each action must be inspected
Events only, no stateObservations, actions, tool responses, seedRe-execute the environment from the seedEnvironment or external system drift makes replay divergeFully simulated, deterministic environments under version control

What do databases, git and event stores already teach about this trade-off?

Databases, version control and event stores that keep change history settle on periodic full copies plus deltas, and cap how many deltas must be applied in a row. Trajectory datasets should borrow that pattern rather than reinvent it.

PostgreSQL's full_page_writes setting writes the entire content of a disk page to the write-ahead log on the first change after each checkpoint, because row-level change records alone cannot restore a page that was only partly written during a crash. The documentation notes that replay always starts from a checkpoint, which is why one full image per page per checkpoint is enough.

Git stores many objects as deltas against other objects, and its pack-objects documentation warns that a deep delta chain slows unpacking because delta data must be applied that many times; the default maximum depth is 50 and the hard maximum 4095. Microsoft's event sourcing guidance recommends snapshots every N events so an entity is rebuilt from the latest snapshot plus later events, and stresses that snapshots are an optimization: the event stream stays the source of truth and snapshots can be regenerated from it.

For a trajectory dataset the translation is direct: checkpoints bound reconstruction cost, a stated maximum chain length bounds the damage of one bad diff, and the event record (actions and tool responses) remains the authority if a snapshot and a diff disagree.

Which diff format survives a second team?

Use an operation-based format such as JSON Patch with an explicit base, not a merge-style partial document. Operation lists say exactly what changed, including removals and array positions, and can carry a guard that fails loudly if applied to the wrong state.

RFC 6902 defines JSON Patch as an ordered array of operations (add, remove, replace, move, copy and test) applied in sequence, where evaluation stops at the first error and a failing test means the patch as a whole does not succeed. RFC 7396 JSON Merge Patch is simpler, but it gives null the special meaning of removing a member, so a merge patch cannot set a field to null; that alone disqualifies it for business records where null and absent mean different things.

  • Every diff names base_step and base_hash, the hash of the canonical state it applies to.
  • Every diff carries result_hash, so the receiver checks the state after applying it.
  • Start each diff with a test operation on a field the action should have read, such as the order status, so a misapplied diff fails at once.
  • Canonicalize before hashing: sorted keys, fixed number formats, UTC timestamps with offset, and a stated rule for array order.
  • Keep diffs of state separate from tool responses. A tool response is evidence of what the agent saw; a diff is the effect on the environment. Merging them hides which one changed.

State fields each step record needs

Whatever design you choose, every step should say which kind of state record it carries and how to verify it. The table lists the state-specific fields; general step fields such as case and step IDs, actor, time, observation, action and tool response sit alongside them.

Minari's dataset standard is a useful reference for the surrounding episode layout: it stores observations for every step including the initial one, expects the info dictionary to keep the same structure at every step, and records reset seed and options in episode metadata. A business trajectory needs the same discipline plus the state fields below.

State fields each step record needs
FieldOn snapshot stepsOn diff stepsCheck the receiver runs
state_kindsnapshotdiffValue is one of the two; first and last steps are snapshots
checkpoint_reasonepisode_start, interval, pre_external_action or episode_endNot usedEvery external action is preceded by a snapshot
base_step and base_hashNot usedStep and hash the diff applies toBase exists and its hash matches
patchNot usedOrdered operation list with a leading testApplies without error
state_uri or inline stateLocation of the full stateNot usedFile exists and matches state_hash
state_hash or result_hashHash of canonical stateHash after applying the patchRecomputed hash equals the stored one
chain_length0Diffs since the last snapshotNever exceeds the stated maximum
external_effectsList of effects outside the state, such as an email sentSameEach effect links to a tool response

Can a second team rebuild every step from the hashes alone?

Yes, if reconstruction is a mechanical procedure that ends in matching hashes and a recomputed outcome. Write the procedure down, ship a reference script, and ask a team that did not build the dataset to run it on a sample before acceptance.

Checklist · 6 items

  1. Load the episode's first snapshot and confirm its state_hash.
  2. For each later step, load the snapshot or apply the patch to the named base; confirm the resulting hash before moving on.
  3. At each external_effects entry, confirm a tool response with a matching call ID exists and that the state change is consistent with it.
  4. At the final step, recompute the outcome from the reconstructed state using the published success rule, and compare it with the stored outcome label.
  5. Report every hash mismatch, missing base and chain longer than the stated maximum, with step IDs, rather than a single pass or fail.
  6. Record the tool versions, canonicalization rule version and reconstruction script version used, so the check itself can be repeated.

0 of 6 ticked. Tick each item as you go.

Worked example (illustrative): an order-management agent

Consider an illustrative dataset of agent episodes in an order-management system. Each episode starts from a customer email, the agent looks up the order, changes a shipping address or splits a shipment, and sometimes issues a credit note. The task state is the order, its lines, shipments and notes, typically a few dozen fields.

The team stores a snapshot at episode start, every 10 steps, before any step that calls the email or credit tool, and at the end; every other step stores a JSON Patch with a leading test on order status. With these illustrative settings, a median episode of 18 steps holds 4 snapshots and 14 diffs, and no state is ever more than 9 diffs from a checkpoint.

During acceptance a second team found that 2 percent of episodes (illustrative) failed hash checks at the same kind of step: a nightly batch job had re-priced open orders between two agent actions, so the diff recorded by the environment did not include a change the agent later saw. The fix was to log the batch job as an environment event with its own diff, not to switch to full snapshots.

The example also shows the limit of the recommendation. Checkpoints plus diffs assume that the environment is the only thing changing state between steps. Where other people or automations edit the same records while the agent works, the trajectory has to record those changes as events too, or take a fresh snapshot each time the agent reads, because otherwise the diff chain describes a world the agent never saw.

Where full snapshots win despite the cost

Choose full snapshots, or before and after pairs, when the state is a screen or document whose meaning does not survive a field-level diff, when the agent acts on a system you cannot re-execute, or when reviewers must judge single steps out of order.

Browser and computer-use tasks are the clearest case. Playwright's trace viewer captures complete DOM snapshots for each action: one when the action is called, one at the moment of input, and one after the action. That design accepts the storage cost because a reviewer judging whether a click was correct needs the whole page as it was, not a list of node changes.

Full snapshots also win for short episodes on small state, where the diff machinery costs more in engineering and failure modes than it saves in volume, and for any dataset that will be split into individual steps for training, since each step then needs to stand alone.

Buying trajectories built from business records

When trajectories are derived from real business systems, ask the supplier which design they used, what the checkpoint policy and maximum chain length are, and whether a reconstruction script and a sample hash report come with the delivery. Those answers matter more than the episode count.

Trajectory-ready records come from SourceX only against a request, sourced from U.S. businesses rather than from stock, and a buyer stating scope, volume, format, timing and licensing needs can name a storage design from the table above as the format. SourceX does not host multi-terabyte sets; a delivery that size stays where the supplier keeps it or moves on encrypted drives, which suits snapshot-heavy datasets.

Frequently asked questions

What is a state diff in an agent trajectory?

It is a record of how one step changed the environment's task state, written as operations against a named earlier state. A usable diff includes the base it applies to and a hash of the resulting state. Without those, nobody can prove the diff was applied to the right state.

Are diffs or full snapshots better for agent training data?

Neither on its own. Most business trajectories are best stored as full snapshots at the start, at fixed checkpoints, before external actions and at the end, with diffs in between. Screen-based tasks and step-level training sets often justify full snapshots throughout.

Should I use JSON Patch or JSON Merge Patch for trajectory diffs?

JSON Patch is the safer default. It is an ordered list of operations, supports a test operation that fails if the state is not what you expect, and can express removals precisely. Merge Patch treats null as a removal, so it cannot record a field being set to null.

How often should checkpoints be taken?

Set a fixed interval and add mandatory snapshots before any action with effects outside the environment. The interval bounds how many diffs a reader must apply and how far one corrupt diff can spread; record both the interval and the maximum chain length in the dataset card.

Can a trajectory store only actions and tool responses, with no state?

Yes, if the environment is fully simulated, versioned and deterministic given a seed, so re-execution reproduces the state. For episodes recorded against live business systems that have since changed, this design usually cannot be reconstructed.

Sources

  • JSON Patch is an ordered list of add, remove, replace, move, copy and test operations applied in sequence; evaluation stops at an error and a failed test fails the patch. Source
  • JSON Merge Patch gives null the meaning of removing a member, so it cannot set a value to null. Source
  • PostgreSQL full_page_writes logs a whole page on its first change after a checkpoint because row-level changes alone cannot restore a torn page, and WAL replay always starts from a checkpoint. Source
  • Git's pack-objects limits delta depth because deep chains slow unpacking; the default depth is 50 and the maximum 4095. Source
  • Event sourcing guidance recommends snapshots every N events, rebuilding from the latest snapshot plus later events, with the event stream remaining the source of truth. Source
  • Playwright's trace viewer captures complete DOM snapshots before, at and after each action. Source
  • Minari stores observations for each step including the initial one, expects info dictionaries with the same structure at every step, and keeps reset seed and options in episode metadata. Source

Tell us what data you need

Share scope, volume, format, timing and licensing needs. Datasets are sourced on request.

See if your company qualifies