AI — Complete

AI — Complete

Type: ai-complete  ·  Package: AI Activities v1.4.1  ·  Output: string

Sends a prompt to a large language model and returns its answer as text. Use it to summarise, draft, translate, classify, or answer questions about some content.

If what you need is specific fields (a serial number, a date, an amount), use AI — Extract instead: it returns an object rather than text you would then have to parse.

How it works

1. Evaluates prompt (required, not empty), system and images. Without model, it uses the provider’s default model (claude-opus-4-8 for Anthropic).
2. If maskPii is on (the default), it replaces the personal data in the prompt with placeholders before sending it (see Personal data).
3. Calls the model: with your credential, 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 instead of returning half an answer.
5. Puts the real values back into the answer and returns the text.

Every call writes an ai-governance line to the log with the activity, provider, model and how many values were masked per kind (never the values themselves), plus a line with the input and output tokens.

Retries and waits: transient failures (provider overloaded, rate limit, 5xx error, dropped connection, timeout) are retried up to maxRetries times, with growing waits (1 s, 2 s, 4 s… up to 30 s). timeout is the wait for each attempt. With the included AI, each attempt waits at most 600 s even if you ask for more.

Required parameters

Parameter	Type	Default	Description
prompt	string	—	The question or task for the model. It cannot be empty. This is the text maskPii masks.

Optional parameters

Parameter	Type	Default	Description
credential	credential	—	Your own key for the provider (the credential’s value, or an integration with an api_key field). 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: the model’s role, rules and output style. They apply to the whole request. Not masked.
images	string | List	—	Path or list of paths of images to send with the prompt: .jpg, .jpeg, .png, .gif, .webp. Empty paths are ignored. Sent as-is, not masked.
effort	string	—	How much work the model puts into the answer: low, medium, high, xhigh, max. Higher effort costs more tokens and takes longer. Empty uses the provider’s setting.
thinking	bool	false	Lets the model reason before answering. Improves multi-step tasks at the cost of extra tokens and latency.
maxTokens	int	16000	Maximum length of the answer, 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 retrying off. A high number costs nothing while the provider is healthy. Since 1.1.0.
usageVariable	string	—	Name of a variable (declare it as an object) that receives the call’s usage: { model, inputTokens, outputTokens }. 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 answer. Since 1.2.0.
piiKinds	List	— (all)	Which kinds to mask when maskPii is on: 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. If Zoan Cloud does not receive that record, the activity carries on and leaves a warning in the log.

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.

A credential written as an expression that evaluates to empty does not count as “no credential”: it is a configuration error and is never charged to the plan.

Personal data: maskPii and piiKinds

With maskPii = true (the default), before sending the prompt the robot replaces each distinct personal value with a stable placeholder —<CEDULA_1>, <EMAIL_1>, <PERSONA_2>…— and, once the answer arrives, swaps the placeholders back for the real values. The provider never sees the values, and you get the answer with the real data.

Kind	What it detects
cedula	ID numbers of 6 to 10 digits preceded by a keyword (cédula, C.C., identificado con, documento:…), also in JSON keys such as "documento".
nit	Tax IDs (NIT) with check digit (900.123.456-7), or after the word NIT.
email	Email addresses.
telefono	Colombian mobile and landline numbers, with or without +57.
cuenta	Account or card numbers (10 to 19 digits) near cuenta, tarjeta, producto, ahorros…
direccion	Street addresses (Calle 12 # 34-56, Cra 7 No. 8-9…).
persona	Names in context: after a title or role (señor, cliente, titular…), phrases such as me llamo or atentamente,, or in JSON keys such as "nombre".

Worth knowing:

• Only the prompt is masked. system and images are sent as-is: if a sensitive document arrives as an image, turn it into text first.
• These are rules, not a model: a bare number without a keyword, or a name without context, is not detected.
• If your organization requires masking in its personal data policy (Organization and SSO), it applies even if you set maskPii = false, and the required kinds are added to piiKinds.
• What was protected in each call (counts per kind) shows up in AI governance.

Output

Returns a string with the model’s answer, with the personal data already restored.

If you set usageVariable, that variable also receives a { model, inputTokens, outputTokens } object with the model that answered and the call’s tokens.

System and prompt

The split matters: system describes who the model is and what rules it follows for the whole request; prompt is the specific task. Putting the rules in the prompt works, but they get diluted when the content is long.

system → "You are a support email classifier. Reply only with one
          of these words: incident, question, spam."
prompt → emailBody

Example

Classify an incoming email and branch, using the AI included in the plan:

AI — Complete   system    = "You are a classifier…"
                prompt    = email["body"]
                maxTokens = 10
                → output: kind
If              condition = kind == "incident"
  ...

Summarise a long contract with your own key and measure what it cost:

PDF Get Text    path = contractPath   → output: text
AI — Complete   credential    = credential("anthropic-key")
                system        = "Summarise in bullet points, at most 5."
                prompt        = text
                usageVariable = usage
                → output: summary
Log             message = "Summary generated with " + usage["inputTokens"] + " input tokens"

Match maxTokens to what you ask for

The default (16000) leaves plenty of room for a long answer. If you expect a single word, lower it: it makes the call cheaper and keeps the model from rambling.

Common errors

Message	Cause and fix
'prompt' is required.	The prompt ended up empty. Check the variable before calling.
The model hit the 'maxTokens' limit before finishing its response. Raise 'maxTokens' or ask for less output.	The answer does not fit. Raise maxTokens (up to 64000) or ask for less text.
'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: …	A value out of range (or not an integer). Fix the parameter.
'effort' must be one of: low, medium, high, xhigh, max. Received: …	Invalid effort value.
'piiKinds' contains an unknown kind '…'. Valid: cedula, nit, email, telefono, cuenta, direccion, persona.	A misspelled kind in piiKinds.
Image not found. / Unsupported image format '…'. Supported formats: .jpg, .jpeg, .png, .gif, .webp.	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: it is not retried.
Choose a credential or turn on the AI included in your plan. The included AI goes through Zoan Cloud: run the process from Zoan Cloud, or sign in to Zoan Cloud in the Designer.	No credential and the run has no Zoan Cloud (for example, a test without a session). 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.	With the included AI, pick a model from the Zoan Cloud catalog, or use your credential for any other.
The request is too large for the AI included in your plan (up to 20 MB and 20 images per call, 25 MB of audio, 50 MB per document). Send less content, or use your own credential.	Too much text or too many images in one call. Split the content.
Zoan Cloud is handling many AI requests at once. Try again in a few minutes, or raise 'maxRetries'.	Congestion: the retries ran out. Raise maxRetries or wrap the activity in a Retry.
The AI provider did not answer in time through Zoan Cloud. Try again, or raise 'timeout'. / The AI provider answered with an error through Zoan Cloud: …	The provider failed after the retries. Try again later.
Zoan Cloud did not recognize this run, so it cannot use the AI included in your plan. …	The run did not authenticate with Zoan Cloud. Run it again from Zoan Cloud or from the Designer with your session open.
Could not reach Zoan Cloud: …	No network to Zoan Cloud after the retries.

Related activities

• AI — Extract — when you want fields rather than text.
• AI — Transcribe — turn audio into text before processing it.
• PDF Get Text — get the text of a document.