Use the Name-free Interaction Toolkit in CLI

Prerequisite: Preview CLI Setup

To use the NFI Toolkit in CLI, you must install the latest version. If you already have CLI installed and want to update to the latest version, click here for instructions to install or update to the latest version of CLI

Use CLI to update the interaction model

Use CLI to tell Alexa which skill launch phrases and intent launch phrases you want the customer to be able to say to access your skill more naturally. When you specify a skill launch phrase, you give the customer a new way to open your skill without using the typical invocation pattern, like telling Alexa to open or launch the skill. When you specify an intent launch phrase, you give the customer a way to launch right into a particular intent within your skill, again without using the typical invocation pattern.

Place the _nameFreeInteraction container within the interaction model. Identify each intent that you want to make available for name-free interaction.

For a skill launch phrase, which is where an IngressPoint launches your skill as a modal launch, set the type field LAUNCH with no name field. Use the format RAW_TEXT and set the value to your skill launch sample utterance. The sample utterance must not contain slots and should be a complete phrase. In your skill, specify up to five skill launch phrases.

For an intent launch phrase, which is where an IngressPoint launches into a specific intent for your skill, set the type field to INTENT and the name field to the existing intent name, as defined in language model for the skill. Use the format RAW_TEXT and set the value to your intent launch sample utterance. The sample utterance must not contain slots and should be a complete phrase. For each IngressPoint, specify up to five intent launch phrases.

Developers using CLI will edit the model.json file locally to include the new nameFreeInteraction container as shown below, and then use the existing commands explained in the CLI documentation for updating your skill. For the purpose of Preview, you will need to use the Preview CLI:

Use ask init [--hosted-skill-id <hosted-skill-id>] [--profile | -p <profile>] [--debug] to create a new skill project from an existing skill

For additional details, refer here.

An example interaction model with _nameFreeInteraction container is available below.

Example

{
  "interactionModel": {
    "languageModel": {},
    "_nameFreeInteraction": {}
  }
}

Sample

{
  "interactionModel": {
    "languageModel": {
      "invocationName": "XYZ 101.8",
      "intents": [
        {
          "name": "PlayGenreIntent",
          "samples": [
            "play jazz music",
            "play classical music",
            "jazz",
            "classical",       
          ]
        }
      ]
    },
    "_nameFreeInteraction": {
      "ingressPoints": [
        {
         "type": "LAUNCH",
         "sampleUtterances": [
           {
             "format": "RAW_TEXT",
             "value": "Launch Seattle's XYZ radio"           
           },
           {
             "format": "RAW_TEXT",
             "value": "Launch Seattle's 101.8"           
           }
         ]
        },
        {
          "type": "INTENT",
          "name": "PlayGenreIntent",
         "sampleUtterances": [
           {
             "format": "RAW_TEXT",
             "value": "play jazz music"           
           },
           {
             "format": "RAW_TEXT",
             "value": "play classical music"           
           }
         ]
        }               
      ]   
    }
  }
}

[Optional] Visual Studio: Download VS Code (recommend version 1.22.0 or higher) and install it to edit your skill project Use ASK CLI ask to build interactionModel with NFI container. Developers can use following CLI commands

ask deploy [--profile | -p <profile>] [--ignore-hash] [--debug] [--help | -h]

ask deploy: Deploy a skill to your developer account including your skill manifest, interaction model, and AWS Lambda functions.

Alternately, you can use following command to build skill model and deploy lambda separately

ask smapi set-interaction-model <-s|--skill-id <skill-id>>
                                  <-g|--stage <stage>>
                                  <-l|--locale <locale>>
                                  <--interaction-model <interaction-model>>
                                  [--if-match <if-match>]
                                  [-p| --profile <profile>]
                                  [--debug]

ask smapi set-interaction-model: Updates the interaction model for the specified skill and locale. Use ASK CLI ask to track the status of interactionModel build.

ask smapi get-skill-status <-s|--skill-id <skill-id>>
                             [--resource <resource>]
                             [-p| --profile <profile>]
                             [--debug]

ask smapi get-skill-status: Retrieves the build status of the specified model. For builds of IMs containing NFI container, get-model-status should also include the status of NFI builds.

SkillStatus: {
  "interactionModel": {
    "en-US": {
      "eTag": "agasguhq34894hjk",
      "lastUpdateRequest": {
        "status": "SUCCEEDED",
        "errors": [],
        "warnings": [],
        "buildDetails": {
          "steps": [
            {
              "name": "LANGUAGE_MODEL_QUICK_BUILD",
              "status": "SUCCEEDED"
            },
            {
              "name": "LANGUAGE_MODEL_FULL_BUILD",
              "status": "SUCCEEDED"
            }
            {
              "name": "DIALOG_MODEL_BUILD",
              "status": "SUCCEEDED"
            }
           {
             "name": "NAME_FREE_INTERACTION_BUILD",
             "status": "IN_PROGRESS | SUCCEEDED | FAILED"
           }
          ]
        }
      }
    }
  }
}

