Build an agent using flows

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:

1. Read flow basics.
2. Perform setup steps.

Create an agent

Create a new agent for this guide:

1. Open the Dialogflow CX console.
2. Create or choose a project.
3. Click Create agent.
4. Select Build your own.
5. Complete the form for basic agent settings:
   1. You can choose any display name.
   2. Select your preferred location. Click the Edit button if you want to change advanced location settings.
   3. Select your preferred time zone.
   4. Select the default language for your agent.
   5. Optionally enable Stackdriver logging.
6. 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:

1. Click the Test Agent button to open the simulator.
2. Enter hello in the text entry and press enter.
3. The agent responds with a default welcome response.
4. Close the simulator.

The following steps were taken by the agent for this end-user input:

1. 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.
2. One of the evaluated routes has the Default Welcome Intent as an intent requirement. Your input matched this intent, so the route was called.
3. The called route has several fulfillment response messages. The agent picked one at random and added it to the response queue.
4. The called route has no transition target, so the active flow and page did not change.
5. 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:

1. Click the Build tab.
2. Select the Default Start Flow in the Flows section.
3. Click the Start node in the graph. This is the start page for the Default Start Flow.
4. 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.
5. 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.
6. Click Save.
7. Close the intent route editing panel.

Test the updated welcome response message

To test your updated response:

1. Click the Test Agent button to open the simulator.
2. Enter hello in the text entry and press enter.
3. The agent responds with your new message.
4. 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:

1. Select the Manage tab.
2. Click Intents.
3. Click Create.
4. Enter store.location for the intent display name.
5. 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?
6. 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:

1. Click the Build tab.
2. Select the Default Start Flow in the Flows section.
3. Click the add button in the Pages section. A text entry for the page display name appears.
4. Enter Store Location for the display name of the page and press enter.
5. Click the options button next to the page display name.
6. Select Edit to open the page editing panel.
7. Find Entry fulfillment and click Edit fulfillment.
8. Enter Our store is located at 1007 Mountain Drive, Gotham City, NJ. in the Agent Says field.
9. Click Save.
10. 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:

1. Click the Build tab.
2. Select the Default Start Flow in the Flows section.
3. Click the Start node in the graph. This is the start page for the Default Start Flow.
4. Add the following intent route:
   • Intent: store.location
   • Transition Page: Store Location
5. Click Save.
6. 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:

1. Click the Test Agent button to open the simulator.
2. Enter What is the store location? and press enter.
3. The agent provides the address.
4. Close the simulator.

The following steps were taken by the agent for the end-user input:

1. 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.
2. One of the evaluated routes has store.location as an intent requirement. Your input matched this intent, so the route was called.
3. The called route has no fulfillment response messages, so it added nothing to the response queue.
4. The called route has a transition target, so the active page changed to the Store Location page.
5. The Store Location page has an entry fulfillment, so the response message for the fulfillment was added to the response queue (the address).
6. 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:

1. Click the Start node in the graph.
2. Click the Intent route add button. The intent route editing panel opens.
3. In the Intent section, select New intent. The intent editing panel opens.

4. Create a store.hours intent with the following training phrases:

   • What are your store hours?
   • What time do you close?
   Note: Outside of this example, production agents must have a minimum of 10 training phrases per intent.

5. Click Save to save the intent. The intent editing panel closes.

6. Scroll down to the Transition section in the intent route editing panel.

7. For Page transition, select New page.

8. Enter Store Hours in the text entry that appears.

9. Click Save. The new page appears on the graph, because there is now a transition that leads to it.

10. Close the intent route editing panel.

11. Add an entry fulfillment that provides the store hours, similar to steps taken for Store Location.

12. 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:

1. Select the Manage tab.
2. Click Entity Types.
3. Click +Create.
4. Set the display name to size.
5. Add the entity entries listed in the table above.
6. 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:

1. Select the part of the training phrase that you want to annotate.
2. Select the desired entity type from the list.
3. 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:

1. Click the New Order page in the graph.
2. Click the Parameters add button. The parameters editing panel opens.
3. Add the parameters as described in the table above.
4. Click Save.
5. 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?	The Default Welcome Intent route in the Default Start Flow is called. The fulfillment for this state handler ("Hello, this...") is added to the response queue. The agent sends the response queue to the end-user.
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?	The order.new intent route in the Default Start Flow is evaluated. The order.new intent is matched, and the color intent parameter is set to "blue". The session transitions to the New Order page, and the color intent parameter becomes a session parameter. The New Order page has an entry fulfillment ("Ok, let's start..."), so this is added to the response queue. The color session parameter is used to fill the like-named form parameter. The true condition route in the New Order page is evaluated and called. It has a response message ("I'd like to collect..."), so this is added to the response queue. The pages's form is not filled, so the agent uses the size prompt ("What size...") and adds this to the response queue. The agent sends the response queue to the end-user.
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.	The end-user input fills the size parameter requested by the agent in the previous conversation turn. The form completion route in the New Order page is evaluated and called. It has a fulfillment ("You have selected..."), which is added to the response queue with its parameter references resolved to actual values supplied by the end-user. The session transitions to the Order Confirmation page. The Order Confirmation page has an entry fulfillment ("You can pick up..."), which is added to the response queue. The agent sends the response queue to the end-user. The session transitions to End Session.

Productionization

Before running your agent in production, be sure to implement the productionization best practices.