AI — Extract

AI — Extract

Type: ai-extract  ·  Package: AI Activities v1.4.1  ·  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 forced to answer in exactly that shape, so the result can be used directly as an object.

It 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 is.

How it works

1. Checks that the provider can guarantee a schema-shaped answer (Anthropic can) and validates schema: it must be a JSON Schema object whose root is "type": "object".
2. If maskPii is on (the default), it replaces the personal data in the prompt with placeholders (see Personal data).
3. Sends the model the prompt (the document text), any images, and the schema. With your credential it goes straight to the provider; without it, through the AI included in your plan via Zoan Cloud.
4. If the answer was cut off by maxTokens, it fails with a clear message.
5. Restores the real values in the answer and returns it as an object with its fields, ready to read with result["field"].

schema is a literal: it is not evaluated field by field, so its texts ("type": "object", the descriptions) are never read as expressions. If you write a string that does not start with {, it is evaluated as an expression (for example, a variable that holds the schema).

Retries, waits and the ai-governance log line work the same as in AI — Complete.

Required parameters

Parameter	Type	Default	Description
prompt	string	—	The text of the document to extract from, plus any instructions about it. It cannot be empty. This is the text maskPii masks.
schema	Dictionary | string	—	JSON Schema of the object to extract (the editor’s object, or the JSON as text). The root must be "type": "object". The description of each field is part of the prompt.

Optional parameters

Parameter	Type	Default	Description
credential	credential	—	Your own key for the provider. Leave it empty to use the AI included in your Zoan Cloud plan: nothing to set up, and the usage shows up in AI Usage. Optional since 1.4.0.
provider	string	"anthropic"	AI provider. Valid values: anthropic (Anthropic, Claude).
model	string	"claude-opus-4-8"	Model id. Leave empty to use the provider’s default model. With the included AI, it must be in the Zoan Cloud catalog.
system	string	—	System instructions: what kind of document this is and how to read it. The schema already describes the fields, so use this for context, not for the output format. Not masked.
images	string | List	—	Path or list of paths of images to extract from: .jpg, .jpeg, .png, .gif, .webp. Sent without masking.
effort	string	—	How much work the model puts in: low, medium, high, xhigh, max. Empty uses the provider’s setting.
thinking	bool	false	Lets the model reason before answering. Helps with dense or inconsistent documents.
maxTokens	int	16000	Maximum size of the extracted object, in tokens. Range: 1 to 64000.
timeout	int	600	Seconds to wait per attempt. Range: 1 to 3600. With the included AI, each attempt waits at most 600 s.
maxRetries	int	5	Retries on a transient failure. Range: 0 to 10; 0 turns them off. Since 1.1.0.
usageVariable	string	—	Name of a variable (declare it as an object) that receives the usage: { model, inputTokens, outputTokens }. A document extracted in batches costs one call per batch: add them up. Since 1.1.0.
maskPii	bool	true	Replaces the personal data in the prompt with placeholders before sending it, and restores the real values in the extracted object. Since 1.2.0.
piiKinds	List	— (all)	Which kinds to mask with maskPii: cedula, nit, email, telefono, cuenta, direccion, persona. Empty = all. Since 1.2.0.

No credential: the AI included in your plan

credential is optional since 1.4.0:

• Empty: if your Zoan Cloud plan includes AI, the activity uses Zoan’s account through Zoan Cloud. You don’t create keys or sign up with a provider: the robot works from its first run, and what it uses shows up in AI Usage and counts toward the usage included in your plan. It works in Zoan Cloud runs and in Designer tests with your session open.
• With your credential: the call goes straight from the robot to your provider, with your key and your terms. Zoan Cloud only records the usage (model and tokens) so you can see it in the same panel; the content never goes through Zoan Cloud and that usage does not count against what is included.

With the included AI you can use the Anthropic (Claude) models in the Zoan Cloud catalog. Text and images travel through Zoan Cloud to the provider without being stored —only the usage is recorded— and personal data is masked on the robot, before sending. Each call accepts up to 20 MB and 20 images.

Personal data: maskPii and piiKinds

Same as in AI — Complete: with maskPii = true, each personal value in the prompt (IDs, tax IDs, emails, phones, accounts, addresses, names in context) is replaced with a placeholder such as <CEDULA_1> before sending, and the robot puts the real values back into the answer’s JSON before turning it into an object. The extracted fields arrive with the real data; the provider only saw placeholders.

Only the prompt is masked: images and system are sent as-is. If your organization’s personal data policy requires it, masking applies even if you set maskPii = false.

Output

Returns an object (a dictionary) shaped as you defined in schema. Read the fields with result["name"]:

• Objects in the schema arrive as dictionaries, arrays as lists.
• Whole numbers arrive as integers (long) and decimals as double; true/false as booleans; null as null.
• A field that is not in required and that the model did not find may be missing from the object: mark fields as required if you always read them.

If you set usageVariable, that variable receives { model, inputTokens, outputTokens }.

The schema is part of the prompt

The model reads the description of each field to decide what to put in it, so write them as 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 whoever issues the invoice" }
  },
  "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 with 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, with the AI included in the plan:

