> ## 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.

<Info>
  El nodo se está habilitando de forma gradual; si no lo ves en el canvas, pide a tu ejecutivo de Jelou que lo active.
</Info>

## 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.

<Frame>
  <img src="https://mintcdn.com/jelouai/ZkRphcrztaZ2KKwO/assets/images/agentes-ia/agente-de-ia-externo/selector-es.png?fit=max&auto=format&n=ZkRphcrztaZ2KKwO&q=85&s=36a95f48401e005de20113b34ebe270f" alt="Selector de agentes de IA externos que aparece al mantener el cursor sobre el ítem AI Agent de la barra de herramientas" width="660" height="908" data-path="assets/images/agentes-ia/agente-de-ia-externo/selector-es.png" />
</Frame>

<Tip>
  Este selector funciona igual que el de pasarela de pago en el nodo [Pagos](/guides/integraciones/pagos/personalizadas/usar-en-brain-studio): eliges primero el proveedor y el nodo llega con los campos correspondientes ya organizados.
</Tip>

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:

<Frame>
  <img src="https://mintcdn.com/jelouai/ZkRphcrztaZ2KKwO/assets/images/agentes-ia/agente-de-ia-externo/canvas-flow-es.png?fit=max&auto=format&n=ZkRphcrztaZ2KKwO&q=85&s=46502813aad5e6aeb2e5fd37dd94b15e" alt="Nodo Agente de IA externo en un flujo, conectado por sus cuatro salidas a un mensaje de respuesta, una pregunta, un handoff a un humano y un mensaje de disculpa" width="1960" height="1120" data-path="assets/images/agentes-ia/agente-de-ia-externo/canvas-flow-es.png" />
</Frame>

## 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 | Dónde lo encuentras en la consola del proveedor |
| :- | :- | :- |
| **Amazon Bedrock (Agents)** | Región de AWS, ID del agente, ID del alias | 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 del agente, protocolo del servidor (HTTP o A2A) | Bedrock AgentCore → Runtimes → tu runtime: el ARN completo y el `ProtocolConfiguration.serverProtocol` (HTTP o A2A) aparecen en su detalle. |
| **Microsoft Copilot Studio** | URL regional de Direct Line o endpoint del token | Copilot Studio → tu agente → Canales → Direct Line: la URL regional está en `regionalchannelsettings`; si usas intercambio de token, el endpoint del token viene del canal Direct Line configurado con "Secret" desactivado. |
| **Azure AI Foundry** | Endpoint del proyecto y el agente (por ID o por nombre, según la generación de API) | AI Foundry → tu proyecto → Overview: el endpoint del proyecto. El agente se identifica por `agentId` (generación clásica, tipo Assistants) o por `agentName` (generación Foundry, vía Responses API), nunca ambos. |
| **Google Vertex AI Agent Runtime** (antes Agent Engine) | Nombre del recurso del agente | Vertex AI → Agent Engine → tu agente: el nombre completo del recurso (`projects/.../locations/.../reasoningEngines/...`). Los agentes desplegados con la plantilla A2A usan el proveedor A2A en lugar de este. |
| **Google Dialogflow CX** | Nombre del agente y código de idioma | Dialogflow CX → tu agente → configuración: el nombre completo (`projects/.../locations/.../agents/...`). El código de idioma se usa cuando la conversación no trae uno propio. |
| **Claude Managed Agents** | ID del agente, ID del entorno | Consola de Claude Managed Agents: el ID del agente (`agent_...`) y el ID del entorno (`env_...`) del agente que publicaste. |
| **Salesforce Agentforce** | ID del agente (18 caracteres), URL de My Domain de tu org | 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`. Solo agentes que no sean del tipo "Agentforce (Default)" son compatibles. |
| **OpenAI (Responses API)** | ID del prompt (formato `pmpt_...`) | Plataforma de OpenAI → Prompts: el ID del prompt reusable que empaqueta instrucciones, modelo y tools. Opcionalmente puedes fijar una versión del prompt. |
| **LangGraph** | URL del despliegue y ID del asistente | LangGraph Platform (LangSmith Deployments) → tu despliegue: la URL del despliegue y el ID del asistente (UUID recomendado, o el nombre del grafo). |
| **Dify** (preconfigurado sobre HTTP personalizado) | URL del espacio de trabajo y credencial | Dify → tu app → API Access: la URL base y la API key del espacio de trabajo. Jelou llama `POST /v1/chat-messages` por ti. |
| **n8n** (preconfigurado sobre HTTP personalizado) | URL del webhook | n8n → tu workflow → nodo Webhook: la URL de producción del webhook. |
| **A2A (Agent-to-Agent)** | URL del Agent Card | El servidor de tu agente A2A: la URL pública donde publica su Agent Card (`.well-known/agent-card.json` o la ruta que definas). |
| **HTTP (contrato de turno de Jelou)** | URL del agente | Tu propio servidor: el endpoint que ya implementa el contrato de turno de Jelou (ver la sección de abajo). |
| **HTTP personalizado** | URL del agente, cuerpo de la solicitud y rutas de la respuesta | Tu propio servidor: cualquier endpoint que reciba JSON, aunque no hable el contrato de turno de Jelou. |

## 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.

<Frame>
  <img src="https://mintcdn.com/jelouai/ZkRphcrztaZ2KKwO/assets/images/agentes-ia/agente-de-ia-externo/panel-multiturn-es.png?fit=max&auto=format&n=ZkRphcrztaZ2KKwO&q=85&s=f1f7354f91d32a2d7d0ae5a48e30d8bd" alt="Configuración del nodo Agente de IA externo con la interacción Varios turnos seleccionada" width="1400" height="2500" data-path="assets/images/agentes-ia/agente-de-ia-externo/panel-multiturn-es.png" />
</Frame>

### 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. |

<Frame>
  <img src="https://mintcdn.com/jelouai/ZkRphcrztaZ2KKwO/assets/images/agentes-ia/agente-de-ia-externo/canvas-node-es.png?fit=max&auto=format&n=ZkRphcrztaZ2KKwO&q=85&s=f4d644f7d53dd04e4af1cc3923ae08ad" alt="Comparación de dos nodos Agente de IA externo, uno configurado por A2A y otro por Amazon Bedrock Agents, mostrando las mismas cuatro salidas" width="1720" height="1200" data-path="assets/images/agentes-ia/agente-de-ia-externo/canvas-node-es.png" />
</Frame>

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 "Guardar la respuesta en"

Cada nodo Agente de IA externo tiene un campo **Guardar la respuesta en** (por defecto `agentReply`) donde se escribe la respuesta del agente. Puedes referenciarla en nodos posteriores del flujo con la sintaxis habitual de variables, por ejemplo `{{$context.agentReply}}` en un nodo de mensaje o en una condición.

Si el agente además envía datos estructurados (por ejemplo con la ruta de datos del HTTP personalizado, o con una señal `variables_set`), esos datos se escriben como variables individuales del contexto del flujo, disponibles para cualquier nodo posterior.

## 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). |
| `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 Enterprise para HTTP personalizado

