Conceptos básicos

Crear una habilidad

Para crear una habilidad de diálogo, debemos ir a la sección de habilidades y hacer click en el botón .

Se nos mostrará una ventana para rellenar la información necearia para crear la habilidad. En éste caso debemos seleccionar el tipo de habilidad Diálogo.

Campo	Descripción	Valor
Título	Nombre de la habilidad. Preferiblemente en minúsculas y sin espacios.	my-first-dialog
Descripción	Breve descripción de la habilidad. Debe ser proporcionada en cada uno de los idiomas soportados.	Esta es mi primera habilidad.
Tipo	Tipo de habilidad. Búsqueda o diálogo.	Diálogo
Idiomas	Lista de idiomas soportados por la habilidad.	Inglés y español
Etiquetas	Lista de etiquetas relacionadas con la habilidad.
Modo de acceso	Selecciona el modo de acceso a la habilidad. Acceso público o lo miembros.	Acceso público
Miembros	Lista de miembros que tienen acceso a la habilidad y sus privilegios asociados.

Al hacer click en el botón Crear, se llevará a cabo la operación y nos mostrará la página de detalle de nuestra habilidad recien creada, lista para que podamos trabajar en ella.

En la parte superior aparecen una serie de pestañas con las que podremos navegar por las diferentes secciones que componen nuestra habilidad. A continuación, comentaremos cada una de ellas para conocer como trabajar en nuestra habilidad de diálogo.

Conversación

Ésta sección es la más importante para nuestra habilidad. Aquí estableceremos el comportamiento de nuestra habilidad definiendo el flujo de trabajo mediante una serie de pasos. En la parte de la derecha vemos una barra lateral en la que se nos muestra en forma de tarjetas otra información asociada con la habilidad.

tip

Puedes definir tus textos en diferentes idiomas cuando veas un campo que lo permite, podrás hacerlo utilizando los botones de selección de idioma.

Barra lateral

En la barra lateral podremos ver y editar información básica asociada a nuestra habilidad.

Título: Este es el título de la habilidad. Es útil para identificarla y conocer su propósito. Se recomienda utilizar letras en minúscula y sin espacios. Descripción: Breve descripción de la habilidad. Este campo es importante porque ayudará a nuestros bots basados en LLM a entender para qué y cuándo debe utilizar esta habilidad. Idiomas: Lista de idiomas que serán soportados por la habilidad. Modo de acceso y miembros: Método de acceso a esta habilidad. Si deseas limitar el acceso a ésta habilidad puedes seleccionar Solo miembros y añadir los usuarios y sus permisos a la lista. Intenciones de arranque: Lista de palabras o frases que ayudarán al bot a identificar cuando debe llamar a ésta habilidad. Etiquetas: Listado de etiquetas asociadas con la habilidad. Variables: Listado de variables asociados con la habilidad. Las variables son útiles si queremos guardar información que necesitemos en nuestro listado de pasos, por ejemplo, si necesitamos realizar una llamada a una API mediante HTTP y debemos enviar un token de autorización, podemos guardar dicho token como una variable. Para utilizar una variable en nuestos pasos debemos utilizar la siguiente sintaxis: {{variables.apikey}}.

Pasos

Aquí es donde crearemos y modificaremos nuestros flujos de trabajo mediante la insercion y modificacion de los pasos en los que constará la conversación. Ainhoa dispone de diferentes tipos de pasos con los que podremos llevar a cabo diferentes acciones. Para añadir un nuevo paso a nuestra habilidad hacemos click en el botón y seleccionamos el tipo de paso que deseamos añadir.

Todos los pasos tienen los siguientes campos comunes:

• Título del paso: Nombre asignado al paso para su identificación. Debe estar en minúsculas y sin espacios.
• Condición: Este campo permite establecer una condicíon que debe cumplirse para ejecutar el paso. Si no establecemos ninguna condición se ejecutará siempre.
• Siguiente paso: Podemos establecer que sucecerá una vez que se ejecute el paso. Podemos elegir entre Continuar, Finalizar o Esperar.

También disponemos de botones de flechas para ordenar nuestros pasos.

tip

Tienes más opciones disponibles sobre una habilidad pulsando en el botón de más opciones . Podrás clonar, borrar o insertar debajo un nuevo paso.

