# Protocolo de integración ## Manejo de sesión del usuario ### Validación de la sesión El agente comprobará el 'token' de sesión que se le ha suministrado a través de un método POST al punto final indicado. Solicitud ``` Method: POST Headers Authorization: Content-Type: application/json; charset=utf-8 Payload { "agent_id":"Id del agente", "agent_name":"Nombre del agente", "source_url":"URL desde la que el agente hace la solicitud (opcional)", "user_sid":"Token de sesión que fue suministrado al agente para ser validado", "params":{... Un conjunto de pares clave/valor que han sido provistos al agente por la aplicación, página que lo ha invocado o establecidos como constantes a enviar en la configuración del agente... } } ``` Respuesta Si el token de sesión es válido ``` Content-Type: application/json; charset=utf-8 { "success": true, "user":"Id interno del usuario", "user_name":"Nombre para mostrar del usuario", "user_phone":"Teléfono visible del usuario (opcional)", "user_email":"Correo electrónico del usuario (opcional)", "channel":"Un identificador del canal de comunicaciones (opcional)", "user_type":"Tipo de usuario", "user_sid":"El mismo token de sesión de la solicitud", "context":"Información del usuario que se incluirá en el contexto de llamada al LLM" } ``` Si el token no es válido ``` Content-Type: application/json; charset=utf-8 { "success":false, "message":"Mensaje de error del servicio" } ``` La validez de la sesión depende en exclusiva de que el campo ```success``` exista en la respueta y esté establecido en ```true```. En cualquier otro caso; aun cuando no se apegue a la respuesta de token inválido prevista; se trata como que el token es inválido y no hay una sesión de usuario. Si el agente no puede comprobar la validez de la sesión, simplemente tratará al usuario como anónimo sin ninguna alerta o mensaje adicional. ### Inicio y cierre de sesión Si se ha habilitado el inicio de sesión de sesión desde la interfaz del agente, se habilitará un link en la parte superior derecha "Inicio de sesión" que dirigirá a la Url indicada en la configuración, el agente espera que la página de inicio de sesión redirija nuevamente a la interfaz de chat adjuntando el parámetro en la URL ```user_sid``` con el identificador de sesión que el agente pueda comprobar. Si se ha habilitado el inicio de sesión de sesión desde la interfaz del agente, también cuando haya una sesión iniciada, habrá un botón de 'Cierre de sesión' que invocará al punto final configurado con el método POST y la siguiente carga útil: Si se ha establecido el valor del encabezado Authorization, se enviará en la solicitud. Solicitud ``` Method: POST Headers Authorization: Content-Type: application/json; charset=utf-8 Payload { "agent_id":"Id del agente", "source_url":"URL desde la que el agente hace la solicitud", "user_sid":"Token de sesión que fue suministrado al agente para ser validado", "params":{... Un conjunto de pares clave/valor que han sido provistos al agente por la aplicación, página que lo ha invocado o establecidos como constantes a enviar en la configuración del agente... } } ``` Independientemente de la respuesta recibida, se eliminará el identificador de sesión de la interfaz del agente y se asumirá al usuario como anónimo. No obstante, se esperaría una respuesta como: ``` { "success":true, "redirect":"Una URL a la que se redirigirá desde la interfaz de chat del agente (si se ha establecido)" } ``` ## Invocación de herramienta externa La invocación de herramientas como resultado de la detección de una intención, se lleva a cabo a través de una solicitud HTTP con el método POST. La carga útil se envía en formato JSON como se indica: ``` Method: POST Headers Authorization: Content-Type: application/json; charset=utf-8 Payload { "intention":"Id de la intención", "preliminary_answer":"Respuesta preliminar del LLM", "original_question":"Pregunta o mensaje original del usuario", "reformulated_question":"Pregunta o mensaje del usuario reformulado por el LLM", "agent_id":"Id del agente", "agent_name":"Nombre del agente", "chat_id":"Identificador de la conversación que invoca la herramienta", "source_url":"URL desde la que el agente hace la solicitud (opcional)", "user_sid":"Token de sesión que fue suministrado al agente para ser validado", "user":"Id del usuario si está autenticado", "user_name":"Nombre para mostrar del usuario", "data":{ ... Un objeto con los datos especificados en las instrucciones de la intención ...}, "params":{... Un conjunto de pares clave/valor que han sido provistos al agente por la aplicación, página que lo ha invocado, definidos de manera constante en la configuración de la intención o en la configuración del agente... } } ``` Los datos de respuesta no requieren un formato específico porque serán devueltos tal cual al usuario como respuesta o bien, volverán a ser procesados por el LLM con el prompt de la intención antes de ser devueltos. ## Recuperación de contexto variable El contexto variable es un conjunto de datos que se integrarán al prompt provenientes de la respuesta de una solicitud POST al punto final confiigurado. La carga útil se envía en formato JSON como se indica (igual que en las herramientas de intención): ``` Method: POST Headers Authorization: Content-Type: application/json; charset=utf-8 Payload { "context_id":"Identificador de contexto variable provisto por la interfaz de Chat", "agent_id":"Id del agente", "agent_name":"Nombre del agente", "chat_id":"Identificador de la conversación que invoca la herramienta", "source_url":"URL desde la que el agente hace la solicitud (opcional)", "user_sid":"Token de sesión que fue suministrado al agente para ser validado", "user":"Id del usuario si está autenticado", "user_name":"Nombre para mostrar del usuario", "data":{ ... Un objeto con los datos especificados en las instrucciones de la intención ...}, "params":{... Un conjunto de pares clave/valor que han sido provistos al agente por la aplicación, página que lo ha invocado o establecidos como constantes a enviar en la configuración del agente... } } ``` Los datos de respuesta no requieren un formato específico porque serán devueltos tal cual al usuario como respuesta o bien, volverán a ser procesados por el LLM con el prompt de la intención antes de ser devueltos.