Before you Begin
This 60-minute hands-on lab is an entry-level exercise for building a skill in Oracle Digital Assistant.
Background
Oracle Digital Assistant is an environment for building digital assistants, which are user interfaces driven by artificial intelligence (AI) that help users accomplish a variety of tasks in natural language conversations. Digital assistants consist of one or more skills, which are individual chatbots that are focused on specific types of tasks.
In this lab, you will create a skill that can be used for interactions with a pizzeria, including ordering pizzas and canceling orders. As part of this process, you will:
- Define intents, utterances, entities.
- Design a conversation flow.
- Validate, debug and test your skill.
What Do You Need?
- Access to Oracle Digital Assistant
Create a Skill
In this lab, we're starting from scratch. So the first thing you'll do is create a new skill.
- With the Oracle Digital Assistant UI open in your browser, click to open the side menu.
- Click Development and then select Skills.
- Click again to collapse the side menu.
- Click the + New Skill button.
- For Display Name enter
Pizza King
. If you are working in an environment where others may also be creating the same tutorial, prefixPizza King
with your unique initials. - Optionally, fill in a one-sentence description (e.g.,
Skill for ordering from Pizza King
) - For the other fields, leave the default values. Note that the Dialog Mode is Visual. Later on in this tutorial, you're going to create a dialog flow, the definition of the skill-user conversation, using the declarative approach of the Visual Flow Designer.
- Click Create.
The designer will then open on the Intents page. Here's where we'll begin to express the Pizza King customer use case in terms of the concepts that support Natural Language Processing (NLP).
Description of the illustration
The Create Skill dialog appears.
Create Intents
Oracle Digital Assistant's underlying natural language processing (NLP) engine doesn't inherently know about the business or task that a skill is supposed to assist with. For the skill to understand what it should react to, you need to define intents and examples (utterances) for how a user would request a specific intent.
For the Pizza King example, you will create intents for ordering pizza, cancelling an order, and filing a complaint. The order pizza intent is a regular intent, which means that it's mapped to a specific flow that will likely involve one or more exchanges between the user and skill. The cancel pizza and file complaint intents are answer intents, meaning that users who express these intents will get a simple static answer. You are implementing these intents as answer intents in the interest of time. You would not typically implement intents that are related to a process like filing a complaint as answer intents, which are often used for returning answers to FAQs.
Create the Order Pizza Intent
- Click the + Intent button.
- Next to the Conversation Name field, click , and enter
Order Pizza
. - In the Name field, type
OrderPizza
. - Select and copy all of the example sentences below to your clipboard:
- Would you happen to have thin crust options on your Pizzas?
- Let's order a cheese pizza
- Would love a large Pepperoni please!
- I feel like eating some pizza
- I would like to order a pizza
- Can I order a Pizza?
- What's on the menu today?
- I want pizza
- Do you server gluten-free pizza?
- I want to order pizza for lunch
- Do you have deep dish pizzas available?
- Order Pizza!
(You'll notice that it's fine for utterances to have inconsistent punctuation and capitalization.)
- In the Examples section, click Advanced input mode.
- In the Utterances to Add field, paste the examples. Then click Create.
Below the Examples section, you should see a table with the utterances that you just added.
Create the Cancel Pizza Intent
The next two intents are not for a transactional intents like OrderPizza. They are instead answer intents: they return a single answer in response to the resolved user input. Though you typically use answer intents for FAQs, here we'll use them for Cancel Pizza and File Complaint so that we can demonstrate a multi-intent skill in action without first having to implement flows for all of the intents.
- Click the + Add Intent button (located at the top left of the page).
- Next to the Conversation Name field, click , and enter
Cancel Pizza
. - In the Name field, type
CancelPizza
. - Click in the Answer field. Enter
I am sorry to hear this. Let me take your cancellation request.
- Select and copy all of the example sentences below to your clipboard:
- Can i cancel my order?
- Cancel my order
- Cancel my Pizza please
- How do I cancel my order?
- I don't want my Pizza anymore
- I really don't want the Pizza anymore
- I'd like to cancel my order please
- Its been more than 20 mts. Please cancel my order and issue a refund to my card.
- Need to cancel my order
- Please cancel my pizza order
- Please don't deliver my Pizza
- In the Utterances to Add field, select Advanced input mode (if needed), then paste the examples.
- Click Create.
Create the File Complaint Intent
- Click the + Add Intent button.
- Next to the Conversation Name field, click , and enter
File Complaint
. - In the Name field, enter
FileComplaint
. - Click in the Answer field. Enter
I am sorry to hear this. Let me take your complaint details.
- Select and copy all of the example phrases below to your clipboard:
- I am upset
- You charged me wrong
- I want to file a complaint
- I am not happy with my recent order
- I have some grief to share
- I want to speak with a manager
- Can I raise a complaint
- In the Utterances to Add field, paste the examples and then click Create.
Your screen should look similar to what is shown in the image below:
Note:
If you're stuck, you can add the intents and their utterances by importing thePizzaKing-Intents.csv
file that's in PizzaKing-Intents_CSV.zip.
Extract this ZIP file to your local system, then click More (located next to +Add Intent), choose Import intents, and browse to, and select, the PizzaKing-Intents.csv
file. Train Your Intents
You've now provided the basic ingredients that allow the skill to recognize user input for ordering a pizza, but right now, the skill has no cognition. It can't understand any user input.
To enable the skill to interpret user input based on the utterances that you just added, you need to train to build the intent model.
- On the right side of the page, locate and click the Train.
- Select Trainer Tm and then click Submit.
Wait for the training to complete. It might take a few minutes.
Test Your Model
It is not realistic to expect to get the training of your intent model right the first time you do it. Good intent models are created in an iterative cycle of training, testing, retraining, and retesting.
A good intent model is one that has a low ambiguity between the different intents. So let's see how well we’re doing so far.
- Click the Test Utterances link that appears near the top of the Intents page.
The Utterance Tester slides out from the right side of the page with its Quick Test page open.
- In the Language field of the dialog, select English.
- In the Utterance field, type I want to order pizza. Then click the Test button (located at the bottom right of the tester) and look at the test results.
- Click Reset (located at the bottom right of the tester).
- Now scroll back to the top of the dialog, enter I feel like eating some pizza in the Utterance field, and then click Test.
This should also resolve to the OrderPizza intent. Click Reset.
- Now try Cancel my order.
This should resolve to the CancelPizza intent. Click Reset.
- And now try Dude, bring me pizza and see what that resolves to.
- Type You are expensive and you still don't deliver on time in the Utterance field and click Test.
In all likelihood, the FileComplaint intent did not receive the highest score. In the above screenshot, CancelPizza "won". For us humans, it is easy to see that "You are expensive and you still don't deliver on time" is not an order but a complaint. However, a skill first needs to be trained with relevant utterances before it is able to gain the same understanding.
- To remedy this, you're going to add this utterance to the FileComplaint intent:
- Click Show More to access the FileComplaint result.
- Select the FileComplaint radio button.
- Click Add to Intent.
Note:
In these examples, you might get slightly different confidence scores than the ones shown here. And in some cases, the matching intents themselves could vary if the differing confidence scores push those intents above or below the given confidence thresholds. The cause of this variance is the non-deterministic nature of the AI behind the natural language processing and the fact that, in order to make this tutorial simpler, these skills have a limited number of training utterances. In real world scenarios, you would be adding a minimum of 80 to 100 utterances per intent. - Retrain the skill with Trainer Tm.
- Think of two or three more phrases that the system might have problems matching to an intent with high confidence and try them in the Intent tester. If you find one that doesn’t match well, select the intent that it should be resolved to and click Add to Intent.
- Train the model again and then re-test.
Notes on What You Just Did
In this part of the tutorial, you have tested the quality of your intent training with the goal being to ensure a high level of confidence when resolving intents.
In a real skill project, you would always need to go back to the intent testing with the user-provided entries that you find in the conversation logs. In cases where the test input doesn't resolve to intents as well as it should, you'll want to augment the intent's utterances to improve the training model.
Note:
You can save utterances as test cases in the Utterance Tester. You can run these test cases every time you update the training model.Create Entities
Now it's time to add entities, which detect information in the user input that can help the intent fulfill a user request. For the Pizza King business, such information could be pizza size, pizza toppings, and delivery time. For example, the user input "I'd like to order a small meaty pizza at 9:00 pm" contains all three of these information types.
We'll create custom entities for size and topping and later use a built-in entity for time. While we're at it, we'll add some synonyms (including some common misspellings) that optimize the entity's ability to tag words from sloppy user input.
Create Entities for Pizza Size and Pizza Topping
- In the left navigation for the designer, select .
- Click + Add Entity to create a new entity.
- In the Name field, change the value to
PizzaSize
. - In the Configuration section, select Value list from the Type menu.
- Click + Value.
- For Value, type
small
. - For Synonyms, type
Personal
, then click Enter. Typesmallest
, and then click Enter again. - Click Create.
- Following the procedure described in the previous four steps, you are going to add two more values to the PizzaSize entity: one for medium-sized pizza orders, and one for large-sized pizza orders.
Value Synonym(s) medium
Middle
large
Big
grande
biggest
- Click Create to complete the entity.
- Click + Add Entity to create another entity.
- In the Name field, change the value to
PizzaTopping
. - In the Configuration section, select Value List from the Type menu
- Add separate values for
Meaty
,Veggie
,Hot and Spicy
, andAmerican Hot
. - Click Create.
PizzaSize and PizzaToppings should appear in the list of entities, as shown in this image:
Edit Prompts for the Entities
Now let's enter some text to prompt users to enter values that can be matched by these entities.
- In the list of entities, select PizzaSize.
- Scroll down to the Prompts section.
- In the row for the default prompt ("Please enter PizzaSize"), click , replace the text with Which size would you like for your pizza? Then click Enter.
- In the list of entities, select PizzaTopping.
- Scroll down to the Prompts section.
- In the row for the default prompt ("Please enter PizzaTopping"), click , replace the text with What type of pizza would you like?
Later on in the tutorial, you'll notice that the skill will use these prompts when it needs to ask the user for pizza size and pizza topping.
Create a Composite Bag Entity
In this step, you're going to simplify your development efforts using a composite bag entity, which enables you to manage the three entities that you just created as a consolidated entity. When these entities are controlled by a composite bag, you won't need to create separate references for them when you create the voice of your skill (aka the dialog flow) later on. In addition to unifying your entities, the various composite bag properties enable your skill to match entity values in complex, real-world scenarios that involve erratic user input.
- Click + Add Entity.
- In the Name field, enter
cbePizza
. - In the Configuration section, select Composite Bag from the Type menu.
Add Entities to the Composite Bag
- Click cbePizza in the entity list to access its editing page.
- To add the entities that are managed by the composite bag, you need to create references for them called bag items. Click + Bag Item.
- In the Add Bag Item dialog, replace BagItem1 in the Name field with
pizzaSize
. - Select Entity as the type.
- Choose PizzaSize from the Entity Name list.
- Click Close (located at the upper right).
- Repeat these steps to create a bag item for the PizzaTopping entity:
- Name the item
pizzaTopping
. - Choose PizzaTopping from the Entity Name list.
- Name the item
- In addition to enabling users to select the pizza type and size, the skill will also enable them to enter a delivery time. For this, you're going add another entity item to the bag. Unlike the PizzaSize and PizzaType entities that you created from scratch, you're instead going to use the built-in TIME entity (or if your skill is Version 22.08 or higher, the DATE_TIME entity), which recognizes various time formats in the user input. To create this item:
- Click +Bag Item.
- Enter
deliveryTime
in the Name field. - Select Entity from the Type list.
- Choose TIME from the Entity Name List. If your skill is Version 22.08 or higher, choose DATE_TIME from the Entity Name List. Then choose TIME from the Subtype menu.
- Scroll down the page, then click + Prompt.
- Type
When can we deliver that for you (e.g., 4pm)?
and then click Enter. - Click Close. When you're done, the Bag Items section of the cbePizza editing page should look like this:
- Click Train.
- Select Entity, then click Submit.
Associate the Entities with OrderPizza Intent
For an entity to be recognized when parsing the user input message, it needs to be associated with the appropriate intents. In this case, we need to associate the composite bag entity with the OrderPizza intent.
- In the left navigation for the designer, select .
- Select the OrderPizza intent.
- Click the Add Entity dropdown (in the upper right side of the page), type
pizza
in the Filter Field, and select cbePizza. - Retrain the model with Trainer Tm.
Test the Entities
The Utterance Tester feature enables you to test whether the skill identifies entity values in user input.
- In the left navigation for the designer, select .
- Click the Test Utterances link. Click Reset to clear the input field.
- In the Utterance field of the dialog, type I want to order a small hot and spicy pizza at 7:30 pm and then click Test.
Since the entities are recognized in the user input, the skill doesn’t have to ask the user for that information later in the flow.
The Utterance Tester applies entity labels to the matched terms in the utterance. It also notes that the entities belong to the cbePizza entity. The labelling for the deliveryTime value changes depending on the version you're using. For Version 22.10, the Utterance Tester labels the subtype selected for the DATE_TIME entity (DATE_TIME.TIME, for example).
- Now let's try another utterance. In the Utterance field, now type I want to order the biggest meaty pizza at noon and click Test.
The result should look like what is shown below. The PizzaSize label notes that the "biggest" synonym is matched for the PizzaSize entity. The Time label notes that "noon" is a recognized value.
Notes on What You Just Did
In this part of the tutorial, you have created custom entities for the Pizza King OrderPizza intent, associated the entities with the intent, and tested the entity recognition in the embedded skill tester.
Similar to the PizzaOrder intent, you would typically need to create and associate entities for the other intents as well. In the interest of time, this tutorial only focuses on the PizzaOrder intent.
Design the Dialog Flow
With the NLP model created, you are ready to build a dialog flow for the skill. The dialog flow is a blueprint for the interactions that enable the conversation between the skill and the user. Although you're going to create a single flow in this tutorial, a skill can have multiple flows that support different use cases and functions.
Each flow is made up of one or more states, and each state executes a function: rendering a skill response message, authenticating a user, branching the conversation when certain conditions are met, etc. The Visual Flow Designer provides you with templates for each state.
Create the Order Pizza Flow
Now that you have the OrderPizza intent and the pizza variable, you're ready to start building the dialog flow.
- Click Flows in the left navbar.
- Click Add Flow.
- In the Create Flow dialog, enter
intent.reg.order
as the name. - For the description, enter
Order pizza flow
. - Select OrderPizza from the Intent Name list to create a mapping between the OrderPizza intent and this flow. This mapping instructs the Main Flow to execute this flow when user input resolves to the OrderPizza intent. You can also set intent event mappings like this one within the Main Flow. .
- Click Create.
- Click intent.reg.order in the flow list.
- In the dialog flow editor, hover over the Start node to display its menu . Click the menu then click Add start state.
- In the Add State dialog, choose Send Message, then enter
startOrderPizza
as the name andGreeting Message
as the description. Then click Insert.
When you're done, the
startOrderPizza
state should appear in the canvas with its property editor open to the Component page. (If the property editor isn't open, click thestartOrderPizza
state.) Note that the editor tags an error for this flow which prevents it from being viable. In this case, it's because this component needs a text message. - Paste the following into the Messages field:
Ok, let's get that order sorted.
When you're done, the Order Pizza flow should look like this so far. - Hover over the
startOrderPizza
state to access the menu. Then click Add State. - In the Add State dialog, choose Resolve Composite Bag.
- Name the state
resolve_cbePizza
. - Enter
Pizza menu
as then description. Then click Insert. - Like the startOrderPizza state, the resove_cbePizza state is flagged with an error because of an undefined property. For this state, the Component page tells you that you can fix this error by adding a variable reference a composite bag entity, which in this case, is the cbePizza entity. To create this variable, click Create.
- Because only the
intent.reg.order
flow uses this variable, choose Flow Scope Variable. The value held by this variable will persist only until the flow executes. If the other flows in this skill needed this variable, then you would create a skill scope variable instead. - For the name, enter
pizza
. - For the description, enter
Resolves the pizza order
. - Select Entity as the variable type, then select cbePizza as the entity name.
- Click Apply.
- Hover over the
resolvePizza
state to access the menu, then click Add state. - Select Send Message.
- Name the state
displayOrderConfirmation
. - Enter
Confirmation message
as the description. Then click Insert. - In the Component page of the property inspector, enter the following confirmation message. It uses Apache FreeMarker expressions to access the values set for the pizza variable:
- For Versions 22.04 and 22.06:
Your ${pizza.value.pizzaSize.value} ${pizza.value.pizzaTopping.value} pizza will be delivered at ${pizza.value.deliveryTime.date?long?number_to_time?string('HH:mm')}
- For Version 22.08 and higher:
Your ${pizza.value.pizzaSize.value} ${pizza.value.pizzaTopping.value} pizza will be delivered at ${pizza.value.deliveryTime.value?time.xs?string['hh:mm a']}.
When you're done, the flow should look like this:
- For Versions 22.04 and 22.06:
When you're done, the resolve_cbePizza
state should appear in the canvas with its property editor open to the Components page. Note the next
transition line that connects it to the startOrderPizza
state.
Notes on What You Just Did
In this section:
- You created a variable that references the composite bag entity and a state for resolving this composite bag entity. If you hadn't created the composite bag entity, you would have needed to create separate variables for pizza size, pizza topping, and delivery time that would, in turn, require separate states in the dialog flow.
- When you created the dialog flow, you mapped it to the OrderPizza intent so that it's executed whenever user input gets resolved to the OrderPizza intent at or above the confidence level.
- By creating the
resolve_cbePizza
state, you learned how to leverage a composite bag to create a compact flow. Finally, for the output message in thedisplayOrderConfirmation
state, you added an Apache FreeMarker expression that accessed the values set for the skill-level pizza variable.
Test Your Skill
In this section, you'll test out the intent.reg.order
flow, but also test out the conversation flows that are handled automatically: the FileComplaint and CancelPizza answer intents and unresolvedIntent
.
Test the Order Pizza Flow
- Open the skill tester by clicking at the top of the page.
- In the Utterance field, type I want to order pizza and then press Enter.
You should see a menu of pizza sizes:
- Click the Intent/Q&A view to see how the utterance resolves to the OrderPizza intent.
- Click the Conversation view.
Note the dialog flow traversal that routes the request from the Main Flow to the
intent.reg.order
flow. - Back in the tester, select an option (e.g., small) from the menu.
A prompt for the pizza topping should appear.
- Continue the conversation by selecting a topping (e.g., Veggie).
A prompt for the delivery time should appear.
- Enter a delivery time, such as
7:30 p.m.
You should receive an order confirmation that summarizes the order. In the Conversation Tester, note the dialog flow traversal that routes the request from the Main Flow to the
intent.reg.order
flow.For Version 22.08 and higher, the FreeMarker expression used in the confirmation message will enable the delivery time to be output in a 12-hour format instead of a 24-hour format (07:30 PM instead of 19:30, for example).
- Note that the state traversal rendered in the Conversation view includes the
displayOrderConfirmation
state. - Click Reset.
- Now try entering Dude, can you get me the biggest hot and spicy pizza you can make at noon.
This time, you should receive the confirmation message immediately.
- Within the Conversation tab of the tester, scroll down to take a look at the Variables section to see the entity values that were extracted from your input.
You can expand the nodes for each entity to see details of the entity values that were extracted.
- Finally, enter I want to order a veggie pizza at 8:00pm.
This time the topping menu and the delivery time should be skipped, but the pizza size list should be displayed.
- Select a pizza size.
Your order should then be completed.
Test the Answer Intents
In testing the order pizza intent, you saw how utterance was resolved to the OrderPizza intent, which you mapped to the intent.reg.order
flow. Now, you're going to test out the FileComplaint and CancelPizza answer intents which are handled automatically. You'll also test out unresolvedIntent
, the flow for handling the user input that can't be resolved to any of the intents that you defined.
- In the Utterance field, enter I want to cancel my order.
The skill should respond with a message regarding pizza cancelation. Because the Main flow alone handles this intent (and the other answer intents that you'll be testing in the section), only the Main flow gets rendered in the Conversation view.
And, in the Intent/Q&A view, you should see that the CancelPizza intent is matched.
- Click Reset
- In the Utterance field, enter I want to speak to your manager and then press Enter.
The skill should respond with "I am sorry to hear this. Let me take your complaint details."
- Now let's try a more random utterance. Click Reset.
- In the Utterance field, enter Can you get me a radio taxi now?
As you can see in the Intent/Q&A view, the confidence threshold level falls below this minimum value of 60% in this case, so the component triggers its unresolvedIntent action.
Congratulations! You have created your first skill and learned key aspects of defining intents, defining entities, designing the conversation flow, and using the Skill Tester to evaluate intent resolution and the conversation flow.
Learn More
Build Your First Skill With Oracle Digital Assistant
F17188-12
April 2023
Copyright © 2023, Oracle and/or its affiliates.
Shows how to create a simple skill in Oracle 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.