A continuación veremos cada uno de los diferentes tipos de pasos que disponemos y como utilizarlos.

Decir

Si queremos que nuestro bot muestre uno o varios mensajes al usuario debemos usar el paso Decir y proporcionar el texto que queremos que muestre. El campo de texto de los mensajes puede definirse en múltiples idiomas.

Preguntar

Podemos hacer que nuestra habilidad obtenga información del usuario mediante el paso Preguntar. Debemos proporcionar la siguiente información:

• Preguntar: Texto de la pregunta o preguntas que deseamos hacerle al usuario. Este campo puede especificarse en múltiples idiomas.
• Respuesta: Si queremos establecer una lista de respuestas predefinidas, como puede ser Sí o No, debemos establecerlas aquí. No es obligatorio ya que siempre se guarda el texto proporcionado por el usuario.
• Puntuación mínima: Si establecemos una lista de opciones predefinidas, puedes establecer una puntuación mínima de confianza en la respuesta establecida por el usuario para aceptarla por válida.
• Guardar en: Nombre de la entidad donde queremos guardar la respuesta del usuario. Podemos especificar también el tipo de la entidad: Cadena, Entero, Númerico, Fecha.

tip

Cuando guardamos una entidad como la respuesta del usuario a una pregunta. Podemos utilizar dicha entidad en otros pasos mediente la siguiente sintaxis: {{@name.value}}.

Llamar API

Si necesitamos realizar integraciones con otros sistemas podemos realizar llamadas HTTP mediante el paso Llamar API. Éste paso es muy útil y potente ya que nos permitirá enviar y recibir información proporcionada por el usuario para poder realizar otras tareas como, por ejemplo, establecer un evento en el calendario, abrir un ticket de soporte u obtener información sobre el estado de un proyecto.

Debemos proporcionar la siguiente información:

• URL: Url del servicio de destino y tipo de llamada a realizar: GET, POST o PUT.
• Cabeceras: Si es necesario enviar alguna cabecera al realizar la llamada, se deben proporcionar aquí. Por ejemplo, si el servicio de destino necesita una API KEY o un Token de autenticación.
• Tipo de contenido: Si la llamada es de tipo POST o PUT. Se debe establecer el tipo de contenido que se va a enviar. Este campo se utilizará en el Content-Type de la llamada HTTP. Por ejemplo: application/json.
• Cuerpo: Si la llamada es de tipo POST o PUT, se debe indicar el contenido que se enviará en el campo Body de la llamada HTTP.
• Guadar en: Nombre de la entidad donde se guardará la respuesta del servicio HTTP. Podemos especificar también el tipo de la entidad: Cadena, Entero, Númerico, Fecha.

tip

Si la respuesta del servicio es de tipo Json, podemos acceder a los diferentes campos de la respuesta mediante la siguiente sintaxis: {{@response:body:field1.value}}.

Habilidad externa

Éste paso permite integrar en nuestros flujos de conversación a otras habilidades que hayamos creado previamente en Ainhoa.

Debemos proporcionar la siguiente información:

• Habilidad: Nombre de la habilidad a que deseamos llamar.
• Reenviar: Indica si debemos reenviar el texto del usuario a la habilidad o por el contrario enviar otro texto diferente que podemos proporcionar. Este campo puede especificarse en múltiples idiomas.

Ir a

Con este paso podemos cambiar el flujo de nuestra conversación saltando a otro paso ya definido. Simplemente especificamos a que paso deberiamos ir.

Asignar

Podemos asignar un valor concreto a una entidad o a la variable Output. Esto es útil para pasar valores a otros pasos.

info

Al establecer un valor en Output le estamos indicando a nuestro bot que utilice ese valor para proporcionar la respuesta al usuario.

Llamar a LLM

Mediante éste paso podremos utilizar alguno de nuestros servicios registrados en Ainhoa para pasarle instrucciones a un LLM y que realice una tarea dada.

Debemos proporcionar la siguiente información:

