Saltar al contenido principal
Un agente externo es un agente de IA que corre fuera de Jelou: Microsoft Copilot Studio, Amazon Bedrock Agents, un runtime propio o cualquier modelo con llamada a herramientas. Con esta guía ese agente puede iniciar workflows publicados en Brain Studio, por ejemplo un onboarding o una apertura de cuenta que piden cédula, correo y dirección, y dejar que el workflow conduzca la conversación con el cliente hasta terminar.
En esta guía, skill y workflow significan lo mismo: un flujo publicado de tu proyecto que se puede ejecutar desde fuera.

​
Cómo funciona

El agente decide cuándo ejecutar un workflow. El workflow decide qué preguntar y recoge los datos.
1

El cliente escribe a tu agente

Por ejemplo: “Quiero abrir una cuenta de ahorros”.
2

Tu agente inicia el workflow

Llama a Jelou por MCP o por la API REST con el identificador del cliente. Jelou responde con un executionId y ejecuta el workflow en segundo plano.
3

El workflow conversa con el cliente

El workflow envía sus mensajes al WhatsApp del cliente: pide la cédula, muestra botones o abre un formulario. Jelou enruta las respuestas del cliente al workflow. Mientras tanto, tu agente no responde.
4

El workflow termina y la conversación vuelve a tu agente

Cuando la ejecución llega a un estado final (completado, fallido o cancelado), tu agente retoma la conversación.
Diagrama de secuencia: el cliente escribe a tu agente, tu agente inicia el workflow en Jelou y recibe un executionId, el workflow pide la cédula y abre un formulario seguro mientras tu agente queda en silencio, y al terminar la conversación vuelve a tu agente
El error más común es que el agente siga respondiendo mientras el workflow espera una respuesta del cliente. El cliente recibe dos respuestas a la vez y el workflow pierde el dato que esperaba. Mientras haya un workflow activo para ese cliente, tu agente debe quedarse en silencio.

​
Elige cómo conectarte

Las opciones MCP y API REST de esta guía son para conversaciones de WhatsApp.

​
Requisitos, desde cero

1

Un workflow publicado

Crea y publica el workflow en Brain Studio (por ejemplo, Apertura de cuenta). Pruébalo primero desde el propio WhatsApp del bot para confirmar que funciona solo.
2

Un canal de WhatsApp conectado al proyecto

El workflow envía sus mensajes por el bot de WhatsApp del proyecto. Anota el botId de ese canal.
3

Una clave API con los scopes correctos

Crea una clave en Claves API con estos scopes:Llama siempre a través de https://gateway.jelou.ai: ahí se aplican los scopes de la clave. La clave va en el encabezado x-api-key.
4

Los identificadores

  • brainId: el identificador del proyecto.
  • skillId: el identificador del workflow (lo obtienes al listar los workflows).
  • referenceId: el identificador del cliente en WhatsApp, normalmente su número sin + (por ejemplo, 50712345678).
5

Que los mensajes del cliente lleguen a tu agente

Si tu agente es quien atiende el WhatsApp del bot, Jelou debe reenviarle los mensajes entrantes de ese bot. Esta redirección la configura el equipo de Jelou: solicítala indicando el bot y la URL de tu agente. Cuando haya un workflow activo, tu agente devuelve a Jelou cada mensaje del cliente sin responderlo para que llegue al workflow. El equipo de Jelou te indica cómo devolverlos al configurar la redirección.

​
Opción A: MCP

Conecta tu agente como cliente MCP al servidor de workflows de tu proyecto:
Autentica con el encabezado x-api-key. El servidor expone:
  • Una herramienta por workflow publicado del proyecto, con los datos de entrada del workflow como parámetros y un campo _context para el cliente.
  • workflow_reply, para pasarle al workflow la respuesta del cliente.

​
Paso a paso

1

Inicia el workflow

Llama a la herramienta del workflow con el cliente en _context:
La llamada espera hasta que el workflow necesita una respuesta del cliente o termina, con un máximo de unos 120 segundos. La respuesta tiene esta forma:
2

No repitas el outbox

outbox contiene los mensajes que el workflow ya entregó al cliente por WhatsApp. Tu agente los lee para saber qué se dijo, pero no los vuelve a enviar ni los parafrasea.
3

Espera la respuesta real del cliente

Si status es pending_input, espera el siguiente mensaje del cliente y pásalo tal cual:
No inventes respuestas ni completes datos por el cliente. El servidor resuelve la ejecución activa por el referenceId: no necesitas enviar el executionId.
4

Repite hasta un estado final

Si la respuesta indica un conflicto (claim.conflict, thread_busy), ya hay una ejecución en curso para ese cliente. No reintentes ni inicies otra. Espera a que termine la actual.

​
Opción B: API REST

1

Lista los workflows del proyecto

Usa el id de cada workflow como skillId. La descripción de cada workflow es lo que tu agente debería leer para decidir cuándo usarlo.
2

