Saltar al contenido principal

Agentes de IA

Un agente de IA es un objeto reutilizable y configurable - como una plantilla - que lee un contexto limitado y emite resultados estructurados validados. El recorrido o trabajo de catálogo que lo rodea usa ese resultado; el agente no envía, ramifica, actualiza atributos ni llama a una API por sí mismo.

Los encontrarás en Configuración → Agentes de IA. Crear y editar agentes requiere el ámbito de rol settings:write (o una clave de API con ai_agents:write); para verlos necesitas settings:read / ai_agents:read.

Solo generación: decide, no actúa​

Esta es la idea central y es intencional. Un agente de IA no es un bot autónomo que llama herramientas. No tiene herramientas ni acciones. En cada ejecución:

  1. Lee únicamente el contexto que autorizaste (atributos seleccionados, segmentos, campos de catálogo, voz de marca e interacción reciente).
  2. Pide al modelo que produzca un resultado que coincida con el esquema de salida estricto que definiste.
  3. Valida ese resultado y lo devuelve, junto con una explanation opcional del razonamiento del modelo.

Todo lo que actúa sobre el resultado ya existe en Joryio: tu recorrido envía el mensaje, toma una rama o escribe el atributo; tu trabajo de enriquecimiento de catálogo escribe el valor en un campo. El agente solo aporta el valor generado. Esto mantiene la maquinaria potente y con efectos secundarios bajo las protecciones en las que ya confías (límites de envío, supresión y ramificación) y limita la IA a lo que hace bien: generar y decidir.

Crear un agente​

Instrucciones​

Las instrucciones son el objetivo del agente: su prompt de sistema. Se convierten en plantilla Liquid con el vocabulario de tu espacio de trabajo y el contexto seleccionado en tiempo de ejecución, para que puedas referirte a nombres reales de atributos y eventos. Describe lo que quieres generar y las reglas que debe seguir (tono, longitud y valores permitidos).

Haz referencia a los campos que realmente expones

El modelo solo ve los campos de contexto que enumeras en Selectores de contexto. Si las instrucciones mencionan un campo (por ejemplo, «comprueba el precio») que no está en el contexto, el modelo no puede usarlo. Nombra el campo exacto que expusiste, por ejemplo «si series_id es mayor que 1200…». El historial de ejecuciones muestra la entrada exacta que vio el modelo, lo que facilita detectarlo.

Etiquetas​

Asigna etiquetas a un agente para organizar y filtrar tu biblioteca de agentes. Las etiquetas proceden del conjunto compartido del espacio de trabajo (las mismas que usas en campañas, recorridos y plantillas), se autocompletan al escribir y permiten filtrar la lista de agentes. Se contabilizan en la interfaz de gestión de Etiquetas como cualquier otro recurso etiquetado.

Modelo: gestionado frente a BYO​

Cada agente se ejecuta con un modelo, configurado de dos formas:

  • Gestionado: Joryio Auto. Una sola opción: Joryio selecciona automáticamente el mejor modelo alojado (y su esfuerzo de razonamiento) para cada ejecución. No hay nada que ajustar: ni ID de modelo ni nivel de razonamiento. Pagas el coste de tokens más nuestro margen, facturado como un crédito por ejecución desde tu cartera. No hay que configurar claves; funciona directamente.
  • BYO (trae tu propia clave): tu propia clave de proveedor. Proveedores compatibles: Anthropic, OpenAI, Google (Gemini), Azure OpenAI y AWS Bedrock. Aquí indicas el ID de modelo concreto que se debe llamar (por ejemplo, claude-opus-4-8, gpt-4o, gemini-1.5-pro). Pagas los tokens directamente a tu proveedor de LLM; Joryio cobra una pequeña tarifa plana de plataforma por ejecución. Añade la clave en Claves de proveedor (más abajo) antes de seleccionar BYO.

Selectores de contexto (lo que puede leer el agente)​

El contexto es de inclusión voluntaria. Un agente no lee nada de un contacto o registro salvo que lo enumeres aquí:

  • Claves de atributo: los atributos del contacto que se deben incluir.
  • Pertenencia a segmentos: indicadores de los segmentos enumerados.
  • Campos de catálogo: campos del catálogo o del registro de entidad que se está enriqueciendo.
  • Campos obligatorios: un subconjunto de campos de catálogo que deben estar presentes para que el agente se ejecute. Durante el enriquecimiento, cualquier fila sin uno de ellos se omite y no se factura (se registra el motivo). Enriquecer una fila incompleta desperdicia una ejecución y normalmente produce una respuesta peor, así que exige los campos que el agente realmente necesita.
  • Voz de marca: incluye la voz de marca del espacio de trabajo para que el resultado suene acorde a ella.
  • Interacción reciente: un resumen breve de la actividad reciente del contacto.
  • Enmascaramiento de PII: la PII se gestiona globalmente; marca un atributo como PII en Atributos personalizados y se oculta automáticamente antes de que el modelo lo vea, en cada agente.

Esquema de salida​

