Spreadsheets carry an enormous amount of real business data, so agents are given first-class ways to work with them: Google Sheets through a Google Drive connection, and Excel workbooks on Microsoft 365 through a Microsoft 365 connection. Uploaded .xlsx and .csv files can be read the same way, though not modified.
How an agent gets to a spreadsheet
An agent works on the spreadsheet it currently has open. It opens a workbook by its URL — from a work item column, from an instruction, from a search result — and the spreadsheet tools then apply to that file and that tab.
This is why the tools have no "which file" argument to get wrong. It also means the practical instruction to give an agent is usually "open this sheet, then update the row for this customer", not "update row 47".
Multi-tab workbooks are handled explicitly. When an agent opens a workbook it is shown the list of tabs and can switch between them, and each write tool says which tab it is currently bound to. You can also pin a link to a particular tab so a step always lands on the right one.
Reading a spreadsheet
Opening a spreadsheet returns a readable table together with the number of rows and columns it actually has. Large sheets are not dumped whole and are not silently cut off: the agent gets the first block of rows plus a clear indication that more exist, and can then ask for specific row ranges until it has covered what it needs.
For finding rows rather than reading them all, there are lookup tools — lookup_sheet for Google Sheets and lookup_excel for Excel. An agent supplies conditions on column values and gets back the matching rows. On a sheet of any size this is dramatically cheaper and more accurate than reading everything and searching by eye.
Merged cells and cells containing line breaks are handled properly, so the table an agent reads matches the table you see.
Writing to a spreadsheet
There are three main ways to change a sheet, and it is worth knowing which one you want.
Tool | Use it for |
Append ( | Adding a new row to the end. |
Update by row ( | Changing rows identified by their content — "set Status to Shipped where Order Id is 4471". |
Upsert ( | "Update the row with this key, or add it if it isn't there." |
Prefer the by-content tools. Update-by-row and upsert find the matching rows themselves; the agent never computes a cell address. Asking an agent to work out row numbers invites the worst kind of spreadsheet error — the write that lands one row off, looks perfectly plausible, and is discovered weeks later. Matching on content removes that class of mistake entirely.
The by-content tools are also deliberately strict about ambiguity. An upsert whose key matches more than one row fails and writes nothing rather than picking one. If you see that happen, the fix is a more specific key, not a retry.
There is still a direct, address-based update tool (update_sheet, update_excel_workbook) for the cases the by-content tools cannot express: editing a header row, setting a specific cell such as a title, or writing into a particular range.
Columns, formulas, and new files
Columns can be added and removed (
add_sheet_column/remove_sheet_column,add_excel_column/remove_excel_column).Formulas work: a value that starts with
=is written as a formula, not as text. That makes=HYPERLINK("…", "Order 4471")and=IMAGE("…")useful ways to produce a sheet a person will actually want to read.New spreadsheets can be created by an agent (
add_google_sheet,add_excel_workbook), optionally with initial data. Have the agent open the destination folder first, so the new file lands where you expect.
What agents are not allowed to change
If a work item column that holds a spreadsheet is marked Read only, the in-place write tools are not offered to the agent at all for that file — reads and lookups still work. This is the reliable way to protect a source-of-record spreadsheet. See The File and Image Property Types.
Files uploaded from a local drive are stored copies and are always read-only in this sense. Keep a spreadsheet in Google Drive or OneDrive if agents need to maintain it.
Importing spreadsheet rows as work items
Reading a spreadsheet is not the only option. You can import its rows into the thunk so that each row becomes a work item flowing through your workflow.
Point the import at a Google Sheet, an Excel workbook, a CSV, or an uploaded file. The platform reads the header row, maps the source columns onto your work item columns — including sensibly matching columns whose names differ — and creates one work item per row. You can also filter, importing only the rows that match conditions you give.
This is the usual way to start a workflow from a list somebody sent you: a batch of claims, a list of vendors to verify, a set of records to reconcile. From then on the data lives in the thunk, with all the status tracking, history, and reliability machinery that work items get — which is a much better home for it than the spreadsheet was.
When you want the spreadsheet itself to stay the system of record and be queried in place instead, use a Spreadsheet content folder.