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
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.
| Field | Meaning | Validation rule | Example (illustrative) |
|---|---|---|---|
| artifact_id | Stable id for this exact version | Unique in the episode; never reused after a change | art-0004 |
| episode_id | Trajectory the artifact belongs to | Matches the episode header | ep-2291 |
| logical_name and version | Human name of the file and its version number | Versions of one logical file increase by one with no gaps | recon-working.xlsx, v2 |
| produced_by_step | Step whose action created this version | Points to an existing step whose action has a file side effect | step 6 |
| consumed_by_steps | Steps whose observations or tool inputs read this version | Every listed step exists and comes after produced_by_step | steps 7, 9 |
| derived_from | Artifact version(s) this one was built from | Each id exists and was produced at an earlier step | art-0003 |
| media_type and capture_mode | File type and how content was captured | For spreadsheets, capture_mode includes formulas and values | xlsx; formulas+values |
| sha256 and size_bytes | Content hash and size of the stored bytes | Recomputed hash matches; size matches | 64 hex characters; 48211 |
| storage_uri | Where the bytes live in the delivery | Resolves inside the package or the documented storage location | artifacts/art-0004.xlsx |
| redaction_state | Whether and how content was de-identified | Same pseudonym map as the trajectory; hash taken after redaction | pseudonymized, 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.
| artifact_id and file | produced_by_step | consumed_by_steps | derived_from | What a reviewer checks |
|---|---|---|---|---|
| art-0001 gl-export.csv v1 | step 2 (saved search export) | steps 4, 5 | none (system of record) | Row count matches the saved search; date range matches the task |
| art-0002 bank-statement.csv v1 | step 3 (bank file download) | steps 4, 5 | none (system of record) | Opening and closing balances match the statement header |
| art-0003 recon-working.xlsx v1 | step 4 (create workbook) | step 5 | art-0001, art-0002 | Both exports pasted in full; no rows dropped |
| art-0004 recon-working.xlsx v2 | step 5 (match formulas added) | steps 6, 7 | art-0003 | Match formulas reference full ranges; stored values present |
| art-0005 unmatched-items.csv v1 | step 6 (filter unmatched) | step 7 | art-0004 | Every unmatched row in v2 appears here, and none of the matched |
| art-0006 je-draft.json v1 | step 7 (draft journal entry) | step 8 | art-0005 | Debits equal credits; accounts exist in the chart |
| art-0007 controller-summary.docx v1 | step 8 (write summary) | step 9 (send for review) | art-0004, art-0006 | Totals 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.