Basic concepts

Create a skill

To create a dialog skill, we need to go to the skills section and click on the button .

You will be shown a window to fill in the necessary information to create the skill. In this case, we should select the skill type as Dialog.

Field	Description	Value
Title	Name of the skill. Preferably in lowercase and without spaces.	my-first-dialog
Description	Brief description of the skill. Must be provided in each of the supported languages.	This is my first skill.
Type	Type of skill. Search or dialog.	Dialog
Languages	List of languages supported by the skill.	English and Spanish
Tags	List of tags related to the skill.
Access Mode	Select the access mode to the skill. Public access or members-only.	Public access
Members	List of members who have access to the skill and their associated privileges.

When you click on the Create button, the operation will be carried out, and it will show us the detail page of our newly created skill, ready for us to work on it.

At the top, there are several tabs that allow us to navigate through the different sections that make up our skill. Below, we'll discuss each of them to understand how to work on our dialog skill.

Conversation

This section is the most important for our skill. Here, we will establish the behavior of our skill by defining the workflow through a series of steps. On the right-hand side, we see a sidebar showing us other information associated with the skill in the form of cards.

tip

You can define your texts in different languages whenever you see a field that allows it; you can do so using the language selection buttons.

Sidebar

In the sidebar, we will be able to view and edit basic information associated with our skill.

Title: This is the title of the skill. It is useful for identifying it and understanding its purpose. It is recommended to use lowercase letters and no spaces. Description: Brief description of the skill. This field is important because it will help our LLM-based bots understand when and why they should use this skill. Languages: List of languages supported by the skill. Access mode and members: Access method for this skill. If you wish to limit access to this skill, you can select Members only and add users and their permissions to the list. Bootstrap intents: List of words or phrases that will help the bot identify when to call this skill. Tags: List of tags associated with the skill. Variables: List of variables associated with the skill. Variables are useful if we want to store information needed in our list of steps. For example, if we need to make an HTTP API call and need to send an authorization token, we can save that token as a variable. To use a variable in our steps, we must use the following syntax: {{variables.apikey}}.

Steps

This is where we will create and modify our workflows by inserting and modifying the steps that will constitute the conversation. Ainhoa has different types of steps with which we can carry out different actions. To add a new step to our skill, we click on the button and select the type of step we want to add.

All steps have the following common fields:

• Step Title: Name assigned to the step for identification. It should be in lowercase and without spaces.
• Condition: This field allows us to establish a condition that must be met to execute the step. If we do not set any condition, it will be executed always.
• Next Step: We can establish what will happen once the step is executed. We can choose between Continue, Finish, or Wait.

We also have arrow buttons to order our steps.

tip

You have more options available for a skill by clicking on the more options button . You can clone, delete, or insert below a new step.

Below, we will see each of the different types of steps we have and how to use them.

Say

If we want our bot to display one or several messages to the user, we must use the Say step and provide the text we want it to display. The text field of the messages can be defined in multiple languages.

Ask

We can have our skill gather information from the user using the Ask step. We need to provide the following information:

• Ask: Text of the question or questions we want to ask the user. This field can be specified in multiple languages.
• Options: If we want to establish a list of predefined answers, such as Yes or No, we should set them here. It is not mandatory as the text provided by the user is always saved.
• Min score: If we set a list of predefined options, we can set a minimum confidence score in the user's response to accept it as valid.
• Save to: Name of the entity where we want to save the user's response. We can also specify the type of the entity: String, Integer, Numeric, Date.

tip

When we save an entity as the user's response to a question, we can use that entity in other steps using the following syntax: {{@name.value}}.

Call API

If we need to integrate with other systems, we can make HTTP calls using the Call API step. This step is very useful and powerful as it allows us to send and receive information provided by the user to perform other tasks such as, for example, setting an event in the calendar, opening a support ticket, or getting information about the status of a project.

We must provide the following information:

• URL: URL of the destination service and type of call to be made: GET, POST, or PUT.
• Headers: If it is necessary to send any headers when making the call, they must be provided here. For example, if the destination service requires an API KEY or an authentication token.
• Content Type: If the call is of type POST or PUT, the content type to be sent must be established. This field will be used in the Content-Type of the HTTP call. For example: application/json.
• Body: If the call is of type POST or PUT, the content to be sent in the body of the HTTP call must be indicated.
• Save to: Name of the entity where the response from the HTTP service will be saved. We can also specify the type of the entity: String, Integer, Numeric, Date.

tip

If the response from the service is of type JSON, we can access the different fields of the response using the following syntax: {{@response:body:field1.value}}.

External skill

This step allows us to integrate other skills that we have previously created in Ainhoa into our conversation flows.

We must provide the following information:

• Skill: Name of the skill we want to call.
• Forward: Indicates whether we should forward the user's text to the skill or send a different text that we can provide instead. This field can be specified in multiple languages.

Go to

With this step, we can change the flow of our conversation by jumping to another already defined step. We simply specify which step we should go to.

Assign

We can assign a specific value to an entity or to the Output variable. This is useful for passing values to other steps.

info

By setting a value in Output, we are telling our bot to use that value to provide the response to the user.

Call LLM

