Intents

5 Intents

Intents allow your bot to understand what the user wants it to do. An intent categorizes typical user requests by the tasks and actions that your bot performs. The PizzaBot’s OrderPizza intent, for example, labels a direct request, I want to order a Pizza, along with another that implies a request, I feel like eating a pizza.

Intents are comprised of permutations of typical user requests and statements, which are also referred to as utterances. As described in Create an Intent, you can create the intent by naming a compilation of utterances for a particular action. Because your bot’s cognition is derived from these intents, each intent should be created from a data set that’s robust (one to two dozen utterances) and varied, so that your bot can interpret ambiguous user input. A rich set of utterances enables a bot to understand what the user wants when it receives messages like “Forget this order!” or “Cancel delivery!”—messages that mean the same thing, but are expressed differently. To find out how sample user input allows your bot to learn, see Intent Training and Testing.

Description of nlp_intent_bb.png follows

Description of the illustration nlp_intent_bb.png

Create an Intent

To create an intent:

Click Intents () in the left navbar.
Click Add Intent.
Name the intent.
As a optional step, add description of the intent. Your description should focus on what makes the intent unique and the task or actions it performs.
Start building the training corpus by adding utterances that illustrate the meaning behind the intent. To ensure optimal intent resolution, use terms, wording, and phrasing specific to the individual intent. Ideally, you should base your training data on real-world phrases, but if you don’t any, aim for one-to-two dozen utterances for each intent. That said, you can get your bot up and running with fewer (three-to-five) when you train it with Trainer Ht. You can save your utterances by clicking Enter or by clicking outside of the input field.

To manage the training set, select a row to access the Edit () and Delete () functions.
Alternatively, you can add an entire set of intents and their respective utterances by importing them from a CSV file.

You can make your bot more resilient by adding utterances that contain commonly misspelled and misused words. See Guidelines for Building Your Training Corpus.
Add an entity if the intent needs one to resolve the user input. To find out how, see Add Entities to Intents.
To teach your bot how to comprehend user input using the set of utterances that you’ve provided so far, click Train, choose a model and then click Submit.
As described in Which Training Model Should I Use?, we provide two models that learn from your corpus: Trainer Ht and Trainer Tm. Each uses a different algorithm to reconcile the user input against your intents. Trainer Ht uses pattern matching while Trainer Tm detects variations in user input. You’d typically follow training process when you’re creating intents:
1. Create the initial training corpus.
2. Train with Trainer Ht. You should start with Trainer Ht because it doesn’t require a large set of utterances. As long as there are enough utterances to disambiguate the intents, your bot will be able to resolve user input.
3. Refine your corpus, retrain with Trainer Ht. Repeat as necessary—training is an iterative process.
4. Train with Trainer Tm. Use this trainer when you’ve accumulated a robust set of intents.
The Train button () activates whenever you add an intent or when you update an intent by adding, changing, or deleting its utterances. To bring the training up to date, choose a training model and then click Train. The model displays an exclamation point whenever it needs training. When its training is current, it displays a check mark.

Note:
For Trainer Ht, your bot needs at least two intents which each have three or more utterances. Trainer Tm also requires more than one intent.
In the test window, click Intents and then enter some of the phrases from your test set. See Testing Intents.

Note:
Enable the conversation intent logging (Settings > General > Intent Conversation) to log your intent testing results. How Do I Run a History Report? describes how you use this data. Be sure to switch this (and all) logging options off when your bot is in a production environment.

Add Entities to Intents

Some intents require entities—both built-in and custom— to complete an action within the dialog flow or make a REST call to a backend API. The system uses only these entities, which are known, as intent entities, to fulfill the intent that’s associated with them. In the absence of intent entities, the system attempts to complete the intent by iterating through all of the bot’s entities. You can associate an entity to an intent when you click Add New Entity and then select from the custom ( This is an image of the Custom icon.

) or built-in ( This is an image of the System icon.

) entities.
This is an image from the

