About Alexa Conversations Description Language (Beta)

Alexa Conversations is a deep learning-based approach to creating conversational skills for Alexa. You can create Alexa Conversations skills by using the command line with the Alexa Conversations Description Language (ACDL) (Beta), or you can use the guided experience in the Alexa Skills Kit developer console.

With ACDL, you author sample conversations, called dialogs, in a declarative manner and use the Alexa Skills Kit Command-Line Interface (ASK CLI) to build and deploy an Alexa Conversations skill.

For a discussion of Alexa Conversations concepts and instructions on how to create an Alexa Conversations skill by using a guided experience in the ASK developer console, see Alexa Conversations Guided Development Experience.

Beta limitations

The capability to create Alexa Conversations skills by using ACDL is in beta. During beta, this feature has the following limitations:

  • Interoperability between the developer console and the ASK CLI – You can create a new ACDL skill or convert an existing Alexa Conversations skill to ACDL, but you can't edit the Alexa Conversations artifacts of ACDL skills by using the developer console. For example, after you convert an existing Alexa Conversations skill to ACDL and deploy the skill by using the ASK CLI, you can no longer edit the Alexa Conversations skill artifacts by using the UI. However, you can switch between the developer console and the ASK CLI to test the skill, and then submit it for certification. However, this capability doesn't extend to editing the skill on the console Build tab.

  • Skill development – You can use ACDL only to build a skill from scratch. Migrating an intent-based skill is out of scope of beta.

  • Programming language and hosting method – The Alexa Conversations quick-start templates, such as Weather Bot, only support Node.js as the programming language, and AWS Lambda as the hosting method.

How ACDL works with Alexa Conversations

To use ACDL, first use the ASK CLI to create a skill based on a quick-start template. Then, within ACDL files, write annotated dialogs that represent the different conversational experiences your skill can support. Next, use the ASK CLI to compile and deploy your dialogs, responses, and other skill artifacts as a skill package to the Alexa cloud. In the Alexa cloud, Alexa Conversations uses a dialog simulator to expand your annotated dialogs into dialog variants that train the dialog management model. The Alexa Conversations runtime hosts the trained model and handles the interaction with the user. Alexa Conversations evaluates the trained dialog management model to process incoming events and predict actions.

ACDL and Alexa Conversations.

The following is an overview of all the steps you use to create and run an Alexa Conversations skill by using ACDL:

  1. ASK CLI installation – Install a beta version of the ASK CLI. For instructions, see Set up the ASK CLI to Use ACDL.
  2. Skill creation – Use the ASK CLI to create a skill based on a quick-start template. To create a skill based on the Weather Bot template, see Tutorial: Create an Alexa Conversations Skill with ACDL.

    When you create your skill based on a template, the ASK CLI creates a skill directory that includes the source code, interaction model, and Alexa Conversations artifacts for your skill. For the layout of the directory, see Understand the Directory Structure of ACDL.
  3. Sample dialog editing – As you work with ACDL, you edit an ACDL file that contains sample dialogs in ACDL format. These sample dialogs demonstrate the conversational experience you want to have between the skill and the user. You annotate the sample dialogs by identifying elements, such as types, actions, events, and so on. You describe the samples in terms of events that take place (for example, the user says, "Hello, my name is {name}") and actions that happen next (for example, the skill responds, "Hello back"). For a step-by-step walkthrough of creating an ACDL file, see ACDL file walkthrough.

    You must declare the type signatures of the events and the actions. You also must annotate a set of sample utterances to represent events of what the user might say, and describe the responses of your skill.
  4. Compilation – After you finish your sample dialogs, you use the ASK CLI to compile and validate your ACDL files. The compilation process generates files in Alexa Conversations Intermediate Representation (ACIR) format.
  5. Deployment – You use the ASK CLI to create and deploy a skill package to the cloud as input to the Alexa Conversations simulation and model training process.
    ACDL Compilation Process.
  6. Dialog expansion – The Alexa Conversations simulator expands your dialog samples into a large sample set. The simulator accomplishes this task by applying general knowledge of conversational experiences and learnings from other models to simulate the interaction between a user and the skill based on the sample dialogs you provide.
  7. Model training – Alexa Conversations machine learning uses the expanded dialog sample set to train a dialog management model. After the model build completes, the Alexa Conversations infrastructure deploys the model to the Alexa cloud for hosting trained models. The infrastructure also ensures that the necessary integration with the skill runtime is in place.
  8. Runtime – After a user launches your skill, the Alexa Conversations runtime uses several components, including an inference engine, to evaluate the trained dialog management model. The inference engine receives events from the outside world (for example, the user says, "What's the weather in Seattle?"), maintains conversation history for each session, manages dialog context, maintains the dialog state, and orchestrates information across different components within the runtime.

    The runtime processes events and predicts the actions that should take place. The action might be to respond to the user, call an AWS Lambda function, perform a calculation, and so on. The runtime either runs the predicted actions implicitly or transforms them to invoke an API. The following diagram shows a conceptual model of the Alexa Conversations inference engine, which hosts a machine-learning-trained dialog management model, processes events, and produces actions.
    Alexa Conversations dialog management model.
    For example, in a weather skill, the user utterance, "What's the weather?" is an event. Based on your sample dialogs, Alexa Conversations predicts that the action to take based on this event is to call the GetWeather action. Alexa Conversations might not take this action right away. For example, if your sample dialogs indicate that the action needs a city and a date, Alexa Conversations has Alexa ask for the city and date before calling the action.

    Keep in mind that there isn't a one-to-one association between an incoming event and a predicted action. The dialog management model can produce actions on its own as a reaction to internal events. It can also process multiple incoming events before producing one or more actions.

