Tutorial 1: Build custom app to determine user intentions

In this tutorial, you create a custom Human Resources (HR) app that predicts a user's intention based on the utterance (text). When you're finished, you have a LUIS endpoint running in the cloud.

The purpose of the app is to determine the intention of conversational, natural language text. These intentions are categorized into Intents. This app has a few intents. The first intent, GetJobInformation, identifies when a user wants information about jobs available inside a company. The second intent, None, is used for any utterances from the user that are outside the domain (scope) of this app. Later, a third intent, ApplyForJob, is added for any utterances about applying for a job. This third intent is different from GetJobInformation because the job information should already be known when someone applies for the job. However, depending on the word choice, determining which intent may be tricky because both are about a job.

After LUIS returns the JSON response, LUIS is done with this request. LUIS doesn't provide answers to user utterances, it only identifies what type of information is being asked for in natural language.

In this tutorial, you learn how to:

  • Create a new app
  • Create intents
  • Add example utterances
  • Train app
  • Publish app
  • Get intent from endpoint

For this article, you can use the free LUIS account in order to author your LUIS application.

Create a new app

  1. Sign in to the LUIS portal with the URL of https://www.luis.ai.

  2. Select Create new app.

    Screenshot of Language Understanding (LUIS) My Apps page

  3. In the pop-up dialog, enter the name HumanResources and keep the default culture, English. Leave the description empty.

    Create LUIS new HumanResources app

    Next, the app shows the Intents page with the None Intent.

GetJobInformation intent

  1. Select Create new intent. Enter the new intent name GetJobInformation. This intent is predicted any time a user wants information about open jobs in the company.

    Screenshot of Language Understanding (LUIS) New intent dialog

  2. By providing example utterances, you are training LUIS what kinds of utterances should be predicted for this intent. Add several example utterances to this intent that you expect a user to ask, such as:

    Example utterances
    Any new jobs posted today?
    What positions are available for Senior Engineers?
    Is there any work with databases?
    Looking for a new situation with responsibilities in accounting
    Where is the job listings
    New jobs?
    Are there any new positions in the Seattle office?

    Screenshot of entering new utterances for MyStore intent

    These few utterances are for demonstration purposes only. A real-world app should have at least 15 utterances of varying length, word order, tense, grammatical correctness, and word count.

None intent

The client application needs to know if an utterance is outside the subject domain of the application. If LUIS returns the None intent for an utterance, your client application can ask if the user wants to end the conversation. The client application can also give more directions for continuing the conversation if the user doesn't want to end it.

These example utterances, outside the subject domain, are grouped into the None intent. Do not leave it empty.

  1. Select Intents from the left panel.

  2. Select the None intent. Add three utterances that your user might enter but are not relevant to your Human Resources app. If the app is about your job postings, some None utterances are:

    Example utterances
    Barking dogs are annoying
    Order a pizza for me
    Penguins in the ocean

Train

  1. In the top right side of the LUIS website, select the Train button.

    Train button

  2. Training is complete when you see the green status bar at the top of the website confirming success.

    Trained status bar

Publish

In order to receive a LUIS prediction in a chat bot or other client application, you need to publish the app to the endpoint.

  1. Select Publish in the top right navigation.

    LUIS publish to endpoint button in top right menu

  2. Select the Production slot and the Publish button.

    LUIS publish to endpoint

  3. Publishing is complete when you see the green status bar at the top of the website confirming success.

    LUIS publish to endpoint

  4. Select the endpoints link in the green status bar to go to the Keys and endpoints page. The endpoint URLs are listed at the bottom.