El esquema de salida limita lo que el modelo puede devolver, para que los nodos posteriores siempre reciban una estructura previsible:

  • Tipo: string, number, boolean o json.
  • Para json, una lista de campos con nombre, cada uno con un tipo primitivo (string, number, boolean) y una descripción opcional.
  • Incluir explicación: captura el razonamiento del modelo en un campo explanation (un rastro económico e inspeccionable).

Los resultados que no coinciden con el esquema se rechazan y se tratan como un fallo (consulta el contrato de errores más abajo).

Valor alternativo​

Cada agente tiene un valor alternativo, el valor que se sustituye cuando una ejecución falla por cualquier motivo. Así se garantiza que tu recorrido nunca se detenga esperando al modelo: ante un fallo toma el borde de error conectado o continúa con el valor alternativo.

Límite diario​

Cada agente tiene su propio límite diario de ejecuciones (250 000 de forma predeterminada; 0 = ilimitado): el máximo de veces que ese agente se ejecuta al día. Al alcanzarlo, las ejecuciones posteriores fallan cerradas con el resultado budget_exceeded (y toman el borde de error o valor alternativo), protegiendo tu gasto de un recorrido descontrolado. Tu cuenta también tiene un límite diario para todo el espacio de trabajo que se aplica a todos los agentes combinados y gestiona Joryio; contáctanos para aumentarlo.

Protecciones​

Protecciones por ejecución: un tiempo de espera estricto (20 s de forma predeterminada), un límite opcional de tokens máximos de salida y la opción de reintentar errores transitorios (solo límites de tasa y 5xx; nunca ante una clave errónea o salida no válida).

Crear un agente con el asistente de IA​

También puedes pedir al asistente de Joryio que cree un agente: describe lo que quieres (por ejemplo, «un agente que lee el precio de un producto y escribe alto o bajo») y te propondrá uno listo para aplicar. Muestra una tarjeta Aplicar que resume el agente; no se crea nada hasta que la pulsas. Al aplicarlo, el agente se crea como borrador y recibes un enlace para abrirlo en el editor, de modo que siempre lo revisas, pruebas y activas tú mismo antes de que se ejecute. Los agentes creados por el asistente siempre son gestionados (Joryio Auto); el asistente nunca selecciona un proveedor BYO ni gestiona claves.

Usar un agente en un recorrido​

Añade un nodo Agente de IA a un recorrido y elige el agente. Para cada contacto, el nodo lee el contexto, ejecuta el agente y escribe la salida en la instantánea de ejecución para que los nodos posteriores (mensajes, ramas y actualizaciones de atributos) puedan referirse a ella.

El nodo expone bordes de resultado de primera clase para que puedas ramificar según cómo haya ido la ejecución:

  • success: el modelo devolvió una salida válida; esa salida está disponible después.
  • fallback: una ejecución falló pero no conectaste un borde de error específico; se usa el valor alternativo y el recorrido continúa.
  • Resultados de error: timeout, rate_limited, invalid_config y budget_exceeded. Cada uno es un borde de rama independiente en el nodo, para que conectes cada resultado de error a su propia ruta del canvas (o dejes que cualquiera continúe en fallback).

Este contrato de errores explícito es un diferenciador intencional: en lugar de fallar silenciosamente a null y obligarte a proteger cada nodo posterior, un agente de IA te permite dirigir «el agente dio error → toma esta rama» como cualquier otra decisión.

Un agente también puede ejecutarse sobre tus registros de catálogo o entidades personalizadas para generar o categorizar un campo: descripciones de productos, etiquetas, un siguiente mejor artículo o una categoría normalizada. Eliges el agente, la entidad, el campo objetivo en el que se escribe la salida y un filtro opcional para limitar los registros procesados. La ejecución de cada fila se mide y rastrea igual que la de un recorrido.

El trabajo de enriquecimiento se ejecuta de forma asíncrona en segundo plano: envías un trabajo y devuelve enseguida un ID de trabajo en cola, de modo que un catálogo grande (hasta 100 000 filas) se procesa fuera de la ruta de solicitud sin bloquearla. Después haces polling del trabajo para conocer su estado y recuentos: el estado pasa por queued → running → completed (o failed), y los recuentos (total, procesados, correctos, fallidos y omitidos) se completan durante el proceso. El trabajo es idempotente por registro, por lo que una nueva ejecución nunca vuelve a cobrar una fila ya enriquecida. Puedes iniciarlo y ver el avance desde el panel o mediante los endpoints de enriquecimiento.

Solo las ejecuciones correctas escriben el campo. Una fila se omite (su valor existente queda intacto) siempre que el agente devuelve un resultado distinto de éxito: falta un campo obligatorio, la cartera está vacía (budget_exceeded), la clave BYO está mal configurada (invalid_config), etc. Cuando se omite alguna fila, el trabajo muestra un motivo (por ejemplo, «2 de 2 filas sin escribir: invalid_config: …») para que sepas por qué no se escribió nada, en vez de ver un recuento sin más. El enriquecimiento de catálogo se factura por ejecución; Prueba y vista previa son gratis (consulta abajo).

Pruebas y vista previa​

