Skip to content

Systems and records

Agent trajectory intermediate artifacts: keeping the spreadsheet between steps

By SourceX Editorial · Updated

10 sections

Short answer

Preserve intermediate agent artifacts as immutable, content-hashed versions listed in an artifact manifest: each row names the step that produced the file, the steps that read it and the artifact it came from, and step records cite those ids back. Capture spreadsheet formulas and computed values together, package with checksums, and ship a validator with one valid and one failing example.

Agent run

Agent trajectory

This page covers agent trajectory intermediate artifacts: keeping the spreadsheet between steps.Illustrative

Key takeaways

  • Most agent errors happen between the first export and the final file, so the versions in between are evidence, not clutter.
  • An artifact manifest gives each file version an id, a hash, the step that produced it, the steps that read it and what it was derived from.
  • Step records and manifest rows must point at each other; a validator that checks both directions catches files changed with no step to explain them.
  • Spreadsheets need formulas and stored values captured together, plus checks for hidden sheets and external links.
  • Redaction must use one pseudonym map across every artifact, with hashes taken after redaction.

How should agent trajectories preserve intermediate spreadsheets and other artifacts?

Keep every file the agent creates or changes as an immutable, content-hashed version, and register it in an artifact manifest that names the step that produced it, the steps that read it and the earlier artifact it was derived from. Trajectory steps then cite artifact ids rather than file paths, so a separate team can open exactly what the agent saw at step 7, not what the file became by step 30.

For spreadsheets, capture formulas and computed values together, because a workbook read one way loses the other. Package the manifest with checksums and a validator, and include one valid and one failing example so a buyer can test the structure before trusting the data.

The rest of this page gives the manifest field by field, shows how it links to step ids in both directions, works through an illustrative month-end reconciliation and lists the checks that should reject a delivery.

Why the final output file is not enough

Most agent errors happen between the first and last file. An agent that exports a ledger, filters it in a working sheet, pastes totals into a summary and emails a PDF can be wrong at any of those hand-offs, and the final PDF only shows that something went wrong. Without the intermediate versions, a reviewer cannot tell whether the export was incomplete, the filter dropped rows or the summary formula pointed at the wrong range.

Intermediate artifacts are also the agent's working memory. Later steps read what earlier steps wrote, so a trajectory that logs actions but overwrites the files cannot be replayed: the observation at step 12 depended on a file that no longer exists in that state. Training on such a trajectory teaches the action without the evidence that justified it.

  • Exports and query results pulled from a system of record, such as a NetSuite saved search or a Salesforce report.
  • Working spreadsheets the agent creates, edits or recalculates.
  • Drafted documents, emails and messages before they are sent.
  • Generated files: PDFs, charts, CSV uploads prepared for another system.
  • Screenshots or rendered views the agent used as observations.
  • Tool outputs too large for the step record, stored as files instead of inline text.

The artifact manifest, field by field

The manifest is one record per artifact version, stored beside the trajectory. Every field below is required unless marked optional, and every rule is one a validator can check without human judgment.

Three optional fields earn their place in most deliveries. A capture_time records when the bytes were frozen, which exposes files saved again after the step ended. A source_system names where an imported file came from, such as the ERP or the bank portal, so a reviewer knows which artifacts are inputs from the world and which the agent made. A reason_missing field lets a supplier declare an artifact that existed but could not be kept, for example a file the source system purged, instead of silently dropping it and leaving a gap the validator reports as an error.

Decide the version boundary in advance. The simplest rule is that a new version exists whenever a step ends with the file's bytes changed; autosaves inside a step do not count. Writing the rule into the dataset card stops one supplier from versioning every keystroke while another versions only the final save.

The artifact manifest, field by field
FieldMeaningValidation ruleExample (illustrative)
artifact_idStable id for this exact versionUnique in the episode; never reused after a changeart-0004
episode_idTrajectory the artifact belongs toMatches the episode headerep-2291
logical_name and versionHuman name of the file and its version numberVersions of one logical file increase by one with no gapsrecon-working.xlsx, v2
produced_by_stepStep whose action created this versionPoints to an existing step whose action has a file side effectstep 6
consumed_by_stepsSteps whose observations or tool inputs read this versionEvery listed step exists and comes after produced_by_stepsteps 7, 9
derived_fromArtifact version(s) this one was built fromEach id exists and was produced at an earlier stepart-0003
media_type and capture_modeFile type and how content was capturedFor spreadsheets, capture_mode includes formulas and valuesxlsx; formulas+values
sha256 and size_bytesContent hash and size of the stored bytesRecomputed hash matches; size matches64 hex characters; 48211
storage_uriWhere the bytes live in the deliveryResolves inside the package or the documented storage locationartifacts/art-0004.xlsx
redaction_stateWhether and how content was de-identifiedSame pseudonym map as the trajectory; hash taken after redactionpseudonymized, map v1

