AI — Complete

AI — Complete

Tipo: ai-complete  ·  Paquete: AI Activities v1.4.1  ·  Salida: string

Envía un prompt a un modelo de lenguaje y devuelve su respuesta como texto. Sirve para resumir, redactar, traducir, clasificar o responder preguntas sobre un contenido. En el Designer en español aparece como IA — Generar texto.

Si lo que necesitas son campos concretos (un número de serie, una fecha, un importe), usa AI — Extract: devuelve un objeto en vez de texto que luego tendrías que parsear.

Cómo funciona

1. Evalúa prompt (obligatorio y no vacío), system e images. Sin model, usa el modelo por defecto del proveedor (claude-opus-4-8 en Anthropic).
2. Si maskPii está activo (por defecto), reemplaza los datos personales del prompt por marcadores antes de enviarlo (ver Datos personales).
3. Llama al modelo: con tu credential, directo al proveedor; sin ella, por la IA incluida en tu plan a través de Zoan Cloud.
4. Si la respuesta se cortó por maxTokens, falla con un mensaje claro en vez de devolver texto a medias.
5. Restaura en la respuesta los valores reales que se habían enmascarado y devuelve el texto.

Cada llamada deja en el log una línea ai-governance con la actividad, el proveedor, el modelo y cuántos datos se enmascararon por tipo (nunca los valores), y otra con los tokens de entrada y salida.

Reintentos y esperas: los fallos pasajeros (proveedor saturado, límite de solicitudes, error 5xx, conexión caída, tiempo agotado) se reintentan hasta maxRetries veces, con esperas crecientes (1 s, 2 s, 4 s… hasta 30 s). timeout es la espera de cada intento. Con la IA incluida, cada intento espera como máximo 600 s aunque pidas más.

Parámetros requeridos

Parámetro	Tipo	Por defecto	Descripción
prompt	string	—	La pregunta o tarea para el modelo. No puede quedar vacío. Es el texto que se enmascara con maskPii.

Parámetros opcionales

Parámetro	Tipo	Por defecto	Descripción
credential	credential	—	Tu propia clave del proveedor (valor de la credencial, o integración con campo api_key). Vacía usa la IA incluida en tu plan de Zoan Cloud: nada que configurar, y el consumo aparece en Consumo de IA. Opcional desde la versión 1.4.0.
provider	string	"anthropic"	Proveedor de IA. Valores válidos: anthropic (Anthropic, Claude).
model	string	"claude-opus-4-8"	Id del modelo. Vacío usa el modelo por defecto del proveedor. Con la IA incluida, debe estar en el catálogo de Zoan Cloud.
system	string	—	Instrucciones de sistema: papel del modelo, reglas y estilo de la respuesta. Aplican a toda la petición. No se enmascaran.
images	string | List	—	Ruta o lista de rutas de imágenes que se envían con el prompt: .jpg, .jpeg, .png, .gif, .webp. Las rutas vacías se ignoran. Se envían tal cual, sin enmascarar.
effort	string	—	Cuánto trabajo pone el modelo en la respuesta: low, medium, high, xhigh, max. Más esfuerzo gasta más tokens y tarda más. Vacío usa el ajuste del proveedor.
thinking	bool	false	Deja que el modelo razone antes de responder. Mejora las tareas de varios pasos a cambio de más tokens y demora.
maxTokens	int	16000	Longitud máxima de la respuesta, en tokens. Rango: 1 a 64000.
timeout	int	600	Segundos de espera por intento. Rango: 1 a 3600. Con la IA incluida, cada intento espera como máximo 600 s.
maxRetries	int	5	Reintentos ante un fallo pasajero. Rango: 0 a 10; 0 desactiva los reintentos. Un número alto no cuesta nada cuando el proveedor responde bien. Desde la versión 1.1.0.
usageVariable	string	—	Nombre de una variable (declárala como objeto) donde se escribe el consumo de la llamada: { model, inputTokens, outputTokens }. Desde la versión 1.1.0.
maskPii	bool	true	Reemplaza los datos personales del prompt por marcadores antes de enviarlo y restaura los valores reales en la respuesta. Desde la versión 1.2.0.
piiKinds	List	— (todos)	Qué tipos ocultar cuando maskPii está activo: cedula, nit, email, telefono, cuenta, direccion, persona. Vacío = todos. Desde la versión 1.2.0.