Get intent

  1. In the Manage section (top right menu), on the Keys and endpoints page (left menu), select the endpoint URL at the bottom of the page. This action opens another browser tab with the endpoint URL in the address bar.

    The endpoint URL looks like https://<region>.api.cognitive.microsoft.com/luis/v2.0/apps/<appID>?verbose=true&subscription-key=<YOUR_KEY>&<optional-name-value-pairs>&q=<user-utterance-text>.

  2. Go to the end of the URL in the address bar and enter I'm looking for a job with Natural Language Processing. The last query string parameter is q, the utterance query. This utterance is not the same as any of the example utterances. It is a good test and should return the GetJobInformation intent as the top scoring intent.

    {
      "query": "I'm looking for a job with Natural Language Processing",
      "topScoringIntent": {
        "intent": "GetJobInformation",
        "score": 0.8965092
      },
      "intents": [
        {
          "intent": "GetJobInformation",
          "score": 0.8965092
        },
        {
          "intent": "None",
          "score": 0.147104025
        }
      ],
      "entities": []
    }
    

    The results include all the intents in the app, currently 2. The entities array is empty because this app currently does not have any entities.

    The JSON result identifies the top scoring intent as topScoringIntent property. All scores are between 1 and 0, with the better score being close to 1.

ApplyForJob intent

Return to the LUIS website and create a new intent to determine if the user utterance is about applying for a job.

  1. Select Build from the top, right menu to return to app building.

  2. Select Intents from the left menu.

  3. Select Create new intent and enter the name ApplyForJob.

    LUIS dialog to create new intent

  4. Add several utterances to this intent that you expect a user to ask for, such as:

    Example utterances
    I want to apply for the new accounting job
    Fill out application for Job 123456
    Submit resume for engineering position
    Here is my c.v. for position 654234
    Job 567890 and my paperwork

    Screenshot of entering new utterances for ApplyForJob intent

    The labeled intent is outlined in red because LUIS is currently uncertain the intent is correct. Training the app tells LUIS the utterances are on the correct intent.

Train again

  1. In the top right side of the LUIS website, select the Train button.

    Train button

  2. Training is complete when you see the green status bar at the top of the website confirming success.

    Trained status bar

Publish again

In order to receive a LUIS prediction in a chat bot or other client application, you need to publish the app to the endpoint.

  1. Select Publish in the top right navigation.

    LUIS publish to endpoint button in top right menu

  2. Select the Production slot and the Publish button.

    LUIS publish to endpoint

  3. Publishing is complete when you see the green status bar at the top of the website confirming success.

    LUIS publish to endpoint

  4. Select the endpoints link in the green status bar to go to the Keys and endpoints page. The endpoint URLs are listed at the bottom.

Get intent again

  1. In the Manage section (top right menu), on the Keys and endpoints page (left menu), select the endpoint URL at the bottom of the page. This action opens another browser tab with the endpoint URL in the address bar.

    The endpoint URL looks like https://<region>.api.cognitive.microsoft.com/luis/v2.0/apps/<appID>?verbose=true&subscription-key=<YOUR_KEY>&<optional-name-value-pairs>&q=<user-utterance-text>.

  2. In the new browser window, enter Can I submit my resume for job 235986 at the end of the URL.

    {
      "query": "Can I submit my resume for job 235986",
      "topScoringIntent": {
        "intent": "ApplyForJob",
        "score": 0.9166808
      },
      "intents": [
        {
          "intent": "ApplyForJob",
          "score": 0.9166808
        },
        {
          "intent": "GetJobInformation",
          "score": 0.07162977
        },
        {
          "intent": "None",
          "score": 0.0262826588
        }
      ],
      "entities": []
    }
    

    The results include the new intent ApplyForJob as well as the existing intents.

Clean up resources

When no longer needed, delete the LUIS app. To do so, select My apps from the top left menu. Select the ellipsis (...) to the right of the app name in the app list, select Delete. On the pop-up dialog Delete app?, select Ok.

Next steps

This tutorial created the Human Resources (HR) app, created 2 intents, added example utterances to each intent, added example utterances to the None intent, trained, published, and tested at the endpoint. These are the basic steps of building a LUIS model.