Alexa has a lot of capabilities, but it is not easy to create a complex conversation. Voiceflow is a tool that allows you to create complex conversations with Alexa without writing code. This integration allows you to create a conversation in Voiceflow and then deploy it to Alexa.
Because of that, In this repository you will find a simple example of how to integrate Alexa with Voiceflow using the Alexa Skills Kit SDK for Node.js and calling the Voiceflow’s Dialog Manager API.
On Voiceflow, you will need to create a project and create a conversation. You can follow the Voiceflow Quick Start to create a simple conversation. On Voiceflow the only thing that you have to care about is to design the conversation.
In this example, we are going to create a simple conversation that asks the user for information about pokemons. The conversation will be like this:
Voiceflow Conversation
Voiceflow has a built-in NLU, since we are going to call Voiceflow using the Dialog Manager API, we will need to design our NLU on Voiceflow and on Alexa.
Following the example, we are going to create an intent called info_intent
and a slot called pokemon
that will be filled with the name of the pokemon that the user wants to know about:
Voiceflow NLU
The Dialog Manager API is a REST API that allows you to interact with Voiceflow. You can find the documentation here.
The DM API automatically creates and manages the conversation state. Identical requests to the DM API may produce different responses depending on your diagram’s logic and the previous request that the API received.
The DM API endpoints is:
https://general-runtime.voiceflow.com/state/user/{userID}/interact
There are different types of requests that can be sent. To see a list of all request types, check out the documentation for the action field below.
To start a conversation, you should send a launch request. Then, to pass in your user’s response, you should send a text request. If you have your own NLU matching, then you may want to directly send an intent request.
Here you have an example of a request:
curl --request POST \
--url 'https://general-runtime.voiceflow.com/state/user/{userID}/interact?logs=off' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'Authorization: VF.DM.96ds3423ds9423fs87492fds79792gf343' \
--data '
{
"action": {
"type": "launch"
},
"config": {
"tts": false,
"stripSSML": true,
"stopAll": true,
"excludeTypes": [
"block",
"debug",
"flow"
]
}
}
'
As you can see, you need to pass the userID
and the Authorization
header. The userID
is the user id that you want to interact with. The Authorization
header is the API key that you can find on the Voiceflow project settings.
You can find the Voiceflow project that I used for this example in voiceflow/project.vf
.
To create an Alexa Skill you need to go to Alexa Developer and create a new skill. You can follow the Alexa Developer Console Quick Start to create a simple skill.
We will need to replicate the Voiceflow NLU (intents and entities) in our Alexa Skill:
Alexa NLU
As you can see, we are using the SearchQuery
type. This type is used to get the user input and send it directly to Voiceflow. You can find more information about this type here.
The Alexa Skill Code is going to be generic, that means that this Alexa Skill Code can be used with any Voiceflow project. To do that, we are going to implement a Lambda function that will call the Voiceflow Dialog Manager API. We are going to use the Alexa Skills Kit SDK for Node.js and Axios to call the API.
We will need to touch only 2 handlers, the LaunchRequestHandler
and the ListenerIntentHandler
. The LaunchRequestHandler
will be used to start the conversation and the ListenerIntentHandler
will be used to send the user input to Voiceflow.
Let’s start with the LaunchRequestHandler
:
const LaunchRequestHandler = {
canHandle(handlerInput) {
return Alexa.getRequestType(handlerInput.requestEnvelope) === 'LaunchRequest';
},
async handle(handlerInput) {
let chatID = Alexa.getUserId(handlerInput.requestEnvelope).substring(0, 8);
const messages = await utils.interact(chatID, {type: "launch"});
return handlerInput.responseBuilder
.speak(messages.join(" "))
.reprompt(messages.join(" "))
.getResponse();
}
};
This Handler is called when the skill is launched. We are going to get the user id and call the Voiceflow Dialog Manager API with the launch
action. Then, we are going to return the response.
The following interactions are going to be handled by the ListenerIntentHandler
:
const ListenerIntentHandler = {
canHandle(handlerInput) {
return Alexa.getRequestType(handlerInput.requestEnvelope) === 'IntentRequest'
},
async handle(handlerInput) {
let chatID = Alexa.getUserId(handlerInput.requestEnvelope).substring(0, 8);
const intent = Alexa.getIntentName(handlerInput.requestEnvelope);
const entitiesDetected = utils.alexaDetectedEntities(handlerInput.requestEnvelope);
const request = {
type: "intent",
payload: {
intent: {
name: intent
},
entities: entitiesDetected
}
};
const messages = await utils.interact(chatID, request);
return handlerInput.responseBuilder
.speak(messages.join(" "))
.reprompt(messages.join(" "))
.getResponse();
}
};
This Handler is called when the user says something. We are going to get the user input and call the Voiceflow Dialog Manager API with the intent
action. Since the NLU Inferece is done by Alexa, we need to get the detected entities and the detected intents and send them to Voiceflow. Then, we are going to return the response.
To get the detected entities, we are going to use the following function:
module.exports.alexaDetectedEntities = function alexaDetectedEntities(alexaRequest) {
let entities = [];
const entitiesDetected = alexaRequest.request.intent.slots;
for ( const entity of Object.values(entitiesDetected)) {
entities.push({
name: entity.name,
value: entity.value
});
}
return entities;
}
You can find the code of this function in lambda/utils.js
.
Finally we have to make sure that we add the handlers to the skill:
exports.handler = Alexa.SkillBuilders.custom()
.addRequestHandlers(
LaunchRequestHandler,
ListenerIntentHandler,
HelpIntentHandler,
CancelAndStopIntentHandler,
FallbackIntentHandler,
SessionEndedRequestHandler,
IntentReflectorHandler)
.addErrorHandlers(
ErrorHandler)
.withCustomUserAgent('sample/hello-world/v1.2')
.lambda();
In the handlers above you can see that we are using a function called utils.interact
. This function is going to call the Voiceflow Dialog Manager API. You can find the code of this function in lambda/utils.js
:
const axios = require('axios');
const VF_API_KEY = "VF.DM.96ds3423ds9423fs87492fds79792gf343";
module.exports.interact = async function interact(chatID, request) {
let messages = [];
console.log(`request: `+JSON.stringify(request));
const response = await axios({
method: "POST",
url: `https://general-runtime.voiceflow.com/state/user/${chatID}/interact`,
headers: {
Authorization: VF_API_KEY
},
data: {
request
}
});
for (const trace of response.data) {
switch (trace.type) {
case "text":
case "speak":
{
// remove break lines
messages.push(this.filter(trace.payload.message));
break;
}
case "end":
{
messages.push("Bye!");
break;
}
}
}
console.log(`response: `+messages.join(","));
return messages;
};
This function is going to return an array of messages. We are going to use this array to build the response. We have also added some code to remove the break lines and weird characters:
module.exports.filter = function filter(string) {
string = string.replace(/\'/g, '\'')
string = string.replace(/(<([^>]+)>)/ig, "")
string = string.replace(/\&/g, ' and ')
string = string.replace(/[&\\#,+()$~%*?<>{}]/g, '')
string = string.replace(/\s+/g, ' ').trim()
string = string.replace(/ +(?= )/g,'')
return string;
};
With this code, we have finished the Alexa Skill. You can find the code of the Lambda function in lambda/index.js
.
Once you have created the Alexa Skill and the Voiceflow project, you can test it. To test it, you can use the Alexa Simulator or you can use a real device.
Following the example we were using, you can test the Alexa Skill with the following sentences to request information about pokemons:
Testing
As you can see, it is very easy to integrate Alexa with Voiceflow. You can create complex conversations with Voiceflow and then deploy them to Alexa. So your focus will be on the conversation and not on the code!
I hope you have enjoyed this tutorial.
You can find the code of this tutorial here.
Happy coding!
]]>En este décimo capítulo de la segunda temporada hablamos sobre las novedades dentro del mundo de Alexa, Dialogflow CX y OpenAI de este pasado mes. Hablamos largo y tendido de los novedades en el ecosistema Alexa:
Posteriormente, hablamos sobre las novedades de Dialogflow CX:
Finalmente, hablamos sobre las últimas novedades de ChatGPT y OpenAI:
¿Te lo vas a perder? ¡Espero que te guste este episodio!
En este noveno capítulo de la segunda temporada hablamos sobre las novedades dentro del mundo de Alexa, Dialogflow CX y Meta de este pasado mes. Hablamos largo y tendido de los novedades en el ecosistema Alexa:
Posteriormente, hablamos sobre las novedades de Dialogflow CX:
Finalmente, hablamos sobre las últimas novedades del Meta Connect:
¿Te lo vas a perder? ¡Espero que te guste este episodio!
En este octavo capítulo de la segunda temporada hablamos sobre las novedades dentro del mundo de Alexa, Dialogflow CX y Voiceflow de este pasado mes.
Hablamos largo y tendido de los novedades en el ecosistema Alexa:
Posteriormente, hablamos sobre las novedades de Dialogflow CX:
Finalmente, hablamos sobre las últimas novedades de Vocieflow:
¿Te lo vas a perder? ¡Espero que te guste este episodio!
En este séptimo capítulo de la segunda temporada hablamos sobre las novedades dentro del mundo de Alexa y Dialogflow CX de este pasado mes. Hablamos largo y tendido de los novedades en el ecosistema Alexa:
Posteriormente, hablamos sobre las novedades de Dialogflow CX:
Finalmente, os cuento mi experencia en el Google IO Connect Amsterdam:
¿Te lo vas a perder? ¡Espero que te guste este episodio!
En este sexto capítulo de la segunda temporada hablamos sobre las novedades dentro del mundo de Alexa y Dialogflow CX de este pasado mes. Hablamos largo y tendido de los novedades en el ecosistema Alexa:
Finalmente hablamos sobre las novedades del Google I/O:
¿Te lo vas a perder? ¡Espero que te guste este episodio!
En este quinto capítulo de la segunda temporada hablamos sobre las novedades dentro del mundo de Alexa y Dialogflow CX de este pasado mes. Hablamos largo y tendido de los novedades en el ecosistema Alexa:
Alexa Widgets finalmente están disponibles para todos los desarrolladores. Explicamos que es el Alexa Radio Kit y su consola no-code. Integración de las Amazon Chime con Alexa Skills para hacer llamadas directamente desde tus dispositivos Alexa Finalmente hablamos sobre las novedades de Dialogflow CX:
Que son los flexible Webhooks y como usarlo en Dialogflow CX. Importar y Exportar intents. Importar y Exportar training phrases. ¿Te lo vas a perder? ¡Espero que te guste este episodio!
En este cuarto capítulo de la segunda temporada hablamos sobre las novedades dentro del mundo de Alexa y Dialogflow CX de este pasado mes. Hablamos largo y tendido de los novedades en el ecosistema Alexa:
Finalmente hablamos sobre las novedades de Dialogflow CX:
En este tercer capítulo de la segunda temporada hablamos sobre las novedades dentro del mundo de Alexa y Dialogflow CX de este pasado mes. Hablamos largo y tendido de los novedades en el ecosistema Alexa:
Finalmente hablamos sobre las novedades de Dialogflow CX y como testear nuestros agentes en la consola:
¿Te lo vas a perder? ¡Espero que te guste este episodio!
Ya está disponible en todas las plataformas de podcasts.
Estas son las tecnologías utilizadas en este proyecto
Testear las conversaciones garantiza que los componentes de un agente funcionen correctamente a un nivel en el que se incluye la infraestructura del agente (como el NLU), el webhook y la integración con sistemas externos.
Un test puede evaluar los componentes de una aplicación a un alto nivel. Podemos utilizar tests para comprobar que dos o más componentes de un agente funcionan y generan el resultado esperado.
Estos tests pueden ejecutarse de forma manual o automatizada en un sistema de integración continua, y se ejecutan en cada nueva versión del agente.
Dialogflow Console es una interfaz web donde puedes diseñar tus conversaciones creando agentes y, dentro de un agente, crear flows, intents, entity types, etc. En la consola de Dialogflow es posible crear tests e interactuar fácilmente con ellos. Para ello, basta con acceder a la URL: https://dialogflow.cloud.google.com/cx. Este es su aspecto:
Dialogflow CX Console
La consola incluye una herramienta realmente útil para testear tu agente de forma manual. Se trata de un simulador en el que puedes interactuar con tu agente para comprobar que la conversación fluye tal y como está previsto. Para empezar a testear tu agente, haz clic en el botón Test Agent en la esquina superior derecha del canvas. Cuando inicies el simulador, deberás elegir el environment, el flow y page que quieres testear. Para interactuar con el simulador puedes simplemente escribir texto y enviarlo al agente, pero también puedes establecer parameters, enviar eventos, etc. Puedes deshacer el último turno de la conversación siempre que quieras.
Una vez que hayas terminado con la interacción manual, puedes:
Simulador de Dialogflow CX
En software, tener diferentes environments en los que los desarrolladores puedan desplegar diferentes versiones de su software es un patrón común (además de una buena práctica). Cada environment cuenta con sus propias configuraciones.
En Dialogflow CX tenemos el mismo concepto. Es posible crear una versión del agente y desplegarla en un environment. Lo mismo ocurre con el webhook: puedes desplegar una versión del webhook y utilizar esa versión en un environment.
Cuando guardas una conversación que has realizado en el simulador como un caso de test, puedes añadirla a un pipeline de integración continua de un environment específico. Encontrarás tus pipelines CI/CD en la pestaña Manage al hacer clic en la sección CI/CD CI/CD:
Dialogflow CX CICD
La Dialogflow CX CLI o cxcli
ies una herramienta de línea de comandos que puedes utilizar para interactuar con tus proyectos en Dialogflow CX en un terminal. Es un proyecto de código abierto creado por Xavier Portilla Edo. Con la cxcli
y puedes interactuar fácilmente con tus pipelines en Dialogflow CX.
Con la cxcli
puedes también interactuar fácilmente con los pipelines CI/CD de los environments de tus agentes en Dialogflow CX.
Puedes encontrar el uso del comando CI/CD en el comando cxcli environment execute-cicd
. Puedes leer la documentación sobre este comando aquí.
cxcli environment execute-cicd [environment] [parameters]
Este es un ejemplo simple del comando cxcli environment execute-cicd
:
cxcli environment execute-cicd cicd-env --project-id test-cx-346408 --location-id us-central1 --agent-name test-agent
El comando anterior te proporcionará un output como este:
$ cxcli environment execute-cicd cicd-env --project-id test-cx-346408 --location-id us-central1 --agent-name test-agent
INFO Executing cicd for environment cicd-env
INFO PASSED
Utiliza el NLU Profiler para testear los utterances de los usuarios y mejorar el modelo de interacción de tu agente.
Con el NLU Profiler puedes comprobar cómo se resuelven los utterancces con los intents y slots de tu modelo de interacción. Si un utterance no se resuelve con el intent o slot correcto, puedes actualizar el modelo de interacción y ejecutar el profiler de nuevo. Con la cxcli
, puedes comprobar los intents que se han considerado y los que se han descartado. A continuación, puedes determinar cómo utilizar frases de entrenamiento adicionales para entrenar tu modelo para que resuelva los utterances según sus intents y slots previstos.
Cada suite se ejecuta en una sesión Dialogflow CX, por lo que puedes testear no sólo tu NLU, sino también la propia conversación.
Todos los comandos que tienes disponibles en la cxcli
ara ejecutar el NLU Profiler se encuentran bajo el comando cxcli profile-nlu
.
Este comando ejecutará una suite que incluye un conjunto de tests. Es importante saber qué suites y tests se pueden ejecutar. SLas suites y los tests se definen como ficheros yaml
. Puedes ejecutar estas suites desde tu terminal o tus pipelines de CI/CD mediante la cxcli
.
Para ejecutar una suite, debes ejecutar el comando cxcli profile-nlu execute
. Para saber cómo utilizarlo, consulta esta página.
cxcli profile-nlu execute [suite-file] [parameters]
Una suite es un fichero YAML con la siguiente estructura:
# suite.yaml
# Name of the suite.
name: Example Suite
# Brief description of the suite.
description: Suite used as an example
# Project ID on Google Cloud where is located your Dialogflow CX agent.
projectId: test-cx-346408
# Location where your Dialogflow CX agent is running.
# More info here: https://cloud.google.com/dialogflow/cx/docs/concept/region
locationId: us-central1
# Agent name of your Dialogflow CX agent.
# Notice: it is the agent name, not the agent ID.
agentName: test-agent
# You can have multiple tests defined in separated files
tests:
# ID of the test.
- id: test_id
# File where the test specification is located
file: ./test.yaml
Puedes consultar la referencia completa aquí
Un test es un fichero YAML con la siguiente estructura:
# test.yaml
# Name of the test.
name: Example test
# Brief description of the test.
description: These are some tests
# Locale of the interaction model that is gonna be tested.
# You can find the locales here: https://cloud.google.com/dialogflow/cx/docs/reference/language
localeId: en
# A check is a test itself: given an input, you will validate the intents and the parameters/entities detected by Dialogflow CX
# You can have multiple checks defined
checks:
# The ID of the check
- id: test
input:
# the input type
# it could be text or audio
type: text
# The input itself in text format. For type: audio, you have to specify the audio tag.
text: I want 3 pizzas
validate:
# Intent that is supposed to be detected
intent: order_intent
# You can have multiple parameters/intents
# Notice: this could be empty if your intent does not have any entities/parameters.
parameters:
# Entity name that is supposed to be detected
- parameter: number
# Value that is supposed to be detected
value: 3
Puedes consultar la referencia completa aquï
Puedes encontrar más ejemplos en nuestro repositorio de GitHub así como en la página de ejemplos.
Este es un ejemplo simple del comando cxcli profile-nlu execute
:
cxcli profile-nlu execute examples/suite.yaml
El comando anterior te proporcionará un output como este:
$ cxcli profile-nlu execute suite.yaml
INFO Suite Information: test-agent
INFO Test ID: test_1
INFO Input: type: text, value: hi
INFO Intent Detected: hi_intent
INFO Input: type: text, value: hello
INFO Intent Detected: hi_intent
INFO Input: type: audio, value: ./audio/hi.mp3
INFO Intent Detected: hi_intent
INFO Test ID: test_2
INFO Input: type: text, value: I want 3 pizzas
INFO Intent Detected: order_intent
INFO Param order_type: pizza
INFO Param number: 3
INFO Input: type: text, value: I want 2 cokes
INFO Intent Detected: order_intent
INFO Param number: 2
INFO Param order_type: coke
Comprueba el uso completo del comando cxcli profile-nlu
, visita esta página.
Si quieres comprobar el uso completo del comando cxcli environment
, visita esta página.
Para obtener más información sobre cómo testear en Dialogflow CX, consulta la documentación oficial.
Este es un tutorial básico para aprender cómo testear adecuadamente tus Agentes en Dialogflow CX. Como hemos visto en este ejemplo, es muy sencillo crear tests y establecer pipelines de CI/CD, ya sea mediante la consola o la cxcli
.
Espero que este tutorial te resulte útil.
¡Eso es todo, amigos!
Happy coding!
]]>