Lab 2: Setting-up the Development Environment

Welcome to Lab 2 of the beginner ACDL workshop about how to build Alexa Conversations by using developer tools. In this lab, you'll learn the major components of an ACDL.

Time required: 10 - 20 minutes

What you'll learn

• How to set up a development environment
• Building "Flight Search" Skill
• What is Alexa Conversations?

How to create a new skill by using ACDL

Now, we are ready to start building our first skill. You need to open your terminal and navigate to a folder where you want to create the skill. You can create a new folder called "Tutorial" to keep your tutorial skills in one place.

1. Run the following command and choose NodeJS:

askx new

2. Choose AWS Lambda as a method to host the skills

3. Choose Empty (Beta) to start with

4. Give a name to your skill; we will use "Flight Search"

5. Give a name to your folder or click enter for the default name; we will use the default name (FlightSearch)

Empty project will create skill related folders and configuration, however, we still need to create "lambda" folder and point that folder in the skill configuration.

• Create a new folder called "lambda" in your skill directory

Now, let's open this skill folder (…./FlightSearch) in VS Code.

• You will have the below folder structure:

<Skill Directory>/
├── .ask/ (You can ignore this directory)
├── lambda/ (This directory contains the source code and skill run-time logic)
│── build/ (This directory contains ASKIR files which are generated by ACDL compiler)
│   └── *.json files   
├── skill-package/    
│   │── conversations/ (This directory contains custom types, events, actions, and dialogs in ACDL file format)
│   │   └── *.acdl files   
│   │── interactionModels/ (This directory contains invocation name, intents, and types for your skill)
│   │   └── custom/
│   │       └── < locale name >.json
│   │       └── < another locale name >.json    
│   │       └── ...
│   │── response      
│   │   └── prompts/ (This directory contains the speech that Alexa prompts the user as APLA files)
│   │       │── < Folder for an APLA document >
│   │       │   └── document.json
│   │       │── < Folder for another APLA document >
│   │       │    └── document.json
│   │       └── < More folders for APLA documents>                 
│   └── skill.json (This file contains dialog management settings, endpoint settings, and other skill metadata information)
└── ask-resources.json (This file contains ask configuration)

Please see the understand the directory structure in ACDL for more details.

We need to configure the ask-resources.json file to set the runtime, lambda handler and backend code path, therefore, we will run the following command in the terminal. Before running this command, ensure that you are in the skill folder you created:

askx init

1. We want to overwrite the ask-resources.json file, so we will type "Y" here:

   

2. We will leave the Skill Id empty, so click enter:

   

3. We will hit enter for skill package path since we don't want to change the path:

   

4. The same applies for lambda code path; we are pointing the newly created lambda folder, so leave it empty by hitting enter:

   

5. When we run askx new we choose to use AWS lambda so, here will say "n":

   

6. We will be using "nodejs16.x" as lambda runtime so, let's enter that and hit enter:

   

7. We will not change the lambda handler, therefore, hit enter to keep it as is:

   

8. Finally, we will confirm both ask-resources.json and ask-states.json files, by entering "Y". As noted below, both files will be shown above the message "Does this look correct?":

   

Your ask-resources.json file should look like the snippet below (Note: you might have a default "awsRegion" based on your AWS configuration)

{
  "askcliResourcesVersion": "2020-03-31",
  "profiles": {
    "default": {
      "skillMetadata": {
        "src": "./skill-package"
      },
      "code": {
        "default": {
          "src": "./lambda"
        }
      },
      "skillInfrastructure": {
        "type": "@ask-cli/lambda-deployer",
        "userConfig": {
          "runtime": "nodejs16.x",
          "handler": "index.handler",
          "awsRegion": "us-west-2"
        }
      }
    }
  }
}

Building "Flight Search" Skill

Throughout this course you will learn how to use Alexa Conversations to build a multi-turn conversational Alexa skill called "Flight Search". Flight Search is a skill that finds the cheapest flight for a given date between departure and arrival cities. To understand how it works, take a look at Flight Search's "happy path" script.

The "happy path" for Flight Search guides our customer through the process of filling three parameters our skill code needs in order to find the cheapest flight. Those parameters are arrival, departure and date.

In this case, the customer provided arrival city at the beginning, but what if they provided both departure and arrival? Or just the date? What if they provide all three parameters at the beginning? What if the customer ignores the question and answers the unexpected slot values?

As you can see, our single "happy path" is a great place to start, but it is not equipped to handle all the ways the conversation could deviate. Throughout this course you'll learn how to train Alexa Conversations to assist you.

Now that you understand what you'll be building, take a moment to familiarize yourself with the fundamentals of Alexa Conversations.

What is Alexa Conversations?

We are only just beginning to scratch the surface of Alexa Conversations. There is much to learn, so we will start with a high-level description and go deeper throughout the course.

Alexa Conversations is an A.I. driven dialog manager that:

• Simulates and predicts how the customer will deviate from your happy path.
• Keeps track of the conversational context.
• Determines how to respond to customer input.
• Handles inputs out of sequence and customer corrections.
• Handles context carry-over so the skill leverages previously collected information.
• Tracks the required inputs in order to perform a task
• Delivers a JSON request to perform a task to your skill code.
• Converts the JSON response from your skill code to spoken output.

That's quite a lot of stuff! These benefits fall into two categories front-end and back-end. Since Alexa Conversations simulates and predicts how the conversation will deviate from your happy path, you don't have to provide as much training data to your front-end to support deviations. Alexa Conversations does a lot of the heavy lifting when it comes to tracking the conversational context, handling user corrections, value confirmations, determining what to prompt for next and how to surface the results of a task to the customer. Since you no longer have to write this code yourself, you are able focus on receiving input and returning output.

Get Started

Now that you have a high-level understanding of Alexa Conversations, it's time to start building! Take your time to navigate through the step-by-step instructions to build the skill. Each step will provide context and explanations to equip you with the knowledge and understanding necessary at that moment to complete the task. This will help solidify the concepts so you'll understand the 'how' and the 'why' as you go along.

Continue to Lab 3 below to start building "Flight Search" with ACDL.