Create a Dialogflow ES agent

This guide shows you how to use the Dialogflow Console to build and test a simple agent.

Before you begin

You should do the following before reading this guide:

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

Create an agent

If you have not already created an agent, create one now:

  1. Go to the Dialogflow ES console.
  2. If requested, sign in to the Dialogflow Console. See Dialogflow console overview for more information.
  3. Click Create Agent in the left sidebar menu. (If you already have other agents, click the agent name, scroll to the bottom and click Create new agent.)
  4. Enter your agent's name, default language, and default time zone.
  5. If you have already created a project, enter that project. If you want to allow the Dialogflow Console to create the project, select Create a new Google project.
  6. Click the Create button.

Import the example file to your agent

The steps in this guide make assumptions about your agent, so you need to import an agent prepared for this guide. When importing, these steps use the restore option, which overwrites all agent settings, intents, and entities.

The agent prepared for this guide is a new agent, with no user-defined intents or entities.

To import the file, follow these steps:

  1. Download the new-agent.zip file.
  2. Go to the Dialogflow ES console.
  3. Select your agent.
  4. Click the settings button next to the agent name.
  5. Select the Export and Import tab.
  6. Select Restore From Zip and follow instructions to restore the zip file that you downloaded.

Intents

Intents categorize an end-user's intention for one conversation turn. For each agent, you define many intents, where your combined intents can handle a complete conversation.

Default intents

When you create an agent, two default intents are created for you:

  • Default Welcome Intent: This intent is matched when the end-user begins a conversation with your agent. This intent should return a response that lets the end-user know what your agent does or what they can say to begin a conversation.
  • Default Fallback Intent: This intent is matched when the agent cannot match the end-user expression to any other intent.

To see these intents, go to the intent list for your agent:

  1. Go to the Dialogflow ES console.
  2. Select the agent you just created.
  3. Click Intents in the left sidebar menu.

The middle of the console shows the list of intents for the agent.

Intents list screenshot

Test the Default Fallback Intent

Simulator screenshot

The Dialogflow simulator is on the right side of the console. With the simulator, you can test your agent by speaking or typing messages.

Try the agent now:

  • Click the Try it now field.
  • Type What is your name?.
  • Press enter.

The agent's response appears in the Default Response section. Since your input didn't match any intent, the Default Fallback Intent was matched, and you received one of the default replies.

Create a new intent

The steps in this section create an intent that can answer the question "what is your name?". For each intent, you define many training phrases. A training phrase is an example of what an end-user might type or say to your agent, also known as an end-user expression. You should define many training phrases that provide Dialogflow with a variety of expressions that should match an intent.

Create an intent:

  1. Click the add intent button next to Intents in the left sidebar menu.
  2. Enter get-agent-name in the Intent name field.
  3. In the Training Phrases section, click Add training phrases.
  4. Enter the following training phrases, pressing enter after each entry:

    • What is your name?
    • Do you have a name?
    • Tell me your name

    Training phrases screenshot

  5. In the Responses section, enter the following in the Text Response section:

    • My name is Dialogflow!

    Training phrases screenshot

  6. Click the Save button and wait until the Agent Training dialog indicates that training is complete.

Test your intent

Simulator screenshot

In the simulator, type What's your name? and press enter.

Your agent responds to the expression correctly, even though the expression was a little different from the training phrases you supplied.

Dialogflow uses training phrases as examples for a machine learning model to match end-user expressions to intents. The model checks the expression against every intent in the agent, gives every intent a score, and the highest scoring intent is matched. If the highest scoring intent has a very low score, the fallback intent is matched.

Parameters and entities

When an intent is matched at runtime, Dialogflow provides the extracted values from the end-user expression as parameters. Each parameter has a type, called the entity type, which dictates exactly how the data is extracted. Unlike raw end-user input, parameters are structured data that can easily be used to perform some logic or generate responses.

When building an agent, you control how data is extracted by annotating parts of your training phrases and configuring the associated parameters.

Create parameters

Create a new intent with parameters:

  1. Click the plus button next to Intents in the left sidebar menu.
  2. Name the intent set-language at the top of the intent form.
  3. Add the following training phrases:
    • I know English
    • I speak French
    • I know how to write in German
  4. Click the Save button and wait until the Agent Training dialog indicates that training is complete.

    Annotated training phrase screenshot

Dialogflow automatically detects parameters in training phrases that are recognized as system entities. These are entities provided by Dialogflow for many common data types like location, color, and date.

Below the Training phrases section, Dialogflow creates a row in the Action & parameters table:

Annotated training phrase screenshot

  • Required: The checkbox is not checked, so this parameter is optional.
  • Parameter Name: This parameter is automatically named language, because the parameter is recognized as a language.
  • Entity: This is the entity type. It is recognized as a @sys.language system entity.
  • Value: This is the identifier you use when referencing the value of this parameter.
  • Is List: The checkbox is not checked, so the parameter is not a list.

