Custom entities

You can create custom entities for matching data specific to your agent. For example, you could define a vegetable entity type that can match the types of vegetables available for purchase with a grocery store agent.

Note: When building your agent, it's best to define your entities prior to adding training phrases to your intents. The console will automatically annotate your training phrases with existing entities. However, if you create entities after training phrases, you can manually annotate the phrases.

Create custom entities

To create a custom entity:

Console

1. Open the Dialogflow CX console.
2. Choose your Google Cloud project.
3. Select your agent.
4. Select the Manage tab.
5. Click Entity Types.
6. Click Create.
7. Enter entity data.
8. Click Save.

API

Use the EntityType's create method. Go to the EntityType API reference

Select a protocol and version for the EntityType reference:

Protocol	V3	V3beta1
REST	EntityType resource	EntityType resource
RPC	EntityType interface	EntityType interface
C++	EntityTypesClient	Not available
C#	EntityTypesClient	Not available
Go	EntityTypesClient	Not available
Java	EntityTypesClient	EntityTypesClient
Node.js	EntityTypesClient	EntityTypesClient
PHP	Not available	Not available
Python	EntityTypesClient	EntityTypesClient
Ruby	Not available	Not available

Close

Limitations

The following limitations apply:

• Custom entity type display names are unique for each agent. Entity type display names should start with a letter and can contain the following: A-Z, a-z, 0-9, _ (underscore), - (dash). Entity reference and synonym values have no such limitation.

Export and import custom entities

Preview

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

You can export and import entities for sharing across agents.

One of the export format options is Json package, which is a zip file that contains a hierarchy of directories and JSON files. The following describes the directory structure:

• entityTypes: This directory contains your entity types.
  • <entity type name>: One or more of these directories exist, and the directory names correspond to entity type display names.
    • entities: This directory contains entity entry files.
      • <language tag>.json: One or more of these files exist, and the file names correspond to language tags. Each file contains language-specific entity entries.
    • <excludedPhrases>: This directory contains excluded phrase files.
      • <language tag>.json: One or more of these files exist, and the file names correspond to language tags. Each file contains language-specific phrase exclusions.
    • <entity type name>.json: This filename corresponds to an entity type display name. The file contains entity-type-specific data not found in other files.

For example:

 entityTypes
 ⤷  Entity Type A
    ⤷  entities
       ⤷  en.json
       ⤷  en-gb.json
       ⤷  en-ca.json
    ⤷  excludedPhrases
       ⤷  en.json
       ⤷  en-gb.json
       ⤷  en-ca.json
    ⤷  Entity Type A.json
 ⤷  Entity Type B
    ⤷  entities
       ⤷  en.json
       ⤷  en-gb.json
       ⤷  en-ca.json
    ⤷  excludedPhrases
       ⤷  en.json
       ⤷  en-gb.json
       ⤷  en-ca.json
    ⤷  Entity Type B.json

When importing entity types, there may be merge conflicts when the display name of an entity type in your existing agent matches that of an imported entity type. You can control the merge behavior when entity type display names match by selecting one of the following:

• Replace existing entity types: An imported entity type overwrites any same-named entity type in your existing agent.
• Merge with existing entity types: The entity entries of an imported entity type are added to the existing entity type. If the same entity entries exist, they won't be duplicated, and the synonyms under them will be merged.
• Rename and import as new entity types: The imported entity type is renamed by appending "_1" to the display name.
• Skip the entity types: The existing entity type remains unchanged, and the imported entity type is ignored.

To export entity types:

Console

1. Open the Dialogflow CX console.
2. Choose your Google Cloud project.
3. Select your agent.
4. Select the Manage tab.
5. Click Entity Types.
6. Select all the entity types you want to export.
7. Click Export selected entity.
8. Select the format and destination.
9. Click Submit.

To import entity types:

Console

1. Open the Dialogflow CX console.
2. Choose your Google Cloud project.
3. Select your agent.
4. Select the Manage tab.
5. Click Entity Types.
6. Click Import.
7. Select the source and merge behavior.
8. Click Submit.

Import entity entries

Preview

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

You can import entity entries to an existing entity type.

The file format used for importing entity entries is the same as the format used for importing entity types. However, the import file can only contain 1 entity type and all the entries under it will be imported to the selected entity type. If the same entity entries exist, they won't be duplicated, and the synonyms under them will be merged.

To import entity entries for an entity type:

Console

1. Open the Dialogflow CX console.
2. Choose your Google Cloud project.
3. Select your agent.
4. Select the Manage tab.
5. Click Entity Types.
6. Select an entity.
7. Click Import to entity.
8. Select a file.
9. Click Submit.