# Notificación de Transferencia a humano. Herramienta estándar de la plataforma que permite a un agente IAE escalar una conversación a un humano cuando determina que no puede resolver el caso por sí mismo. El agente notifica a los humanos designados, opcionalmente se desactiva de la conversación, y el humano retoma el hilo desde la auditoría. ## Punto final (endpoint) La herramienta se expone como un endpoint REST en la forma: ``` agent.induxsoft.net/{agent_id}/tools/handoff/ ``` ## Activación El handoff se configura como una **intención a sí mismo**. Esto significa que: - El endpoint se registra como una intención más del agente, apuntando a su propio punto final de handoff. - El agente decide cuándo invocarlo basándose en su preámbulo y conocimientos generales, como parte de su razonamiento natural. - No requiere que el usuario pida explícitamente hablar con un humano; el agente lo determina autónomamente (aunque también puede responder a una solicitud directa del usuario si su preámbulo así lo indica). ## Flujo de ejecución 1. El agente razona que necesita escalar. 2. Invoca la intención que apunta a `/{agent_id}/tools/handoff/`. 3. El endpoint ejecuta la lógica de notificación según la configuración almacenada: - Envía notificación por WhatsApp a los números configurados (si está habilitado). - Envía notificación por correo electrónico a los destinatarios configurados (si está habilitado). - Registra la solicitud de handoff para que la auditoría la despliegue como notificación en pantalla a los operadores en línea. 4. Si "Desactivarme de la conversación" está habilitado, el agente se desactiva del hilo. 5. El endpoint devuelve al agente el mensaje de respuesta configurado. 6. El agente utiliza ese mensaje para informar al usuario lo conducente (adaptándolo a su tono conversacional). 7. El humano recibe la notificación (en pantalla en la auditoría, por WhatsApp y/o por correo). 8. El humano accede a la conversación desde la auditoría y responde en el mismo hilo. 9. Cuando el humano termina, puede reactivar al agente mediante un switch en la auditoría. ## Configuración La configuración se ubica dentro de la opción **"Más opciones"** del agente, enla sección **"Configuración de transferencia a humano"**. - Notificación por WhatsApp - Notificación por correo electrónico - Mensaje de respuesta del endpoint - Comportamiento del agente ### Notificación por WhatsApp ``` - Notificar por WhatsApp Números de teléfono (con código de país e indicador de "número móvil", separados por comas): . ejemplo para méxico: +52 1 0000000000, +52 1 0000000001 Agente remitente (opcional):Configura las credenciales del agente IA. agent_id: token: (Si no se especifica, se usa el propio agente como remitente) Plantilla de mensaje: Predeterminado: "Un prospecto necesita atención humana @chat_link" ``` ### Notificación por correo electrónico - Notificar por correo electrónico - Configuración SMTP:Configura los datos del servidor smtp y plantilla de envío. - Servidor: - Usuario: - Contraseña: - SSL: - Remitente: Nombre y/o correo. ejemplo: Mi Nombre - Destinatarios (separados por comas): Ejemplo: micorreo1@modominio,micorreo2@modominio. - Asunto: Predeterminado: "Solicitud de intervención humana" - Cuerpo: Predeterminado: "Un prospecto necesita atención humana @chat_link" **Nota:** Tanto el asunto como el cuerpo del correo admiten macros. ### Comportamiento del agente ``` - Desactivarme de la conversación. Valor Activado/Desactivado. ``` - **Marcado:** El agente deja de responder en ese hilo tras notificar. El humano retoma desde la auditoría. El humano puede reactivar al agente con el switch. - **No marcado:** El agente avisa al usuario que alguien lo contactará, pero sigue activo y responde si el usuario le escribe mientras espera. ### Mensaje de respuesta del endpoint El punto final de handoff devuelve un mensaje configurable al agente, que este utiliza como base para informar al usuario sobre lo que sucederá. Esto permite que el creador controle exactamente qué le dice el agente al usuario cuando escala. ``` Mensaje de respuesta: Predeterminado: "He notificado a un asesor humano para que te atienda. En breve alguien se comunicará contigo por este mismo medio." ``` **Nota:** Este mensaje admite macros. El agente recibe este texto como respuesta de la herramienta y lo usa para formular su mensaje al usuario, pudiendo adaptarlo a su tono y estilo conversacional. ### Macros para plantillas Las macros se resuelven al momento de ejecutar la notificación y están disponibles en todos los campos de plantilla (mensaje de WhatsApp, asunto de correo y cuerpo de correo). | Macro | Descripción | Ejemplo de resultado | |---|---|---| | `@chat_link` | Enlace directo a la conversación en la auditoría | `https://agent.induxsoft.net/.../audit/conv/abc123` | | `@chat_summary` | Resumen generado por IA de la conversación hasta el momento del handoff | "El usuario preguntó por disponibilidad de un producto, solicitó precio mayoreo y pidió hablar con un asesor." | | `@chat_user_name` | Nombre del usuario si se identificó durante la conversación | "María López" (o vacío si no se identificó) | ### Caso de uso. Un agente IA atiende consultas de clientes sobre producto "martillo" en tamaño pequeño, mediano y grande, precios y disponibilidad. Sin embargo, hay situaciones en las que el agente no tiene autoridad para resolver, como negociaciones de precio o reclamos complejos. En esos casos, debe escalar la conversación a un humano. ##### **Ejemplo de interacción IA-Humano.** - *Cliente:* “Quiero comprar 100 unidades, pero necesito un descuento especial.” - *Agente IA:* Razona que no tiene autoridad para negociar precios. - *Acción:* Invoca el endpoint de handoff. - *Notificación:* - *WhatsApp a los asesores con el mensaje:* "Un prospecto necesita atención humana `@chat_link`". - *Correo a ventas con asunto:* "Solicitud de intervención humana". - *Auditoría:* Muestra notificación en pantalla con acceso directo al hilo. - *Agente IA al cliente:* "He notificado a un asesor humano para que te atienda. En breve alguien se comunicará contigo por este mismo medio." - *Humano:* Ingresa al hilo desde la auditoría y negocia directamente con el cliente. - *Finalización:* Cuando termina, el humano reactiva al agente con el switch para que continúe disponible en la conversación. ##### **Configuración del agente.** En este caso practico y sencillo, los *conocimientos generales* del agente son: - *Somos una empresa de ventas de herramientas exclusivas en el ramo ferretero.* - *No dar información diferente a lo que comercializamos.* - *Solo vendemos Martillos.* - *Precios por piezas: Martillo chico=$50.00, Martillo Mediano=$75.00,Martillo Grande=$100.00.* - *Quienes quieran precios de mayoreo o especial deberás de transferirlos a un humano.* - **Configuración de la intención.** - Agrega la intención. - Dale un ID, Descripción y las instrucciones necesarias. Ejemplo para este caso practico y sencillo, la instrucción a la intención: `Transferir a un humano cuando sea necesario.` - Punto final(URL): Agrega aquí el punto final del agente, puedes copiarlo desde la configuración de notificaciones del agente en el botón **"Más opciones"** , y localiza la sección **"Configuración de transferencia a humano"**. - Encabezado: 'Authorization': Agrega aquí la Authorization, Bearer del agente, puedes copiarlo desde la configuración de notificaciones del agente en el botón **"Más opciones"** , y localiza la sección **"Configuración de transferencia a humano"**. - Guardar. - **Configuración de la notificación.** - Accede a la configuración del agente en el botón **"Más opciones"** , y localiza la sección **"Configuración de transferencia a humano"**. - Da clic en el botón "Editar" - *Notificación por WhatsApp* - Activa la casilla "Notificar por WhatsApp" - Introduce los números de teléfono (con código de país e indicador de "número móvil", separados por comas): ejemplo para méxico: +5219617654321,+5219617658033 - Si no especificas un agent_id, token, el agente actual es quien enviará la notificación. Nota: El agente que envíe la notificación debe estar vinculador por WhatsApp QR. - *Notificación por correo electrónico* - Activa la casilla Notificar por correo electrónico. - Configura los datos y credenciales de tu servidor SMTP. - Agrega los datos del Remitente: ejemplo: Notificación de IA - Agrega los destinatarios (separados por comas): Ejemplo: Pedro@gmail.com, maria@hotmail.com. - Si requieres puedes modificar el asunto y cuerpo del mensaje predeterminado. - *Comportamiento del agente.* - Activa la casilla "Desactivarme de la conversación"(Si no deseas que el agente deje de responder en ese hilo dejalo desactivado y seguira respondiendo). - Si requieres puedes modificar el mensaje de respuesta del agente. - Para finalizar la configuración de notificación da clic en "Confirmar"