Read data from a document

This guide is for authors who want an automation to read a document, such as a commercial invoice or a packing list, and use what it says. An AI Agent block reads the file and returns named values, later blocks check them, and a person corrects anything that looks wrong.

You need an AI provider connection. Files and their names are sent to that provider.

Read, check, and ask a person only about the documents that need it.

1. Get the document into the run

A run has to carry the file before a block can read it. Use the trigger that fits where documents come from:

Operation: add a file upload to the form, so someone can submit the document from Operations.
Email received: the message’s Attachments are files.
Webhook: another system sends the file as a multipart part, and it arrives under Attachments.

2. Read the file with AI Agent

Add AI Agent after the trigger. In its Setup tab:

Connection and Model: your provider and a model that accepts the file type.
System message: the rules. For example: “Copy every value exactly as printed. Never guess or correct a value.”
User message: the request for this run. Type @ to add values such as a job reference.
Files: map the upload from the trigger.

Leave Workspace access and Write access as they are. A block that only reads a document needs neither.

A file that is	Is sent as	Limit
PDF or image	The file itself	20 MB in total, and the model must support the type. Some allow less.
Plain text, CSV or JSON	Text in the message	256 KB per file and 1 MB in total.
Anything else	Not sent, and the step fails	ZIP and GZIP archives are refused. One block takes up to 10 files.

If the model does not accept the file, the step fails and says so. Choose another model, or read the text first with Extract document text, which runs OCR on scanned pages. It reads layout only and returns no named fields, so a model still has to pick out the values.

3. List the fields you want

Set Answer format to Fields and add the Output fields. Each has a Field name, a Field type and whether it is Required:

Field type	Use it for
String	Numbers that are really references, names and dates as printed
Number	Totals and quantities
Boolean	A flag, such as whether the document is signed
Enum	One value from a list you give under Enum values

A field name starts with a letter and holds only letters, numbers and underscores. You can list up to 64 fields.

An AI Agent block's settings with Answer format set to Fields and Output fields such as the invoice number, invoice date, shipper and consignee.

Later blocks map each field with @, under the block’s Answer.

Fields are flat. When the answer has repeating rows, such as the lines of an invoice, set Answer format to JSON and describe it under Answer shape, with records and lists. Later blocks can then map each declared field. An answer shape can’t allow null, so mark a field as not required instead.

4. Connect both exits

The block leaves on Completed or Stopped. Stopped covers everything else: a missing required field, a tool error, or reaching the step limit. Connect it, and read Terminal reason to see why it stopped.

5. Test it on real documents

A form with file uploads can’t start a draft run, so the first test is live:

Publish the automation and submit a document from Operations.
Open the run, select the AI Agent step and read its Output against the document.
Change the block in the editor, then click Run draft and choose A past run to try it on the same file.

Each of these runs calls the model and uses your provider account. Model answers are not always the same, so try awkward documents as well: poor scans, unusual layouts, values that are missing. Runs that used AI show AI usage in the run header.

6. Check the answer

Don’t send a model’s answer on unchecked. A Checklist block runs several named checks at once and reports every difference. It can compare:

two values, such as the invoice number printed on both documents;
a value with your own data, such as the client’s agreed Incoterm from a reference table;
two lists row by row, such as the invoice lines and the packing list lines. List rows come from an answer shape, not from Fields. See Reconcile two documents or lists.

With no findings the block leaves on Approved. With findings it leaves on Rejected, or, set to Send for correction, opens its own review of just the differences.

To find the record to compare with, use Find Required Reference Record. When nothing matches, it can pause and ask a person for the right value. See Look up reference data.

7. Let a person correct it

Send the findings to an Approval block:

Request: what to do, in a few words. It becomes the escalation’s title.
Data to review: the block’s Answer.
Reviewer can: Correct the data.
Source documents: the uploaded files, so they are shown beside the data.

An Approval block's settings with a short request, the answer as the data to review, Correct the data, and the shipment documents as source documents.

The reviewer sees the document next to the values, fixes what is wrong and approves.

An approval escalation showing a commercial invoice beside the data read from it, with the invoice and packing list lines as editable rows, and the Approve and Reject buttons.

After the Approval block, map from its Reviewed data, not from the agent’s Answer, or the corrections are lost. See Put a person in the loop.

Call an outside API, to send what you read to another system.
Use AI blocks
Data Lake