Through this step, we can use one of our services registered in Ainhoa to pass instructions to an LLM and have it perform a given task.

We must provide the following information:

• Service connection: We will select the LLM service type that we want to use in this step. It must be previously configured in Ainhoa.
• Max tokens per response: We will establish the maximum number of tokens to be used to provide the response.
• Temperature: The temperature we want to use in our call to the LLM service. Values between 0 and 1. Values closer to 0 will provide more precise and deterministic responses, while values closer to 1 will provide more creative and random responses.
• Prompt: The prompt we want to send with our instructions to the LLM service. This field can be specified in multiple languages.
• Assign to: Name of the entity where the response from the LLM service will be saved.

Event

If we want to provide information that provides context or helps the user understand what our conversational flow is doing, we can send an event that the bot can display to the user. We simply need to specify which message or messages we want to show. Messages can be specified in multiple languages.

Intents

Intents are very useful for establishing predefined responses that the user can select in the conversation or for quickly identifying the user's goal or purpose. Intents allow the bot to interpret the meaning of user inputs, even if it is not expressed clearly or directly, thus enabling it to select the most appropriate response.

We can define all the intents we need from the Intents tab. To define an intent, we must provide a keyword and write one or more associated values for that intent in the different languages enabled in our skill.

The keyword of the intent allows us to establish conditions in our conversational flow in a very simple way.

We can use the defined intents to establish response options in the Ask step and use that intent as a condition in some subsequent step.

Intents	Ask step

Parameters

In Ainhoa, skills are used to expand the catalog of functions available to our bots. To facilitate the use of these functions by our bots, we can specify input parameters for our functions. With these parameters, we are telling our bot what information it needs to carry out its function.

For example, we could create a function that provides information about a specific flight, and as parameters, we would need to provide the flight number and the departure date, or a function that provides the weather in a city, where the city would be the parameter.

We can define all the parameters we need from the Parameters tab. To define a parameter, we must provide the following information:

• Name: Name of the parameter. It will be used to reference it later in our steps. It should be in lowercase and without spaces.
• Type: Specifies the data type of the parameter. Possible values are: String, Number, and Boolean.
• Required: Specifies whether the field is mandatory or not.
• Description: Brief description of the parameter. This information is very useful for our bot to understand why it needs this parameter. This field can be specified in multiple languages.
• Values: You can specify a list of possible default values.

Once we have created our parameter, we can use it in our steps with the following syntax: {{@parameters:city.value}}.

info

In Ainhoa, all entities that we use in our steps will be accessible using the syntax: {{@entity.value}}. If the entity is a hierarchical object, for example, a JSON object, we can access its different fields in the following way: {{@entity:field1.value}}.

In the entities, we can also perform data conversion operations. We can do this by using a suffix to specify the desired data type. The available conversions are as follows:

• value: Returns the value as a string. Example: {{@entity.value}}.
• bool: Converts the value to boolean. Example: {{@entity.bool}}.
• number: Converts the value to a number. Example: {{@entity.number}}.
• datetime: Returns the value in date and time format. Example: {{@entity.datetime}}.
• date: Returns only the date part of the value. Example: {{@entity.date}}.
• time: Returns only the time part of the value. Example: {{@entity.time}}.

Variables will be accessible using the following syntax: {{variables.apikey}}.

Source code

You can review the source code associated with your skill in the Source Code tab. This code comprises all the information about the skill and is used to keep track of the changes made over time.

tip

Expert users familiar with YAML language can use the advanced editor in Ainhoa to edit the source code of a skill instead of using the graphical interface.

Test skill

Ainhoa has tools to help you test and debug your skills, check behavior with different identities, audiences, and languages. All of this can be done in the Test Skill tab.

In this tab, we have a chat window (2) to directly test the skill and a debug window (3) where we can see logging information associated with each message sent or received from the skill. We also have a toolbar (1) for various configurations. Let's go through each section in more detail.

1. Toolbar

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. Chat window

Once we have made the desired adjustments on the toolbar, we can perform our tests directly in the chat window. This simulates a bot with our configured skill.

3. Debug window

In the debug window, you can review, by clicking on a message, the logging information provided by the skill about that message.

History

In the History tab, you will have access to all the versions associated with the skill. Ainhoa creates a different version every time a change is made to a published version. This allows you to track all the changes you have made to your skill and, if necessary, revert to a previous version.

If your skill is in draft status, all changes you make will be saved in the latest version of the skill and no new versions will be created.

You can see a paginated list of all versions of your skill ordered by modification date. For each of them, you have a menu of actions.

The actions you can perform on the different versions are as follows:

• Train Snapshot: Allows training the selected version of the skill.
• Publish Snapshot: Allows publishing the selected version of the skill.
• Create New Version: Allows creating a new version based on the selected version.
• Compare with Current: Show the changes made between the selected version and the current one.
• Compare with Previous: Show the changes made between the selected version and the previous one.
• Test Skill: Allows testing and debugging the selected version in the same way as in the Test Skill tab.
• Retire Snapshot: Allows disabling the selected version of the skill.
• Delete Snapshot: Permanently deletes the selected version of the skill.

info

Ainhoa has a powerful version comparator so that you can easily check the different changes that occurred between two versions of the skill at a glance.