Spreadsheet & Workbook Agents

8 min read

Y43
Playbook · Domain Playbooks

Spreadsheet & workbook agents.

A workbook agent that reads cell values is reading a cache, and the thing it is caching is a dependency graph nobody drew. That is why these agents demo beautifully and audit terribly: the cell displaying 48,210 is the output of a formula whose inputs sit on three other sheets, so an edit that looks local is not, and a diff that shows one changed cell can have moved forty numbers. Build on the formula graph rather than the rendered grid, make your write primitive a formula patch plus a recalculation diff, and set autonomy from the one benchmark gap that matters — single-instruction edits score roughly 57% while multi-sheet workflows sit below 35%.

Step 1Two files, two different objects: read the graph, not the grid.

An .xlsx file stores, for each cell, a formula and the last value that formula evaluated to. Both are in the file. Which one your library hands you is a configuration decision most teams make by accident, and it determines what kind of agent you have built:

# openpyxl: the same cell, two different objects

wb = load_workbook("plan.xlsx")                 # formulas
wb["Rev"]["E12"].value   -> '=SUM(Q1:Q4)*FX!B3'

wb = load_workbook("plan.xlsx", data_only=True)  # cached values
wb["Rev"]["E12"].value   -> 48210

# and the trap: data_only reads the value EXCEL last wrote.
# a workbook generated by a script and never opened in Excel has
# no cached values at all — every formula cell reads as None.

So the agent that reads values is reading whatever the last human to press save happened to have on screen, and the agent that reads formulas is reading the actual model. Only the second can answer the question that matters for any edit: what depends on this? Parse the formulas into a dependency graph once, on ingest, and you get the precondition for safe writes — a reachable set for every cell. Without it, every edit is a blind write.

The read-side half of this problem — getting a queryable schema out of a human-formatted sheet in the first place, and why the header row is the whole schema decision — is retrieval over tables and spreadsheets. This playbook is about the write side.

Step 2Let the benchmark gap set your autonomy, because it is unusually clear.

Spreadsheet work has better public measurement than most agent domains, and the numbers say something specific about where to put the human. Treat the vendor-reported figures as vendor-reported and the preprint as a preprint, and the shape still holds:

  • Single-instruction edits: roughly half right, and improving fast. SpreadsheetBench (NeurIPS 2024) is 912 questions taken from online Excel forums. Its authors reported GPT-4o and commercial products including Copilot in Excel at 17–20%, against humans above 70%. Microsoft has since reported Excel's Agent Mode at 57.2% on that same 912-instruction set, graded with the benchmark authors' own openpyxl-based script. A ~3x improvement in about two years is real progress on a real task distribution.
  • Multi-sheet workflows: not close. The SpreadsheetBench 2 preprint evaluates 321 expert-annotated tasks over multi-sheet workbooks — end-to-end business work rather than one instruction. Overall accuracy stays below 35%, and among spreadsheet products the highest reported was Claude for Excel at 15.4%.
  • Debugging someone else's workbook: the floor. In the same preprint, debugging is the weakest category at 12.00%.

Those three lines are an autonomy policy, not a scoreboard. "Add a column that computes margin" is the first bullet and can run with light review. "Rebuild the quarterly consolidation across these six sheets" is the second, and should be gated at the plan, not at the output. "Find out why this model's total is wrong" is the third, and is a research task where the agent's job is to produce evidence a human judges — a progressive autonomy ladder with a rung for each.

The gap between bullets one and two is not a capability gap you should expect to close by waiting. A single-instruction task has its own oracle — the instruction says what to do. A multi-sheet workflow does not; it has an intent, and the structure that satisfies the intent is underdetermined. That is the same reason evaluating multi-turn agents is harder than evaluating single turns, showing up in a domain where you can actually see it in the numbers.

Step 3The write primitive: a formula patch, then a recalculation diff.

Do not let the agent hand you a new workbook. A regenerated file has no reviewable relationship to the old one — formatting moves, column widths change, and the one edit you care about is invisible inside a thousand incidental differences. Make the unit of work a patch over the formula graph, and the unit of review the effect of applying it:

# what the agent proposes
patch:
  - cell: Rev!F12
    before: '=SUM(B12:E12)'
    after:  '=SUM(B12:E12)*FX!$B$3'
    reason: convert local-currency total to USD

# what the harness computes BEFORE anything is saved
recalc diff (LibreOffice --headless / formulas / Excel COM):
  Rev!F12         48,210  ->  44,433   (intended)
  Rev!F13..F28    unchanged
  Summary!C4   1,284,900  ->  1,281,123  (expected: rolls up F12)
  Board!B7        12.4%   ->   11.9%   (NOT in the plan)
  Covenants!D2      PASS   ->     FAIL   (NOT in the plan)

# 2 cells edited. 5 outputs moved. the last two are the review.

