This guide shows you how to use the Dialogflow CX Console to build and test a simple shirt ordering agent using flows. When interacting with this agent, you can ask for the store location, get store hours, or make a shirt order.
Your completed agent for this guide will be graphed by the console like the following:
Before you begin
You should do the following before reading this guide:
- Read flow basics.
- Perform setup steps.
Create an agent
Create a new agent for this guide:
- Open the Dialogflow CX Console.
- Create or choose a project.
- Click Create agent.
- Select Build your own.
- Complete the form for basic agent settings:
- You can choose any display name.
- Select your preferred location. Click the Edit button if you want to change advanced location settings.
- Select your preferred time zone.
- Select the default language for your agent.
- Optionally enable Stackdriver logging.
- Click Save.
Optional agent import
This guide walks you through the steps to build a simple shirt ordering agent. If you would like to skip the console steps, you can download the agent and import it.
Default flow and intents
The following flow and intents are created automatically for a new agent. You can find the intents by clicking Manage, then Intents. You can find the flow by clicking Build.
Term | Definition |
---|---|
Default Welcome Intent | The Default Welcome Intent has simple training phrases like "Hi" or "Hello" that are meant to match initial end-user input. You can edit this intent as desired. |
Default Negative Intent | The Default Negative Intent can be used to add training phrases to this intent that act as negative examples. |
Default Start Flow | The Default Start Flow can be used as your only flow. It is the only flow that will be used in this guide. For more complex agents, you can add more flows. This flow has a default intent route with the Default Welcome Intent as an intent requirement. |
Test the default welcome response message
The default flow and intents can handle a basic conversation with only a welcome message. To test your new agent:
- Click the Test Agent button to open the simulator.
- Enter
hello
in the text entry and press enter. - The agent responds with a default welcome response.
- Close the simulator.
The following steps were taken by the agent for this end-user input:
- When you provided input, the Default Start Flow was the active flow, and the flow's start page was the active page. Each of the state handlers applied to the active flow were in scope, so the agent evaluated them.
- One of the evaluated routes has the Default Welcome Intent as an intent requirement. Your input matched this intent, so the route was called.
- The called route has several fulfillment response messages. The agent picked one at random and added it to the response queue.
- The called route has no transition target, so the active flow and page did not change.
- The agent responded with the contents of the response queue.
Edit the welcome response message
You can change this welcome message. To edit the welcome response message:
- Click the Build tab.
- Select the Default Start Flow in the Flows section.
- Click the Start node in the graph. This is the start page for the Default Start Flow.
- Find the intent route with the Default Welcome Intent as an intent requirement and click it. This opens a panel to edit the intent route information.
- Find the fulfillment section and delete all response messages,
then add
Hello, this is a shirt ordering virtual agent. How can I help you?
as the only response. - Click Save.
- Close the intent route editing panel.
Test the updated welcome response message
To test your updated response:
- Click the Test Agent button to open the simulator.
- Enter
hello
in the text entry and press enter. - The agent responds with your new message.
- Close the simulator.
Store location page
A Conversational Agents (Dialogflow CX) conversation (session) can be described and visualized as a state machine. The states of a CX session are represented by pages. So far, you only have one page, so the agent is not very useful. In this section, you create another page that handles questions about the store's location.
Create the location intent
An intent categorizes an end-user's intention for one conversation turn. To create an intent that is matched when end-user input requests the store's location:
- Select the Manage tab.
- Click Intents.
- Click Create.
- Enter
store.location
for the intent display name. - Enter the following training phrases:
Where is the store?
Directions
Tell me the address
Where do I pick up my order?
How do I get there?
Where is the store located?
What street are you on?
What is your address?
How do I get to your store?
Where are you located?
- Click Save.
Create the location page
Now create the new page. You can add an entry fulfillment to this page that gets called whenever the page becomes active. This entry fulfillment should have a response message that provides the store's location. To create the store location page:
- Click the Build tab.
- Select the Default Start Flow in the Flows section.
- Click the add add button in the Pages section. A text entry for the page display name appears.
- Enter
Store Location
for the display name of the page and press enter. - Click the options more_vert button next to the page display name.
- Select Edit to open the page editing panel.
- Find Entry fulfillment and click Edit fulfillment.
- Enter
Our store is located at 1007 Mountain Drive, Gotham City, NJ.
in the Agent Says field. - Click Save.
- Close the page editing panel.
Add a location intent route to the flow
Now you need to create a route that has the store location page as a transition target. When this route is called, the session transitions to the store location page. This route is applied to the Default Start Flow, so it is in scope as long as the flow is active. For a single-flow agent, this means that the route is always in scope. At any point in the conversation, the end-user can ask for the store location, and this route will be called.
To create this route:
- Click the Build tab.
- Select the Default Start Flow in the Flows section.
- Click the Start node in the graph. This is the start page for the Default Start Flow.
- Add the following intent route:
- Intent:
store.location
- Transition Page:
Store Location
- Intent:
- Click Save.
- Close the intent route editing panel.
When you close the editing panel, notice that your new page has a node on the graph. The arrow from the Start node to the Store Location node indicates how the session can transition from node to node.
Test the store location page
To test your page:
- Click the Test Agent button to open the simulator.
- Enter
What is the store location?
and press enter. - The agent provides the address.
- Close the simulator.
The following steps were taken by the agent for the end-user input:
- When you provided input, the Default Start Flow was the active flow, and the flow's start page was the active page. Each of the state handlers applied to the active flow were in scope, so the agent evaluated them.
- One of the evaluated routes has store.location as an intent requirement. Your input matched this intent, so the route was called.
- The called route has no fulfillment response messages, so it added nothing to the response queue.
- The called route has a transition target, so the active page changed to the Store Location page.
- The Store Location page has an entry fulfillment, so the response message for the fulfillment was added to the response queue (the address).
- The agent responded with the contents of the response queue.
Store hours page using inline creation
In this section, you create a Store Hours page that handles end-user questions about store hours. In previous sections, you created pages and intents from the Build and Manage tabs. This section shows you a faster way of creating these types with inline creation.
To inline create an intent route, intent, and page:
- Click the Start node in the graph.
- Click the Intent route add add button. The intent route editing panel opens.
- In the Intent section, select New intent. The intent editing panel opens.
Create a
store.hours
intent with the following training phrases:What are your store hours?
What time do you close?
Click Save to save the intent. The intent editing panel closes.
Scroll down to the Transition section in the intent route editing panel.
For Page transition, select New page.
Enter
Store Hours
in the text entry that appears.Click Save. The new page appears on the graph, because there is now a transition that leads to it.
Close the intent route editing panel.
Add an entry fulfillment that provides the store hours, similar to steps taken for Store Location.
Close any open editing panels.
Order item page
Next, you will create a page that uses form parameters. When the end-user requests a new shirt order, the session will transition to this page. When active, this page collects a size and color for the shirt order.
Create a custom entity type for shirt size
Entity types are used to control how data from end-user input is extracted. Conversational Agents (Dialogflow CX) provides predefined system entities that can match many common types of data. For example, there are system entities for matching dates, times, colors, email addresses, and so on. You can also create your own custom entities for matching custom data.
For this agent, you can use a system entity for the shirt color, but you need to create a custom entity for the shirt size. The size entity type should have the following entity entries:
Entity | Synonyms |
---|---|
small | small, tiny, little |
medium | medium, regular, average |
large | large, big, giant |
To create this entity:
- Select the Manage tab.
- Click Entity Types.
- Click +Create.
- Set the display name to
size
. - Add the entity entries listed in the table above.
- Click Save.
Create an order intent with intent parameters
You need an intent that is matched when the end-user requests a new shirt order. This intent should also optionally capture the desired shirt color and/or size provided by the end-user in case they provide that info up front.
Parameters are used to capture and reference values that have been supplied by the end-user during a session. Each parameter has a display name and an entity type. Unlike raw end-user input, parameters are structured data that can easily be used to perform some logic or generate responses.
You control how end-user data is extracted with intent matching by
annotating
parts of your training phrases and configuring the associated
intent parameters.
For example, consider a training phrase like
"What is the forecast tomorrow for Tokyo?"
You should annotate "tomorrow" with a date
parameter
and "Tokyo" with a location
parameter.
When you annotate parts of a training phrase,
Conversational Agents (Dialogflow CX) recognizes that these parts are just examples
of actual values that will be provided by end-users at runtime.
For an end-user input like
"What is the forecast on Friday for Sydney?",
Conversational Agents (Dialogflow CX) would extract the date
parameter from "Friday"
and the location
parameter from "Sydney".
To annotate a training phrase with the console:
- Select the part of the training phrase that you want to annotate.
- Select the desired entity type from the list.
- A parameter is created for you in the parameter table below.
Create an intent similar to steps you followed above.
Name this intent order.new
.
For each phrase that contains a color,
annotate the color with a color
parameter
and the @sys.color
system entity type.
For each phrase that contains a shirt size,
annotate the size with a size
parameter
and the @size
custom entity type you created in prior steps.
Your training phrases and parameters should look similar to the following:
Create an order page
Create the new order page following steps similar to prior steps:
- Display name:
New Order
- Entry fulfillment:
Ok, let's start a new order.
Add a form to the order page
For each page, you can define a form, which is a list of parameters that should be collected from the end-user for the page. The agent interacts with the end-user for multiple conversation turns, until it has collected all of the required form parameters, which are also known as page parameters. For each form parameter, you also provide prompts that the agent uses to request that information from the end-user. This process is called form filling.
When an end-user supplies intent parameters for an intent match, the intent parameters become session parameters. When a page initially becomes active, all of its form parameters are pre-filled with any like-named session parameters. So, if the end-user supplies size or color when the order.new intent is matched, these values will be automatically filled for the form.
For the new order page, you need to define two required form parameters:
Required | Display name | Entity type | Is list | Prompt |
---|---|---|---|---|
color | @sys.color | What color would you like? | ||
size | @size | What size do you want? |
To add this form:
- Click the New Order page in the graph.
- Click the Parameters add add button. The parameters editing panel opens.
- Add the parameters as described in the table above.
- Click Save.
- Close the parameters editing panel.
Add a order intent route to the flow
Similar to steps you followed above, add a route to the Default Start Flow. This route should be called when the end-user wants to make a new order:
- Intent: order.new
- Transition Target page: New Order
Confirmation page
Your final page will just confirm the order and end the session.
Create the confirmation page
Create a confirmation page with a response that uses the session parameters to confirm the order:
- Display name:
Order Confirmation
- Entry fulfillment:
You can pick up your order for a $session.params.size $session.params.color shirt in 7 to 10 business days. Goodbye.
Add condition routes to the order page
You can also use conditions to determine whether a route is called. Conditions are commonly used to check whether a form is complete, or they are configured to always be called when evaluated.
To set conditions in the console, check the Set conditions documentation.
Add the following route to the order page, which will be called when the order page form is filled. Note how this condition route uses parameter references in its response to the end-user and how it transitions the session to the Order Confirmation page.
- Condition:
$page.params.status = "FINAL"
- Agent Says:
You have selected a $session.params.size, $session.params.color shirt.
- Transition Page:
Order Confirmation
Add the following route to the order page, which will be called for each conversational turn in which the page is active and the condition route is evaluated. When the condition above is evaluated and called, the page becomes inactive, so this true condition route is not evaluated:
- Condition:
true
- Agent Says:
I'd like to collect a bit more information from you.
Create a condition route to end the session
Add the following condition route to the Confirm Order page to end the session once that page has become active and its entry fulfillment is processed:
- Condition:
true
- Transition Target: Page:
End Session
Test the completed agent
Test the agent with the following dialogue:
Dialogue | Explanation |
---|---|
End-user: Hi Agent: Hello, this is a shirt ordering virtual agent. How can I help you? |
|
End-user: I want to buy a blue shirt Agent: Ok, let's start a new order. Agent: I'd like to collect a bit more information from you. Agent: What size do you want? |
|
End-user: large Agent: You have selected a large, blue shirt. Agent: You can pick up your order for a large blue shirt in 7 to 10 business days. Goodbye. |
|
Productionization
Before running your agent in production, be sure to implement the productionization best practices.