Alternatively, you can click New Entity to add an intent-specific entity. See Custom Entity Types.
This is an image of the Create Entity dialog.

Tip:

Only intent entities are included in the JSON payloads that 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. See How Do Custom Components Work?

Import Intents from a CSV File

You can add your intents manually, or import them from a CSV file. You can create this file by exporting the intents and entities from another bot, or by creating it from scratch in a spreadsheet program or a text file.

The CSV file has two columns: query and topIntent:

query,topIntent
I want to order a pizza,OrderPizza
I want a pizza,OrderPizza
I want a pizaa,OrderPizza
I want a pizzaz,OrderPizza
I'm hungry,OrderPizza
Make me a pizza,OrderPizza
I feel like eating a pizza,OrderPizza
Gimme a pie,OrderPizza
Give me a pizza,OrderPizza
pizza I want,OrderPizza
I do not want to order a pizza,CancelPizza
I do not want this,CancelPizza
I don't want to order this pizza,CancelPizza
Cancel this order,CancelPizza
Can I cancel this order?,CancelPizza
Cancel my pizza,CancelPizza
Cancel my pizaa,CancelPizza
Cancel my pizzaz,CancelPizza
I'm not hungry anymore,CancelPizza

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

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

To export your intents and their utterances:

Click Intents () in the left navbar.
Click More, and then choose Export intents.
Save the file.

Tip:
Remember to train your bot after you import the CSV file.

Intent Training and Testing

Training a model with your training corpus allows your bot to discern what users say (or in some cases, are trying to say).

You can improve the acuity of the cognition through rounds of intent testing and intent training. In Intelligent Bots, you control the training through the intent definitions alone; the bot can’t learn on its own from the user chat.

Test Sets

We recommend that you set aside 20% percent of your corpus for testing your bot and train your bot with the remaining 80%. Keep these two sets separate so that the test set remains “unknown” to your bot.

Apply the 80/20 split to the each intent’s data set. Randomize your utterances before making this split to allow the training models to weigh the terms and patterns in the utterances equally.

The Intent Tester

The Intent tester is your window into your bot’s cognition. By entering phrases that are not part of the training corpus (the utterances that you’ve maintained in your testing set), you can find out how well you’ve crafted your intents and entities through the ranking and the returned JSON. This ranking, which is the bot’s estimate for the best candidate to resolve the user input, demonstrates its acuity at the current time.

Testing Intents

To find out how well you’ve labeled your intents and entities:

Click Test () to open the tester window.
Open the Intent tab.
Enter a string of text that is not part of the corpora.
Click Send and then take a look at the ranking.
Expand the JSON window to see how your bot ranked the intents.
If your bot’s top-ranking candidate isn’t what you expect, you might need to retrain the intents after doing one or both of the following:
- Update the better candidate’s corpus with the input text that you just entered—Select the appropriate intent and then click Add Example.
  
  Caution:
  Consider the impact on your training data before you add a test phrase. Adding a test phrase can change how the utterances that are similar to it get classified after retraining. In addition, adding a test phrase invalidates the test, because the incorporation of a test phrase into the training set ensures that the test will be successful.
- Correct the system by editing the corpus using the Edit () and Delete () functions. A FAQ intent, for example, might receive a top rank because of the scope and phrasing of its constituent utterances. If you don’t want your users to get a FAQ whenever they ask typical questions, you’ll need to revise the corpus.
You need to retrain an intent whenever you add, change, or delete an utterance. A dirty Train icon () indicates when your training becomes outdated. When the retraining completes, click Reset () and then send the test phrase again.

The Intent Testing History

You can export the training data into CSV file so that you can find out how the intents were trained.

By examining these logs in a text editor or spreadsheet program like MicroSoft Excel, you can see each user request and bot reply. You can sort through these logs to see where the bot matched the user request with the right intent and where it didn’t.

Export Intent Data

To capture all of the intent testing data in a log, be sure to enable Intent Conversation in Settings > General before you test your intents.