Cuando tu agente usa **HTTP (contrato de turno de Jelou)** o **HTTP personalizado**, tu empresa puede tener acceso a opciones adicionales:

<Frame>
  <img src="https://mintcdn.com/jelouai/ZkRphcrztaZ2KKwO/assets/images/agentes-ia/agente-de-ia-externo/panel-connection-es.png?fit=max&auto=format&n=ZkRphcrztaZ2KKwO&q=85&s=14de4b000f500c8c6a8934f4179990d1" alt="Pestaña Conexión del nodo Agente de IA externo con la URL del agente, autenticación, certificado mTLS, firma HMAC y headers fijos" width="1400" height="2500" data-path="assets/images/agentes-ia/agente-de-ia-externo/panel-connection-es.png" />
</Frame>

| 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 valores con variables (`{{...}}`). Máximo 10 headers. |
| **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. |
| **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. |

<Frame>
  <img src="https://mintcdn.com/jelouai/ZkRphcrztaZ2KKwO/assets/images/agentes-ia/agente-de-ia-externo/panel-advanced-es.png?fit=max&auto=format&n=ZkRphcrztaZ2KKwO&q=85&s=8e6e6afd741f1a41d363642d8248462f" alt="Pestaña Avanzado del nodo Agente de IA externo con el tiempo límite por turno y el número de intentos" width="1400" height="1640" data-path="assets/images/agentes-ia/agente-de-ia-externo/panel-advanced-es.png" />
</Frame>

<Note>
  Estas opciones están disponibles en planes Enterprise. Si no las ves en tu nodo, pide a tu ejecutivo de Jelou que verifique tu plan.
</Note>

### 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.
</Warning>

El campo **Tarea** 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, y solo aplican a proveedores HTTP. Se configuran en la pestaña **Transformar** del nodo, junto a la tarea que se envía y la variable donde se guarda la respuesta:

<Frame>
  <img src="https://mintcdn.com/jelouai/ZkRphcrztaZ2KKwO/assets/images/agentes-ia/agente-de-ia-externo/panel-transform-es.png?fit=max&auto=format&n=ZkRphcrztaZ2KKwO&q=85&s=31485e1238fdefb44696db27574fb3e6" alt="Pestaña Transformar del nodo Agente de IA externo con el campo Tarea, la variable Guardar la respuesta en, y el editor de Pre Request / Post Request" width="1400" height="2600" data-path="assets/images/agentes-ia/agente-de-ia-externo/panel-transform-es.png" />
</Frame>