Inicia el workflow

​
string
requerido
Canal de la conversación. Usa WHATSAPP.
​
string
requerido
Origen de la ejecución. Usa API.
​
string
requerido
El bot de WhatsApp del proyecto. Con botId y referenceId, Jelou carga al cliente real y el workflow le escribe a él.
​
string
requerido
El número de WhatsApp del cliente sin +.
​
object
Lo que pidió el cliente, en sus palabras. No incluyas datos personales aquí (ver Datos personales).
Respuesta:
Esta llamada no tiene clave de idempotencia. Si falla con un error 5xx, no la reintentes automáticamente: la ejecución pudo haber empezado y un reintento abriría una segunda solicitud para el mismo cliente. Consulta primero el resultado con el executionId, si lo tienes, o avisa al cliente del error.
3

Deja que el workflow conduzca

Jelou envía los mensajes del workflow al WhatsApp del cliente y enruta sus respuestas al workflow. Tu agente no las reenvía por la API. Mientras el workflow esté activo:
  • no respondas los mensajes del cliente;
  • devuélvelos a Jelou tal cual (ver el último paso de Requisitos);
  • guarda el executionId y marca la conversación como ocupada por un workflow.
4

Detecta cuándo termina

Consulta el resultado:
Devuelve { "executionId", "status", "output" }. output viene vacío hasta que la ejecución termina.Consulta con espera creciente (por ejemplo, cada pocos segundos) y define tu propio tiempo máximo. Si el cliente abandona el workflow, no esperes para siempre para retomar la conversación.
Hoy solo se pueden cancelar las ejecuciones iniciadas por MCP. Una ejecución iniciada por la API REST termina por sí sola: al completarse o al vencer su tiempo de espera.

​
Formularios (webviews) dentro del workflow

Muchos workflows de datos personales abren un formulario seguro en lugar de pedir cada dato por chat. Por ejemplo, un formulario de apertura con correo, dirección y actividad económica. Jelou abre el formulario con el executionId de la ejecución. Cuando el cliente lo envía, el formulario le devuelve el resultado a Jelou y el workflow continúa. Tu agente no hace nada en este paso: no intercepta el formulario ni reenvía sus datos. Si el workflow parece detenido en WAITING después de enviar un formulario, el cliente probablemente aún no lo completó.

​
Datos personales

Los workflows de onboarding y apertura manejan datos sensibles: cédula, correo, dirección, ingresos. El diseño recomendado es que esos datos viajen solo entre el cliente y el workflow, nunca por tu agente.
Envía solo lo que pidió el cliente (“quiero abrir una cuenta”). El workflow pide la cédula y los demás datos por sí mismo, con sus validaciones. Si tu agente ya conoce un dato, no lo reenvíes en texto libre: el workflow lo pedirá o lo tomará de sus propias fuentes.
El referenceId, el botId y cualquier identificador del cliente deben salir de la sesión de tu servidor, nunca de lo que escribe el modelo. Si el modelo pudiera elegir el referenceId, podría iniciar un workflow para otra persona. En los agentes de Copilot Studio o Bedrock, pasa estos valores desde la configuración de la acción o el contexto de la sesión, no como parámetros que el modelo complete.
El outbox de MCP y el output de una ejecución pueden contener datos del cliente. No los guardes en logs, no los muestres en paneles y no los reenvíes a otros sistemas sin necesidad.
Los mensajes que envía el workflow pasan por los controles de datos de Jelou. Los mensajes que tu agente envía directamente al cliente, no: aplica tus propias reglas de redacción antes de enviarlos.
Da a la clave solo los scopes que usa tu agente (workflows:read, workflows:execute, executions:read). Guárdala como secreto de tu plataforma y rótala si se expone.

​
Ejemplo completo: apertura de cuenta

1

El cliente: “Quiero abrir una cuenta de ahorros”

Tu agente reconoce la intención y no pide datos por su cuenta.
2

Tu agente inicia el workflow

Por MCP (herramienta del workflow con _context.referenceId) o por REST (POST /v2/skills/{skillId}/execute). El referenceId sale de la sesión del servidor. Marca la conversación como ocupada.
3

El workflow pide la cédula

El mensaje llega al WhatsApp del cliente. Tu agente no lo repite.
4

El cliente responde con su cédula

Jelou entrega la respuesta al workflow. Con MCP, tu agente la pasa tal cual con workflow_reply. Tu agente no la guarda ni la interpreta.
5

El workflow abre el formulario de datos

El cliente completa correo y dirección en el formulario seguro. El formulario le devuelve el resultado a Jelou.
6

El workflow termina

status pasa a COMPLETED (REST) o completed (MCP). Tu agente retoma la conversación: “¿Te ayudo con algo más?”
Conversación de WhatsApp de ejemplo: el cliente pide abrir una cuenta, el agente responde, el workflow pide la cédula y abre el formulario seguro, confirma la solicitud y el agente retoma la conversación

​
Solución de problemas