Linking artifacts and step records in both directions

The manifest points from artifacts to steps; the step records must point back. Every step whose tool call wrote a file lists the artifact ids it produced, and every step that read a file lists the ids it used. A validator then checks that both directions agree, which catches the most common defect: a file that changed with no step to explain it.

Existing protocols already carry the hooks. In the Model Context Protocol specification, a tool result may include a resource_link with a URI, name and media type, or an embedded resource that carries the content itself; recording the resource URI and the tool call that returned it is enough to tie a file to a step. OpenTelemetry's generative AI conventions define gen_ai.tool.call.id as the tool call identifier supplied by the model or provider, which is the natural join key between a trace span and a manifest row. Both conventions are still evolving, so record the specification version used.

The vocabulary for the relations is older than agents. W3C PROV-O models activities that use entities and generate new ones, with prov:used, prov:wasGeneratedBy and prov:wasDerivedFrom. Mapping a step to an activity and an artifact version to an entity makes the manifest's consumed_by_steps, produced_by_step and derived_from fields a direct translation, and lets provenance tools query the chain.

Spreadsheets need formulas and computed values captured together

A spreadsheet carries two layers: the formulas and the values they produced the last time the workbook was calculated. Libraries often read one layer at a time. The openpyxl documentation describes its data_only flag as choosing between the formula, the default, and the value stored the last time Excel read the sheet. Capture only formulas and a reviewer cannot see what the agent saw; capture only values and nobody can tell whether a total was typed or computed.

Store each spreadsheet version as the original file, then add a sidecar extract with both layers per cell for the ranges the agent touched. Record which application last calculated the workbook, because a file written by a script may hold formulas with no stored values at all, and recalculating it in a different engine can change results.

Check the parts agents most often miss: hidden sheets, named ranges, external workbook links and pivot caches. An external link to a file outside the package is a replay failure waiting to happen; either include the linked file as its own artifact or record the link as broken in the manifest.

Illustrative manifest for a month-end reconciliation episode

The episode below is invented for illustration and is not customer data. An agent reconciles a bank statement against the general ledger for one account: it exports both, builds a working sheet, flags unmatched items, drafts a journal entry and writes a summary for the controller. Each row is one artifact version and its links to steps.

Illustrative manifest for a month-end reconciliation episode
artifact_id and fileproduced_by_stepconsumed_by_stepsderived_fromWhat a reviewer checks
art-0001 gl-export.csv v1step 2 (saved search export)steps 4, 5none (system of record)Row count matches the saved search; date range matches the task
art-0002 bank-statement.csv v1step 3 (bank file download)steps 4, 5none (system of record)Opening and closing balances match the statement header
art-0003 recon-working.xlsx v1step 4 (create workbook)step 5art-0001, art-0002Both exports pasted in full; no rows dropped
art-0004 recon-working.xlsx v2step 5 (match formulas added)steps 6, 7art-0003Match formulas reference full ranges; stored values present
art-0005 unmatched-items.csv v1step 6 (filter unmatched)step 7art-0004Every unmatched row in v2 appears here, and none of the matched
art-0006 je-draft.json v1step 7 (draft journal entry)step 8art-0005Debits equal credits; accounts exist in the chart
art-0007 controller-summary.docx v1step 8 (write summary)step 9 (send for review)art-0004, art-0006Totals quoted match the workbook values, not retyped figures

A manifest that fails, and what the validator reports

This second illustrative manifest is what a delivery looks like when files were collected after the fact rather than captured at each step. Each line below is a validator finding; any error rejects the episode.

At a glance

A manifest that fails, and what the validator reports

  • ERROR art-0004: produced_by_step 5, but step 5 lists no produced artifacts.
  • ERROR art-0004: sha256 does not match stored bytes; the file was saved again after capture.
  • ERROR art-0005: derived_from art-0009, which is produced at step 11, after art-0005's own step 6.
  • ERROR recon-working.xlsx: versions 1 and 3 present, version 2 missing, but step 7 reads version 2.
  • ERROR art-0004: capture_mode is values only for a spreadsheet; formulas required.
  • WARNING art-0007: external workbook link to a path outside the package.
  • WARNING art-0002: redaction_state pseudonymized with map v2, while the trajectory uses map v1.

