Before you Begin
In this one-hour tutorial you will use three pre-defined skills to create your own personal digital assistant (DA) on the Oracle Digital Assistant platform (ODA). You will also get hands-on experience tuning your digital assistant’s conversational capabilities and interaction style.
Background
The purpose of this lab is to give you hands-on experience adding skills to a DA, configuring routing and smart dialogs, and testing a DA to ensure that it’s performing as expected.
In addition, you will learn strategies for dealing with various types of user inputs, including explicit and implicit invocation of skills, requests for help, and handling non-sequitur utterances.
What Do You Need?
- Access to an Oracle Digital Assistant instance.
- Intro-to-Routing-Tutorial-Files.zip, which contains the skills that you will use in this lab.
Clone, Train and Publish Skills
Import and Clone Skills
We’ll start by importing the three skills that were provided in the zip file referenced above (Your_Initials_Finance_For_DA_Starter
, Your_Initials_Pizza_For_DA_Starter
and Your_Initials_Retail_For_DA_Starter
).
And since you may not be the only one using your ODA instance, we’ll create a unique clone of each for your use.
Complete the following steps:
- Download the file containing each of the skill zip files and unzip it.
You should see three zip files, one for each skill that you'll be importing.
- With the Oracle Digital Assistant UI open in your browser, click to open the side menu.
- Click Development and select Skills.
- Click Import Skill in the upper right and select the zip file for one of the three skills.
If you receive an error message similar to the one in the image below, it means that someone has already imported the skills and you can skip to the next step.
- Return to the Skills landing page by clicking Skills in the left navigation.
- Import the other two skills by repeating the previous two steps.
- Within the tile for the
Your_Initials_Retail_For_DA_Starter
, click and select Clone. - In the Display Name field, enter
<YourInitials>_Retail
. (For example:AB_Retail
.) - Click Clone.
- Repeat the cloning process for the
YourInitials_Finance_Skill
andYourInitials_Pizza_Skill
.
Train Your Skills
The next step in the process is to train each of your cloned skills. (Cloned skills are not automatically trained.)
- Open one of the three skills and click in the upper right corner.
- Select the Trainer Ht model and click Submit.
- Repeat this process for the other two cloned skills.
Note: We're using Trainer Ht here, because the training takes less time than it does for Trainer Tm. However, you should use Trainer Tm for production skills and digital assistants.
Publish Your Skills
Finally, before skills can be added to a digital assistant, they must be published. Publishing skills freezes them in their current state. No changes can be made to a version of a skill once it has been published.
- Return to the Skills landing page by clicking Skills in the left navigation.
- Select one of the skills that you just trained, click in its tile and select Publish.
- In the Publish Skill dialog, click Publish.
- Repeat steps 2 and 3 for the other two skills.
Create Your Digital Assistant and Add Skills
Now we'll create a digital assistant and then add our skills to it.
Create a Digital Assistant
- In the left navigation, click Development and select Digital Assistants.
- Click + New Digital Assistant
- In the Create Digital Assistant dialog, for Name and Display Name, enter
<YourInitials>_DA_Pizza_Finance_Retail
.For example:
AB_DA_Pizza_Finance_Retail
- In the Description field, enter
Demo digital assistant for illustrating routing behavior
. - Click Create.
Review the Base Digital Assistant Features
You’ve now created a digital assistant. Though it doesn't have any skills added to it yet, the DA does have some capabilities. Let’s see what some of those capabilities are.
- Find the tester icon () on the top of the page and click it.
- In the tester's Utterance field, type hi, press Enter, and note the DA's greeting.
- In the right pane, select the Routing tab.
Here you see information about how the digital assistant's response to the user input was determined.
Add Your Published Skills to Your Digital Assistant
Before your DA can do anything useful (like help with ordering a pizza or checking a bank balance), we must add the individual skills that have been specifically developed to accomplish these tasks (the skills that you cloned, trained and published earlier).
- If the tester is still open, close it.
- In your DA, click Add Skill ().
- Find the tiles for each of the three skills and select the checkbox for each.
- Close the Skill Catalog. (The Close button is on the upper right side of the page.)
- Retrain the DA by clicking and clicking Submit.
Now that you have added skills to your DA and trained it, it is now smarter. If you try out your DA at this point, you’ll find that it knows which skills it has and can help a new user discover them.
- Click , click Reset, type help in the Utterance field, and press Enter.
You can see a carousel that lists each of the available skills.
- Click to cycle through the different skills.
Tip: You can use the Filter field to help find your skills.
Explicit Routing, Implicit Routing and Configuring Skills
In general, there are two different ways to begin a conversation with a DA:
- Explicitly include the name of the skill to which you are referring.
- Start a conversation with an utterance that implies a certain desire, and let the DA determine which skill is best suited to handle the input.
Explicit invocation tends to be quicker and require fewer conversational "turns", since the user is telling the DA what skill they want to access. On the other hand, explicit invocation also requires some prior knowledge of what the DA can do.
Explicit Routing Example
- Make sure that the invocation name is set for your copy of the retail skill.
- In the left navigation of the DA, select , select the entry for the retail skill, and scroll down to the Interaction Model section of the page.
- In the Invocation field, enter
Retail Skill
.
- Click , click Reset, type ask retail skill what's my balance in the Utterance field, and press Enter.
- In the right side of the tester, select the Routing tab and scroll down to the Rules section.
Notice in the Rules section that there is a statement about how explicit invocation takes precedence over other potential skill matches (even though those skills had very high confidence scores).
Implicit Routing Example
- In the tester, click Reset, type what's my balance in the Utterance field, and press Enter.
Notice how the Rules section in the Routing tab has changed. Because there was no explicit direction for which skill should handle the utterance, the DA considered all possible candidate skills.
In this case there are multiple skills that might be able to respond (i.e., have high enough confidence levels), so the DA automatically presented another smart dialog for the user to clarify their intentions.
Set Invocation Name and Create Invocation Samples
You may have noticed that the name of the Finance skill is a bit vague. To remedy that and some other things, we need to add some additional configuration options that were not part of the pre-built skill that you imported. We will update the:
- Invocation, which is the name or phrase which a user can input to explicitly access the skill.
- Example Utterances, which are the clickable items that show up in the smart dialogs and trigger specific flows within the skills.
- Close the Tester.
- In the left navigation of your DA, select .
- Select the
<Your_Initials>_Finance_Skill
. - Scroll down to the Interaction Model section.
- Change the Invocation value to
CashBank
. - In the Example Utterances field, edit the phrases to replace
Fin Skill
withCashBank
:ask CashBank to check my balance
go to CashBank
send money using CashBank
Tip: You can open the inline editor for a phrase by mousing over it and then clicking .
- Click , click Reset, type Ask cashbank to check my balance in the Utterance field, and press Enter.
Note how the DA took you directly to the skill that you’ve now named
CashBank
.
You’ve now created a complete digital assistant that is capable of recognizing explicit calls to skills and disambiguating calls to skills when it’s not sure how to resolve an input.
Tuning Confidence Thresholds and Smart Dialogs
Oftentimes we’ll want conversational behavior for our DA to vary by use case. For example, whether the DA confirms its understanding before proceeding will depend on the task at hand.
The Importance of Context
The context of a conversation makes a significant difference in conversational routing. The first utterance with a digital assistant is treated as being in the context of the DA (as opposed to being in the context of a specific skill for later utterances).
- First, make sure that the invocation name is set for your copy of the pizza skill.
- In the left navigation of the DA, select , select the entry for the pizza skill, and scroll down to the Interaction Model section of the page.
- In the Invocation field, enter
Pizza Skill
.
- In the tester, click Reset, type can you cancel my pizza order in the Utterance field, and press Enter.
Your results should look like the image below:
Note how the DA asks which skill to cancel.
Now let’s take a look at how the DA treats the exact same utterance when it is in the context of the pizza skill.
- Click , click Reset, type go to Pizza skill in the Utterance field, and press Enter.
- Now type in the phrase can you cancel my pizza order.
Your results should look like this:
This time the CancelPizza candidate flow (intent) was invoked by the routing engine, even though the Retail Skill was also above the confidence threshold value (as shown in the Candidate Skills section on the Routing tab). This is because extra weight is given to results within the current skill as indicated by the rule that is cited in the Rules section of the Routing tab:
Pinning to context. Will only look for match in current context.
Set Confidence Thresholds to Change Routing Behavior
- Close the tester.
- Click and select the Configurations tab.
- Within the Routing Parameters section of the page, locate the Candidate Skills Confidence Threshold property and change its value to
0.9
. - Click , click Reset, type Can you cancel my pizza order in the Utterance field, and press Enter.
This time you should see very different results:
Notice now how the DA went immediately to the order cancellation in the pizza skill. This is because Pizza Skill is the only skill among the skills evaluated in the Candidate Skills section of the Routing tab that had a confidence score exceeding 90%.
- Important: Change the Candidate Skills Confidence Threshold to
0.7
.Now that you can see the impact that this setting has, it's best to return its value to a more realistic level.
Now let’s change the threshold setting for candidate skills to see what effect this has on the conversation.
Implementing and Configuring Help
A key element of good conversational design relates to the discoverability of your DA’s capabilities. Allowing a user to quickly and easily determine what the DA can do is critical for a good user experience. This includes being able to ask about the DA's capabilities using natural language (e.g. "what can you do for me?").
DA-Level Help vs Skill-Level Help
As previously noted, the conversational context of a help request matters. For example, the DA will provide different responses depending on whether you are in the context of a particular skill or in the context of the DA.
Let’s examine the difference between asking for help when engaged with the DA vs. when within a skill.
- Click , click Reset, type help in the Utterance field, and press Enter.
Because this is the first utterance of the conversation, you’re interacting with the digital assistant. The DA is showing you help for all of its skills.
- Now enter I want to send money.
- Now enter help.
Your results should look like this:
This time the same input ("help") led to a different outcome (skill-specific help). This is because we are now engaged with the CashBank skill.
Non Sequiturs and Conversational Confirmation
In a conversation with a DA, a non sequitur is input that doesn’t make sense within the current flow.
Oracle Digital Assistant has built-in features to simplify the handling of non sequiturs.
Conversational Memory and Non Sequiturs
- Click , click Reset, type I want to order pizza in the Utterance field, and press Enter.
- Now enter how much money do I have in checking?
You can see that the DA asked to confirm that you want to switch from the pizza ordering process.
- Select Yes to confirm that you want to see your balance.
The DA automatically switches to the CashBank skill and answers the balance inquiry.
The DA also remembers that you were in the process of ordering a pizza! So, after displaying your balance, it asks you if you want to go back to OrderPizza.
- Close the tester.
Configuring Confirmation Prompts
The default behavior of Oracle Digital Assistant is to ask for explicit confirmation before exiting a flow.
However, the conversational designer may prefer to allow a user to switch flows without confirmation.
- Click and select the Configurations tab.
- Within the Conversation Parameters section of the page, scroll down to the Interrupt Prompt Confidence Threshold property and set its value to
0.80
. - Click , click Reset, type I want to order a pizza in the Utterance field, and press Enter.
- Now enter how much money do I have in checking.
Your interaction should look like this:
Note that this time, the DA did not ask you to confirm if you wanted to switch to the CashBank skill. It just did it.
You have now seen some examples of the ODA platform’s capabilities such as non sequitur interactions and conversational configuration. This should start to give you a sense of options available for conversational designers to tune DA interactions.
Exit Strategies
By now you’re familiar with ODA’s use of smart dialogs and the customization options behind them. Similar to non sequitur handling, ODA offers various configuration options for exiting flows and exiting the DA itself.
Exit Confirmation
- In the tester, click Reset, type ask CashBank to check my balance in the Utterance field, and press Enter.
You will be presented with a card that contains account options.
- Now enter exit.
Note how your DA understands that you want to exit, and it asks you to confirm.
Let’s configure the DA to not request confirmation of an exit request if it’s confident that the user really wants to exit.
- Close the tester.
- Click and select the Configurations tab.
- Scroll down until you find the Exit Prompt Confidence Threshold property.
- Change the property's value to
0.8
. - Click , click Reset, type ask CashBank to check my balance in the Utterance field, and press Enter.
- Enter exit.
Notice that there isn't a prompt to confirm that you want to exit. It simply exits and provides a message that it has done so.
Learn More
Introduction to Routing in Digital Assistants
F17190-05
June 2021
Copyright © 2021, Oracle and/or its affiliates.
Shows you how to fine tune conversational capabilities and interaction style in a digital assistant.
This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.
If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, then the following notice is applicable:
U.S. GOVERNMENT END USERS: Oracle programs (including any operating system, integrated software, any programs embedded, installed or activated on delivered hardware, and modifications of such programs) and Oracle computer documentation or other Oracle data delivered to or accessed by U.S. Government end users are "commercial computer software" or "commercial computer software documentation" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, the use, reproduction, duplication, release, display, disclosure, modification, preparation of derivative works, and/or adaptation of i) Oracle programs (including any operating system, integrated software, any programs embedded, installed or activated on delivered hardware, and modifications of such programs), ii) Oracle computer documentation and/or iii) other Oracle data, is subject to the rights and limitations specified in the license contained in the applicable contract. The terms governing the U.S. Government's use of Oracle cloud services are defined by the applicable contract for such services. No other rights are granted to the U.S. Government.
This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications.
Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.
Intel and Intel Inside are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Epyc, and the AMD logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.
This software or hardware and documentation may provide access to or information about content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services unless otherwise set forth in an applicable agreement between you and Oracle. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services, except as set forth in an applicable agreement between you and Oracle.