AI Extract

AI Extract

Type: ai-extract  ·  Package: AI Activities v1.0.0  ·  Output: object

Extracts specific fields from a document using a large language model. You describe the fields you want with a JSON Schema and the model is required to answer in exactly that shape, so the result is used directly as an object.

This is the activity for reading documents whose layout changes: the same configuration reads one supplier’s invoice and another’s, because you describe what each field means rather than where it sits.

How it works

Sends the model the prompt (the document text), the images if there are any, and the schema. The answer arrives already validated against the schema and is returned as an object, ready to read with result["field"].

Required parameters

Parameter	Editor	Description
credential	credential	Zoan Cloud credential holding the provider’s API key.
prompt	expression	The document text to extract from, plus any instruction about it.
schema	JSON	JSON Schema of the object to extract. The root must be "type": "object".

Optional parameters

Parameter	Editor	Description
provider	enum	AI provider. Defaults to Anthropic (Claude).
model	expression	Model id. Leave empty to use the provider’s default model.
system	expression	System instructions: what kind of document this is and how to read it.
images	list	Paths of images to extract from (.jpg, .png, .gif, .webp).
effort	enum	How much work the model puts in: low, medium, high, xhigh, max.
thinking	boolean	Let the model reason before answering.
maxTokens	expression	Maximum size of the extracted object, in tokens. Default 16000.
timeout	expression	Seconds to wait. Default 600.

Output

Returns an object shaped as defined in schema. Read the fields with result["name"].

The schema is part of the prompt

The model reads the description of each field to decide what belongs in it, so write them the way you would explain them to someone seeing the document for the first time:

{
  "type": "object",
  "properties": {
    "number":   { "type": "string", "description": "Invoice number exactly as printed" },
    "date":     { "type": "string", "description": "Issue date in YYYY-MM-DD format" },
    "total":    { "type": "number", "description": "Total amount including taxes" },
    "supplier": { "type": "string", "description": "Legal name of the issuing company" }
  },
  "required": ["number", "date", "total", "supplier"],
  "additionalProperties": false
}

Ask for the literal value when traceability matters

If you need to know where a value came from — to review it, highlight it, or audit it — add a field holding the text exactly as it appears in the document, described as “the literal text this value comes from”. A value you can find again in the document is a value you can verify.

Example

Read a PDF invoice and use its fields:

PDF Get Text   path = = invoicePath   → output: text
AI Extract     credential = = credential("anthropic-key")
               prompt     = = text
               schema     = {…}
               → output: invoice
Log            message = = "Invoice " + invoice["number"] + ": " + invoice["total"]

Extract from a scanned document, going through OCR first:

PDF To Images   path = = scanPath   dpi = 200   → output: pages
OCR Get Lines   path = = pages[0]              → output: lines
AI Extract      credential = = credential("anthropic-key")
                prompt     = = join(map(lines, "l => l[\"text\"]"), "\n")
                schema     = {…}
                → output: equipment

Common errors

Message	What happened
'schema' must be a JSON Schema whose root is "type": "object"	The schema asks for a list or a bare value. Wrap it in an object with a field holding that list.
The model hit the 'maxTokens' limit before finishing	The extracted object does not fit. Raise maxTokens or ask for fewer fields per call.
The credential does not contain an Anthropic API key	The credential exists but is empty or holds something else.
Claude declined this request for safety reasons	The model refused the content. This is an answer from the model, not a configuration failure.

Related activities

• AI Complete — when you want text instead of fields.
• PDF Get Text — get the text before extracting.
• OCR — read scanned documents.
• Queue Process — extract a large batch of documents with retries.