Sin credencial: la IA incluida en tu plan

credential es opcional desde la versión 1.4.0:

• Vacía: si tu plan de Zoan Cloud incluye IA, la actividad usa la cuenta de Zoan a través de Zoan Cloud. No creas claves ni contratas un proveedor: el robot trabaja desde la primera ejecución, y lo que consume aparece en Consumo de IA y cuenta en el consumo incluido en tu plan. Funciona en las ejecuciones de Zoan Cloud y en las pruebas del Designer con tu sesión abierta.
• Con tu credencial: la llamada va directo del robot a tu proveedor, con tu clave y tus condiciones. Zoan Cloud registra solo el consumo (modelo y tokens) para que lo veas en el mismo panel; el contenido nunca pasa por Zoan Cloud y ese uso no descuenta del consumo incluido. Si Zoan Cloud no recibe ese registro, la actividad sigue y deja una advertencia en el log.

Con la IA incluida puedes usar los modelos de Anthropic (Claude) del catálogo de Zoan Cloud. El texto y las imágenes viajan por Zoan Cloud hasta el proveedor sin guardarse —solo se registra el consumo— y el enmascarado de datos personales se aplica en el robot, antes de enviarlos. Cada llamada admite hasta 20 MB y 20 imágenes.

Una credencial escrita como expresión que resulta vacía no cuenta como «sin credencial»: es un error de configuración y no pasa a cobrarse del plan.

Datos personales: maskPii y piiKinds

Con maskPii = true (el valor por defecto), antes de enviar el prompt el robot reemplaza cada dato personal distinto por un marcador estable —<CEDULA_1>, <EMAIL_1>, <PERSONA_2>…— y, al recibir la respuesta, cambia los marcadores de vuelta por los valores reales. El proveedor nunca ve los valores, y tú recibes la respuesta con los datos reales.