Replaying an episode from the manifest alone

A second team should be able to rebuild the state at any step using only the package: load the artifacts listed as consumed by that step, confirm their hashes and compare what the step's observation reported. If that works for every step and the final state matches the recorded outcome, the trajectory is replayable.

Packaging conventions for this already exist. The BagIt format in RFC 8493 uses a payload manifest named after its checksum algorithm that maps each file path to a checksum, and requires checksum validation before a bag is declared valid. Wrapping the artifacts, the trajectory and the manifest in such a bag gives buyers a standard first check before any agent-specific validation.

Score the outcome against system state, not against the summary text. The tau-bench benchmark compares the database state at the end of an episode with the expected state; for a reconciliation the equivalent is the posted journal entry and the reconciled balance, stored as an expected-state artifact with its own id.

  • Replay instructions name the application and version used to open and recalculate each file type.
  • Each step's observation can be regenerated from the consumed artifact versions and nothing else.
  • The final artifacts and expected-state file agree with the recorded outcome.

De-identifying artifacts without breaking the chain

Redaction has to preserve links across files. If a vendor name appears in the export, the working sheet, the journal draft and the summary, it must become the same pseudonym in all four, or the derived_from chain stops making sense and formulas that match on names break. Apply one mapping per episode, record its version in redaction_state, and take the hash after redaction so the delivered bytes verify.

Spreadsheets hide identifiers in places text scrubbers miss: comments, sheet names, defined names, document properties and cached pivot data. Check them, and rerun the formula-and-value extract after redaction to confirm totals still compute. Removing identifiers does not settle the licensing question; rights to the records, privacy obligations and the contract terms are separate reviews.

Requesting trajectories that come with their working files

Put the manifest fields, the capture rules for spreadsheets and the validator in the request before any episode is recorded or reconstructed, and ask for the failing-manifest report alongside the data. Retrofitting artifacts after collection is the most common source of the errors above.

Because SourceX sources each dataset from U.S. businesses only when a buyer requests it, the artifact capture rules can travel in the request form alongside scope, volume, format, timing and licensing needs. Where artifact sets are very large, SourceX's delivery practice keeps them in the seller's own storage or ships them on encrypted drives rather than hosting multi-terabyte data, so the storage_uri field should name that location.

Frequently asked questions

What should an artifact manifest tied to trajectory step IDs include?

One row per artifact version with its id, episode, logical name and version, the step that produced it, the steps that consumed it, the artifact it was derived from, media type and capture mode, a SHA-256 hash and size, a storage location and its redaction state. Step records must list the same artifact ids so both directions can be checked.

Why not store only the final spreadsheet with its version history?

Application version history records saves, not agent steps, and it rarely says which step read which version. A manifest ties each version to the action that produced it and the observations that used it, which is what replay and error attribution need.

Do spreadsheet artifacts need both formulas and values?

Yes. Formulas show how a number was computed and values show what the agent actually saw. Tools such as openpyxl read one layer or the other, so capture the file itself plus an extract of both layers for the ranges the agent touched.

Can another team rebuild the state at a given step from the artifacts alone?

Only when every consumed artifact is present at the version the step read, hashes match, replay instructions name the applications used, and an expected-state artifact defines success. The validator in this guide checks the first three mechanically; the last needs a domain reviewer on a sample.

Which standards can an artifact manifest borrow from?

W3C PROV-O supplies the used, generated-by and derived-from relations; BagIt from RFC 8493 supplies checksum manifests for packaging; MCP resource links and OpenTelemetry tool call ids supply join keys to tool results and traces. None of them is a complete agent artifact standard, so record which versions you used.

Sources

  • The MCP specification (2026-07-28) lets a tool result return a resource_link with a URI, name and media type, or an embedded resource carrying the content. Source
  • OpenTelemetry's GenAI semantic conventions define gen_ai.tool.call.id as the tool call identifier supplied by the model or provider, with Development status. Source
  • W3C PROV-O describes activities that use entities (prov:used) and generate new ones (prov:wasGeneratedBy), and chains entities with prov:wasDerivedFrom. Source
  • openpyxl's load_workbook data_only flag controls whether formula cells return the formula, the default, or the value stored the last time Excel read the sheet. Source
  • RFC 8493 BagIt uses payload manifests named for their checksum algorithm that map file paths to checksums, and requires checksum validation before a bag is valid. Source
  • tau-bench scores agent episodes by comparing the end-of-episode database state with the expected goal state. 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