| Complemento | Agentes IA - Avanzado |
El generador de integraciones es una herramienta avanzada que, sin necesidad de programación, le permite conectar su agente IA a cualquier API o fuente de datos aunque no posea grandes competencias técnicas o de programación. Puede usar contenidos dinámicos para personalizar sus chats y mejorar las resoluciones automatizadas.
Imagine un agente IA con capacidad para acceder sin dificultad a la información del cliente que contiene su sistema de back office, recuperar datos de cualquier otra fuente de datos externa o interactuar con aplicaciones de terceros, todo ello sin necesidad de escribir una sola línea de código.
Con su capacidad para usar contenido dinámico, el generador de integraciones permite recuperar, analizar y transformar datos en tiempo real, lo que capacita a su agente IA para ofrecer respuestas, recomendaciones y soluciones personalizadas basadas en las necesidades específicas de los usuarios.
Gracias a su interfaz fácil de usar, sus funciones intuitivas y las funcionalidades que no precisan de programación, el generador de integraciones ofrece una flexibilidad y personalización máximas sin necesidad de grandes conocimientos técnicos.
En este artículo exploraremos las características y ventajas principales del generador de integraciones, y ofreceremos una guía paso a paso sobre cómo aprovechar sus capacidades para conectar su agente IA a cualquier API o fuente de datos.
Primeros pasos
Para acceder al generador de integraciones, simplemente haga clic en "Integraciones de API" en el menú de navegación lateral. Se abrirá una lista de información general donde aparecerán y estarán accesibles todas sus futuras integraciones. Al principio comenzará sin integraciones de API o con una integración de API de ejemplo, dependiendo de su estrategia de integración.
Para crear una integración nueva, haga clic en "Agregar integración", en la esquina superior derecha.
Ingrese un nombre para la integración.
Agregue una descripción breve con contexto adicional.
Cuando termine, haga clic en "Guardar" para ir a la página de configuración de la integración.
Si no puede ver las integraciones de API en la navegación lateral, seguramente se debe a que usted no es un Administrador de clientes. Actualmente solo tienen acceso al generador de integraciones los administradores de clientes. En ese caso, contacte con su representante de cuenta para consultar sus derechos de acceso.
Si el formato audiovisual le resulta más didáctico, vea el vídeo introductorio de Chloe, miembro de nuestro equipo de ingeniería personalizada:
Solicitar parámetros
Para empezar, debe configurar los parámetros de solicitud necesarios para garantizar una respuesta correcta de la API. Estos parámetros de solicitud contienen información obtenida de la conversación y permiten definir los detalles de la solicitud a la API. Por ejemplo, si desea recuperar información de un usuario concreto para mostrarla durante la conversación, es esencial incluir el ID de usuario en la solicitud. Esto garantiza que la respuesta de la API contenga datos relevantes para el usuario o visitante actual que participa en el chat.
A continuación se muestra un ejemplo de un parámetro de solicitud configurado.
Además de especificar la clave y el tipo de parámetro de solicitud, tiene la posibilidad de establecer un valor de prueba. Es muy recomendable hacerlo, ya que este valor se utilizará durante la configuración al usar la funcionalidad de prueba, a la que se accede en la esquina superior derecha. Durante una conversación real en vivo, el valor se pasará a la integración de la API antes de realizar la solicitud. Sin embargo, dado que no conocemos el contexto de la conversación en vivo actual, es necesario establecer un valor de prueba para realizar correctamente una llamada a la API.
La casilla de verificación "Requerido" permite determinar si el parámetro de solicitud es opcional o si se debe obtener antes de llamar a las integraciones de la API en la conversación, si aún no se ha guardado en la sesión.
La inclusión de parámetros de solicitud depende de los requisitos concretos de la API a la que se llama. En algunas API, los parámetros de solicitud se agregan a la URL, mientras que en otras se incluyen en los encabezados o en el cuerpo de la solicitud. Consulte la documentación de su API para determinar dónde debe incluirse el parámetro de solicitud. Una vez identificado el parámetro de solicitud, puede agregarlo a la URL, el encabezado o el cuerpo simplemente haciendo referencia a la clave incluida entre llaves dobles: {{userID}}.
Entornos
Una vez agregado el parámetro de solicitud, la configuración principal para la llamada a la API se puede realizar dentro de la sección Entorno. Junto al nombre del entorno, que aparece durante las pruebas de integración o cuando se hace referencia a él en el generador de diálogo, debe elegir el método, la URL y el tipo de autorización basándose en la documentación de la API subyacente.
Tipo de autorización
Ofrecemos los siguientes tipos de autorización:
| Tipo de autorización | Descripción | Ejemplo |
| Clave API | Una clave de API simple que debe facilitar el dueño de la API. |  |
| Token de portador | Otro token que debe ser proporcionado por el dueño de la API. |  |
| Autenticación básica | Un nombre de usuario y una contraseña que se usan para la autenticación con la API. |  |
| OAuth 2.0 | Se necesitan varios datos de autenticación que dependen del tipo de concesión. |  |
| Personalizadas | Autorización mediante token de vencimiento | Consulte Uso de la autorización personalizada con el generador de integraciones. |
Recuerde incluir el token de autorización en la solicitud agregándolo como {{apiToken}} a los encabezados para todos los tipos de autorización (a menos que no sea necesaria ninguna autorización). Puede ver un ejemplo en la sección de encabezado.
Encabezados
Los encabezados contienen información adicional sobre la solicitud o sobre la comunicación entre el cliente y el servidor. Son pares clave-valor incluidos en la sección de encabezado de la solicitud. Algunos de los encabezados más utilizados son:
- Content-Type: indica el formato de los datos en el cuerpo de la solicitud (p. ej., JSON, XML, datos de formulario).
- Authorization: proporciona credenciales o tokens para autenticar al cliente que realiza la solicitud.
- User-Agent: especifica el agente de usuario que inicia la solicitud, que normalmente es el navegador web o la aplicación cliente.
- Accept: informa al servidor sobre los formatos de respuesta aceptados por el cliente.
- Cache-Control: define las directivas de memoria caché para el servidor o las memorias caché intermedias.
- X-Requested-With: identifica el tipo de solicitud (por ejemplo, XMLHttpRequest, Fetch API) realizada por el cliente.
Cuerpo
El cuerpo de una solicitud de API contiene los datos enviados a la API. Suele utilizarse en solicitudes que requieren datos de entrada para su procesamiento o manipulación por parte de la API. El cuerpo puede contener varios formatos, como JSON, XML, texto sin formato o datos de formulario, en función de la API y del extremo específico al que se llame. En nuestro caso, de momento solo se admite JSON.
Administración de entornos
Para abordar los desafíos del manejo de entornos sandbox y de producción en las API, hemos incorporado el concepto de entornos en el generador de integraciones. Además del entorno principal predeterminado, que se crea automáticamente al configurar una integración, existe la posibilidad de incluir entornos adicionales.
Dichos entornos adicionales ayudan a personalizar la URL, los detalles de autenticación, los encabezados y el cuerpo de las solicitudes, lo que permite concentrarse en entornos sandbox o de producción específicos dentro de la API.
Para crear un entorno, basta con hacer clic en el botón "+" situado junto a la sección Entorno. Si desea replicar un entorno existente, pase el mouse por encima y elija la opción "duplicar" del menú de tres puntos. Tenga en cuenta que solo se puede establecer un entorno como predeterminado, que se colocará al principio de la lista y se seleccionará automáticamente en primer lugar en el generador de diálogo (a menos que se modifique deliberadamente).
Si un entorno no está siendo utilizado por ningún agente IA, y no es el único entorno ni el predeterminado, se puede borrar. Para modificar la configuración predeterminada, puede seleccionar la opción pertinente en el menú de tres puntos.
Funcionalidad de prueba
Después de completar la configuración de la solicitud de API, es conveniente verificar si todas las configuraciones se realizaron correctamente. Para facilitar este proceso, el generador de integraciones ofrece una práctica función de prueba situada en la esquina superior derecha.
El botón de prueba se puede identificar fácilmente por la etiqueta "Prueba" seguida del nombre del entorno predeterminado. Al presionarlo, el generador de integraciones envía una solicitud a la API utilizando la información proporcionada en las secciones de parámetros de solicitud y de entorno. La respuesta recibida de la API se muestra en la sección Probar integración, en la parte derecha de la interfaz. Si desea probar la API haciendo uso de los detalles de la solicitud desde un entorno diferente, solo tiene que seleccionar el entorno deseado en el menú desplegable de la funcionalidad de prueba y presionar otra vez el botón de prueba.
Contenido de la respuesta
En la sección Probar integración, el generador de integraciones presenta la respuesta obtenida de la API. El contenido de la respuesta está organizado en los siguientes objetos:
| Objetos | Contenido | Ejemplo |
| statusCode | Los códigos de estado de respuesta HTTP indican si una solicitud HTTP concreta se ha completado con éxito. Más información. | "statusCode": 200 |
| data | El objeto de datos muestra los datos relevantes de la API si la solicitud tiene éxito. De lo contrario, proporciona información adicional basada en los códigos de estado correspondientes. |
"data": { "name": "Germany", "capital": "Berlin", "region": "Europe", "population": 83240525, "area": 357114 } |
| requestParameters | Dentro del objeto requestParameters, el generador de integraciones expone los parámetros de la solicitud junto con los valores de prueba asociados que se emplean para llamar a la API. |
"requestParameters": { "country": "de"} |
Antes de volver a utilizar la funcionalidad de prueba para examinar la integración con cambios en la configuración, asegúrese de guardar la integración.
Escenarios
Cada integración recién creada incluye tres escenarios preconfigurados. Dos de estos escenarios pueden personalizarse o eliminarse en función de la necesidades del usuario, pero el tercero, denominado "Fallback" (Opción alternativa), no puede editarse. El escenario "Fallback" es la opción alternativa principal si no se dispara ninguno de los escenarios anteriores.
| Escenario | Consulta predeterminada | Descripción |
| Success | statusCode >= 200 y statusCode < 300 | El escenario que debe capturar la ruta preferida/correcta si el código de estado está comprendido entre 200 y 300. |
| Error | statusCode < 200 o statusCode >= 300 | El escenario que debe capturar la ruta incorrecta si el código de estado está fuera del intervalo 201-299. |
| Fallback | - | Escenario de opción alternativa para desencadenar siempre un escenario como mínimo. |
Los escenarios son equivalentes a las diferentes ramas que sigue la conversación en el diálogo cuando se activa la integración de la API.
Consultas de escenario
Solo se puede activar un escenario por cada integración de API. La lógica para determinar qué escenario se disparará durante una conversación se basa en las consultas de escenario y en el orden en que se definen los escenarios.
Las consultas de escenario representan las condiciones que deben cumplirse para desencadenar un escenario concreto. Para determinar si una condición es verdadera, el generador de integraciones examina la consulta de escenario, además de los datos que contiene la respuesta de la API. Los campos de datos que se utilizan habitualmente incluyen códigos de estado, datos específicos de la API dentro del objeto de datos de la respuesta de la API y, posiblemente, incluso valores de los parámetros de la solicitud.
La consulta de escenario pretederminada del escenario Success requiere que el código de estado de la respuesta de la API esté comprendido dentro del intervalo de 200 a 300. Si se cumple esta condición, se activará el escenario Success.
Dado que las consultas de escenario predeterminadas pueden modificarse y se pueden agregar escenarios nuevos, es posible que den un resultado verdadero varias consultas de escenario diferentes en función de la respuesta de la API. En estos casos, el orden de los escenarios determina qué escenario se disparará.
Para ofrecer información visual, hemos implementado una función que indica qué escenario se dispararía en función de la respuesta actual de la API. También identifica los escenarios que teóricamente deberían dispararse, pero que en realidad no lo hacen porque se dispara un escenario de orden superior. Además, destaca los escenarios que no se dispararían porque no se cumplen sus condiciones.
| Los criterios coinciden | Visualización | Descripción |
| Los criterios coincidentes son los primeros en el orden |  |
El escenario resaltado con un punto sólido azul representa el escenario que se activará. |
| Los criterios no coinciden |  |
Los escenarios marcados con un punto hueco no se dispararán. |
| Los criterios coinciden pero no son los primeros en el orden |  |
El escenario o escenarios representados por un punto sólido gris solo se dispararían teóricamente. |
Para cambiar el orden de los escenarios, basta con hacer clic en un escenario y arrastrarlo para reorganizar el orden. El escenario Fallback siempre permanece en la última posición, pero puede ajustar el orden de los demás en función de sus preferencias.
Parámetros de sesión
Cuando configure un escenario, tiene la posibilidad de mejorar la conversación con varios puntos de datos de sus sistemas backend. Puede especificar los datos que desea tener accesibles para cada escenario si transforma y almacena la información relevante de la respuesta de la API en parámetros de sesión. Dichos parámetros se pueden usar luego durante la generación de diálogos para presentar información a los visitantes o mapear el flujo de trabajo subyacente.
Un parámetro de sesión se define mediante un par clave-valor. La clave sirve como referencia dentro del generador de diálogo, mientras que la consulta se emplea para transformar y extraer datos específicos de la respuesta de la API para guardar el valor. El generador de integraciones proporciona comentarios en tiempo real sobre cómo aparecerá el valor guardado, en función de la respuesta actual, en el campo de valor de respuesta.
En la imagen anterior, la clave del parámetro de sesión se define como "capital" y se puede hacer referencia a ella dentro del generador de diálogo mediante llaves: {{capital}}. La consulta determina qué datos se deben transformar y guardar como valor del parámetro de sesión. En este caso, extrae el contenido del campo "capital" dentro del objeto de datos de la respuesta de la API.
Lenguaje de consulta: JSONata
JSONata se usa como lenguaje de consulta tanto para consultas de escenario como de parámetros de sesión. Su diseño se basa en el principio de que las consultas sencillas deben ser fáciles de programar, de modo que estén al alcance de profesionales con distintos niveles de conocimientos técnicos. JSONata es fácil de aprender, se puede dominar en poco tiempo y permite ejecutar funciones básicas, transformar fechas e incluso fusionar diferentes puntos de datos.
JSONata es un lenguaje de consulta y transformación cuya documentación pública puede consultarse aquí.
0 comentarios
Iniciar sesión para dejar un comentario.