To aid in building applications that have better natural language understanding, Microsoft came out with LUIS or Language Understanding Intelligent Services. LUIS can be used for understanding speech for the Bot Framework, Bing Speech, or even with Cortana.

In this post, we’ll learn how to create a LUIS app, apply basic LUIS concepts, and how to call the LUIS API using Python.

As usual, the code in this post is on GitHub.

Creating a LUIS App

To integrate with LUIS, you must first create a LUIS app. To start the process of creating a LUIS app, first, navigate to the website LUIS.ai. Log in and click on “Go to my apps”. From there, click on “Create new app”. Type in a name for your app and click “Done”. You’ll now be able to can start building out your new LUIS app.

There are three main components of a LUIS app:

  • Intents – The actions to be performed that complete a task. Such as playing music.
  • Utterances – This is the text from a user of your app that LUIS will attempt to understand. For example, someone could say, “play Frank Sinatra”, or “play music”. Utterances will match up to intents to perform the specified task.
  • Entities – Any specific information within an utterance. For instance, in the utterance, “Add Moonlight Sonata to playlist”, the term “Moonlight Sonata” would be an entity.

Below is an example that satisfies all three properties of a LUIS app:

  • Utterance: Add eggs to my shopping list
  • Entities: Eggs, shopping
  • Intent: CreateTask

Microsoft has some pre-built intents, utterances, and entities that you can experiment with.

Let’s create our own intent to get a better idea of how things work. We’ll design a new intent that will handle the creation of notes called “CreateNote”. Once the intent has been created, you’ll be redirected to the intent details view where you can add utterances and entities.

Create a few utterances and then, on the left navigation, click on “Entities” to create a new entity. I created one called “NoteName”. At this point, we can return to our “CreateNote” intent and update our utterances to use the new entity. To do so, just click on a word in any utterance to apply the entity to it.

With entities applied to utterances, we can now train and test our app. In the top right of the site click on “Train” and when that process finishes, click on “Test” to start the testing process.

We’ve now created a small LUIS app that we can start working with.

Calling LUIS from Python

At this point, we have a configured LUIS app that has intents, utterances, and entities. However, before we can start calling the API, we must first publish our LUIS app and get the keys needed to call the API.

Publish your App
To retrieve LUIS data from the API, you must publish your app to a Production slot. Otherwise, if you try to make API calls to your app, you’ll receive a response stating that you need to publish your app before making any API calls.

The process of publishing a LUIS app is straightforward. Go to the “Publish” section from the top navigation. From the “Publish app” page you can either set the app to publish to production or staging. The publishing options can be used for further testing of the API.

The “Include all predicted intent scores” will set the response to include all intents with their confidence scores. The “Enable Bing spell checker” will auto correct any misspelled words before sending it to your LUIS app. To publish your app to allow API calls to it, click the “Publish to production slot” button. There is an option to select Staging in the drop down to allow you to test our your app before pushing to Production.

Getting App Keys
Now that our app is published, we need to obtain some app keys. Otherwise, we’d get an unauthorized error when calling the API. Below where you published your app, you will find the Resources and Keys section.

As you can tell, I blurred the keys out, but you may notice on the endpoint URL that I blurred out two keys. The first key, which is the key to the left of the URL, is the Subscription ID. The second key is the App ID. While the key is provided to you in the URL, you can also access it directly by going to the “Settings” section on the top navigation.

Calling the LUIS API
Now that we have our app set up let’s use Python to make an API call and see what we get back in the response. We’ll be using the requests package to make it simpler to call our API. For our API keys, I included a config.json file which will not be checked into source control; you will have to provide your own config.json file to use this code.

Let’s import what we need and get our config file loaded.

import requests
import json

config = json.load(open("./config.json"))

From the Publish page, it gives us our endpoint URL.

luis_url = f"https://westus.api.cognitive.microsoft.com/luis/v2.0/apps/{config['LuisAppID']}"

I’m using Python’s string interpolation to build the URL with the LUIS App ID. We could use the URL the Publish page shows, put the Subscription ID in the URL as a query string, but it may be safer including the ID in the header for the request. We can easily add the ID to the header of requests by making a dictionary.

headers = {
    "Ocp-Apim-Subscription-Key": config['SubscriptionKey']
}

Besides using a dictionary for header requests, we will use another dictionary to hold our query parameters. If you look at the endpoint URL from the Publish page, you will see that it includes a “q” parameter that represents a query value. This parameter will contain our text that our LUIS app will process to determine if any intents and entities exist within.

params = {
    "q": "Create note"
}

And with our query set, let’s see what LUIS returns from the API.

response = requests.get(luis_url, headers=headers, params=params)
response.json()

LUIS found that our query best matches our CreateNote intent and is 99.999% accurate. Let’s try another query with an entity and see if it finds that.

params = {
    "q": "Add to shopping list"
}

response = requests.get(luis_url, headers=headers, params=params)
response.json()

LUIS was able to, not only find the intent, but it found that “shopping” was an entity of type NoteName.


In this post we briefly went over components of LUIS, or Language Understanding Intelligent Services, building a simple LUIS app, and then using the LUIS app through API calls using Python.

There are a lot of applications of using LUIS for language understanding inside of your application. You could use the Bing Speech API to transcribe speech to text and send that text to your LUIS app to complete an action. You could also integrate your LUIS app into Microsoft’s Bot Framework so your bot can be more intelligent when someone is chatting with it; which is precisely what we will do in our next post.