Custom Knowledge Intents

Custom knowledge intents enable your knowledge skill to answer questions it otherwise wouldn't be able to answer. For example, suppose you have a knowledge skill that uses the People Directory template, and your data contains a value in the "end_date" CSV column for every employee. Although your data provides employee end dates, your knowledge skill can't answer "When did {employee} leave the company?", because "When did {employee} leave the company?" doesn't automatically map to the "end_date" CSV column.

How custom knowledge intents work

Custom knowledge intents work by mapping user utterances to data within your skill and then automatically generating answers. When you create a custom knowledge intent, you configure the following five settings:

  • Intent name – A friendly name for the knowledge skill. This name is not user-facing.
  • Intent text – User utterances that invoke the custom knowledge intent. Each utterance must have one – and only one – slot, which is a variable that is populated by values from your knowledge skill data. You define slots within user utterances by typing words within curly braces, such as when did {employee} leave.
  • Slot constraints – The range of values that can populate a slot. You define slot constraints by selecting a knowledge skill template (for example, People Directory) whose rows (for example, Mary Major) populate the slot. For example, in the custom knowledge intent "When did {employee} leave?", "employee" is a slot that you can constrain to rows from the People Directory template. This intent matches utterances such as, "When did Mary Major leave?" and "When did Jane Doe leave?", where Mary Major and Jane Doe are rows in the People Directory dataset.
  • Response type – The format of the response that Alexa speaks when the user utterance matches the intent text.
  • Status – Whether the intent is live to users. Valid values are Disabled and Live.

When a user utterance is routed to your knowledge skill, your skill attempts to match it to a custom knowledge intent. If the user utterance matches to a custom knowledge intent, the custom knowledge intent produces a response defined by its response type. If no custom knowledge intents match the utterance, your skill attempts to answer the question by using its default understanding.

Custom knowledge intent limits

Custom knowledge intents have the following limits:

  • Each custom knowledge intent supports up to 100 utterance variations.
  • Custom knowledge intents can't be a protected utterance variation. Protected utterance variations are utterances that Alexa doesn't enable your skill to override. If you try to create a custom knowledge intent that is a protected utterance variation, the custom knowledge intent creation fails.

How do custom knowledge intents differ from custom intents?

The following table shows how custom knowledge intents differ from custom intents.

Aspect Custom Knowledge Intent Custom Intent

Answers

Automatically produces answers based on a knowledge skill's data.

Doesn't automatically produce answers

Source for slot values

Provided by rows from a CSV file you upload.

Manually added in line, or by data catalogs

Skill manifest

Not present in the knowledge skill's manifest or interaction model.

Present in the skill's interaction model

Compatibility

Can't be used with custom skills

Can be used with custom skills

Accessibility

Can't receive a payload in your own Lambda function or service

Can receive a payload in your own Lambda function or service

Syntax

Supports syntax that enables shortcuts

Doesn't support a shortcut syntax

How to add a custom knowledge intent

Each custom knowledge intent that you create should target a single user objective, such as getting an employee's start date. If you want to address a new user objective, such as finding an employee's location, you should do this in a separate custom knowledge intent.

For the following examples, assume you're working with the People Directory dataset and attempting to have your knowledge skill answer the question, "When did {employee} leave?", which it doesn't answer automatically, as explained previously.

To create a custom knowledge intent

  1. Log in to the developer console and navigate to your knowledge skill.
  2. On the left, under Optional, click Custom Knowledge Intents.
    The custom knowledge intents page displays a table that shows your custom knowledge intents.
  3. Click Create intent.
  4. For Intent name, enter a friendly name for the custom knowledge intent.
    This name is for your reference only. It is not user-facing. For example, your intent name might be When Did Employee Leave.
  5. For Intent text, enter utterances that users might say to invoke the intent. Each utterance must include one – and only one – slot. Define a slot by typing a word within curly braces, such as when did {employee} leave. Slots are populated by rows from a template enabled for your knowledge skill (for example, "Mary Major" from the People Directory template). In the next step, you select the template whose rows will populate the slot.
    Note the following tips:
    • You can name slots using alphabetical characters.
    • You don't need to name words that your knowledge skill ignores when trying to match user utterances. For a list of ignored words, see Words that are ignored when matching utterances.
    • To reduce redundancy within intent text, you can use parentheses to group wording variations and pipes to separate each variation. For details, see Shortcut syntax for intents.
    • You don't need to specify differences in verb tense, plurality, or contractions. For example, the intent text what is {employee} last day will match what was {employee} last day and what's {employee} last day.
    • You can surround words with quotes to enforce an exact match.
  6. For Slot Constraints, define the range of values that can populate a slot. You must constrain slots to rows from a single knowledge skill template, so select a template from the drop-down. For example, to match the utterance When did Mary Major leave? you would choose People Directory as the template, because "Mary Major" is a row from that template.
  7. For Response type, choose how your knowledge skill responds when the user utterance matches the custom knowledge intent. Currently, there is only one option, CSV Column, which is selected by default. For this response type, the answer combines the slot value (for example, Mary Major) and the CSV column (for example, "end_date") in a natural-language sentence. For example, for CSV column "end_date", Alexa might say "Mary Major's end date was September 15, 2015."
  8. For Status, choose whether the custom knowledge intent is live to users of your skill by selecting one of the following options:
    • Disabled (default): Custom knowledge intents are disabled in the live version of your skill. With this setting, an intent is not testable.
    • Live: With this setting, which is available after you've saved a custom knowledge intent, an intent is testable. However, the intent is also active for all users of your skill.
  9. Click Create intent.

Custom knowledge intent tips

When you create your custom knowledge intents, keep in mind the following tips.

Shortcut syntax for intents

To reduce redundancy within intent text, you can use parentheses to group wording variations and pipes to separate each variation, such as when did {employee} (leave|depart). When attempting to match utterances, your skill will automatically expand each of these variations. For example, the above example produces two variations: "When did {employee} leave" and "When did {employee} depart". You can also nest pipe groups within each other. You can view these variations in the preview window as you edit the intent text.

Words that are ignored when matching utterances

Custom knowledge intents can match an utterance even when up to three of the following words occur and the intent text does not include them. For example, the intent text "where is {event}" will match "where is the {event}", even though "the" is not included in the intent text.

  • a
  • an
  • are
  • at
  • be
  • did
  • do
  • does
  • from
  • get
  • had
  • has
  • have
  • is
  • on
  • the
  • was
  • were
  • will
  • with
  • would

Testing custom knowledge intents

To test live intents without impacting skill users, you can use one of the following methods:

  • You can add and test the custom knowledge intent before publishing the skill to users.
  • You can create and add the custom knowledge intent to a dedicated "test" skill that you don't publish to users.

In both cases, you can test live intents by submitting utterances in the Test tab of the developer console, or by interacting with your knowledge skill on a device registered to an account that has the knowledge skill enabled.

Custom knowledge intent FAQ

Q: How do custom knowledge intents differ from custom intents?
They differ in several respects, such as in the answers they provide, the slot value source, skill manifest, compatibility, accessibility, and syntax. For details, see How do custom knowledge intents differ from custom intents?.
Q: Can I create a custom knowledge intent with no slots?
No. Every custom knowledge intent must have one, and only one, slot.
Q: Can I share a custom knowledge intent across multiple knowledge skills?

No. Currently, custom knowledge intents are only available within a single knowledge skill.

Q: Can I share a custom knowledge intent across skill types (for example, with a custom skill)?

No. Currently, custom knowledge intents are only available within a single knowledge skill.

Q: Do custom knowledge intents support locales outside of en-US?

Currently, custom knowledge intents are only available in en-US.