Create and manage entities

When setting up your agent, it's best to define your entities prior to adding the training phrases to your intents. This will ensure the correct words are annotated when the training phrases are supplied. You can create entities afterwards, but you'll need to manually annotate the training phrases in each intent.

Create developer entities

To create a set of developer entities, follow these steps:

  1. In the left menu, click Entities.
  2. Click CREATE ENTITY.
  3. Enter a name for the entity at the top of the page.
  4. Click in the first row and enter an entry.
  5. Click in the next column or press Enter and enter related synonyms for the inital entry.
  6. Continue adding entries and synonyms.
  7. Click SAVE.

Allow automated expansion

Automated expansion of developer entities allows an agent to recognize values that have not been explicitly listed in the entity.

If a user's request includes an item that isn't listed in the entity, automatic expansion recognizes the undefined item as a parameter in the entity. The agent sees the user's request is similar to the examples provided, so it can derive what the item is in the request.

For example, consider a shopping list with items to buy:

If a user says "I need to buy some vegetables", "vegetables" will be picked up as a value, even though it's not included in the @item entity. With automated expansion enabled, the agent sees the user's query is similar to the training phrases provided in the intent and can pick out what should be extracted as a new value.

The closer the user's input is to the examples provided in the training phrases section, the better the results the automated expansion feature provides. This is another reason to provide as many examples as possible.

Batch operations

You can move, copy, or delete multiple entities at once using batch operations.

Operation Description
Copy This keeps the selected entities in the current agent and moves copies into the destination agent.
Move This option removes the selected entities from the current agent and moves them into the destination agent.
Delete This option permanently deletes the selected entities.

Additional options for copy and move operations include the following:

  • Copy related entities: This is generally an option you want to check, as it will also move or copy entities used in the composite entities (entities that consist of two or more entities).
  • Overwrite entities: This option will overwrite entities with the same name.

To copy, move, or delete multiple entities, follow these steps:

  1. Click ENTITIES in the left menu.
  2. Hover over the list and check one or more entities. This will reveal the options available for the selection.
  3. Choose the desired action.

  4. Check the desired options in the resulting dialog.

  5. Click START.

Export and upload entities

Depending on your use case, you may have a substantial number of entities you want to add to your agent. Additionally, you may want to export a large list of entities that you've cultivated from training your agent. This section will show you how to both upload and export the entities for an agent.

JSON format

The JSON file should correspond to the entity object format for the V1 or V2 API, depending on which version you're using.

CSV format

The CSV file should have the following format:

  • Each entry corresponds to a new line.
  • The reference value and synonyms should be separated by commas.
  • Each reference value and synonym should be enclosed in double-quotes.
  • The reference value should be at the beginning of the line.
  • Include the reference value twice of you want it to be matched by the entity.

For example, this is an item in a CSV:

"New York City", "New York City", "NYC", "New York City, USA"

And this is the result, once uploaded to an agent:

Export

To download entities in either JSON or CSV format, follow these steps:

  1. Click Entities in the left menu.
  2. Hover over an entity and click on the cloud/download icon cloud_download.
  3. Choose JSON or CSV for the download format.

  4. Choose a location on your system to save the generated file.

Upload

Entities can be created by uploading a JSON or CSV file. This is ideal if you want to add large collections of terms and synonyms to your agent.

To upload entities in JSON or CSV format, follow these steps:

  1. Click Entities in the left menu.
  2. Click the more icon more_vert.
  3. Click Upload entity and choose the file you want to upload.