About Alexa Conversations Description Language (Beta)
Note: Sign in to the developer console to build or publish your skill.
Note: Alexa Conversations Description Language (ACDL) is offered as a beta and may change as we receive feedback and iterate on the feature.
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.
Note:Version 2.29 of the Alexa Skills Kit Command Line Interface (ASK CLI) is now available. This single tool lets you work with all Alexa skills, including Alexa Conversations Description Language (ACDL) skills, interaction model skills, and skills that use both. You can continue to use the current ASK CLI for ACDL, but it will no longer be updated. To get the latest supported features and functionality, use version 2.29 or later.
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.
The following is an overview of all the steps you use to create and run an Alexa Conversations skill by using 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.
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.
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.
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.
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.
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.
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.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.
dialog Weather {
sample {
// Declare an event.
weatherEvent = expect(Invoke, getWeatherEvent)
// Ensure that the user provided all the required arguments.
ensure(
{arguments = [getWeather.arguments.cityName], response = request_city_prompt},
{arguments = [getWeather.arguments.date], response = request_date_prompt}
)
// The action that should be performed. This specific action is implemented as an AWS Lambda. The declaration of the action's type signature is shown in the next example.
weatherResult = getWeather(weatherEvent.cityName, weatherEvent.date)
// Another action that should be performed. This action describes the response to the user with the weather information returned by the API call.
response(weather_prompt, Notify {actionName = getWeather, success = true}, payload = {weatherResult = weatherResult})
}
}
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.
action WeatherResult getWeather(US_CITY cityName, DATE date)
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.
UtteranceEvent<CityAndDateType> getWeatherEvent = utterances<CityAndDateType>([
"What's the weather {date} in {cityName}",
"What is the weather {date}",
"How is the weather {date}",
"How is the weather in {cityName} {date}",
"How is the weather",
"Can you please give me the weather report for {date}",
"What's the weather"
])
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.
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 Add Visuals and Audio to Your Skill.
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.
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:
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:
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.
[
"What's the weather {date} in {cityName}",
"What is the weather {date}",
"How is the weather {date}",
"How is the weather in {cityName} {date}",
"How is the weather",
"Can you please give me the weather report for {date}",
"What's the weather"
]
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.
type WeatherResult {
US_CITY cityName
NUMBER highTemp
NUMBER lowTemp
}
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.
