Agente de IA externo

Conecta un agente de IA que ya vive fuera de Jelou como un nodo de tu flujo.

El nodo Agente de IA externo conecta a tu flujo un agente de IA que ya vive fuera de Jelou. Jelou mantiene el canal, la seguridad y el registro de cada turno; tu agente decide la respuesta.

​

Cómo agregar el nodo

Ambos tipos de agente de IA se agregan desde el mismo punto de entrada: el ítem AI Agent en la barra de herramientas del builder. Su comportamiento cambia según cómo lo uses:

• Clic: agrega un nodo AI Agent normal: el agente de IA de Jelou.
• Mantener el cursor encima (hover): abre un selector de proveedores de agentes de IA externos. Al elegir un proveedor, Jelou agrega un nodo Agente de IA externo preconfigurado para ese proveedor.

Una vez agregado, el nodo Agente de IA externo se conecta al resto de tu flujo por sus cuatro salidas, igual que cualquier otro nodo:

​

AI Agent o agente de IA externo

Elige según dónde viva el agente. Para construirlo dentro de Jelou, usa el nodo AI Agent (guía general).

	AI Agent	Agente de IA externo
El agente	Lo construyes y ajustas en Jelou.	Ya existe y está en producción fuera de Jelou.
Dónde vive la lógica	En el prompt y las tools del nodo.	En tu sistema o el de tu proveedor.
Modelo	Lo eliges en el nodo.	Lo define tu agente; el nodo no lo conoce.
Cambios	Los haces en el builder.	Los haces en tu plataforma; en Jelou solo actualizas la conexión.
Seguridad	Jelou revisa las respuestas del modelo.	Tu agente aplica la suya; Jelou también revisa sus respuestas.

​

Proveedores disponibles

Cada proveedor pide sus propios campos, tomados directamente de su consola, y valida mientras escribes. Las credenciales se seleccionan por el nombre del secreto de la organización que las guarda; el valor del secreto nunca se muestra ni se guarda en el flujo.