• Conexión de servicio: Seleccionaremos el servicio de tipo LLM que deseamos utilizar en este paso. Debe esta previamente configurado en Ainhoa.
• Tokens máximos por respuesta: Estableceremos el número máximo de tokens que se utilizará para proporcionar la respuesta.
• Temperatura: Temperatura que deseamos utilizar en nuestra llamada al servicio LLM. Valores entre 0 y 1. Los valores cercanos a 0 proporcionarán respuestas mas precisas y deterministas, en cambio, valores mas cercanos a 1 proporcionarán respuestas mas creativas y aleatorias.
• Prompt: El prompt que deseamos enviar con nuestras instrucciones al servicio de LLM. Este campo puede especificarse en múltiples idiomas.
• Asignar a: Nombre de la entidad en la que se guardará la respueta del servicio LLM.

Evento

Si deseamos proporcionar información que proporcione contexto o ayude al usuario a entender qué está realizando nuestro flujo conversacional podemos enviar un evento que el bot podrá mostrar al usuario. Simplemente debemos establecer qué mensaje o mensajes debemos mostrar. Los mensajes pueden especificarse en múltiples idiomas.

Intenciones

Las intenciones son muy útiles para establecer respuestas predefinidas que el usuario puede seleccionar en la conversación o para identificar de manera rápida el objetivo o la finalidad del usuario. Las intenciones permitirán al bot interpretar el significado de la entradas de usuario, incluso si no lo expresa de forma clara o directa, permitiendo así seleccionar la respuesta mas adecuada.

Podemos definir todas las intenciones que necesitemos desde la pestaña Intenciones. Para definir una intención debemos proporcionar una palabra clave y escribir uno o varios valores asociados a dicha intención en los diferentes idiomas que estén habilitados en nuestra habilidad.

La palabra clave de la intención nos permtirá establecer condiciones en nuestro flujo conversacional de una manera muy sencilla.

Podemos utilizar las intenciones definidas para establecer opciones de respuesta en el paso Preguntar, y utilizar dicha intención como condición en algún paso posterior.

Intenciones	Paso preguntar

Parámetros

En Ainhoa las habilidades sirven para ampliar el catálogo de funciones del que disponen nuestros bots. Para facilitar el uso de éstas funciones a nuestros bots podemos especificar párametros de entrada para nuestras funciones. Con dichos parámetros estaremos indicando a nuestro bot qué información necesita para llevar a cabo su función.

Por ejemplo, podriamos crear una función que proporcione información sobre un determinado vuelo y como párametro deberemos proporcionar el número de vuelo y la fecha de salida o una función que proporcione el tiempo que hace en una ciudad, la ciudad sería el parámetro.

Podemos definir todos los parámetros que necesitemos desde la pestaña Parámetros. Para definir una parámetro debemos proporcionar la siguiente información:

• Nombre: Nombre del parámetro. Nos servirá para poder referenciarlo posteriormente en nuestros pasos. Debe ser en minúscula y sin espacios.
• Tipo: Especifica el tipo de dato del parámetro. Los valores posibles son: Cadena, Número y Booleano.
• Requerido: Especifica si el campo es obligatorio o no.
• Descripción: Breve descripción del párametro. Ésta información es muy útil para que nuestro bot entienda para que necesita dicho parámetro. Este campo puede especificarse en múltiples idiomas.
• Valores: Puedes especificar una lista de posibles valores predeterminados.

Una vez creado nuestro parámetro, podremos utilizarlo en nuestros pasos con la siguente sintaxis: {{@parameters:city.value}}.

info

En Ainhoa todas las entidades que usemos en nuestros pasos serán accesibles mediante la sintaxis: {{@entity.value}}. Si la entidad es un objecto con jerarquía, por ejemplo, un objeto JSON, podemos acceder a los diferentes campos de dicho objeto de la siguiente manera: {{@entity:field1.value}}.

En las entidades también podemos realizar operaciones de conversión de los datos. Esto lo podemos hacer utilizando un sufijo para especificar el tipo de dato que desamos. Las conversiones disponibles son las siguientes:

• value: Devuelve el valor como cadena. Ejemplo. {{@entity.value}}.
• bool: Convierte el valor a booleano. Ejemplo. {{@entity.bool}}.
• number: Convierte el valor en un número. Ejemplo. {{@entity.number}}.
• datetime: Devuelve el valor en formato fecha y hora. Ejemplo. {{@entity.datetime}}.
• date: Devuelve solo la fecha del valor. Ejemplo. {{@entity.date}}.
• time: Devuelve solo la hora del valor. Ejemplo. {{@entity.time}}.