To export data:

In the bots catalog, open the menu in the tile and then click Export Conversation Log.
In the Export Bot dialog, choose the log type (conversation or intent) and a logging period.
Open the CSV files in a spreadsheet program to review it. You see if your model matches intents consistently by filtering the rows by keyword.

Batch Testing Intents

You can use the intent testing data that you’ve exported on new iterations of your bot to gauge the accuracy of its intent detection.

To use that test data:

Open the tester () and then click Batch.
Click Load and then upload the intents log.
Choose the number of tests running in parallel. Increasing the number of concurrent tests may speed up testing, but may also burden the system.
Click Test.
The results display in the test window.
Drill down () to see how the test results compare to the batch data.

Which Training Model Should I Use?

We provide a duo of models that you can train to mold your bot’s cognition. You can use one or both of these models, each of which uses a different approach to machine learning.

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 bot’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.

Tip:

Because of its quick training, use Trainer Ht to help you define and refine your training corpus. While you can add sentences to an intent whenever the resolution is faulty (or in the worst case, add your entire testing corpus), be sure to aim for a concise training corpus by following the guidelines in Guidelines for Building Your Training Corpus.

Trainer Tm

Because Trainer Tm doesn’t focus as heavily on matching rules as Trainer Ht, it can help your bot interpret user input that falls outside of your training corpus. Trainer Tm differs from Trainer Ht in other ways as well: its intent resolution can be less predictable across training sessions.

Note:

Trainer Ht is the default model, but you can change this by clicking Settings > General and then by choosing another model from the list. The default model displays in the tile in the bot catalog.
This is an image of the bot tile.

Guidelines for Building 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 bot smart”. The corpus is the key to your bot’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 bot-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:

Create 12 to 24 sample phrases per intent (if possible). Keep in mind that the more examples you add, the more resilient your bot becomes.

Important:
Trainer Tm can’t learn from an intent that has only one utterance.
Avoid sentence fragments and single words. Instead, use complete sentences (which can be up to 255 characters). If you must use single key word examples, choose them carefully.
Vary the vocabulary and sentence structure in your sample phrases by one or two permutations using:
- slang words (moolah, lucre, dough)
- common expressions (Am I broke? for an intent called AccountBalance)
- alternate words (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)
- Create parallel sample phrases for opposing intents. For intents like CancelPizza and OrderPizza, define contrasting sentences like I want to order a pizza and I do not want to order a pizza.
- When certain words or phrases signify a specific intent, you can increase the probability for a correct match by bulking up the training data not only with the words and phrases themselves, but with synonyms and variations as well. For example, a training corpus for an OrderPizza intent might include a high concentration of “I want to” phrases, like I want to order a Pizza, I want to place an order, and I want to order some food. Use similar verbiage sparingly for other intents, because it might skew the training if used too freely (say, a CancelPizza intent with sample phrases like I want to cancel this pizza, I want to stop this order, and I want to order something else). When the high occurrence of unique words or phrases within an intent’s training set is unintended, however, you should revise the initial set of sentences or use the same verbiage for other intents.
  
  Use different concepts to express the same intent, like I am hungry and Make me a pizza.
Watch the letter casing: use uppercase when your entities extract proper nouns, like Susan and Texas, but use lowercase everywhere else.
Grow the corpus by adding any mismatched sentence to the correct intent.

Tip:

Keep a test corpus as CSV file to batch test intent resolution by clicking More and then Export Intents. Because adding a new intent example can cause regressions, you might end up adding several test phrases to stabilize the intent resolution behavior.

Reference Intents in the Dialog Flow

Within your dialog flow, your intents can define the actions property, as shown in the PizzaBot’s intent state. See System.Intent.

  intent:
    component: "System.Intent"
    properties:
      variable: "iResult"
      confidenceThreshold: 0.4
    transitions:
      actions:
        OrderPizza: "resolvesize"
        CancelPizza: "cancelorder"
        unresolvedIntent: "unresolved"