AI Activities

Versión: 1.0.0  ·  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, o extraer campos concretos de un documento sin escribir una expresión regular por cada plantilla.

Cómo funciona este paquete

• Sin sesión: cada actividad recibe la credencial y hace su llamada. No hay que “conectar” ni “cerrar”.
• La credencial guarda la API key del proveedor, igual que cualquier otra credencial de Zoan Cloud. Nunca escribas la clave en el playbook.
• El proveedor se elige por actividad con el parámetro provider. Hoy está disponible Anthropic (Claude); el paquete está construido para añadir otros sin tocar los playbooks que ya existen.
• 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.

Qué actividad usar

La diferencia entre las dos actividades 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.

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.

Documentos escaneados

Las dos actividades 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 y envía el texto resultante. Es más barato en tokens y el resultado es rastreable a lo que leyó el OCR.
• Imagen directa: renderiza las páginas con PDF To Images y pásalas en images. Cuesta más tokens, 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:

PDF Get Text   path = = rutaFactura   → output: texto
AI Extract     credential = anthropic-key   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.
• OCR — leer documentos escaneados antes de extraer.