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:

Copied to clipboard.

askx new
askx new step 1
Choose Node.JS
  1. Choose AWS Lambda as a method to host the skills
askx new step 2
Choose AWS Lambda
  1. Choose Empty (Beta) to start with
askx new step 3
Choose Empty (Beta)
  1. Give a name to your skill; we will use "Flight Search"
askx new step 4
Skill Name
  1. Give a name to your folder or click enter for the default name; we will use the default name (FlightSearch)
askx new step 5
Folder Name

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:

Copied to clipboard.

askx init
  1. We want to overwrite the ask-resources.json file, so we will type "Y" here:
    askx init step 1
    Overwrite ask-resources.json
  2. We will leave the Skill Id empty, so click enter:
    askx init step 2
    Skill id
  3. We will hit enter for skill package path since we don't want to change the path:
    askx init step 3
    Skill package path
  4. The same applies for lambda code path; we are pointing the newly created lambda folder, so leave it empty by hitting enter:
    askx init step 4
    Lambda folder path
  5. When we run askx new we choose to use AWS lambda so, here will say "n":
    askx init step 5
    Lambda deployment
  6. We will be using "nodejs16.x" as lambda runtime so, let's enter that and hit enter:
    askx init step 6
    Lambda runtime
  7. We will not change the lambda handler, therefore, hit enter to keep it as is:
    askx new step 7
    Lambda handler
  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?":
    askx new step 8

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

Copied to clipboard.

  "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.

Happy path script

Customer: I want to travel to New York.

Alexa: OK, where are you traveling from?

Customer: Seattle

Alexa: What date are you planning to travel?

Customer: Sunday

Alexa: Great, you want to travel from Seattle to New York on Sunday, is that right?

Customer: Yep

Alexa: The Cheapest flight I found from Seattle to New York is $450. It is at 12 pm on Sunday with Hippogriff Air Lines.

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.

Was this page helpful?