Las variables serán accesibles mediente la siguiente sintaxis: {{variables.apikey}}.

Código fuente

Puedes revisar el código fuente asociado con tu habilidad en la pestaña Código fuente. Éste código es el que compone toda la información de la habilidad y el que se utiliza para llevar el control de los cambios que se han realizado con el tiempo.

tip

Los usuarios expertos y conocedores del lenguaje YAML pueden utilizar el editor avanzado de Ainhoa para editar el código fuente de una habilidad en vez de utilizar la interfaz gráfica.

Probar habilidad

Ainhoa dispone de herramientas para ayudarte a probar y depurar tus habilidades, comprobar el comportamiento con diferentes identidades, audiencias e idiomas. Todo ello lo podemos hacer en la pestaña Probar habilidad.

En ésta pestaña disponemos de una ventana de chat (2) para probar directamente la habilidad y una ventana de depuración (3) en la que podremos ver información de registro asociado a cada mensaje que se envía o recibe desde la habilidad. También disponemos de una barra de herramientas (1) para realizar diferentes configuraciones. Pasemos a continuación a ver más en detalle cada una de las secciones.

1. Barra de herramientas

La barra de herramientas nos permite realizar diferentes ajustes para probar el comportamiento de nuestra habilidad en diferentes situaciones. Disponemos de los siguientes ajustes:

• Versión de la instantánea: Nos permitirá probar nuestra habilidad en una versión concreta. Esto es muy útil para asegurarnos que nuestra nueva versión se comporta como esperamos antes de publicarla o comparar con otras versiones para comprobar el grado de mejora.
• Identidad: Podremos probar nuestra habilidad suplantando otra identidad. Esto es útil para asegurarse el comportamiento con diferentes usuarios y permisos.
• Idioma: Para asegurarnos que nuestra habilidad tiene configurada correctamente las traducciones podemos cambiar entre los diferentes idiomas disponibles y realizar pruebas.
• Audiencias: Un punto muy importante es la seguridad. Estableciendo diferentes audiencias podremos realizar pruebas de acceso y gestión de permisos en nuestra habilidad.

2. Ventana de chat

Una vez que hemos realizado los ajustes que deseamos sobre la barra de herramientas, podemos realizar nuestras pruebas directamente en la ventana del chat. Esto simula un bot con nuestra habilidad configurada.

3. Ventana de depuración

En la ventana de depuración podrás revisar, haciendo click en un mensaje, la información de regitro que proporciona la habilidad sobre dicho mensaje.

Historial

En la pestaña Historial tendrás acceso a todas las versiones asociadas con la habilidad. Ainhoa crea una versión diferente cada vez que se realiza un cambio sobre una versión publicada. Esto permite que puedas llevar una trazabilidad de todos los cambios que has realizado sobre tu habilidad y de ser necesario volver a una versión anterior.

Si tu habilidad se encuentra en estado borrador, todos los cambios que realizes se guardarán en la última versión de la habilidad y no se crearán nuevas versiones.

Podrás ver en una lista páginada todas las versiones que tiene tu habilidad ordenadas por fecha de modificación. Para cada una de ellas dispones de un menú de acciones.

Las acciones que puedes realizar sobre las diferentes versiones son las siguientes:

• Entrenar instantánea: Permite entrenar la versión seleccionada de la habilidad.
• Publicar instantánea: Permite publicar la versión seleccionada de la habilidad.
• Crear nueva versión: Permite crear una versión nueva basada en la versión seleccionada.
• Comparar con actual: Mostrar los cambios realizados entre la versión seleccionada y la actual.
• Comprara con anterior: Mostrar los cambios realizdos entre la versión seleccionada y la anterior.
• Probar habilidad: Permite probar y depurar la versión seleccionada de la misma manera que se hace en la pestaña Probar habilidad.
• Retirar instantánea: Permite deshabilitar la versión seleccionada de la habilidad.
• Borrar instantánea: Borra definitivamente la versión seleccionada de la habilidad.

info

Ainhoa dispone de un potente comparador de versiones para que puedas comprobar de un simple vistazo los diferentes cambios que se produjeron entre dos versiones de la habilidad.