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 → IA → 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.

Usar tu clave para el asistente y la generación de contenido​

Las claves de proveedor no son solo para los agentes. En la pestaña Claves de proveedor, cada clave guardada tiene un interruptor, Usar para el asistente y la generación de contenido. Actívalo en una clave y el asistente de Joryio de este espacio de trabajo y todas las funciones de contenido con IA (asuntos, texto del mensaje, voz de marca, variantes de secciones) funcionan con tu propia cuenta en lugar de la clave de plataforma de Joryio. Solo una clave por espacio de trabajo puede llevar el interruptor; activarlo en una segunda clave lo mueve.

  • Qué cambia. Los prompts van a tu proveedor bajo tu contrato; pagas al proveedor por los tokens. Joryio cobra una pequeña tarifa de plataforma por uso (por generación, por turno del asistente) de tu monedero, igual que se cobran las ejecuciones de agentes con tu propia clave, y el presupuesto mensual de IA de la clave de plataforma deja de aplicarse a estas llamadas. El crédito de IA gratuito se usa antes que el monedero.
  • Qué proveedores. La generación de contenido funciona con todos los proveedores compatibles: Anthropic, OpenAI, Google (Gemini), Azure OpenAI y AWS Bedrock. El asistente necesita la API de uso de herramientas de Anthropic, así que funciona con tu clave solo cuando es una clave de Anthropic; con cualquier otro proveedor el asistente se queda en la clave de plataforma de Joryio y solo se enruta la generación de contenido.
  • Si la clave deja de funcionar. Una clave desactivada, inválida o incompleta hace que estas funciones fallen con un mensaje claro: nunca vuelven en silencio a la clave de Joryio, porque eso enviaría tus prompts a un proveedor que no elegiste y los facturaría de otra forma. Corrige la clave o desactiva el interruptor.
  • Cuando tu proveedor rechaza la clave. Si tu cuenta del proveedor se queda sin créditos, la función muestra "La clave de tu proveedor de IA no tiene créditos"; si el proveedor rechaza la clave, muestra "Se rechazó la clave de tu proveedor de IA". Ambos mensajes remiten a Agentes de IA → Claves de proveedor: añade créditos en tu proveedor o actualiza la clave.
  • Cuando la IA no está disponible con la clave de Joryio. Si la IA está caída o sobrecargada del lado de Joryio, las funciones de IA muestran "La IA no está disponible temporalmente - inténtalo de nuevo más tarde" (o "La IA está ocupada ahora mismo - inténtalo de nuevo en un minuto" con mucha carga). No hay nada que cambiar en tu espacio de trabajo; Joryio recibe un aviso y las funciones se recuperan solas.

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.
  • error: una rama para cualquier fallo (timeout, rate_limited, invalid_config, budget_exceeded, error del proveedor). El nodo muestra un único borde de Error; la clase y el motivo se escriben junto a la salida como {{ agent.<var>_outcome }} y {{ agent.<var>_error }}, así que un nodo Rama posterior puede seguir enrutando por el porqué cuando lo necesites. Un Error sin conectar continúa en fallback. Un recorrido guardado antes de este cambio con una rama por clase sigue funcionando: la rama específica se respeta primero.

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. Una cuenta del proveedor sin créditos no es un límite de tasa: la ejecución termina en error y no se reintenta, porque reintentar no puede funcionar hasta que se añadan créditos.

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. Lo mismo se aplica por generación y por turno del asistente cuando una clave está activada para el asistente y la generación de contenido.

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.

Clasificar: enrutar un recorrido por etiqueta​

Un agente tiene una tarea: Escribir (el agente de hoy - texto libre o una estructura JSON, guardada en una variable del recorrido) o Clasificar. Un agente de clasificación elige una etiqueta de una lista que tú defines, y su nodo de recorrido recibe una rama por etiqueta más No seguro. Nunca eliges un motor; Joryio lo elige y muestra lo que cuesta una ejecución junto a la tarea.

Para crear uno, elige Clasificar en el editor y añade tus etiquetas: un nombre que reconozcas y una descripción de una línea de cuándo elegirla. Los ids se asignan al guardar y se mantienen al renombrar, así que una etiqueta renombrada conserva su rama. No seguro por debajo de la confianza (por defecto 0,6) es el umbral bajo el cual una respuesta toma la rama "No seguro" en lugar de una etiqueta; una respuesta fuera de tu lista también es "No seguro", nunca un error.

En el lienzo, elige el agente en el nodo Agente de IA: el nodo muestra una rama por etiqueta, la rama "No seguro" y los resultados de error. Conecta cada una al siguiente paso; una rama sin conectar pasa al siguiente paso por defecto. Si más tarde cambias las etiquetas del agente, el nodo lo indica - vuelve a elegir el agente para refrescar las ramas y reconecta cualquier etiqueta que se haya movido. La etiqueta elegida y su confianza también se guardan en la variable de salida ({{ agent.<var>.label }}).

Cada ejecución se factura a la tarifa de Clasificación, más baja que una ejecución de escritura, y registra el conjunto de etiquetas con el que respondió, así que las ejecuciones antiguas conservan su significado cuando cambias la lista. Los datos personales de la entrada - un mensaje entrante, una respuesta de texto libre, un atributo de perfil - se leen solo a través de los selectores de contexto que actives, igual que en cualquier agente.

Siguientes pasos​