The recalculation diff is the whole control. It is cheap — a headless recalculation of a copy — and it converts an unreviewable change into a short list of moved numbers, which is a thing a finance owner can actually approve. Crucially, the agent must declare its expected blast radius before the diff runs, so the harness can flag outputs that moved and were not predicted. An unpredicted move is not necessarily wrong, but it is always the thing to look at, and it is the tabular case of the general blast-radius discipline.

Two mechanics worth getting right. Preserve absolute references exactly as written — $B$3 and B3 behave differently the moment anything is copied, and an agent that normalises them has introduced a bug that appears later, in a different cell, for a different user. And never write in place: operate on a copy, keep the original, and make the restore path a file move. Undo and reversibility is unusually cheap here and unusually valuable, because the alternative is a finance team with no way back.

Step 4The failure that survives review: conceptually right, structurally wrong.

The characteristic workbook-agent error is not a wrong answer. It is a formula that implements the correct idea with the wrong ranges, which produces numbers that are the right order of magnitude, formatted correctly, in the right cells. The SpreadsheetBench 2 preprint documents the extreme form: formulas it describes as conceptually reasonable but structurally wrong, yielding around 4% cell accuracy. Nothing about the output looks broken.

The ways this arrives are a short and repeating list, and each has a mechanical check:

  • Off-by-one ranges that include the header or the totals row. SUM(B1:B50) where the header is row 1 and Total is row 50. Check: assert that no aggregation range intersects a row the table card marked as header or total.
  • A range that stops short of the data. Hard-coded B2:B400 on a sheet that now has 412 rows silently drops twelve. Check: compare every range's extent against the sheet's used range and flag any aggregation that ends before the last data row.
  • Double-counting through a subtotal. Summing a column that already contains subtotals. Check: flag any range that contains a cell which is itself a SUM over cells in that same range — a pure graph property, cheap to compute, and it catches the costliest version of this.
  • Units and currency, silently mixed. Adding a column in thousands to one in units. Check: carry a declared unit per column and refuse an addition across two different ones.
  • Hard-coded numbers where a reference belongs. =48210*1.085 gives the right answer today and is frozen forever. Check: flag any proposed formula containing a numeric literal that equals a current cell value elsewhere in the workbook.

Run these as deterministic assertions over the patch, not as a request to a model. They are graph predicates with crisp answers, which makes them exactly the wrong job for a judge and exactly the right job for code — the distinction argued in a deterministic finance workflow in code.

Step 5What the agent must not do, and what has to survive the edit.

Workbooks are frequently the system of record for something regulated, and they are the only system of record with no transaction log. A few constraints follow, and they are not negotiable in a finance or reporting context:

  • Never silently replace a formula with its value. It is the one edit that is invisible in a value diff and destroys the model. If the agent must freeze a figure, the patch has to say so in words and the original formula must be preserved in a comment or an adjacent audit column.
  • Attribute every changed cell. One sheet appended with cell address, prior formula, new formula, run id, prompt, and model version. This is the audit trail, and in a workbook it has to live in the workbook, because the file will be emailed away from your infrastructure within the hour.
  • Treat the workbook's own contents as untrusted input. Cell text, comments and sheet names arrive from wherever the file came from, and a workbook forwarded by a counterparty is a prompt-injection surface — see prompt injection. Never execute macros, and never let a WEBSERVICE or external link formula run during recalculation; strip them at ingest.
  • Stop at the signed artefact. If a workbook feeds a filed report, the agent's output is a proposal, not a submission. The number that lands in a regulatory filing needs a named human, which is the accountability rule applied to a file nobody thinks of as a system.

One more, easy to overlook: protect the inputs tab. Most real models have a small set of assumption cells that everything else reads. Mark them, make them read-only to the agent by default, and require an explicit, separately-approved patch to touch one. An agent that reaches an intended output by editing an assumption has not done the work — it has moved the goalposts, and the recalculation diff will look perfect.

Step 6The workbook-agent checklist.

  • Ingest: parse formulas, not values; build the dependency graph; record header rows, total rows and per-column units; strip macros and external-link formulas.
  • Propose: a formula patch with a reason per cell and a declared expected blast radius.
  • Verify: headless recalculation on a copy; diff computed outputs; flag every moved output that was not predicted.
  • Assert: the five structural checks from STEP 4, as code, failing closed.
  • Gate: light review for single-cell edits; plan-level approval for multi-sheet work; evidence-only for debugging. Assumption cells always need their own approval.
  • Record: an audit sheet inside the file; the original kept intact; restore is a file move.
  • Measure: your own task bank from real requests, scored on recalculated outputs rather than cells touched — plus the rate at which the agent's predicted blast radius matched the actual diff, which is the single best leading indicator that it understood the model.

If you build one thing first, build the recalculation diff — before the agent, before the prompt. It is a headless recalculation of a copy and a comparison of two value grids, it is the control that makes every later decision reviewable, and it is the only artefact that turns "the agent edited the model" into something a finance owner can approve or reject in thirty seconds. Then add the dependency graph, so the agent can predict that diff instead of discovering it.