Proveedor	Qué necesitas en Jelou	Autenticación	Dónde lo encuentras
Amazon Bedrock Agents	Región de AWS, ID del agente y ID del alias (hasta 10 letras y números cada uno)	Rol de AWS IAM (lo asume Jelou) o claves de acceso de AWS	Bedrock → Agents → tu agente: el ID del agente y el ID del alias aparecen en la vista general; la región es la de tu consola de AWS.
Amazon Bedrock AgentCore	ARN del runtime, protocolo del runtime (HTTP o A2A) y, opcional, calificador del endpoint	Rol de AWS IAM, claves de acceso de AWS, credenciales de cliente OAuth2 o token Bearer	Bedrock AgentCore → Runtimes → tu runtime: el ARN completo y el protocolo (serverProtocol) aparecen en su detalle.
Microsoft Copilot Studio	URL regional de Direct Line y endpoint del token (ambos opcionales)	Secreto de Direct Line o ninguna	Copilot Studio → tu agente → Canales: el endpoint del token es el del canal App móvil; la URL regional de Direct Line está en regionalchannelsettings.
Azure AI Foundry	Endpoint del proyecto y la API de agentes. Con la API nueva, el nombre del agente (y su versión, opcional); con la clásica, el ID del asistente (asst_...)	Credenciales de cliente OAuth2 o token Bearer	AI Foundry → tu proyecto → Overview: el endpoint del proyecto. La API clásica se retira en marzo de 2027.
Google Agent Runtime (ADK) (antes Agent Engine)	Nombre del recurso del agente	Cuenta de servicio de Google	Vertex AI → Agent Engine → tu agente: el nombre completo del recurso (projects/.../locations/.../reasoningEngines/...). Solo para agentes ADK; los que se despliegan con la plantilla A2A usan el proveedor A2A.
Google Dialogflow CX	Nombre del agente, código de idioma y, opcional, entorno	Cuenta de servicio de Google	Dialogflow CX → tu agente → configuración: el nombre completo (projects/.../locations/.../agents/...). El código de idioma es el predeterminado del nodo.
Claude Managed Agents	ID del agente (agent_...), ID del entorno (env_...) y, opcional, versión del agente	API key en el header x-api-key	Consola de Claude Managed Agents: los IDs del agente y del entorno que publicaste.
Salesforce Agentforce	ID del agente (18 caracteres, empieza con 0Xx) y URL de My Domain	Credenciales de cliente OAuth2	Setup → Agentforce Agents: el Id del BotDefinition. La URL debe ser la de My Domain (https://tuorg.my.salesforce.com), nunca la de lightning.force.com. Los agentes de tipo “Agentforce (Default)” no son compatibles.
OpenAI Responses API (prompt guardado)	ID del prompt (pmpt_...) y, opcional, versión del prompt, organización (org-...), proyecto (proj_...) y URL base	Token Bearer	Plataforma de OpenAI → Prompts: el ID del prompt reutilizable que empaqueta instrucciones, modelo y herramientas. Usa la Responses API con un prompt guardado. OpenAI deja de ofrecer los objetos de prompt reutilizables el 30 de noviembre de 2026 (guía de migración de OpenAI). Para los agentes guardados de la API de Agents de OpenAI (agent_...), usa OpenAI Agents (beta) (fila siguiente).
OpenAI Agents (beta)	ID del agente (agent_...) y, opcional, entorno de ejecución, organización (org-...), proyecto (proj_...) y URL base	Token Bearer	Plataforma de OpenAI → Agents: el ID del agente guardado. La API de Agents está en beta. Ver OpenAI Agents (beta).
LangGraph Platform	URL del deployment e ID del assistant	API key en el header x-api-key	LangSmith Deployments → tu deployment: la URL y el ID del assistant (UUID recomendado, o el nombre del grafo).
Dify (preconfigurado sobre HTTP personalizado)	La URL ya viene con https://api.dify.ai/v1/chat-messages; cámbiala si tu Dify es propio	Token Bearer con la API key de tu app	Dify → tu app → API Access. Jelou envía query, conversation_id y user, y lee answer y conversation_id de la respuesta.
n8n (preconfigurado sobre HTTP personalizado)	URL del webhook	Ninguna (puedes cambiarla)	n8n → tu workflow → nodo Webhook: la URL de producción. Jelou envía message y sessionId, y lee output de la respuesta.
A2A (Agent2Agent 1.0)	URL del Agent Card	API key en un header, token Bearer, credenciales de cliente OAuth2, cuenta de servicio de Google o ninguna	El servidor de tu agente A2A: la URL donde publica su Agent Card (.well-known/agent-card.json). Solo A2A 1.0 por JSON-RPC.
HTTP (contrato de turno de Jelou)	URL del agente	API key en un header, token Bearer, credenciales de cliente OAuth2 o ninguna	Tu propio servidor: un endpoint que implementa el contrato de turno de Jelou (ver el contrato).
HTTP personalizado	URL del agente, cuerpo de la solicitud y rutas de la respuesta	API key en un header, token Bearer, credenciales de cliente OAuth2 o ninguna	Tu propio servidor: cualquier endpoint que reciba JSON, aunque no hable el contrato de turno de Jelou.

Amazon Bedrock Agents ya figura en AWS como “Agents Classic” y AWS recomienda AgentCore para agentes nuevos. Con Amazon Bedrock AgentCore en modo HTTP, Jelou envía su cuerpo de turno completo (ver el contrato), así que tu handler debe leerlo; en modo A2A el runtime puede publicar un Agent Card A2A 1.0 o 0.3 (el que publican los runtimes creados con el extra por defecto del SDK de AgentCore).

​

Comportamiento por proveedor

Estos detalles explican qué salida toma el nodo en los casos que cada proveedor trata de forma particular. Recuerda que Pide más información solo existe en una tarea; en varios turnos el nodo entrega el mensaje y espera al usuario.

• Amazon Bedrock Agents: si el agente pide una acción de retorno de control (return of control), el nodo toma Pide más información. El resultado de esa acción viaja al agente en el siguiente turno, junto con el identificador de la invocación, y el agente continúa. Se admite una sola acción por turno; si el agente pide varias a la vez, el turno falla.
• Amazon Bedrock AgentCore: en modo A2A se aceptan Agent Cards 1.0 y 0.3. El calificador del endpoint se aplica al Agent Card y a las llamadas, y Jelou mantiene el mismo identificador de sesión del runtime durante toda la conversación para que los turnos lleguen a la misma sesión. En modo HTTP, si el runtime informa un error dentro de la propia respuesta (error, error_type y message), el turno falla con ese motivo.
• Claude Managed Agents: Jelou lee la sesión por streaming hasta que el agente queda inactivo. Si el agente se detiene esperando el resultado de una herramienta, el nodo toma Pide más información. Si el agente agota sus reintentos, el turno falla y se puede reintentar; si alcanza su presupuesto o el modelo se niega a responder, falla sin reintento; si la sesión termina, falla porque el agente ya no está activo. Un error pasajero que el propio agente está reintentando no corta el turno. La versión fijada del agente es un número entero de 1 en adelante.
• Salesforce Agentforce: cada mensaje se interpreta por su tipo. Inform es texto para el usuario. Inquire y Confirm también se entregan como texto y, en una tarea, el nodo toma Pide más información. Escalate toma Derivar a operador, SessionEnded termina la conversación, y Failure o Error hacen fallar el turno con el motivo que informa Salesforce, sin reintento.
• LangGraph Platform: si el grafo se detiene con una interrupción, el nodo toma Pide más información y tu respuesta reanuda el grafo. Cuando hay varias interrupciones pendientes a la vez, Jelou reanuda la primera indicando su ID. Un error que el grafo devuelve dentro de una respuesta exitosa hace fallar el turno con su motivo.
• Microsoft Copilot Studio: Jelou entrega solo las actividades del bot y descarta el eco del mensaje del propio usuario.
• Azure AI Foundry: si la respuesta llega con estado fallido, cancelado o incompleto, o con un error aunque el HTTP sea 200, el turno falla con el motivo que informa Foundry. Una respuesta incompleta por el filtro de contenido se trata como rechazada y no se reintenta; un error rate_limit_exceeded o server_error sí se reintenta. Con la API clásica, el motivo sale del campo last_error de la ejecución.

​

OpenAI Agents (beta)

El proveedor OpenAI Agents (beta) conecta un agente guardado en la plataforma de OpenAI mediante su API de Agents, que está en beta. Es distinto de OpenAI Responses API (prompt guardado), que usa un prompt reutilizable (pmpt_...) y que OpenAI deja de ofrecer el 30 de noviembre de 2026; para agentes nuevos, usa OpenAI Agents.

Campo	Qué poner
ID del agente (obligatorio)	El ID del agente guardado en la plataforma de OpenAI. Empieza con agent_.
Entorno	Sin entorno (por defecto) es para agentes de chat sin sandbox; la búsqueda web alojada funciona. Elige Alojado por OpenAI solo si el agente ejecuta código, archivos o un navegador. El entorno autoalojado no es compatible.
Organización	org-.... Solo si tu API key pertenece a varias organizaciones.
Proyecto	proj_.... Solo si tu API key no está limitada al proyecto del agente.
URL base	https:// obligatorio. Por defecto, https://api.openai.com/v1.

Autenticación: token Bearer. Elige el secreto de la organización que guarda tu API key de OpenAI; la key debe pertenecer al proyecto dueño del agente. Si es una key restringida, necesita los permisos api.agents.read y api.agents.write.

Cómo funciona un turno:

1. Jelou crea una sesión con el agente guardado y le envía el mensaje.
2. Consulta el turno hasta que termina, dentro del tiempo límite por turno, y entrega el texto de la respuesta final del agente.
3. En una tarea, la sesión se elimina al terminar. En varios turnos, Jelou conserva la sesión y envía cada mensaje del usuario como un mensaje nuevo en ella.

Casos particulares:

• Si el agente llama a una función de tu lado, en una tarea el nodo toma Pide más información, y tu resultado vuelve al agente como resultado de la herramienta.
• Si el agente pide una aprobación de uso del computador o la reconexión de un entorno, el turno falla como rechazado con un mensaje legible, porque un chat no puede responderlo.
• Si el turno no termina dentro del tiempo límite, el nodo toma Hubo un error y Jelou intenta cancelar el turno.
• Los límites de uso, de gasto, de facturación y las políticas de OpenAI hacen fallar el turno sin reintento; una sobrecarga o un límite de frecuencia sí se reintentan.

​

Pestañas del nodo

El panel del nodo tiene cuatro pestañas y, si tu empresa tiene habilitadas las métricas de eventos, una quinta, Eventos:

• Conexión: el tipo de conexión, la URL o los campos del proveedor, los headers fijos, la Instrucción que se envía al agente (por defecto {{$message.text}}), los Datos que envías y la Interacción (una tarea o varios turnos).
• Autenticación: el tipo de autenticación, el secreto de la organización, el certificado mTLS y la firma HMAC.
• Transformar: los scripts previo y posterior y, según el proveedor, la forma de la solicitud y de la respuesta.
• Avanzado: la variable de respuesta, el tiempo límite por turno, los intentos y, en varios turnos, la inactividad de la sesión y el comando de reinicio.

El botón Probar conexión está al pie de todas las pestañas.

​

Eventos y condiciones de evaluación

La pestaña Eventos tiene las mismas dos secciones que el AI Agent: Configuración de eventos y Condiciones de evaluación. Solo aparece si tu empresa tiene habilitadas las métricas de eventos.

Las condiciones de evaluación miden los resultados de la conversación con el agente externo. Defines con un prompt qué debe cumplirse; cuando la conversación termina con éxito, Jelou analiza el historial (lo que dijo el usuario y lo que respondió el agente) contra cada condición activa. Por cada condición que se cumple, se dispara un evento con su nombre, listo para analizarse en Métricas.

• Una tarea: la conversación se evalúa cuando el agente completa la tarea.
• Varios turnos: se evalúa cuando el agente da por terminada la conversación, con todos los turnos desde el inicio.
• Si el turno falla, no se evalúa nada.
• Un nodo sin condiciones activas se comporta exactamente igual que antes y no guarda ninguna conversación para evaluar.

Los campos, los límites (hasta 10 condiciones por nodo) y el toggle de cada condición funcionan igual que en el AI Agent. La evaluación usa el modelo por defecto de la plataforma y se factura como las evaluaciones del AI Agent.

Ver la guía de condiciones de evaluación del AI Agent Ver guía completa de eventos de nodo

​

Una tarea o varios turnos

Al configurar el nodo eliges cómo interactúa con tu agente:

• Una tarea: el nodo envía la tarea una vez, recibe la respuesta y sale del nodo.
• Varios turnos: el nodo mantiene la conversación con el agente, mensaje a mensaje, hasta que el agente la termine o la derive. Mientras el agente responde sin terminar la conversación, el nodo no toma ninguna salida: envía los mensajes al usuario y espera su siguiente mensaje para continuar con el agente.

​

Ejemplo: una tarea

Usuario:  Quiero saber el estado de mi pedido EJ-48213
Agente:   Tu pedido EJ-48213 está en camino y llega mañana antes de las 18:00.

El nodo recibe la respuesta, la entrega al usuario y sale por Respondió. No hay una segunda vuelta con el agente: cualquier mensaje posterior del usuario ya no pasa por este nodo.

​

Ejemplo: varios turnos

Usuario:  Quiero un reembolso de mi última compra
Agente:   Claro, para verificar tu solicitud de reembolso necesito el número
          de pedido. ¿Podrías compartirlo?

[el nodo entrega el mensaje al usuario y espera su respuesta]

Usuario:  Mi número de pedido es EJ-48213
Agente:   Listo, encontré tu pedido EJ-48213. El reembolso de $45.00 fue
          aprobado y se verá reflejado en 3 a 5 días hábiles.

El nodo permanece activo entre el primer y el segundo mensaje: no toma ninguna salida hasta que el agente da por terminada la conversación. Recién ahí sale por Respondió.

​

Salidas del nodo

El nodo Agente de IA externo tiene cuatro salidas:

Salida	Se activa cuando
Respondió	En una tarea, el agente respondió. En varios turnos, el agente terminó la conversación.
Pide más información	Solo en una tarea: el agente se detuvo a esperar una acción o un dato adicional. En varios turnos esto se trata como una respuesta normal y el nodo sigue esperando al usuario; no es una salida en ese modo.
Derivar a operador	El agente pidió pasar la conversación a un humano, después de entregar sus mensajes.
Hubo un error	El agente falló, rechazó la credencial, devolvió una respuesta inválida, o la sesión expiró por tiempo de espera.

Conecta cada salida a lo que deba pasar en tu flujo. Un patrón típico:

• Respondió → el mensaje del agente ya se entregó; continúa el flujo o termínalo.
• Pide más información → un nodo de pregunta que recoge el dato faltante y vuelve a llamar al agente.
• Derivar a operador → tu nodo de transferencia a la Bandeja de entrada.
• Hubo un error → un mensaje de disculpa y, si aplica, un reintento o una derivación a un operador.

​

La variable de respuesta

El mensaje del agente se entrega al usuario directamente. Los datos estructurados que el agente devuelve, por ejemplo con una señal variables_set o con la ruta de datos del HTTP personalizado, se guardan en la memoria del flujo bajo la variable que defines en la tarjeta Guardar respuesta de la pestaña Avanzado (por defecto agentReply; en el canvas aparece como “Guardar la respuesta en”). Luego puedes leer cada dato en nodos posteriores, por ejemplo {{$memory.agentReply.ticket}} en un nodo de mensaje o en una condición.

Si no necesitas esos datos en el flujo, apaga el interruptor de Guardar respuesta: el nodo no escribe nada en la memoria, el mensaje del agente se entrega igual y las salidas funcionan igual. Los nodos que ya existían siguen con el interruptor encendido.

Si el agente no devuelve datos estructurados, la variable queda vacía: el texto de la respuesta no se guarda en ella.

​

Autenticación y secretos de la organización

Cada proveedor admite uno o varios esquemas de credencial, según lo que su API acepta:

Esquema	Qué guarda el secreto
api_key_header	Un valor que se envía en un header con nombre configurable.
bearer	Un token que se envía como Authorization: Bearer ....
oauth2_client_credentials	El client secret; Jelou intercambia un token con tu endpoint OAuth2 antes de cada llamada (o reutiliza uno vigente). Si tu agente rechaza el token con un 401 o un 403, Jelou lo descarta y pide uno nuevo en el siguiente turno, así que una rotación o una revocación no deja al nodo fallando hasta que el token venza.
aws_sigv4_keys	Un objeto JSON {accessKeyId, secretAccessKey, sessionToken?}; Jelou firma la solicitud con SigV4.
aws_sigv4_role	No guarda una clave: Jelou asume el rol de AWS que indiques, usando un external id guardado como secreto.
google_service_account	La clave JSON completa de la cuenta de servicio.
direct_line_secret	El secreto de canal Direct Line de Copilot Studio.
mtls	Se combina con el certificado mTLS de tu empresa (ver más abajo); es independiente del resto de esquemas.
none	Sin credencial; solo válido cuando tu agente no exige autenticación.

En todos los casos, el nodo guarda solo el nombre del secreto de la organización, nunca su valor. El secreto se resuelve en el momento de la llamada y nunca se muestra ni se guarda en el flujo.

​

Opciones avanzadas para HTTP personalizado

Cuando tu agente usa HTTP (contrato de turno de Jelou) o HTTP personalizado, dispones de opciones adicionales. Se configuran en las pestañas Conexión (headers fijos), Autenticación (OAuth, certificado mTLS y firma HMAC), Transformar (scripts) y Avanzado (reintentos y tiempo límite):

Opción	Para qué sirve
Firma de solicitud (HMAC)	Firma cada solicitud con un secreto compartido, para que tu agente verifique que viene de Jelou.
Headers estáticos	Agrega headers fijos que tu agente espera en cada llamada. No se permiten headers sensibles como authorization, cookie, host o x-jelou-signature, ni referencias a secretos de la organización. El valor puede usar variables de Jelou (por ejemplo {{$memory.tenant}}), que se resuelven antes de cada llamada; si una variable queda vacía, el turno falla con un error claro. Máximo 10 headers, de hasta 256 caracteres cada uno. Las variables en headers no se usan en la prueba de conexión ni cuando el agente se usa como herramienta de un Agente de IA.
Scripts previos y posteriores	Ejecuta un script antes de enviar la solicitud o después de recibir la respuesta, en el mismo entorno seguro que usa el nodo API. Se configuran en la pestaña Transformar (ver más abajo).
OAuth	Autenticación mediante credenciales de cliente OAuth2.
mTLS	TLS mutuo con el certificado de cliente de tu empresa, independiente de la credencial: puedes combinar OAuth y mTLS a la vez.
Reintentos	Hasta 3 intentos; solo se reintentan tiempos de espera, límites de uso y errores del servidor, nunca una solicitud rechazada.
Tiempo límite por turno	Cuánto espera el nodo la respuesta del agente antes de tomar la salida de error. Por defecto 25 segundos, hasta un máximo de 120 segundos.
Inactividad de la sesión	Solo en varios turnos: la sesión con el agente se olvida tras este tiempo sin actividad (de 60 a 86400 segundos; 3600 por defecto).
Comando de reinicio	Mensaje del usuario (por defecto /reset) con el que la conversación con el agente empieza de nuevo.

La firma HMAC, los headers estáticos y mTLS están disponibles sin un plan especial (para mTLS, primero registra un certificado de cliente en Jelou). Los scripts previos y posteriores dependen de una opción que Jelou activa por empresa: si la pestaña Transformar muestra que no están disponibles, pide a tu ejecutivo de Jelou que los active.

​

Firma HMAC: qué se firma y cómo verificarla

Cuando activas la firma de solicitud, Jelou calcula un HMAC-SHA256 sobre el cuerpo exacto de la solicitud (los mismos bytes que se envían) usando el secreto que elijas, y lo envía en un header:

Campo	Valor por defecto	Notas
Header	X-Jelou-Signature	Configurable.
Codificación	Hexadecimal	También admite Base64.
Qué se firma	Solo el cuerpo (body)	También admite timestamp.body, que firma "{timestamp}.{body}" y agrega el timestamp Unix en un segundo header que tú nombras.

Tu propio servidor puede verificar la firma así (Node.js, usando solo el cuerpo):

const crypto = require("crypto");

function isValidJelouSignature(rawBody, signatureHeader, sharedSecret) {
  const expected = crypto
    .createHmac("sha256", sharedSecret)
    .update(rawBody, "utf8")
    .digest("hex");
  const a = Buffer.from(signatureHeader || "", "utf8");
  const b = Buffer.from(expected, "utf8");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// rawBody debe ser el cuerpo crudo tal como llegó, antes de parsear el JSON
const valid = isValidJelouSignature(rawBody, req.headers["x-jelou-signature"], SHARED_SECRET);

Verifica siempre sobre el cuerpo crudo de la solicitud, antes de que tu framework lo parsee a JSON. Volver a serializar el JSON parseado puede cambiar el orden de las propiedades o el espaciado y hacer que la firma no coincida aunque el contenido sea el mismo.

El campo Instrucción (pestaña Conexión) acepta variables. Para enviar al agente el mensaje del usuario, usa {{$message.text}}: contiene el texto del mensaje que llegó al flujo. {{$input.message}} no es una variable de mensaje: $input solo guarda los datos que tu flujo recolectó (por ejemplo, con un nodo Input), así que sale vacío cuando el nodo se ejecuta desde un mensaje de chat.

​

Scripts previos y posteriores

Los scripts corren en el mismo entorno seguro (sandbox) que usa el nodo API. Se configuran en la pestaña Transformar del nodo, en dos subpestañas: Jelou → Tu agente (script previo) y Tu agente → Jelou (script posterior). Qué puede cambiar cada script depende del proveedor:

Proveedores	Script previo	Script posterior
HTTP (contrato de turno de Jelou) y HTTP personalizado	Puede modificar agentRequest.body y agentRequest.headers antes de enviar la solicitud.	Debe dejar en agentResponse.body el objeto que lee el mapeo de la respuesta.
Todos los demás proveedores	Lee y modifica solo agentRequest.body.text, el mensaje que se envía al agente. Los headers y los demás campos se ignoran.	Corre solo en respuestas completadas. Lee agentResponse.body.text y agentResponse.body.variables; puede reemplazar el texto y agregar o sobrescribir variables.

En todos los casos, un texto vacío o sin cambios conserva el original, y un error del script hace fallar el turno.

Script previo con proveedores HTTP: $context.get("agentRequest") contiene { task, sessionId, body, headers }. Por ejemplo, para envolver el cuerpo en un sobre propio de tu empresa:

const request = $context.get("agentRequest");

$context.set("agentRequest.body", {
  header: {
    canal: "whatsapp",
    empresa: "Banco Ejemplo",
  },
  data: request.body,
});

Script posterior con proveedores HTTP: $context.get("agentResponse") contiene { status, body }. El script debe dejar en agentResponse.body el objeto que luego lee el mapeo de la respuesta (las rutas textPath, dataPath, sessionIdPath, etc.).

const response = $context.get("agentResponse");

$context.set("agentResponse.body", response.body.data);

Un error que lanza el script hace fallar el turno por la salida Hubo un error del nodo. Los cambios del script nunca tocan las variables propias del flujo: solo modifican lo que Jelou envía o lee para esta llamada.

​

Responder después (confirma y responde después)

Algunos agentes externos no contestan dentro de la misma llamada: confirman que recibieron el mensaje y envían su respuesta más tarde, por su cuenta. Para ese caso, el nodo Agente de IA externo tiene un modo opcional. Viene desactivado, así que un nodo existente se comporta exactamente igual que antes.

El campo Cómo responde el agente aparece en la pestaña Transformar, subpestaña Tu agente → Jelou, cuando el tipo de conexión es HTTP (contrato de turno de Jelou) o HTTP personalizado y la interacción es Varios turnos. Tiene dos opciones:

• En la misma respuesta (por defecto): el agente responde dentro de la misma llamada, como hasta ahora.
• Confirma y responde después: el agente confirma con cualquier respuesta 2xx. Jelou no entrega nada del cuerpo de la confirmación y deja el nodo esperando el siguiente mensaje del usuario, con el mismo tiempo de inactividad de la sesión. Ese mensaje se reenvía al agente dentro de la misma ejecución.

Con HTTP personalizado, en este modo ya no es obligatoria la Ruta del texto de respuesta, porque no se entrega ningún texto del cuerpo.

​

Cuándo termina la conversación

En la misma subpestaña, estos dos campos opcionales aparecen solo en este modo:

• Campo que termina la conversación: la ruta del campo en el cuerpo de la confirmación, por ejemplo status, data.state o items[0].s (máximo 200 caracteres).
• Valores que terminan la conversación: de 1 a 20 valores distintos, separados por comas. Acepta texto, números enteros y verdadero o falso. Cuando el campo trae uno de ellos, la conversación termina y el flujo sigue por la salida Respondió.

​

Salidas que debes conectar

• Conecta siempre la salida Hubo un error: es la que toma el nodo cuando vence la espera sin que el usuario escriba. Sin esa conexión no podrás publicar el flujo.
• Conecta la salida Respondió solo si definiste el campo que termina la conversación. Sin esos campos no se usa.
• La salida Derivar a operador no es obligatoria.

El nodo muestra un aviso en el lienzo mientras falte una de las conexiones necesarias.

Cuando la espera vence, el flujo sigue por Hubo un error y Jelou no le envía ningún mensaje al usuario. Conecta esa salida a un Fin silencioso, sin mensaje de error.

​

No respondas después del límite de tiempo

Si tu agente confirma tarde y el nodo ya venció, el flujo sigue por Hubo un error y puede enviar su mensaje de respaldo. Si tu agente igual publica su respuesta después, el usuario recibe las dos. Jelou no puede retirar un mensaje que tu agente ya envió por la API de envío, así que la regla es del lado del agente: no envíes la respuesta cuando ya pasó el límite del turno.

Para saber cuándo vence, depende de cómo se conecta tu agente:

• Con HTTP personalizado, el script previo (pestaña Transformar) recibe agentRequest.turn con turnId, inputId, deadlineMs y expiresAt (hora absoluta en formato ISO). Pásalo en el cuerpo para que tu agente lo vea:

const request = $context.get("agentRequest");

$context.set("agentRequest.body", { ...request.body, reply_by: request.turn.expiresAt });

Tu agente compara la hora actual con reply_by antes de enviar y, si ya pasó, descarta la respuesta. Los nodos cuyo script no lee turn se comportan igual que antes.

• Con HTTP (contrato de turno de Jelou), la solicitud ya trae turnId, inputId y deadlineMs en el cuerpo. deadlineMs son los milisegundos que el nodo espera desde que envía la solicitud, no una hora absoluta: calcula el límite sumándolos a la hora en que tu agente recibe el mensaje.

​

Acciones: el agente elige la salida

Con HTTP personalizado de varios turnos, o con HTTP (contrato de turno de Jelou) en el modo Confirma y responde después, tu agente puede decidir por dónde sigue el flujo. En la subpestaña Tu agente → Jelou de la pestaña Transformar, la sección Acciones (salidas adicionales) te deja declarar hasta 12 acciones, por ejemplo login o ejecutar_prestamo. Cada acción agrega una salida propia al nodo, Acción: login, Acción: ejecutar_prestamo, y el flujo sigue por ella en la misma ejecución, sin esperar al usuario.

• Nombre de la acción: minúsculas, números y guion bajo, hasta 32 caracteres, sin repetir.
• Campo con el nombre de la acción: la ruta en la respuesta de tu agente que trae el nombre. Por defecto es action.
• Campo con los datos de la acción (opcional): la ruta de un valor que quieres usar en la rama. Se guarda junto al nombre en la variable de respuesta como actionData.

Por ejemplo, con la ruta result.action y la ruta de datos result.data, esta respuesta de tu agente toma la salida Acción: ejecutar_prestamo:

{ "result": { "action": "ejecutar_prestamo", "data": { "monto": 1500 } } }

En la rama, la variable de respuesta trae action con el nombre y actionData con { "monto": 1500 }.

• Un campo vacío o ausente no es una acción: el turno sigue como siempre.
• Un nombre que no está en la lista hace fallar el turno y el flujo sigue por Hubo un error.
• Conecta cada acción a un nodo: el nodo muestra un aviso en el lienzo mientras falte. Si quitas una acción, sus conexiones se eliminan.
• Cuando la rama termina y vuelve al nodo, el nodo espera el siguiente mensaje del usuario y lo reenvía al agente en la misma ejecución.

​

Mensajes que no son texto

Cuando el usuario envía una imagen, un audio, un documento, una respuesta de WhatsApp Flow, un botón, una lista o una ubicación, el agente ya no recibe una tarea vacía. La tarea llega como [tipo] descripción (o solo [tipo]), y la solicitud incluye un objeto input.inbound con el tipo, el texto, la descripción, el tipo de archivo y el id del mensaje.

Los datos sensibles no se envían por defecto. En la pestaña Conexión, el campo Datos que envías te deja elegir cuáles agregar:

• URL del archivo
• Respuesta de botón o lista
• Respuesta de WhatsApp Flow
• Ubicación

Marca solo los que tu agente necesita: pueden contener información personal. Esto aplica a cualquier tipo de conexión. El texto simple y los botones con título se envían igual que antes.

​

Prefijo de la firma

Algunos agentes esperan la firma HMAC con un texto delante, por ejemplo sha256= seguido del valor. En la pestaña Autenticación, en Firmar las solicitudes, el campo Prefijo de la firma (ej. sha256=) agrega ese texto literal antes del valor de la firma. Acepta de 1 a 32 caracteres: letras, números y _ = . : / + -; no admite espacios ni plantillas. El header de la marca de tiempo nunca lleva prefijo. Se aplica a HTTP (contrato de turno de Jelou) y HTTP personalizado, y en cada reintento.

​

Token OAuth2 por mTLS

Si tu agente usa Credenciales de cliente OAuth2 y exige el certificado de cliente también para pedir el token, en la pestaña Autenticación, elige un Certificado mTLS y activa Pedir el token también con el certificado mTLS. El pedido del token viaja por el mismo certificado que la llamada al agente. La URL del token debe seguir siendo https. El interruptor solo aparece con esa autenticación y con un certificado elegido; si quitas el certificado, se desactiva. Desactivado, el token se pide como siempre.

​

El contrato de turno de Jelou

Cuando eliges HTTP (contrato de turno de Jelou), tu servidor recibe y responde con una forma fija que Jelou ya sabe interpretar, sin mapear rutas. Jelou envía un POST con el turno (turnId, input.parts, conversation, user, deadlineMs, interaction…) y tu agente responde con status, outputs y, si hace falta, signals. La descripción campo por campo, con ejemplos para copiar, está en Agente de IA externo: qué recibe y qué responde tu agente.

Solicitud que envía Jelou

{
  "turnId": "trn_01J8A7K2M4XQ",
  "inputId": "inp_9f3c2a71",
  "conversation": { "key": "wa:593999999999", "channel": "whatsapp", "locale": "es-EC" },
  "user": { "ref": "usr_8d41c0aa" },
  "input": { "parts": [{ "type": "text", "text": "Quiero un reembolso de mi última compra" }] },
  "deadlineMs": 25000,
  "trace": { "executionId": "exec_5b2e", "nodeId": "n_agent" },
  "interaction": "multi_turn"
}

En la segunda vuelta de la misma conversación, el agente ya conoce el número de pedido y cierra la conversación con la señal conversation_ended:

Segunda respuesta del agente

{
  "status": "completed",
  "outputs": [
    { "type": "text", "text": "Listo, encontré tu pedido EJ-48213. El reembolso de $45.00 fue aprobado y se verá reflejado en 3 a 5 días hábiles." }
  ],
  "signals": [{ "type": "conversation_ended" }]
}

Lo que responde el agente decide la salida del nodo:

Respuesta del agente	Salida del nodo
status: "completed"	Respondió (en varios turnos, solo cuando además envía la señal conversation_ended; si no, el nodo sigue esperando al usuario)
status: "completed" con la señal handoff_requested	Derivar a operador, después de entregar sus mensajes
status: "action_required" con la señal action_required	Pide más información (solo en una tarea)
status: "failed", "timed_out" o "blocked", o una respuesta que no cumple el formato	Hubo un error

La respuesta es estricta: los nombres deben ser exactamente status y outputs. Jelou rechaza alias como output, messages, result o turnStatus, y el mensaje de error indica qué campo corregir.

Si tu agente no habla este contrato, usa HTTP personalizado: ahí defines tú mismo la forma del cuerpo que se envía y las rutas donde Jelou debe leer el texto de respuesta, los datos estructurados y el identificador de sesión, en la pestaña Transformar del nodo.

​

Probar conexión

Antes de publicar tu flujo, usa el botón Probar conexión en la pestaña Conexión del nodo para verificar que todo está bien configurado, sin esperar a que un usuario real dispare el nodo. La prueba corre una serie de verificaciones encadenadas, deteniéndose en la primera que falle:

Verificación	Qué comprueba
Contrato	La configuración del nodo cumple con el esquema esperado.
Proveedor	El tipo de proveedor elegido está disponible.
Certificado mTLS	Si configuraste mTLS, que el certificado cargue y pertenezca a tu empresa.
Secreto	El secreto de la organización referenciado existe y se puede leer.
Token / acceso	La credencial efectivamente emite acceso (por ejemplo, que el intercambio OAuth2 o la firma AWS funcionen).
Agent Card (solo A2A)	La Agent Card es alcanzable y declara una interfaz HTTPS compatible con la credencial configurada.
Rechaza anónimo	El agente rechaza una llamada sin la credencial (si aplica al esquema).
Responde a una tarea	El agente contesta una tarea de prueba dentro del contrato, dentro del tiempo límite.
Sesión (solo varios turnos)	El agente emite un identificador de sesión para el siguiente turno.

Si todas las verificaciones pasan, ves una confirmación:

Si alguna falla, Jelou te dice cuál fue y por qué, para que corrijas la configuración antes de publicar. Por ejemplo, si el agente rechaza la credencial:

​

Seguridad

• Las credenciales nunca salen de los secretos de tu organización. El nodo guarda solo el nombre del secreto; su valor nunca se muestra ni se guarda en el flujo.
• Solo HTTPS. Jelou no llama a direcciones internas ni privadas.
• Las respuestas de tu agente pasan por los mismos controles de seguridad de Jelou que las respuestas de un AI Agent, antes de llegar al usuario: se filtran igual que cualquier mensaje saliente, sin que tengas que configurar nada adicional en el nodo.

​

Solución de problemas

El nodo sale siempre por 'Hubo un error'

Revisa primero Probar conexión: casi siempre señala si el problema es el certificado, el secreto, el token o el propio agente. Las causas más comunes son una credencial que expiró o se revocó, una URL que dejó de responder, o una respuesta del agente que no es JSON válido o no trae el campo esperado en la ruta configurada.

El turno tarda mucho y termina en error

El nodo espera como máximo el tiempo límite por turno configurado (25 segundos por defecto, hasta 120 como máximo). Si tu agente necesita más tiempo, sube el límite en la pestaña Avanzado; si el agente falla de forma intermitente, revisa los reintentos: solo aplican a tiempos de espera, límites de uso (HTTP 429) y errores de servidor (5xx), nunca a una solicitud que el agente rechazó explícitamente.

La firma HMAC no coincide en mi servidor

Verifica siempre sobre el cuerpo crudo de la solicitud, antes de parsear el JSON (ver la sección de firma HMAC más arriba). Confirma también que usas el mismo secreto, la misma codificación (hexadecimal o Base64) y, si activaste timestamp.body, que estás firmando "{timestamp}.{body}" y no solo el cuerpo.

'Pide más información' no aparece en varios turnos

Es esperado: esa salida solo existe en modo una tarea. En varios turnos, cuando el agente necesita un dato adicional simplemente lo pide como un mensaje normal y el nodo sigue esperando la respuesta del usuario, sin tomar ninguna salida.

No veo el nodo Agente de IA externo ni el selector de proveedores

El nodo se está habilitando de forma gradual. Pide a tu ejecutivo de Jelou que lo active para tu empresa.

​

Disponibilidad

El nodo Agente de IA externo se está habilitando de forma gradual. Si no lo ves en el canvas de tu proyecto, contacta a tu ejecutivo de cuenta de Jelou para solicitar su activación.

Nodo AI Agent

Configuración general del nodo AI Agent.