> ## Documentation Index > Fetch the complete documentation index at: https://docs.jelou.ai/llms.txt > Use this file to discover all available pages before exploring further. # 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. ![Selector de agentes de IA externos que aparece al mantener el cursor sobre el ítem AI Agent de la barra de herramientas](https://mintcdn.com/jelouai/l9VvHeVZQWf9KWeT/assets/images/agentes-ia/agente-de-ia-externo/selector-es.png?fit=max\&auto=format\&n=l9VvHeVZQWf9KWeT\&q=85\&s=fc987a1469640b4da06c03183ab42f48) 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: ![Nodo Agente de IA externo en un flujo, conectado por sus cuatro salidas a un mensaje de respuesta, una pregunta, una derivación a un humano y un mensaje de disculpa](https://mintcdn.com/jelouai/l9VvHeVZQWf9KWeT/assets/images/agentes-ia/agente-de-ia-externo/canvas-flow-es.png?fit=max\&auto=format\&n=l9VvHeVZQWf9KWeT\&q=85\&s=be38fc0b2f10e15f22cb6a978f144313) ## 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](/guides/agentes-ia)). | | 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](https://developers.openai.com/api/docs/guides/prompting/migrate-from-prompt-object)). 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)](#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](#el-contrato-de-turno-de-jelou)). | | **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. | > [!NOTE] > > 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](#el-contrato-de-turno-de-jelou)), 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. ![Pestaña Conexión del nodo Agente de IA externo con el tipo OpenAI Agents (beta), el ID del agente, el entorno, la organización, el proyecto y la URL base](https://mintcdn.com/jelouai/l9VvHeVZQWf9KWeT/assets/images/agentes-ia/agente-de-ia-externo/panel-openai-agents-es.png?fit=max\&auto=format\&n=l9VvHeVZQWf9KWeT\&q=85\&s=1789572bf33a99eed8e8d43b393bc9bf) | 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. ![Pestaña Conexión del nodo Agente de IA externo con el tipo de conexión, la URL del agente, los headers fijos, la instrucción, los datos que envías y la interacción](https://mintcdn.com/jelouai/LlBsjjB0B2Hw2vhE/assets/images/agentes-ia/agente-de-ia-externo/panel-connection-es.png?fit=max\&auto=format\&n=LlBsjjB0B2Hw2vhE\&q=85\&s=7dd87c701bd5e9a42806988da5db4c5c) 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](/guides/nodos/ai-agent) [Ver guía completa de eventos de nodo](/guides/observabilidad/eventos) ## 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. ![Configuración del nodo Agente de IA externo con la interacción Varios turnos seleccionada](https://mintcdn.com/jelouai/LlBsjjB0B2Hw2vhE/assets/images/agentes-ia/agente-de-ia-externo/panel-multiturn-es.png?fit=max\&auto=format\&n=LlBsjjB0B2Hw2vhE\&q=85\&s=e3b3fe0a803066d731d30c55510f2a61) ### 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. | ![Comparación de dos nodos Agente de IA externo, uno configurado por A2A y otro por HTTP (contrato de turno de Jelou), mostrando las mismas cuatro salidas](https://mintcdn.com/jelouai/l9VvHeVZQWf9KWeT/assets/images/agentes-ia/agente-de-ia-externo/canvas-node-es.png?fit=max\&auto=format\&n=l9VvHeVZQWf9KWeT\&q=85\&s=6abe56200b8ee47318ed0860bf9786ee) 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): ![Pestaña Autenticación del nodo Agente de IA externo con el tipo de autenticación, el secreto, el certificado mTLS y la firma HMAC](https://mintcdn.com/jelouai/LlBsjjB0B2Hw2vhE/assets/images/agentes-ia/agente-de-ia-externo/panel-auth-es.png?fit=max\&auto=format\&n=LlBsjjB0B2Hw2vhE\&q=85\&s=5f0e0a21b7d65f85b8251e988aa23e01) | 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. | ![Pestaña Avanzado del nodo Agente de IA externo con la variable de respuesta, el tiempo límite por turno, los intentos, la inactividad de la sesión y el comando de reinicio](https://mintcdn.com/jelouai/LlBsjjB0B2Hw2vhE/assets/images/agentes-ia/agente-de-ia-externo/panel-advanced-es.png?fit=max\&auto=format\&n=LlBsjjB0B2Hw2vhE\&q=85\&s=db84b64ec1b6f27807ade9fb77be96c1) > [!NOTE] > > 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): ```js theme={null} 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); ``` > [!WARNING] > > 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. ![Pestaña Transformar del nodo Agente de IA externo con las subpestañas Jelou → Tu agente y Tu agente → Jelou, y el editor del script previo](https://mintcdn.com/jelouai/LlBsjjB0B2Hw2vhE/assets/images/agentes-ia/agente-de-ia-externo/panel-transform-es.png?fit=max\&auto=format\&n=LlBsjjB0B2Hw2vhE\&q=85\&s=ed75f0f6bd9e69e2fdaf3962fba53742) **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: ```js theme={null} 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.). ```js theme={null} const response = $context.get("agentResponse"); $context.set("agentResponse.body", response.body.data); ``` > [!NOTE] > > 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. ![Subpestaña Tu agente → Jelou del nodo Agente de IA externo con Cómo responde el agente en Confirma y responde después, el aviso de la salida de fallo y el campo que termina la conversación](https://mintcdn.com/jelouai/LlBsjjB0B2Hw2vhE/assets/images/agentes-ia/agente-de-ia-externo/ack-reply-es.png?fit=max\&auto=format\&n=LlBsjjB0B2Hw2vhE\&q=85\&s=9b86ee0c94918b386dd1f50c5bec2d53) 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. > [!WARNING] > > 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: ```javascript theme={null} 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**: ```json theme={null} { "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. ![Campo Datos que envías abierto al pie de cualquier pestaña del nodo Agente de IA externo, con las opciones URL del archivo, Respuesta de botón o lista, Respuesta de WhatsApp Flow y Ubicación](https://mintcdn.com/jelouai/LlBsjjB0B2Hw2vhE/assets/images/agentes-ia/agente-de-ia-externo/inbound-es.png?fit=max\&auto=format\&n=LlBsjjB0B2Hw2vhE\&q=85\&s=e9820ab5c31baf12d306b37b0e676fe5) ## 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](/guides/nodos/agente-ia-externo). ```json Solicitud que envía Jelou theme={null} { "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" } ``` ```json Respuesta que devuelve el agente theme={null} { "status": "completed", "outputs": [ { "type": "text", "text": "Claro, para verificar tu solicitud de reembolso necesito el número de pedido. ¿Podrías compartirlo?" } ] } ``` 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`: ```json Segunda respuesta del agente theme={null} { "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** | > [!WARNING] > > 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. > [!NOTE] > > 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: ![Resultado de Probar conexión cuando todas las verificaciones pasan, con el mensaje 'Conexión correcta'](https://mintcdn.com/jelouai/LlBsjjB0B2Hw2vhE/assets/images/agentes-ia/agente-de-ia-externo/test-connection-passed-es.png?fit=max\&auto=format\&n=LlBsjjB0B2Hw2vhE\&q=85\&s=2610d7ee7723825af41c8aa85d9c12a2) 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: ![Resultado de Probar conexión cuando una verificación falla, con el detalle de qué falló y por qué](https://mintcdn.com/jelouai/LlBsjjB0B2Hw2vhE/assets/images/agentes-ia/agente-de-ia-externo/test-connection-failed-es.png?fit=max\&auto=format\&n=LlBsjjB0B2Hw2vhE\&q=85\&s=999f45cc120128ea165ed663baab32c6) ## 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. ## Disponibilidad El nodo Agente de IA externo está disponible en todos los proyectos. > **[Nodo AI Agent](/guides/nodos/ai-agent)** > > Configuración general del nodo AI Agent. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.