Tutorial: Build LUIS 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).

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.

User intentions as intents

The purpose of the app is to determine the intention of conversational, natural language text:

Are there any new positions in the Seattle office?

These intentions are categorized into Intents.

This app has a few intents.

Intent Purpose
ApplyForJob Determine if user is applying for a job.
GetJobInformation Determine if user is looking for information about jobs in general or a specific job.
None Determine if user is asking something app is not supposed to answer. This intent if provided as part of app creation and can't be deleted.

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

  4. Select Done.

Create intent for job information

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

    Screenshot of Language Understanding (LUIS) New intent dialog

  2. Select Done.

  3. Add several example utterances to this intent that you expect a user to ask:

    Example utterances
    Any new jobs posted today?
    Are there any new positions in the Seattle office?
    Are there any remote worker or telecommute jobs open for engineers?
    Is there any work with databases?
    I'm looking for a co-working situation in the tampa office.
    Is there an internship in the san francisco office?
    Is there any part-time work for people in college?
    Looking for a new situation with responsibilities in accounting
    Looking for a job in new york city for bilingual speakers.
    Looking for a new situation with responsibilities in accounting.
    New jobs?
    Show me all the jobs for engineers that were added in the last 2 days.
    Today's job postings?
    What accounting positions are open in the london office?
    What positions are available for Senior Engineers?
    Where is the job listings

    Screenshot of entering new utterances for MyStore intent

    By providing example utterances, you are training LUIS about what kinds of utterances should be predicted for this 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, punctuation, and word count.

Add example utterances to the None intent

The client application needs to know if an utterance is not meaningful or appropriate for the application. The None intent is added to each application as part of the creation process to determine if an utterance can't be answered by the client application.

If LUIS returns the None intent for an utterance, your client application can ask if the user wants to end the conversation or give more directions for continuing the conversation.

Caution

Do not leave the None intent 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:

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

Train the app before testing or publishing

  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 the app to query from the endpoint

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 prediction from the endpoint

  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.9923871
      },
      "intents": [
        {
          "intent": "GetJobInformation",
          "score": 0.9923871
        },
        {
          "intent": "None",
          "score": 0.007810574
        }
      ],
      "entities": []
    }
    

    The verbose=true querystring parameter means include all the intents in the app's query results. 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.

Create intent for job applications

Return to the LUIS portal 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 to get to the list of intents.

  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
    Fill out application for Job 123456
    Here is my c.v. for position 654234
    Here is my resume for the part-time receptionist post.
    I'm applying for the art desk job with this paperwork.
    I'm applying for the summer college internship in Research and Development in San Diego
    I'm requesting to submit my resume to the temporary position in the cafeteria.
    I'm submitting my resume for the new Autocar team in Columbus, OH
    I want to apply for the new accounting job
    Job 456789 accounting internship paperwork is here
    Job 567890 and my paperwork
    My papers for the tulsa accounting internship are attached.
    My paperwork for the holiday delivery position
    Please send my resume for the new accounting job in seattle
    Submit resume for engineering position
    This is my c.v. for post 234123 in Tampa.

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 prediction 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.9634406
      },
      "intents": [
        {
          "intent": "ApplyForJob",
          "score": 0.9634406
        },
        {
          "intent": "GetJobInformation",
          "score": 0.0171300638
        },
        {
          "intent": "None",
          "score": 0.00670867041
        }
      ],
      "entities": []
    }
    

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

Client-application next steps

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. The conversational follow-up is provided by the client application such as an Azure Bot.

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.

Continue with this app, adding a simple entity and phrase list.