Files in Agent Steps

An Agent Step works with text. Everything the model reads arrives either in the prompt or in the result of a tool call, and both are text. A binary file such as an Excel workbook, a PDF or a Word document therefore never reaches the model as a file. It has to be turned into something the model can read, or, for images and PDF pages, attached as images at the start of the step.

This chapter explains which route a file takes into an Agent Step, why a file an agent downloads itself is not readable on its own, and the patterns that make it readable.

Two routes into the model

Route	What the model gets	When it happens
Step inputs	Text inputs are placed in the prompt. Images and PDFs read by the step's own inputs are attached as images, one image per PDF page, when the model supports vision. Other file types appear only in the files list as metadata.	Once, when the step starts, before the first model call.
Tool calls	The text the tool returns. A tool that downloads a file adds it to the run as a runtime file and returns its name, type, size, a file metadata object and a runtimeFile reference, nothing else.	During the step, each time the agent calls a tool.

The second row is the one that surprises people. An Agent Step with a download tool alone, for example a Dooap attachment download, an OpenAPI file endpoint, Get_Gateway_Email_Attachment or Download_Sftp_File, gets this back from the download:

{
  "fileName": "price-list.xlsx",
  "contentType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
  "sizeBytes": 8787,
  "runtimeFile": { "$runtimeFile": "90243b2c...", "fileName": "price-list.xlsx", "...": "..." },
  "file": { "id": "90243b2c...", "fileName": "price-list.xlsx", "...": "..." }
}

The workbook is safely in the run, but the model only knows that it exists. Asked to analyze the sheet, it will answer that it cannot see the content. The same holds for a file produced by Convert_To_PDF, Extract_PDF_Pages or Extract_Embedded_Files inside the step. See Files downloaded from APIs for how the download itself works.

Pattern 1: download and read in one Agent Step

Add the built-in Read_Context_File tool next to the download tool. The agent downloads the file, passes the returned runtimeFile to Read_Context_File, and gets the content back in the same step:

• an Excel workbook (.xlsx, .xlsm, .xltx) comes back as the rows of one sheet in JSON, with sheetName, hasHeaders and maxRows parameters like Read_Excel_Sheet;
• a Word document (.docx) comes back as text with headings, list items and tables;
• a PDF with a text layer comes back as Markdown, and pages selects the pages to read (1-3, 1,4-8, 1-3,last);
• an HTML page comes back as its visible text;
• CSV, JSON, XML, Markdown, YAML and plain-text files come back as they are.

A prompt for this pattern names both steps of the work:

Download the attachment {{inputs.triggerPayload.attachmentName}} of invoice
{{inputs.dooapEventPayload.dooapInvoiceId}}, then read it with Read_Context_File
and summarize the totals per cost center.

The agent sees the file id in the download result and in the step's files list, so it can read the right file even when the run holds several. Read_Context_File without a reference reads the newest file in the run, which is the file just downloaded in the common case.

Read_Excel_Sheet works the same way for workbooks only. Convert_Excel_To_CSV does not help here: it produces another runtime file and returns a reference, so the model still sees no content.

Pattern 2: download in a Tool Call Step, read through an input

When the download needs no reasoning, do it in a Tool Call Step and let the next step read the file through an input:

1. A Tool Call Step named, for example, Download attachment calls the download tool with template parameters such as {{inputs.dooapEventPayload.dooapInvoiceId}}.
2. The following Agent Step gets an input that reads the file:
   • Read_Excel_Sheet with runtimeFile set to {{steps.Download attachment.data.runtimeFile}} puts the rows into the step input, so the prompt can reference them directly.
   • Read_Context_File with the same reference hands the file to the step. A PDF or an image is then attached to the model as images; a text file is placed in the prompt; a workbook or Word document appears only as metadata, so use Read_Excel_Sheet for workbooks or give the step the Read_Context_File tool and let it read the document.

Pass the download step's runtimeFile object rather than latest whenever the flow produces more than one file. Runtime Files and File References lists every reference form.

Files the model must see: scanned PDFs and images

Read_Context_File returns text, and a scanned PDF or an image has none. The tool does not fail in that case: it returns readable: false and a reason that says why, so the agent can explain the situation or carry on with other work instead of the step failing. To let a model look at such a file, use one of these:

• an OCR Step that reads the file through a Read_Context_File input and hands the recognized text to the next step, or
• a following Agent Step whose own Read_Context_File input reads the file, so the pages are attached as images.

Only a step's own inputs are attached as images. A file that an agent downloads during the step cannot be shown to the same model call, which is why the download belongs in an earlier step when the file must be seen rather than read.

What Read_Context_File returns

Every result carries the file's fileName, contentType, sizeBytes, fileId, a format such as xlsx or pdf, a kind (spreadsheet, pdf, word, html, text, image, archive, legacyspreadsheet or unsupported), readable, warnings, and the runtimeFile and file objects for passing the file on. Readable files add:

Kind	Fields
spreadsheet	sheetName, sheetNames, headers, rows, rowCount, isTruncated
pdf	content (Markdown), contentFormat, pageCount, pages, confidence, isTruncated, totalCharacters
word, html, text	content, contentFormat (markdown, text, csv, json, xml or yaml), isTruncated, totalCharacters

Files that cannot be read return readable: false with a reason:

• images, scanned PDFs and PDFs without a text layer point at the OCR Step or a Read_Context_File input on a following Agent Step;
• ZIP archives point at Extract_Embedded_Files;
• legacy .xls and .ods spreadsheets, PowerPoint and other formats point at saving the file as .xlsx or converting it with Convert_To_PDF first.

A file reference that does not resolve is an error, like any wrong tool parameter.

Limits

Setting	Default	Maximum
maxRows (workbooks)	1,000 rows	10,000 rows
maxCharacters (Word, PDF, HTML, text)	200,000 characters	1,000,000 characters
pages (PDF)	all pages	the document's pages

When a file is cut down, isTruncated is true, totalCharacters or rowCount tells the real size, and a warning says what was left out. Large content counts as tool output tokens in the model's context, so read the sheet or pages the task needs rather than the whole file, and keep the Agent Step's prompt size limit in mind (see Prompt Size Limit).

Letting Shepherd design it

When you describe the flow to Shepherd, say what the file is and what the model should do with it. Shepherd pairs a download tool with Read_Context_File when the agent must analyze the file in the same step, and moves the download to a Tool Call Step with an OCR Step or a Read_Context_File input after it when the model must see a scanned document or an image.

Troubleshooting

• The agent says it cannot read the file. Open the run, check the step's tool calls: if the only call is the download and the step has no Read_Context_File or Read_Excel_Sheet tool, add one of them (Pattern 1) or move the download to an earlier step (Pattern 2).
• readable is false and the reason mentions a text layer. The PDF is scanned. Route it through an OCR Step, or attach it through a Read_Context_File input on a following Agent Step.
• The content stops early. isTruncated is true. Raise maxCharacters or maxRows within the limits, select the pages that matter, or split the work across steps.
• The wrong file was read. The call used latest or no reference while the run held several files. Pass the download result's runtimeFile, or the file id from the files list.

---