ACDL concepts

The following table provides an overview of ACDL concepts and how you represent the concepts by using Alexa Conversations artifacts.

Concept Description

Dialog

A dialog is a set of sample conversations that tie together events (triggers) and actions (outcomes, such as action invocations) to represent the different conversational experiences your skill can support. Alexa Conversations significantly expands the dialog samples into a large sample set and then uses the expanded dialog sample set to train a dialog management model. You write dialogs in ACDL format. For details, see Dialogs in ACDL.

Action

An action represents the behavior of the skill, such as a verbal or visual response to the user, an AWS Lambda invocation, or a dialog management instruction (for example, to end the dialog). You define actions in ACDL files.

For the syntax of actions, see Use Actions in ACDL. For built-in actions that the Alexa Conversations Core Library (ACCL) provides, see Actions in the ACCL.

Event

An event represents a trigger, such as something the user says. When you represent something the user says as an event, you specify an utterance set that contains examples of what the user might say or type to trigger the event. You then use the event in a dialog sample. In doing so, you specify a request act that conveys to Alexa Conversations some additional information about the event. For example, the request act conveys whether the event represents the initiation of a conversational flow, an affirmation to a previously returned question, a denial, and so on.

For the syntax of events, see Use Events in ACDL.

Response

Responses are text, audio, or visual content that Alexa renders to the user, along with any necessary arguments and a response act that indicates the purpose of the response.

Response prompts are the speech that Alexa says to the user, in the form of APL for Audio (APLA) JSON files. For details, see Response Prompt Files for Alexa Conversations.

For Alexa devices with a screen, response displays are the visual content that Alexa shows the user (if applicable), in the form of Alexa Presentation Language (APL) JSON files. For details about APL, see Understand Alexa Presentation Language (APL).

You specify responses by using the response<T>() action from the ACCL. For details about responses, see Use Responses in ACDL.

Dialog act

If you develop Alexa Conversations skills by using the developer console, you're familiar with the concept of dialog acts. Dialog acts help Alexa Conversations identify the purpose of user utterances and Alexa responses within the flow of a dialog. In ACDL, you specify user-input dialog acts by using request acts, and Alexa dialog acts by using response acts.

For a cross reference between dialog acts that you use in the developer console with the request acts and response acts that you use with ACDL, see Cross reference between response acts and dialog acts and Cross reference between request acts and dialog acts.

Request act

In ACDL, you associate events with request acts. Request acts convey to Alexa Conversations some additional information about an event, such as whether the event represents the initiation of a conversational flow, an affirmation to a previously returned question, a denial, and so on.

Alexa Conversations supports the following request acts:

For details about request acts, see Request Acts in the ACCL. For the syntax of events, see Use Events in ACDL.

Response act

In ACDL, you associate responses with response acts. Response acts convey to Alexa Conversations some additional information about a response, such as whether the response represents a request for the user to confirm an action, a suggestion to call a new action, and so on.

Alexa Conversations supports the following response acts:

  • Bye ("Thanks for using Weather Bot. Goodbye.")
  • ConfirmAction ("You'd like to know the weather for Seattle, right?")
  • ConfirmArgs ("That was for Seattle?")
  • Notify ("The weather in Seattle is 65 degrees.")
  • Offer ("Would you like the hour-by-hour forecast?")
  • ReqAlt ("Would you like to know the weather for a different city?")
  • ReqMore ("Is there anything else I can do for you?")
  • Request ("Which city?")

Utterance set

Utterance sets group together what a user might say to trigger an event. For each utterance set, you provide an annotated list of sample utterances. You define utterance sets in ACDL files and refer to the utterance sets from event declarations.

For details, see Utterance Sets in the ACCL and Declare an utterance event.

Type

Types define how Alexa recognizes and passes data between components. ACDL is a statically typed and strongly typed declarative language. All variables that pass between user utterances, Alexa responses, and APIs must have a type.

You specify types in ACDL format. For details, see Types in ACDL.

Why use ACDL instead of the developer console?

ACDL has the following advantages over the developer console:

  • Command-line support – With ACDL, you build and deploy the skill artifacts and the skill code by using the ASK CLI.
  • Modularity – You can put any of the necessary artifacts (for example, dialogs, types, events, and actions) in separate files.
  • Process and tool integration – You can use ACDL with software engineering processes and tools, such as source-code version control, code review, continuous integration, and deployment pipelines.

Get started

To get started creating Alexa Conversations skills by using ACDL, install and configure a version of the ASK CLI that supports Alexa Conversations. For details, see Set up the ASK CLI to Use ACDL.

Next, you can use the ASK CLI to create an Alexa Conversations skill from a Weather Bot template. For details, see Tutorial: Create an Alexa Conversations Skill with ACDL.