Antes de desplegar un agente, usa Probar para ejecutarlo en seco con un contexto de ejemplo que proporciones (atributos de ejemplo, pertenencias a segmentos, un registro de catálogo y un resumen de interacción). La vista previa devuelve exactamente lo que produciría una ejecución real:

  • outcome: success, fallback o uno de los resultados de error.
  • output: la salida estructurada validada (o el valor alternativo en caso de fallo).
  • explanation: el razonamiento del modelo, cuando tu esquema lo incluye.

Las ejecuciones de prueba y vista previa usan una clave de ejecución nueva, nunca cuentan para un recorrido real y son gratuitas: no requieren saldo en la cartera. Así puedes iterar con un agente (solo las ejecuciones reales de recorrido o catálogo necesitan una cartera con fondos). Si una prueba informa un resultado distinto de éxito, muestra el motivo de error exacto para que puedas corregirlo (clave ausente, cartera sin fondos, salida que no supera la validación del esquema, etc.).

El contrato de errores​

Cada ejecución termina con exactamente un resultado:

ResultadoSignificado¿Se reintenta?
successSalida válida que coincide con el esquema.-
fallbackUna ejecución falló y no se conectó un borde de error específico; se usa el valor alternativo.-
timeoutLa ejecución superó el tiempo de espera por ejecución.Transitorio: se reintenta si está habilitado.
rate_limitedEl proveedor aplicó un límite de tasa a la solicitud.Transitorio: se reintenta si está habilitado.
invalid_configFallo determinista: clave incorrecta o caducada, error de configuración de precios/débitos o salida del modelo que no supera la validación del esquema.No: nunca se reintenta.
budget_exceededSe alcanzó un límite de gasto: límite diario del agente, límite diario del espacio de trabajo de la cuenta o saldo insuficiente en la cartera para una ejecución facturada.No.

Los reintentos usan espera exponencial limitada y solo se aplican a fallos transitorios.

Medición y coste​

Las ejecuciones se miden por invocación:

  • Gestionado: un crédito por ejecución, cargado a tu cartera. El crédito se calcula con margen para tokens más nuestro margen.
  • BYO: una pequeña tarifa plana de plataforma por ejecución; pagas directamente los tokens a tu propio proveedor.

Crédito de IA gratis. Cada cuenta recibe un saldo mensual de crédito de IA gratis (por defecto, 5 USD/mes) que solo pueden gastar las ejecuciones de agentes de IA. Es independiente de tu cartera de mensajería, por lo que SMS, WhatsApp y email nunca lo consumen. Cada ejecución gasta primero el crédito gratis y luego usa tu cartera de pago cuando se agota. El crédito se restablece al inicio de cada mes (úsalo o piérdelo) y su saldo se muestra en Configuración → Uso. Las ejecuciones de prueba y vista previa siempre son gratis, independientemente del crédito.

Los cargos son idempotentes por ID de ejecución, por lo que un paso de recorrido reintentado nunca se cobra dos veces. Los recuentos de tokens y el coste interno se registran en cada ejecución para tus informes de uso.

Límites de gasto. Cada agente tiene su propio límite diario de ejecuciones, y tu cuenta tiene un límite diario de ejecuciones de IA para toda la cuenta que abarca todos los agentes y espacios de trabajo. Joryio puede ajustar por cuenta tanto el crédito gratis como el límite de la cuenta; contáctanos si necesitas más margen.

Historial de ejecuciones​

Cada ejecución queda registrada y se puede consultar en la pantalla Historial de ejecuciones del propio agente. Ábrela con el botón Ejecuciones del agente en la lista (es una página dedicada, no está oculta en el editor de configuración). Cada ejecución se puede expandir y muestra:

  • el resultado, cualquier motivo de error, la latencia y el coste;
  • la entrada que vio el modelo, el prompt exacto (instrucciones de sistema + contexto seleccionado ya enmascarado);
  • la salida devuelta y la explicación opcional.

Ver la entrada real junto a la salida es la forma más rápida de depurar y mejorar un agente: si la respuesta es incorrecta, la entrada suele indicar el motivo (por ejemplo, que la instrucción hacía referencia a un campo que no expusiste). También puedes obtener ejecuciones mediante el endpoint de ejecuciones.

Gobierno de datos​

  • La PII es voluntaria. Un agente solo ve los atributos, segmentos y campos que seleccionas explícitamente. Por defecto no llega al modelo nada sobre un contacto.
  • Enmascaramiento global de PII. Marca un atributo una vez como PII en Atributos personalizados y se oculta automáticamente antes de que el contexto llegue al modelo, en todos los agentes; no tienes que seleccionarlo de nuevo para cada agente.
  • La entrada se almacena enmascarada para inspección. Para que puedas depurar y mejorar agentes, cada ejecución guarda el prompt que vio el modelo (sistema + contexto), después de enmascarar PII y con un tamaño limitado. Nunca contiene valores que hayas marcado como PII. Esto alimenta el historial de ejecuciones anterior.
  • Aislamiento del espacio de trabajo. Un agente solo puede leer el espacio de trabajo en el que se ejecuta, y las claves BYO viven en una bóveda cifrada por espacio de trabajo; la API nunca devuelve sus valores secretos.

Siguientes pasos​