AI Activities

Versión: 1.4.1  ·  ID: zoan-packages-ai  ·  Autor: Zoan Software

El paquete AI llama a un modelo de lenguaje (LLM) desde un playbook. Sirve para lo que las reglas fijas no cubren: leer un documento cuyo formato cambia de un proveedor a otro, clasificar un correo por su intención, resumir un texto largo, extraer campos concretos de un documento sin escribir una expresión regular por cada plantilla, o convertir un audio en texto.

Cómo funciona este paquete

• Sin sesión: cada actividad hace su llamada. No hay que “conectar” ni “cerrar”.
• La credencial es opcional (desde la versión 1.4.0). Vacía, la actividad usa la IA incluida en tu plan a través de Zoan Cloud: sin claves que configurar, con el consumo en Consumo de IA. Con tu propia credencial, la llamada va directo a tu proveedor y Zoan Cloud registra solo el consumo. Nunca escribas una clave en el playbook.
• Los datos personales se ocultan antes de salir: AI — Complete y AI — Extract reemplazan por marcadores las cédulas, NIT, correos, teléfonos, cuentas, direcciones y nombres del prompt (maskPii, activo por defecto) y restauran los valores reales en la respuesta. Ver Datos personales.
• El proveedor se elige por actividad con el parámetro provider. Hoy está disponible Anthropic (Claude) para texto y extracción; la transcripción usa OpenAI o un servicio compatible con Whisper.
• Se paga por token, no por llamada: el coste sube con el tamaño del documento que envías y de la respuesta que pides. usageVariable te da los tokens de cada llamada.
• Reintenta solo lo pasajero: un proveedor saturado o una conexión caída se reintentan (maxRetries, 5 por defecto); una negativa del modelo o un tope del plan, no.

Qué actividad usar

La diferencia entre las dos primeras no es el modelo, sino qué forma tiene la respuesta.

Actividad	Tipo	Salida	Cuándo usarla
AI — Complete	ai-complete	string	Quieres texto: un resumen, una redacción, una respuesta a una pregunta.
AI — Extract	ai-extract	object	Quieres campos: número de serie, fecha, importe, marca. La respuesta llega ya como objeto.
AI — Transcribe	ai-transcribe	string	Tienes un audio: una nota de voz o una llamada que quieres convertir en texto.

Si vas a leer la respuesta con expresiones regulares para sacarle datos, la actividad que buscas es AI — Extract.

Extracción garantizada por esquema

AI — Extract no pide el formato en el prompt: recibe un JSON Schema y el modelo está obligado a responder con esa forma exacta. Eso cambia dos cosas en producción:

• No hay que parsear la respuesta ni validar que llegó completa: sale directamente como objeto con sus campos.
• No hay reintentos por JSON mal formado, que es el fallo típico cuando el formato se pide en el prompt y el modelo lo ignora una de cada cien veces.

Las descripciones de cada campo del esquema son parte del prompt: el modelo las lee para decidir qué poner en cada uno. Un campo descrito como “número de serie del equipo” se llena mucho mejor que uno llamado serie a secas.

Límites de la IA incluida

Límite	Valor
Tamaño de una llamada de texto o extracción	Hasta 20 MB y 20 imágenes
Audio por transcripción	Hasta 25 MB
Espera por intento	Hasta 600 s, aunque timeout pida más
Consumo mensual	El incluido en tu plan; al llegar al tope, las llamadas sin credencial se detienen con un mensaje claro y las que usan tu credencial siguen

Documentos escaneados

AI — Complete y AI — Extract aceptan imágenes además de texto. Para un PDF escaneado tienes dos caminos:

• Texto primero (recomendado para lotes grandes): pasa el escaneo por el paquete OCR o por IDP — Load Document y envía el texto resultante. Es más barato en tokens, el resultado es rastreable a lo que se leyó y el texto sí pasa por el enmascarado de datos personales.
• Imagen directa: renderiza las páginas con PDF To Images y pásalas en images. Cuesta más tokens y las imágenes no se enmascaran, pero no depende de la calidad del OCR.

Si el PDF sí tiene capa de texto, usa PDF Get Text y ahórrate ambos.

Un flujo típico

Leer una factura y extraer sus datos como campos, con la IA incluida en el plan:

PDF Get Text   path = rutaFactura   → output: texto
AI — Extract   prompt = texto   schema = {…}   → output: factura
Log            message = "Factura " + factura["numero"] + " por " + factura["total"]

Siguientes pasos

• AI — Extract — extraer campos de un documento (lo más común).
• AI — Complete — respuestas en texto libre.
• AI — Transcribe — convertir un audio en texto.
• Consumo de IA — qué cuenta y qué pasa al llegar al tope.
• OCR — leer documentos escaneados antes de extraer.