> ## 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. # Ejecutar workflows desde un agente externo > Conecta un agente que vive fuera de Jelou (Copilot Studio, Amazon Bedrock Agents, tu propio runtime o cualquier LLM con herramientas) para que ejecute workflows publicados, como un onboarding o una apertura de cuenta, paso a paso y sin exponer datos personales. 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. > [!NOTE] > > 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](https://mintcdn.com/jelouai/RsS2oQfVkEw3sI-F/assets/images/agentes-ia/agentes-externos-flujo_es.png?fit=max\&auto=format\&n=RsS2oQfVkEw3sI-F\&q=85\&s=12f73a8daeb4c9f6bf6d15d59c54844e) > [!WARNING] > > 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 | Opción | Úsala si… | Qué obtiene tu agente | | - | - | - | | **MCP** | Tu agente habla MCP: Copilot Studio, Amazon Bedrock Agents, Claude, OpenAI Agents, etc. | Cada workflow publicado aparece como una herramienta. La llamada espera hasta que el workflow necesita una respuesta o termina. | | **API REST** | Cualquier backend o agente que haga llamadas HTTP. | Inicias el workflow con una llamada y consultas su resultado por `executionId`. | | **Canal personalizado** | Tu app **es** el canal (web, app móvil) y no usas WhatsApp. | Jelou envía los mensajes del workflow a tu `webhookUrl`. Consulta [Canal personalizado](https://docs.jelou.ai/api/canal-personalizado/introduccion.md). | 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](https://docs.jelou.ai/guides/configuracion/claves-api.md) con estos scopes: | Scope | Para | | - | - | | `workflows:read` | Listar los workflows del proyecto | | `workflows:execute` | Iniciar workflows (y usar MCP) | | `executions:read` | Consultar el resultado de una ejecución | 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: ``` https://gateway.jelou.ai/workflows/mcp/{brainId} ``` 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`: ```json theme={null} { "_context": { "referenceId": "50712345678", "channel": "WHATSAPP" } } ``` 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: ```json theme={null} { "status": "pending_input", "executionId": "8f2c…", "outbox": [ { "type": "TEXT", "text": "Para empezar, ¿me compartes tu número de cédula?" } ], "cursor": 1 } ``` **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: ```json theme={null} { "text": "8-123-4567", "_context": { "referenceId": "50712345678" } } ``` 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** | `status` | Qué hacer | | - | - | | `pending_input` | Espera la respuesta del cliente y llama a `workflow_reply(text)` | | `running` | El workflow sigue procesando: llama a `workflow_reply` con `text: ""` para seguir esperando | | `completed` / `failed` / `cancelled` | Final. La conversación vuelve a tu agente | > [!NOTE] > > 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** ```bash theme={null} curl "https://gateway.jelou.ai/workflows/v1/skills?brainId=TU_BRAIN_ID&limit=100" \ -H "x-api-key: TU_CLAVE_API" ``` 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** ```bash theme={null} curl -X POST "https://gateway.jelou.ai/workflows/v2/skills/TU_SKILL_ID/execute" \ -H "x-api-key: TU_CLAVE_API" \ -H "content-type: application/json" \ -d '{ "channel": "WHATSAPP", "origin": "API", "botId": "TU_BOT_ID", "referenceId": "50712345678", "message": { "type": "text", "text": "Quiero abrir una cuenta de ahorros" } }' ``` **channel** `string` *required* Canal de la conversación. Usa `WHATSAPP`. **origin** `string` *required* Origen de la ejecución. Usa `API`. **botId** `string` *required* El bot de WhatsApp del proyecto. Con `botId` y `referenceId`, Jelou carga al cliente real y el workflow le escribe a él. **referenceId** `string` *required* El número de WhatsApp del cliente sin `+`. **message** `object` Lo que pidió el cliente, en sus palabras. **No incluyas datos personales aquí** (ver [Datos personales](#datos-personales)). Respuesta: ```json theme={null} { "status": "success", "message": "…", "data": { "executionId": "8f2c…" } } ``` > [!WARNING] > > 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](#requisitos-desde-cero)); * guarda el `executionId` y marca la conversación como *ocupada por un workflow*. **4. Detecta cuándo termina** Consulta el resultado: ```bash theme={null} curl "https://gateway.jelou.ai/workflows/v1/executions/EXECUTION_ID/result" \ -H "x-api-key: TU_CLAVE_API" ``` Devuelve `{ "executionId", "status", "output" }`. `output` viene vacío hasta que la ejecución termina. | `status` | Significado | | - | - | | `STARTED`, `PROCESSING` | En curso | | `WAITING` | Esperando al cliente (una respuesta o un formulario) | | `COMPLETED` | Terminó bien. La conversación vuelve a tu agente | | `CANCELED`, `CRASHED` | Terminó sin completar. La conversación vuelve a tu agente | 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. > [!NOTE] > > 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. > **No pases datos personales en `message`** > > 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. > **Fija la identidad en el servidor, no en el modelo** > > 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. > **Trata el outbox y los resultados como datos sensibles** > > 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. > **Lo que tu agente envía por su cuenta no pasa por los filtros de Jelou** > > 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. > **Mínimo privilegio en la clave API** > > 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](https://mintcdn.com/jelouai/RsS2oQfVkEw3sI-F/assets/images/agentes-ia/agentes-externos-whatsapp_es.png?fit=max\&auto=format\&n=RsS2oQfVkEw3sI-F\&q=85\&s=8efda0db5b3874410cb93553f5ad4a6e) ## Solución de problemas | Síntoma | Causa probable | Solución | | - | - | - | | `401 Unauthorized` | Clave ausente o inválida, o falta el scope | Revisa `x-api-key` y los scopes de la clave | | `404 User or company could not be found` | `botId` o `referenceId` no corresponden | Usa el `botId` del canal de WhatsApp del proyecto y el número sin `+` | | El cliente recibe dos respuestas | Tu agente respondió con un workflow activo | Silencia al agente mientras la ejecución no esté en un estado final | | Se crean dos solicitudes para el mismo cliente | Reintento automático o doble inicio | No reintentes un 5xx a ciegas. Con MCP, respeta `claim.conflict` | | La ejecución queda en `WAITING` | El cliente no ha respondido o no completó el formulario | Espera y aplica tu propio tiempo máximo. No inicies otra ejecución | This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.