Use parameter data in a response

The value of a parameter can be used in your responses. For example, you can use the $language parameter reference in your responses when building an agent. At runtime, it will be replaced with the language specified in the end-user expression.

Add a response that uses a parameter:

  1. Scroll down to the Responses section.
  2. Add the following text response: Wow! I didn't know you knew $language.
  3. Click the Save button and wait until the Agent Training dialog indicates that training is complete.

Test your parameter

Simulator screenshot

In the simulator, enter I know Russian.

You can see that Dialogflow correctly extracts the language parameter with the value Russian, and Russian was correctly inserted where the parameter reference was used in the response.

Create your own entities

In most cases, you have specific data you need to gather from users that isn't provided by system entities. You can create custom entities to handle this.

Create a custom entity:

  1. Click the add entity button next to Entities in the left sidebar menu.
  2. Enter language-programming for the name of the entity.
  3. Add the following entity entries (rows):

    Reference Value Synonyms
    JavaScript JavaScript, js, ECMAScript
    Java Java
    Python Python, py
  4. Click the Save button and wait until the Agent Training dialog indicates that training is complete.

Entity use screenshot

Dialogflow can handle simple things like plurality and capitalization, but you should add all possible synonyms for your entries. The more you add, the better your agent can determine your entities.

Use your new entity

Add training phrases to the set-language intent that make use of the new entity:

  1. Click Intents in the left sidebar menu.
  2. Click the set-language intent.
  3. Add the following training phrases:
    • I know javascript
    • I know how to code in Java
  4. Notice that the programming languages in these training phrases are automatically annotated and added to parameters in the Action and Parameters section.
  5. In the Responses section, add the following second text response: $language-programming is an excellent programming language..
  6. Click the Save button and wait until the Agent Training dialog indicates that training is complete.

Test your new entity

Simulator screenshot

In the simulator, enter I know how to code in py.

You can see that Dialogflow correctly extracted py for the language-programming parameter, identified it as the Python entity, and inserted the value in the response.

Contexts

To control the flow of the conversation, you can use context.

Add a follow-up intent

Follow-up intents provide a simple way to control a conversation without having to create and manage contexts manually.

When you create a follow-up intent, an output context is added to the parent intent and an input context of the same name is added to the child intent. This means that the follow-up intent is matched only when the parent intent is matched in the previous conversational turn.

Add a custom follow-up intent to the set-language intent:

  1. Select the set-language intent you created in previous steps.
  2. In the Response section, update the text response:
    • Wow! I didn't know you knew $language. How long have you known $language?
  3. Click the Save button and wait until the Agent Training dialog indicates that training is complete.
  4. Click Intents in the left sidebar menu.
  5. Hover over the set-language intent and click Add follow-up intent.
  6. Click custom in the revealed list.
  7. Click the Save button and wait until the Agent Training dialog indicates that training is complete.

Dialogflow automatically names the follow-up intent set-language - custom.

Followup screenshot

Intent matching with follow-up intents

Follow-up intents are only matched after the parent intent has been matched. Since the set-language - custom intent is only matched after the set-language intent, you can assume that the user has just been asked the question How long have you known $language?. Now you can add training phrases for likely user answers to that question:

  1. Click Intents in the left sidebar menu.
  2. Click the set-language - custom intent.
  3. Add the following training phrases:
    • 3 years
    • about 4 days
    • for 5 years
  4. Click the Save button and wait until the Agent Training dialog indicates that training is complete.

Test your follow-up intent

Enter I know French in the simulator, then answer the question How long have you known French with about 2 weeks.

Despite there being no response for the second expression (about 2 weeks), you can see the expression is matched to the correct intent (set-language - custom), and the duration parameter is correctly parsed (2 weeks).

Intents and contexts

Inspect the set-language intent to see that set-language-followup is listed as an output context and is prefaced by the number 2. This number is called the lifespan.

Output context screenshot

After the set-language intent is matched, the set-language-followup context is active and attached to the conversation for two turns (lifespan of 2). Therefore, when the user responds to the question, How long have you known $language?, the set-language-followup context is active.

Inspect the set-language - custom intent to see that set-language-followup is listed as an input context, which is the same as the output context for the set-language intent.

Any intents with an input context that matches an active context are heavily favored when Dialogflow matches intents.

Contexts and parameters

Contexts store parameter values, and you can access the values of parameters defined in the set-language intent when its output context is active.

In the set-language - custom intent, you only asked for the duration the user has known the language, and not the referenced language itself.

To reference the language in the response:

  1. Update the set-language - custom intent text response to I can't believe you've known #set-language-followup.language for $duration!
  2. Click the Save button and wait until the Agent Training dialog indicates that training is complete.

The #set-language-followup.language reference is known as a parameter reference for an active context.

Test the context parameter

Enter I know French in the simulator, and then respond to the question with 1 week. Notice that the language parameter value is retrieved from the context.

Productionization

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

What's next

Try the fulfillment quickstart.