Retrieve interaction model

Use ASK CLI ask to retrieve interactionModel with NFI intents

ask smapi get-interaction-model <-s|--skill-id <skill-id>>
                                  <-g|--stage <stage>>
                                  <-l|--locale <locale>>
                                  [-p| --profile <profile>]
                                  [--debug]

Or

ask smapi get-interaction-model-version <-s|--skill-id <skill-id>>
                                          <-g|--stage <stage>>
                                          <-l|--locale <locale>>
                                          <--version <version>>
                                          [-p| --profile <profile>]
                                          [--debug]

Testing Name Free Interaction in Isolation (en-* only)

After building a skill, consider testing your skill in isolation with name-free utterances to help you understand the user experience when Alexa invokes your skill by using name-free interaction. Keep in mind that testing in isolation isn't required for certification of your skill.

Testing in isolation means the simulation tool considers only the intents in the development-stage interaction model. In isolation, Alexa routes the name-free utterance to your skill. The testing doesn't reflect actual routing decisions made by Alexa across all published skills and experiences. You might observe different outcomes in production because Alexa considers a variety of signals when routing name-free requests.

Typically, you would invoke your skills using the named invocation method:

User > ask “Joe’s horoscopes”, for the Cancer horoscope for today Alexa > Here is the horoscope for Cancer……

As part of NFI, you should be able to start simulations using name-free utterances for your skill's NFI participating intents, such as:

User > What is the horoscope for Cancer today? Alexa > OK, here is Joe’s horoscope Alexa > For Cancer, Mercury is no longer in retrograde, so….

If testing results in not mapping to any intent, be sure you have enough sample utterances for your intent and follow the guidelines for name free utterances found in the Do’s and Don’ts section. You should have at least 10 utterances for your intent. You can also try to adjust FallbackIntent sensitivity.

If you are finding that the simulation is mapping to the wrong intent, check for utterance conflicts, or update samples and slots to the right intent and remove conflicting samples in other intents that could be conflicting with the sample utterances.

Use preview ASK cli (ask) to test how a skill containing NFI intents behaves in isolated NFI testing.

You should first enable the skill that you will use in simulation. If you have not enabled the skill, you will receive the following error message “Skill is currently disabled in <development/live> stage. Please enable skill in order to call this API.”

Use the command

ask dialog -p <profile>
            -s <skill id>
            -l <locale>
            -g <stage>
            --simulation-type <NFI_ISOLATED_SIMULATION>

or

ask smapi simulate-skill -p <profile>
                        -s <skill id>
                        --device-locale <locale>
                        -g <stage>
                        --simulation-type <NFI_ISOLATED_SIMULATION>
                        --input-content <utterance text>

To get the simulation result use: ask smapi get-skill-simulation -p <profile> -s <skill id> -g <stage> -i <simulation id>

ask dialog: Opens a dialog mode in which developers can simulate a multi-turn conversation with Alexa. Each dialog uses simulate-skill

ask smapi simulate-skill: This is an asynchronous API that simulates a skill execution in the Alexa eco-system given an utterance text of what a customer would say to Alexa.

ask smapi get-skill-simulation: This API gets the result of a previously run simulation. A successful response contains the status of the simulation.

Certification and NFI Model Training

Once you are satisfied with the changes to your interaction model, you will submit your skill for publishing. Amazon will review the interaction model updates in order to certify the skill.

CLI ask smapi submit-skill-for-certification

Otherwise, you do not need to take any additional action to deploy the updated skill.

Upon publication, the name-free interaction model begins learning how to route traffic to your skill and intents. With the recurring training of Alexa machine learning and artificial intelligence, it might take up to eight weeks for Alexa to route name-free interaction utterances to your skills.

Troubleshooting

Common reasons for the build process to fail:

  • incorrect intent name
  • More than 5 skill launch phrases
  • More than 5 intent launch phrases per intent
  • Intent Launch Phrase is not part of intent’s language model
  • intent not included in language model
  • NFI Container does not have an ingress point field
  • NFI Container has ingress point field but the ingress point list is empty
  • Ingress point contains a null entry
  • Ingress point name is empty/blank
  • Ingress point does not have a valid type defined
  • Duplicate ingress points
  • Unsupported ingress points (Note: Built-In Intents are not supported)
  • Name Free Interactions can only be added to published skills.
  • This skill is in an unsupported locale. Name Free Interactions are only available for English locales (en-US, en-GB, en-IN, en-CA, en-AU).
  • Mature rated skills are not allowed to use name free interactions
  • This skill is not eligible to receive name free invocations due to quality and engagement factors. These eligibility requirements might change in the future.
Was this page helpful?

Last updated: Apr 30, 2024