PDF Get Text   path = invoicePath   → output: text
AI — Extract   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: order

Common errors

Message	Cause and fix
'schema' must be a JSON Schema whose root is "type": "object", so the extracted result maps to named fields.	The schema asks for a list or a single value. Wrap it in an object with a field that holds that list.
'schema' is required. / 'schema' is not valid JSON: … / 'schema' must be a JSON Schema object, but it is …	The schema is missing or the text is not a JSON object. Check the syntax.
'prompt' is required.	The document text ended up empty (for example, a scanned PDF read with PDF Get Text). Check it beforehand.
The model hit the 'maxTokens' limit before finishing its response. Raise 'maxTokens' or ask for less output.	The extracted object does not fit. Raise maxTokens or ask for fewer fields per call.
Anthropic (Claude) returned a response that is not valid JSON despite the schema: …	Should not happen with a strict schema; if it does, retry.
'maxTokens' must be between 1 and 64000. Received: … / 'timeout' must be between 1 and 3600 seconds. Received: … / 'maxRetries' must be between 0 and 10. Received: … / 'effort' must be one of: …	A parameter out of range. Fix it.
'piiKinds' contains an unknown kind '…'. Valid: cedula, nit, email, telefono, cuenta, direccion, persona.	A misspelled kind in piiKinds.
Image not found. / Unsupported image format '…'. …	A path in images does not exist or is not a supported image.
The credential does not contain an Anthropic API key. Store the key as the credential's value in Zoan Cloud.	The credential exists but is empty or holds something else.
Claude declined this request for safety reasons: …	The model refused the content. It is the model’s answer, not a configuration problem.
Choose a credential or turn on the AI included in your plan. The included AI goes through Zoan Cloud: …	No credential and no Zoan Cloud in the run. Sign in or use your own credential.
Choose a credential or turn on the AI included in your plan.	No credential and your plan does not include AI.
The AI usage included in your plan for this month has been reached. Use your own credential or upgrade the plan.	All the AI usage included this month is spent. With your own credential the robot keeps going.
The model '…' is not available in the AI included in your plan. Pick another model, or use your own credential.	Pick a model from the Zoan Cloud catalog, or use your credential.
The request is too large for the AI included in your plan (up to 20 MB and 20 images per call, …).	Split the document or send fewer images.
Zoan Cloud is handling many AI requests at once. … / The AI provider did not answer in time through Zoan Cloud. …	Transient failure after the retries ran out. Raise maxRetries or use a Retry.

Related activities

• AI — Complete — when you want text rather than fields.
• PDF Get Text — get the text before extracting.
• OCR — read scanned documents.
• IDP — Extract — extraction with a project, located values and review.
• Queue Process — extract a large batch of documents with retries.