Use Dynamic Entities for Customized Interactions
- How dynamic entities work
- Update the list of entities with the Dialog.UpdateDynamicEntities directive
- Use of dynamic entities in an intent response
- Expire dynamic entities at the end of a session
With the use of dynamic entities, you can augment your skill's predefined slot type in the interaction model by allowing your skill to dynamically create new entities in runtime. Without dynamic entities, the entities are resolved at build time and remain the same until an update is made to the skill, and you cannot customize entities by customer or by dialog turn. With dynamic entities, you can create personalized voice experiences, and dynamically enable or disable slot values based on conversation or user context. The use of dynamic entities boosts speech recognition, natural language understanding, and entity resolution accuracy by dynamically biasing Alexa's models based on the newly-loaded slot values.
You can use dynamic entities to develop personalized experiences within a session for your skill customers. For example, suppose you have a custom skill, called My Shopping List, and a customer wants to add milk to the list.
User: Alexa, open My Shopping List.
User: Alexa, ask My Shopping List to add milk to my cart.
The skill can upload a slot value from the customer's personal catalog to resolve "milk" to "SomeBrand 2% Organic Milk" based on that user's preferences and shopping patterns with My Shopping List. Thus, Alexa can resolve "milk" to be "SomeBrand 2% Organic Milk."
Slot values are not always static, and they can vary by time or location. Dynamic entities allow your skill to adapt to the dynamic nature of slot values by providing your skill the ability to load entities in runtime. Suppose you have a skill called, My Food Order, for an online food delivery company.
User: Alexa, open My Food Order.
User: Alexa, ask My Food Order to order food from CoolRestaurant.
When the customer says, "Alexa ask My Food Order to order food from CoolRestaurant", the My Food Order skill can load today's menu that is specific to CoolRestaurant.
This ability to dynamically enable and disable slot values through personalized and dynamic entity resolution helps improve accuracy. The Alexa skill is biased towards the slot value based on the loaded catalog, which can help create better speech and entity recognition.
Here are some examples where dynamic entities can be useful:
- A restaurant skill provides daily lunch specials that resolve to the menu item of the day.
- A shopping skill resolves entities against a personalized favorite items list.
- A communication skill loads a contact list at runtime, so that someone's name can resolve to an entity in the contact list. For example, if a customer Bob speaks the utterance "call alice", "alice" will resolve to "Alice" on Bob's contact list when Bob tries to place a call.
- A game skill specifies different loot drops based on the specific customer's game state.
Dynamic entities can be used to enhance the usefulness of entity resolution. With static entity resolution, you can create a static list of synonyms for slot values and synonyms to help clarify a customer's utterances. However, these synonyms are not customized to each customer and cannot respond dynamically. With dynamic entities, you can specify slot values and synonyms dynamically when the skill is launched and change them on subsequent utterances. Thus, your skill can take advantage of more accurate, context-aware entity resolution.
How dynamic entities work
An entity is the result of resolving a slot from an utterance against a list of slot values provided by the developer. Thus, for a flight skill, if the utterance is "Book a flight to Logan", then Logan (slot : AirportName) will be resolved as follows:
{"id":"BOS" , "name":"Boston Logan International Airport"}
The dynamic entities are used to resolve a slot value, just as with a slot type value in the interaction model.
Alexa returns entity resolution results from both the dynamic slot type values and slot type values in the interaction model. The skill can then choose which one to use. If the dynamic catalog returns ER_NO_MATCH, then the skill service code can be written so that your skill defaults to the one from the slot type values in the interaction model instead.
Alexa prioritizes slot type values in the following order:
- Custom slot type with dynamic entities
- Extended built-ins with dynamic entities
- Custom slot type without dynamic entities
- Extended built-ins without dynamic entities
Update the list of entities with the Dialog.UpdateDynamicEntities directive
To use dynamic entities, ensure that your skill has a slot type value in the interaction model with defined slot types and slot names. Dynamic entities can only modify an existing slot type. Ensure your skill meets the dialog directives requirements. Dynamic entities can "augment" an existing slot type by adding additional slot values and synonyms.
Dynamic entities can be used in combination with the dialog management feature or separately. You do not need to use the Dialog.Delegate directive, slot filling, or any other dialog management feature in order to use the Dialog.UpdateDynamicEntities directive.
When a customer invokes your skill, Alexa sends an intent response to the skill's lambda function. This response can be used to ingest the dynamic entity catalog for access by the skill during the session. Just as with slot types in the interaction model, you can upload IDs and synonyms for all your dynamic entities.
This intent response example demonstrates how to ingest dynamic entities in an intent response in a travel skill that references airports, and which uses the existing slot type "Airport". For the sake of brevity, only two dynamic entities, representing Boston Logan and LaGuardia airports, are shown here. You can also include more than one slot type, but the total number of dynamic entities, including synonyms, for all slot types should not exceed 100.
You can upload a different dynamic entity catalog in a subsequent intent response, but the new dynamic entity catalog then overwrites the previous one.
If you load more than 100 entities in an intent response, then you will get a 403 error and none of these dynamic entities are loaded. However, the standard slot type in the interaction model will still be used.
The dynamic entity catalog is loaded by customer ID, so can be personalized to the customer.
The Dialog.UpdateDynamicEntities directive, along with the desired dynamic entity catalog, is used in an intent response to update the dynamic entities. Currently, the supported values for updateBehavior are "REPLACE" and "CLEAR".
Example–Update a dynamic entity with 'REPLACE'
For brevity, only the directives portion of the intent response is shown in the following example.
"directives": [
{
"type": "Dialog.UpdateDynamicEntities",
"updateBehavior": "REPLACE",
"types": [
{
"name": "AirportSlotType",
"values": [
{
"id": "BOS",
"name": {
"value": "Logan International Airport",
"synonyms": [
"Boston Logan"
]
}
},
{
"id": "LGA",
"name": {
"value": "LaGuardia Airport",
"synonyms": [
"New York"
]
}
}
]
}
]
}
]
The following examples show how to update the dynamic entities with either the Alexa Skills Kit SDK for Node.js or the Alexa Skills Kit SDK v2 for Java.
This code example uses the Alexa Skills Kit SDK for Node.js (v2).
const FlightDetailsHandler = {
// ...
handle (handlerInput) {
// Slot values to be added at runtime for the AirportSlotType type.
// The slot type must exist in the interaction model.
let replaceEntityDirective = {
type: 'Dialog.UpdateDynamicEntities',
updateBehavior: 'REPLACE',
types: [
{
name: 'AirportSlotType',
values: [
{
id: 'SJC',
name: {
value: 'San Jose International Airport',
synonyms: ['San Jose', 'SJC']
}
},
{
id: 'JFK',
name: {
value: 'John F. Kennedy International Airport',
synonyms: ['New York', 'LGA']
}
},
{
id: 'BOS',
name: {
value: 'Logan International Airport',
synonyms: ['beantown', 'bean town', 'the hub', 'logan']
}
}
]
}
]
};
const repeat = 'What airport would you like to depart from?';
const speech = 'Thank you for flying with us. ' + repeat;
return handlerInput.responseBuilder
.speak(speech)
.reprompt(repeat)
.addDirective(replaceEntityDirective)
.getResponse();
}
};
This code example uses the Alexa Skills Kit SDK for Java.
public class FlightDetails implements RequestHandler {
// ...
public static Optional<Response> generateQuestion(HandlerInput handerInput) {
// This is a basic example of adding a single dynamic entity to a slot value.
List<Entity> entities = new ArrayList<>();
ArrayList<String> synonyms = new ArrayList<String>();
// Example of adding synonyms to an entity.
synonyms.add("New York");
synonyms.add("LGA");
// Slot Id, slot value, and synonyms for an entity.
Entity entity = Entity.builder()
.withId("LGA")
.withName(EntityValueAndSynonyms.builder()
.withValue("LaGuardia Airport")
.withSynonyms(synonyms)
.build())
.build();
// Add multiple entity/slot values to a single entity list.
entities.add(entity);
// Create the dynamic entities directive and specify the slot type
// (AirportSlotType). This slot must already exist in the interaction model.
// The update behavior is a REPLACE to add new entities.
DynamicEntitiesDirective replaceEntityDirective = DynamicEntitiesDirective
.builder()
.addTypesItem(EntityListItem.builder()
.withName("AirportSlotType")
.withValues(entities)
.build())
.withUpdateBehavior(UpdateBehavior.REPLACE)
.build();
String question = "What airport would you like to depart from?";
String speech = "Thank you for flying with us. " + question;
return handlerInput.getResponseBuilder()
.withSpeech(speech)
.withReprompt(question)
.addDirective(replaceEntityDirective)
.withShouldEndSession(false)
.build();
}
}
Use of dynamic entities in an intent response
When a customer makes a request, and the skill responds with an intent response, the response includes the entity resolution results. See Entity resolution. Suppose the customer is in a shopping skill and speaks the utterance, "Add milk". If the dynamic entity catalog has been set up already, a typical intent response could be similar to the following example, in which a standard entity resolution is shown in the first resolutionsPerAuthority array element, and the second resolutionsPerAuthority array element represents a dynamic entity resolution based on the ingested catalog.
For brevity, only the slots portion of the intent response is shown here. In this example, the slot type here is toDrink, and it must already exist in the skill's dialog model.
{
"slots": {
"toDrink": {
"name": "product",
"value": "milk",
"resolutions": {
"resolutionsPerAuthority": [
{
"authority": "amzn1.er-authority.echo-sdk.amzn1.ask.skill.72455255-7c82-4bdf-b0e1-4bc299be200d.ProductName",
"status": {
"code": "ER_SUCCESS_MATCH"
},
"values": [
{
"value": {
"name": "Generic Milk Brand",
"id": "1234"
}
}
]
},
{
"authority": "amzn1.er-authority.echo-sdk.dynamic.amzn1.ask.skill.72455255-7c82-4bdf-b0e1-4bc299be200d.ProductName",
"status": {
"code": "ER_SUCCESS_MATCH"
},
"values": [
{
"value": {
"name": "BestCows 2% GrassFed Milk",
"id": "4567"
}
}
]
}
]
},
"confirmationStatus": "NONE"
}
}
}
Expire dynamic entities at the end of a session
Although dynamic entities will persist for 30 minutes, which may be longer than the customer's skill session, a best practice is to "expire" the dynamic entities at the end of a session, that is to delete them. To delete dynamic entities, as you might do when the customer exits the skill, call the Dialog.DynamicEntityDirective CLEAR function to clear all dynamic entities for that customer, as shown in the following example.
A session is defined as the time a customer invokes the skill until they exit the skill. A session is deemed complete either when a customer says "Exit", or when the skill times out. The uploaded dynamic entities time out after 30 minutes, so they will persist if the customer re-invokes the skill before the end of this 30-minute period. However, a best practice is to re-ingest the dynamic entity catalog in an intent response every session, even if the dynamic entities have not yet expired.
Example–Expire dynamic entities with 'CLEAR'
For brevity, only the directives portion of the response is shown in the following example.
"directives": [
{
"type": "Dialog.UpdateDynamicEntities",
"updateBehavior": "CLEAR"
}
]
The following examples show how to update the dynamic entities with either the Alexa Skills Kit SDK for Node.js or the Alexa Skills Kit SDK v2 for Java.
This code example uses the Alexa Skills Kit SDK for Node.js (v2).
const ClearBookingHandler = {
// ...
handle (handlerInput) {
// This intent clears out the user's flight data when dynamic entities are
// no longer needed.
const clearEntitiesDirective = {
type: 'Dialog.UpdateDynamicEntities',
updateBehavior: 'CLEAR'
};
return handlerInput.responseBuilder
.speak('Clearing out your request. What would you like to do now?')
.reprompt('What would you like to do now?')
.addDirective(clearEntitiesDirective)
.getResponse();
}
};
This code example uses the Alexa Skills Kit SDK for Java.
public class FlightDetails implements RequestHandler {
// ...
public static Optional<Response> resetDynamicEntities(HandlerInput handlerInput) {
// Build the directive with just the CLEAR behavior.
DynamicEntitiesDirective clearEntityDirective = DynamicEntitiesDirective.builder()
.withUpdateBehavior(UpdateBehavior.CLEAR)
.build();
String question = "What would you like to do now?";
String speech = "Clearing out your request. " + question;
return handlerInput.getResponseBuilder()
.withSpeech(speech)
.withReprompt(question)
.addDirective(clearEntityDirective)
.withShouldEndSession(false)
.build();
}
}
Last updated: Jul 15, 2024