Skip to content
Zoan Docs

AI Activities

Version: 1.4.1  ·  ID: zoan-packages-ai  ·  Author: Zoan Software

The AI package calls a large language model (LLM) from a playbook. It covers what fixed rules cannot: reading a document whose layout changes from one supplier to the next, classifying an email by intent, summarising a long text, extracting specific fields from a document without writing a regular expression per template, or turning audio into text.

How this package works

Section titled “How this package works”
  • No session: each activity makes its own call. Nothing to “connect” or “close”.
  • The credential is optional (since 1.4.0). Empty, the activity uses the AI included in your plan through Zoan Cloud: no keys to set up, with the usage in AI Usage. With your own credential, the call goes straight to your provider and Zoan Cloud only records the usage. Never write a key in the playbook.
  • Personal data is hidden before it leaves: AI — Complete and AI — Extract replace IDs, tax IDs, emails, phones, accounts, addresses and names in the prompt with placeholders (maskPii, on by default) and restore the real values in the answer. See Personal data.
  • The provider is chosen per activity with the provider parameter. Today Anthropic (Claude) is available for text and extraction; transcription uses OpenAI or a Whisper-compatible service.
  • You pay per token, not per call: the cost grows with the size of the document you send and of the answer you ask for. usageVariable gives you each call’s tokens.
  • Only transient failures are retried: an overloaded provider or a dropped connection is retried (maxRetries, 5 by default); a model refusal or a plan limit is not.

Which activity to use

Section titled “Which activity to use”

The difference between the first two is not the model but the shape of the answer.

ActivityTypeOutputWhen to use it
AI — Completeai-completestringYou want text: a summary, a draft, an answer to a question.
AI — Extractai-extractobjectYou want fields: serial number, date, amount, brand. The answer arrives already as an object.
AI — Transcribeai-transcribestringYou have audio: a voice note or a call you want as text.

If you are going to read the answer with regular expressions to pull data out of it, the activity you want is AI — Extract.

Schema-guaranteed extraction

Section titled “Schema-guaranteed extraction”

AI — Extract does not ask for the format in the prompt: it takes a JSON Schema and the model is forced to answer in exactly that shape. That changes two things in production:

  • No parsing of the answer and no checking that it arrived complete: it comes out directly as an object with its fields.
  • No retries for malformed JSON, the typical failure when the format is requested in the prompt and the model ignores it one time in a hundred.

The description of each schema field is part of the prompt: the model reads it to decide what to put in each one. A field described as “the device’s serial number” gets filled far better than one simply called serial.

Limits of the included AI

Section titled “Limits of the included AI”
LimitValue
Size of a text or extraction callUp to 20 MB and 20 images
Audio per transcriptionUp to 25 MB
Wait per attemptUp to 600 s, even if timeout asks for more
Monthly usageWhat your plan includes; at the limit, calls without a credential stop with a clear message and those using your credential keep going

Scanned documents

Section titled “Scanned documents”

AI — Complete and AI — Extract accept images as well as text. For a scanned PDF you have two paths:

  • Text first (recommended for large batches): run the scan through the OCR package or IDP — Load Document and send the resulting text. It is cheaper in tokens, the result is traceable to what was read, and the text does go through personal data masking.
  • Image directly: render the pages with PDF To Images and pass them in images. It costs more tokens and images are not masked, but it does not depend on OCR quality.

If the PDF does have a text layer, use PDF Get Text and skip both.

A typical flow

Section titled “A typical flow”

Read an invoice and extract its data as 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"] + " for " + invoice["total"]

Next steps

Section titled “Next steps”