Create an Intent
Here are the steps for creating an intent in a skill.
Add Entities to Intents
Value Agnostic applies to built-in entities only. You cannot apply it to custom entities.
Alternatively, you can click New Entity to add an intent-specific entity.
Tip:
Only intent entities that are included in the JSON payloads are sent to, and returned by, the Component Service. The ones that aren’t associated with an intent won’t be included, even if they contribute to the intent resolution by recognizing user input. If your custom component accesses entities through entity matches, then be sure to add the entity to your intent.Value Agnostic Intent Entities
The Value Agnostic feature allows you to adjust how entity values affect intent classification. When you enable this feature, the specific values for an associated built-in entity do not have bearing on the intent classification. However, when you disable this feature, you allow the entity value to play a key role in resolving the input.
Example Intents | Associated Entity | Training Utterances | Enable Value Agnostic? |
---|---|---|---|
Account Balance | DATE |
|
Yes – The specific date values do not signal the intent. The various date values in these utterances can be ignored because a user can ask for an account balance on any day. |
Holiday Store Hours | DATE |
|
No – The intent classification is based on a specific (and limited) set of values and users are inquiring about holidays. |
|
DATE |
|
No – Disable Value Agnostic for both intents. Agnostic DATE values in this case would mean that the model would not consider a value as past or future. A "last month" value, which should signal the Check Past Vacation Balance intent, would be ignored. As a result, similarly worded input like "Did I take any time off next month" may resolve incorrectly to this intent. |
Import Intents from a CSV File
You can add your intents manually, or import them from a CSV file. You can create this file from a CSV of exported intents, or by creating it from scratch in a spreadsheet program or a text file.
The CSV file has six columns for skills that use the Natively-Supported language mode and five columns for those that don't. Here are the column names and what they represent:
query
: An example utterance.topIntent
: The intent that the utterance should match to.conversationName
: The conversation name for the intent.answer
: For answer intents, the static answer for the intent.enabled
: Iftrue
, the intent is enabled in the skill.nativeLanguageTag
: (For skills with native-language support only) the language of the utterance. For values, use two-character language tags (fr
,en
, etc,).- For skills with Digital Assistant's native language support, this column is required.
- For skills without the native language support, you can't import a CSV that has this column.
Here's an excerpt from a CSV file for a skill that does not have native language support and which doesn't use answer intents.
query,topIntent,conversationName,answer,enabled
I want to order a pizza,OrderPizza,Order a Pizza.,,true
I want a pizza,OrderPizza,Order a Pizza.,,true
I want a pizaa,OrderPizza,Order a Pizza.,,true
I want a pizzaz,OrderPizza,Order a Pizza.,,true
I'm hungry,OrderPizza,Order a Pizza.,,true
Make me a pizza,OrderPizza,Order a Pizza.,,true
I feel like eating a pizza,OrderPizza,Order a Pizza.,,true
Gimme a pie,OrderPizza,Order a Pizza.,,true
Give me a pizza,OrderPizza,Order a Pizza.,,true
pizza I want,OrderPizza,Order a Pizza.,,true
I do not want to order a pizza,CancelPizza,Cancel your order.,,true
I do not want this,CancelPizza,Cancel your order.,,true
I don't want to order this pizza,CancelPizza,Cancel your order.,,true
Cancel this order,CancelPizza,Cancel your order.,,true
Can I cancel this order?,CancelPizza,Cancel your order.,,true
Cancel my pizza,CancelPizza,Cancel your order.,,true
Cancel my pizaa,CancelPizza,Cancel your order.,,true
Cancel my pizzaz,CancelPizza,Cancel your order.,,true
I'm not hungry anymore,CancelPizza,Cancel your order.,,true
don't cancel my pizza,unresolvedIntent,unresolvedIntent,,true
Why is a cheese pizza called Margherita,unresolvedIntent,unresolvedIntent,,true
Here's an excerpt from a CSV file for a skill with native-language support that uses answer intents.
query,topIntent,conversationName,answer,enabled,nativeLanguageTag
Do you sell pasta,Products,Our Products,We sell only pizzas. No salads. No pasta. No burgers. Only pizza,true,en
Vendez-vous des salades,Products,Our Products,Nous ne vendons que des pizzas. Pas de salades. Pas de pâtes. Pas de hamburgers. Seulement pizza,fr
do you sell burgers,Products,Our Products,We sell only pizzas. No salads. No pasta. No burgers. Only pizza,true,en
Do you sell salads,Products,Our Products,We sell only pizzas. No salads. No pasta. No burgers. Only pizza,true,en
Vendez des hamburgers,Products,Our Products,Nous ne vendons que des pizzas. Pas de salades. Pas de pâtes. Pas de hamburgers. Seulement pizza,true,fr
To import a CSV file:
-
Click Intents () in the left navbar.
-
Click More, and then choose Import intents.
-
Select the
.csv
file and then click Open. -
Train your skill.
Export Intents to a CSV File
You can reuse your training corpus by exporting it to CSV. You can then import this file to another skill.
-
Click Intents in the left navbar.
-
Click More, and then choose Export intents.
-
Save the file. This file has the following columns, which are described in Import Intents from a CSV File:
query, topIntent, conversationName, answer, enabled, nativeLanguageTag
Which Training Model Should I Use?
You can't use Trainer Ht for skills that use answer intents, use native language support, or have a large number of intents. Use Trainer Tm for these skills.
Trainer Tm
You don't need to bulk up your training data with utterances that accommodate case sensitivity (Tm recognizes BlacK Friday as Black Friday, for example), punctuation, similar verbs and nouns, or misspellings. In the latter case, Trainer Tm uses context to resolve a phrase even when a user enters a key word incorrectly. Here are some general guidelines for building a training corpus when you're developing your skill with this model.
- Recognizing the irrelevant content. For I'm really excited about the
coming Black Friday deals, and can't wait for the deals. Can you tell me
what's going to be on sale for Black Friday?, Trainer Tm:
- Discards the extraneous content (I'm really excited about the coming Black Friday deals...)
- Resolves the relevant content (Can you tell me what's going to be on sale for Black Friday?) to an intent. In this case, an intent called Black Friday Deals.
Trainer Tm can also distinguish between the relevant and irrelevant content in a message even when the irrelevant content can potentially be resolved to an intent. I bought the new 80 inch TV on Black Friday for $2200, but now I see that the same set is available online for $2100. Do you offer price match? for example, could be matched to the Black Friday Deals intent and to a Price Matching intent, which is appropriate for this message. In this case Trainer Tm:- Recognizes that I bought the new 80 inch TV on Black Friday for $2200, but now I see that the same set is available online for $2100 is extraneous content.
- Resolves Do you offer price match?
- Resolving intents when a single word or a name matches an entity. For example, Trainer Tm can resolve a message consisting of only Black Friday to an intent that's associated with a entity for Black Friday.
- Distinguishing between similar utterances (Cancel my order vs. Why did you cancel my order?).
- Recognizing out-of-scope utterances, such as Show me pizza recipes or How many calories in a Meat Feast for a skill for fulfilling a pizza order and nothing else.
- Recognizing out-of-domain utterances, such as What's the weather like
today for a pizza ordering skill.
Tip:
While Trainer Tm can easily distinguish when a user message is unclassifiable because it's clearly dissimilar from the training data, you might still want to define anunresolvedIntent
with utterances that represent the phrases that you want to make sure do not resolve to any of your skill's intents. These phrases can be within the domain of your skill, but are still out of scope, even though they may share some of the same words as the training data. For example, I want to order a car for a pizza skill, which has also been trained with I want to order a pizza. - Distinguishing between similar entities – For example, Tm recognizes that mail is not same as email in the context of an intent called Sign Up for Email Deals. Because it recognizes that an entity called regular mail would be out of scope, it would resolve the phrase I want to sign up for deals through regular mail at a lower confidence than it would for I want to sign up for email deals.
Trainer Ht
Trainer Ht is the default training model. It needs only a small training corpus, so use it as you develop the entities, intents, and the training corpus. When the training corpus has matured to the point where tests reveal highly accurate intent resolution, you’re ready to add a deeper dimension to your skill’s cognition by training Trainer Tm.
You can get a general understanding of how Trainer Ht resolves intents just from the training corpus itself. It forms matching rules from the sample sentences by tagging parts of speech and entities (both custom and built-in) and by detecting words that have the same meaning within the context of the intent. If an intent called SendMoney has both Send $500 to Mom and Pay Cleo $500, for example, Trainer Ht interprets pay as the equivalent to send . After training, Trainer Ht’s tagging reduces these sentences to templates (Send Currency to person, Pay person Currency) that it applies to the user input.
Because Trainer Ht draws on the sentences that you provide, you can predict its behavior: it will be highly accurate when tested with sentences similar to the ones that make up the training corpus (the user input that follows the rules, so to speak), but may fare less well when confronted with esoteric user input.
Build Your Training Corpus
When you define an intent, you first give it a name that illustrates some user action and then follow up by compiling a set of real-life user statements, or utterances. Collectively, your intents, and the utterances that belong to them, make up a training corpus. The term corpus is just a quick way of saying “all of the intents and sample phrases that I came up with to make this skill smart”. The corpus is the key to your skill’s intelligence. By training a model with your corpus, you essentially turn that model into a reference tool for resolving user input to a single intent. Because your training corpus ultimately plays the key role in deciding which route the skill-human conversation will take, you need to choose your words carefully when building it.
Generally speaking, a large and varied set of sample phrases increases a model’s ability to resolve intents accurately. But building a robust training corpus doesn’t just begin with well-crafted sample phrases; it actually begins with intents that are clearly delineated. Not only should they clearly reflect your use case, but their relationship to their sample sentences should be equally clear. If you’re not sure where a sample sentence belongs, then your intents aren’t distinct from one another.
You probably have sample utterances in mind when you create your intents, but you can expand upon them by using these guidelines.
Guidelines for Trainer Tm
- Use a minimum confidence threshold of 0.7 for any skill that you plan to put into production.
- Use good naming conventions for your intent names so it's easy to review related intents.
- As a general rule, create at least 80 to 100 utterances for each intent. Per the corpus size and shape guidelines, the minimum (through not recommended) number of utterances for an intent is two. The total number of utterances in your training set should not exceed 25,000.
- If possible, use unmodified, real-word phrases that include:
- vernacular
- standard abbreviations that a user might enter ("opty" for opportunity, for example)
- non-standard names, such a product names
- spelling variants ("check" and "cheque", for example)
- Create fully formed sentences that mention both the action and the entity on which the action is performed.
- Try to keep the utterance length between 3 and 30 words. Utterances that are too short and lacking context can cause the model to generalize in unpredictable ways. Utterances that are too long may prevent the model from identifying the pertinent words and phrases. There can be exceptions, however, for one- or two-word utterances when they're commonly used phrases. If you expect two-word messages like order status, price check, membership info, or ship internationally) that specify both the entity and action, add them to your training data. Be sure that your sample phrases have both an action and an entity.
- Be specific. For example, What is your store phone number? is better than What is your phone number? because it enables Trainer Tm to associate a phone number with a store. As a result of this learning, it will resolve What's your mom's phone number? to a lower confidence score.
- While Trainer Tm detects out-of-scope utterances, you can
still improve confidence and accuracy by creating an
unresolvedIntent
for utterances that are in domain but still out of scope for the skill's intents. This enables Trainer Tm to learn the boundary of domain intents. You can define anunresolvedIntent
for phrases that you do not want resolved to any of your skill's intents. You may only want to define anunresolvedIntent
when user messages have been resolved to a skill's intents even when they don't apply to any of them. - Vary the words and phrases that surround the significant content as much as possible. For example, I'd like a pizza, please", "Can you get me a pizza?", "A pizza, please"
- Some practices to avoid:
- Do not associate a single word or phrase with a specific intent unless that word or phrase indicates the intent. Repeated phrases can skew the intent resolution. For example, starting each OrderPizza utterance with "I want to …" and each ShowMenu intent with "Can you help me to …" may increase the likelihood of the model resolving any user input that begins with "Can you help me to" with OrderPizza and "I want to" with ShowMenu.
- A high occurrence of one-word utterances in your intents. One-word utterances are an exception. Use them sparingly, if at all.
- Open-ended utterances that can easily apply to other domains or out-of-domain topics.
- Your corpus doesn't need to repeat the same
utterance with different casing or with different word forms
that have same lemma. For example, because Trainer Tm can
distinguish between manage, manages, and manager, it not only
differentiates between "Who does Sam manage?" and "Who manages
Sam?", but also understands that these words are related to one
another.
Note
You may be tempted to add misspellings of words. But before you do, use those misspellings in the utterance tester to see if the model recognizes them. You might be surprised at how well it handles them. Also, by not adding misspellings you run less risk of skewing your model in unexpected ways.
- Create test cases to ensure the integrity of the intent resolution.
- Run the Overview report for skill quality to maintain a balanced training set. Run the anomalies report as well to check for misclassified or unusual utterances.
- When you deploy your skill, you can continuously improve the
training data by:
- Reviewing the Conversation Logs, summaries of all conversations that have occurred for a specified period. You enable the logging by switching Enable Insights on in Settings.
- Running Skill Quality Reports and by assigning (or reassigning) actual user messages
to your intents with the Insights Retrainer. If these reports indicate
that
unresolvedIntent
has a lot of misclassified utterances within the domain intents:- Move the in-scope utterances from
unresolvedIntent
to the domain intents. - Move the out-of-scope utterances from the domain
intents to
unresolvedIntent
.
- Move the in-scope utterances from
Guidelines for Trainer Ht
- vernacular
- common misspellings
- standard abbreviations that a user might enter ("opty" for "opportunity", for example)
- non-standard names, such a product names
- spelling variants ("check" and "cheque", for example)
-
Vary the vocabulary and sentence structure in these starter phrases by one or two permutations using:
-
slang words (moolah, lucre, dough)
- standard abbreviations that a user might enter ("opty" for opportunity, for example)
- non-standard names, such a product names
-
common expressions (Am I broke? for an intent called AccountBalance)
-
alternate wording (Send cash to savings, Send funds to savings, Send money to savings, Transfer cash to savings.)
-
different categories of objects (I want to order a pizza, I want to order some food).
-
alternate spellings (check, cheque)
-
common misspellings ("buisness" for business)
-
unusual word order (To checking, $20 send)
-
- Use different concepts to express the same intent, like I am hungry and Make me a pizza
- Do not associate a single word or phrase with a specific intent unless that word or phrase indicates the intent. Repeated phrases can skew the intent resolution. For example, starting each OrderPizza utterance with "I want to …" and each ShowMenu intent with "Can you help me to …" may increase the likelihood of the model resolving any user input that begins with "I want to" with OrderPizza and "Can you help me to" with ShowMenu.
-
Avoid sentence fragments and single words. Instead, use complete sentences (which can be up to 255 characters) that include the action and the entity. If you must use single key word examples, choose them carefully.
- Create test cases to ensure the integrity of the test the intent resolution. Because adding a new intent examples can cause regressions, you might end up adding several test phrases to stabilize the intent resolution behavior.
Limits for Training Data Shape and Size
Regarding training data and shape, here are the limits to the number of intents and utterances.
Intents:
- Minimum number of intents per skill: 2
- Maximum number of intents per skill: 2,500
Utterances:
- Maximum number of utterances per skill: 25,000
- Minimum number of utterances per intent: 2
- Utterance word length: Between 3 and 30 words. Per the guidelines for Trainer Tm, there are exceptions where one or two-word utterances can be appropriate if they are commonly used.
These are technical limits, not recommendations. See Guidelines for Trainer Tm for practical recommendations for shaping your skills and providing robust training data.
Export Intent Data
To log conversations, be sure to enable Enable Insights in Settings > General before you test your intents.
To export data for a skill:- Click to open the side menu and select Development > Skills.
- In the tile for the skill, click and select Export Conversations.
- Choose Intent Conversation Log, set the logging period, and then click Export.
- Review the user input by opening the CSV files in a spreadsheet program.