**Script previo (pre-request):** `$context.get("agentRequest")` contiene `{ task, sessionId, body, headers }`. El script puede modificar `agentRequest.body` o `agentRequest.headers` antes de que Jelou envíe la solicitud. 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 (post-response):** `$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 de 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.
</Note>

## 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 **Conexión** 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.

<Frame>
  <img src="https://mintcdn.com/jelouai/rXl0gajV6cghfzcz/assets/images/agentes-ia/agente-de-ia-externo/ack-connection-es.png?fit=max&auto=format&n=rXl0gajV6cghfzcz&q=85&s=eb84a8eada40c76064b0a0431f969403" alt="Pestaña Conexión 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, el interruptor del token con el certificado mTLS y el prefijo de la firma" width="384" height="2200" data-path="assets/images/agentes-ia/agente-de-ia-externo/ack-connection-es.png" />
</Frame>

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 pestaña **Avanzado**, 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ó**.

<Frame>
  <img src="https://mintcdn.com/jelouai/rXl0gajV6cghfzcz/assets/images/agentes-ia/agente-de-ia-externo/ack-advanced-es.png?fit=max&auto=format&n=rXl0gajV6cghfzcz&q=85&s=129c140d573eedfbafccc40d6fc5df5e" alt="Pestaña Avanzado del nodo Agente de IA externo con el campo que termina la conversación y sus valores" width="384" height="2200" data-path="assets/images/agentes-ia/agente-de-ia-externo/ack-advanced-es.png" />
</Frame>

### 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.
</Warning>

## 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 **Transformar**, el campo **Datos sensibles de mensajes no texto que recibe el agente** 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.

<Frame>
  <img src="https://mintcdn.com/jelouai/rXl0gajV6cghfzcz/assets/images/agentes-ia/agente-de-ia-externo/ack-transform-es.png?fit=max&auto=format&n=rXl0gajV6cghfzcz&q=85&s=6c4d05be0152a3d04f6504039d3e944a" alt="Pestaña Transformar del nodo Agente de IA externo con los datos sensibles de mensajes no texto que recibe el agente" width="384" height="2200" data-path="assets/images/agentes-ia/agente-de-ia-externo/ack-transform-es.png" />
</Frame>

## Prefijo de la firma

Algunos agentes esperan la firma HMAC con un texto delante, por ejemplo `sha256=` seguido del valor. 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, 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 necesidad de mapear rutas manualmente. Esto es lo que Jelou realmente envió y recibió en una prueba real contra un servidor de agente, con la firma HMAC redactada:

<CodeGroup>
  ```json Solicitud que envía Jelou theme={null}
  {
    "method": "POST",
    "headers": {
      "content-type": "application/json",
      "accept": "application/json",
      "channel-id": "whatsapp",
      "organization-id": "org-001",
      "x-jelou-signature": "<redacted>"
    },
    "body": {
      "event": "message",
      "endpoint": "agent",
      "text": "Quiero un reembolso de mi última compra",
      "session": "",
      "user": "usr_9f3ka2"
    }
  }
  ```

  ```json Respuesta que devuelve el agente theme={null}
  {
    "data": {
      "reply": "Claro, para verificar tu solicitud de reembolso necesito el número de pedido. ¿Podrías compartirlo?",
      "session": "sess_ej3nc9dk2m"
    }
  }
  ```
</CodeGroup>

En la segunda vuelta de la misma conversación, el agente ya conoce el número de pedido y el nodo entrega la conversación como terminada:

```json Segunda respuesta del agente theme={null}
{
  "data": {
    "reply": "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.",
    "session": "sess_ej3nc9dk2m"
  }
}
```

<Note>
  Si tu agente no habla exactamente 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.
</Note>

## 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:

<Frame>
  <img src="https://mintcdn.com/jelouai/ZkRphcrztaZ2KKwO/assets/images/agentes-ia/agente-de-ia-externo/test-connection-passed-es.png?fit=max&auto=format&n=ZkRphcrztaZ2KKwO&q=85&s=1541de1c62a6039f1195e0a990516480" alt="Resultado de Probar conexión cuando todas las verificaciones pasan, con el mensaje 'Conexión correcta'" width="1400" height="2900" data-path="assets/images/agentes-ia/agente-de-ia-externo/test-connection-passed-es.png" />
</Frame>

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:

<Frame>
  <img src="https://mintcdn.com/jelouai/ZkRphcrztaZ2KKwO/assets/images/agentes-ia/agente-de-ia-externo/test-connection-failed-es.png?fit=max&auto=format&n=ZkRphcrztaZ2KKwO&q=85&s=c9016f72199401e5632d17bdefc5c719" alt="Resultado de Probar conexión cuando una verificación falla, con el detalle de qué falló y por qué" width="1400" height="2500" data-path="assets/images/agentes-ia/agente-de-ia-externo/test-connection-failed-es.png" />
</Frame>

## 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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="'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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="No veo las opciones Enterprise (HMAC, headers estáticos, scripts, mTLS)">
    Estas opciones están disponibles en planes Enterprise. Pide a tu ejecutivo de Jelou que verifique tu plan.
  </Accordion>
</AccordionGroup>

## 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.

<Card title="Nodo AI Agent" icon="robot" href="/guides/nodos/ai-agent">
  Configuración general del nodo AI Agent.
</Card>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.