Tipo	Qué detecta
cedula	Números de documento de 6 a 10 dígitos precedidos de una palabra clave (cédula, C.C., identificado con, documento:…), también en claves JSON como "documento".
nit	NIT con dígito de verificación (900.123.456-7), o tras la palabra NIT.
email	Correos electrónicos.
telefono	Celulares y fijos de Colombia, con o sin +57.
cuenta	Números de cuenta o tarjeta (10 a 19 dígitos) cerca de cuenta, tarjeta, producto, ahorros…
direccion	Direcciones urbanas (Calle 12 # 34-56, Cra 7 No. 8-9…).
persona	Nombres en contexto: tras un tratamiento o rol (señor, cliente, titular…), frases como me llamo o atentamente,, o en claves JSON como "nombre".

Lo que conviene saber:

• Solo se enmascara el prompt. system y las images se envían tal cual: si un documento sensible llega como imagen, conviértelo antes a texto.
• Son reglas, no un modelo: un número suelto sin palabra clave o un nombre sin contexto no se detecta.
• Si tu organización exige el enmascarado en su política de datos personales (Organización y SSO), se aplica aunque pongas maskPii = false, y los tipos obligatorios se suman a los de piiKinds.
• Qué se protegió en cada llamada (conteos por tipo) lo ves en Gobierno de IA.

Salida

Devuelve un string con la respuesta del modelo, con los datos personales ya restaurados.

Si indicas usageVariable, esa variable recibe además un objeto { model, inputTokens, outputTokens } con el modelo que respondió y los tokens de la llamada.

System y prompt

La separación importa: system describe quién es el modelo y qué reglas sigue durante toda la petición; prompt es la tarea concreta. Poner las reglas en el prompt funciona, pero se diluyen cuando el contenido es largo.

system → "Eres un clasificador de correos de soporte. Responde solo con una
          de estas palabras: incidencia, consulta, spam."
prompt → cuerpoDelCorreo

Ejemplo

Clasificar un correo entrante y ramificar, con la IA incluida en el plan:

AI — Complete   system    = "Eres un clasificador…"
                prompt    = correo["body"]
                maxTokens = 10
                → output: tipo
If              condition = tipo == "incidencia"
  ...

Resumir un contrato largo con tu propia clave y medir lo que costó:

PDF Get Text    path = rutaContrato   → output: texto
AI — Complete   credential    = credential("anthropic-key")
                system        = "Resume en viñetas, máximo 5, en español."
                prompt        = texto
                usageVariable = consumo
                → output: resumen
Log             message = "Resumen generado con " + consumo["inputTokens"] + " tokens de entrada"

Ajusta maxTokens a lo que pides

El valor por defecto (16000) da margen de sobra para una respuesta larga. Si esperas una palabra, bájalo: hace la llamada más barata y evita que el modelo se explaye.

Errores comunes

Mensaje	Causa y solución
'prompt' es obligatorio.	El prompt quedó vacío. Valida la variable antes de llamar.
El modelo llegó al límite de 'maxTokens' antes de terminar su respuesta. Sube 'maxTokens' o pide una salida más corta.	La respuesta no cabe. Sube maxTokens (hasta 64000) o pide menos texto.
'maxTokens' debe estar entre 1 y 64000. Recibido: … / 'timeout' debe estar entre 1 y 3600 segundos. Recibido: … / 'maxRetries' debe estar entre 0 y 10. Recibido: …	Un valor fuera de rango (o no entero). Corrige el parámetro.
'effort' debe ser uno de: low, medium, high, xhigh, max. Recibido: …	Valor de esfuerzo no válido.
'piiKinds' contiene un tipo desconocido '…'. Válidos: cedula, nit, email, telefono, cuenta, direccion, persona.	Un tipo mal escrito en piiKinds.
No se encontró la imagen. / Formato de imagen no admitido '…'. Formatos admitidos: .jpg, .jpeg, .png, .gif, .webp.	Una ruta de images no existe o no es una imagen admitida.
La credencial no contiene una API key de Anthropic. Guarda la clave como valor de la credencial en Zoan Cloud.	La credencial existe pero está vacía o guarda otra cosa.
Claude rechazó esta solicitud por motivos de seguridad: …	El modelo rechazó el contenido. Es una respuesta del modelo, no un fallo de configuración: no se reintenta.
Elige una credencial o activa la IA incluida en tu plan. La IA incluida va a través de Zoan Cloud: ejecuta el proceso desde Zoan Cloud o, en el Designer, inicia sesión en Zoan Cloud.	Sin credencial y la ejecución no tiene Zoan Cloud (por ejemplo, una prueba sin sesión). Abre tu sesión o usa una credencial propia.
Elige una credencial o activa la IA incluida en tu plan.	Sin credencial y tu plan no incluye IA.
Se alcanzó el consumo de IA incluido en tu plan este mes. Usa una credencial propia o amplía el plan.	Se usó todo el consumo de IA incluido este mes. Con una credencial propia el robot sigue sin pausa.
El modelo «…» no está disponible en la IA incluida en tu plan. Elige otro modelo o usa una credencial propia.	Con la IA incluida, elige un modelo del catálogo de Zoan Cloud, o usa tu credencial para cualquier otro.
La solicitud es demasiado grande para la IA incluida en tu plan (hasta 20 MB y 20 imágenes por llamada, 25 MB de audio y 50 MB por documento). Envía menos contenido o usa una credencial propia.	Demasiado texto o demasiadas imágenes en una llamada. Divide el contenido.
Zoan Cloud está atendiendo muchas solicitudes de IA a la vez. Inténtalo de nuevo en unos minutos o sube 'maxRetries'.	Congestión: se agotaron los reintentos. Sube maxRetries o envuelve la actividad en un Retry.
El proveedor de IA no respondió a tiempo a través de Zoan Cloud. Inténtalo de nuevo o sube 'timeout'. / El proveedor de IA respondió con un error a través de Zoan Cloud: …	Fallo del proveedor tras los reintentos. Reintenta más tarde.
Zoan Cloud no reconoció esta ejecución, así que no puede usar la IA incluida en tu plan. …	La ejecución no se autenticó ante Zoan Cloud. Vuelve a ejecutarla desde Zoan Cloud o desde el Designer con la sesión abierta.
No se pudo contactar a Zoan Cloud: …	Sin red hacia Zoan Cloud tras los reintentos.

Actividades relacionadas

• AI — Extract — cuando quieres campos en vez de texto.
• AI — Transcribe — convertir un audio en texto antes de procesarlo.
• PDF Get Text — obtener el texto de un documento.