Entities

An entity represents a specific piece of data or variable in a user's input. It often corresponds to nouns or values that help clarify or complete a user's request.

Entity Example

Imagine you're interacting with a travel booking virtual assistant:

User input:

"Book a flight from New York to Paris on June 15."

Here’s how the virtual agent breaks it down:

Intent: Book a flight

Entities:

departure_city: New York

destination_city: Paris

date: June 15

These entities provide the details the agent needs to perform the task.

The Importance of Entities in Virtual Assistants 💡

Entities are important components in your virtual agent architectures, enabling more effective interactions with users. They can be classified into two categories:

  • Custom Entities: Defined by the AI Studio user, tailored to specific needs, such as coffee_type (e.g., latte, espresso) or size (small, medium, large).

  • System Entities: Predefined entities available in AI Studio, covering a wide range of standard data points.

Benefits of Using Entities 🚀

  1. Flexibility: Entities allow the virtual assistant to adapt to various user input variations, improving interaction quality.

  2. Data Collection: They help gather necessary information for specific actions, like booking or searching.

  3. Personalization: Entities support customization by incorporating user names or preferences, enhancing the user experience.

Entities are essential for creating a responsive and personalized virtual assistant, making interactions smoother and more efficient.

Introducing the NEW Hybrid NLU 🚀


Custom Entities for Hybrid NLU

The New Hybrid NLU allows these methods to define custom entities:

Description

Write natural language rules about what the entity should capture. Use this when the entity has a clear structure but no predefined values.

Example:

“Order number consists of four letters, an underscore, and four digits.”

Both Description and Closed List

Provide a list of acceptable values and optional synonyms - Ideal for well-bounded value sets.

Example:

Entity: communication_type

Description: "The method someone wants to use to communicate."

Values and synonyms:

Phone → "call", "phone call", "mobile" Fax → "facsimile", "fax message" Email → "e-mail", "mail"


💡 Prompt Library for Commonly Used Entities & Corrector Functions

In some scenarios, you might want to tweak an existing system entity to improve the Virtual Agent's performance. Create your own Custom Entity by using the below recommended prompts as “Description” for the Custom Entity.

Entity type
Recommended Prompt for Text Channels (eg: WA, SMS, HTTP)
Recommended Prompt for Voice Channel

Phone Number

Extract the phone number mentioned. Normalize it by removing all separators. Do not add a country code unless explicitly written. Output only digits.

Extract the phone number mentioned. Convert phrases like “triple seven” or “zero four” to digits. Remove all separators. Output only digits. Add country code only if clearly mentioned or inferable from timezone {{timezone}}.

Web URL

Extract the URL mentioned. It may contain spelled out components. Convert numbers in words to digits. Return a valid URL.

Extract the spoken URL. Convert phrases like “dot” → ., “slash” → /, and numbers in words to digits. Return a clean, valid URL.

Email

Extract the email address. Convert words like “at” → @, “dot” → .. Numbers in words should be converted to digits if inside the email. Ignore unrelated parts. Return a valid email.

Extract the spoken email. Handle ASR misinterpretations like “dot” → ., “at” → @, “one” → 1. Convert only relevant words. Do not invent or complete missing parts.

Date/ Time

Extract any date or time. If AM/PM is not stated, return two versions. Return in ISO 8601 format. Provide timezone and current time context.

Extract any date or time mentioned. Account for ASR errors in numbers and expressions. If AM/PM not stated, return two variants. Format in ISO 8601. Provide timezone and current time context.

Name

Extract the name or nickname. It may be partial. Return it capitalized.

Extract the spoken name or nickname. Account for possible ASR errors. Return it capitalized.

Confirmation

Identify if the user said yes, no, or maybe. Handle informal variations like “yeah” or “nah”. Return only one of: yes, no, maybe.

Detect confirmation intent in speech: “yes”, “no”, “maybe”. Handle casual phrases like “yep”, “nah”, or “mm-hmm”. Return one of: yes, no, or maybe.

Number

Extract the number. Convert written words like “one”, “nil” to digits. Return as an integer.

Extract the number from speech. Convert words like “o”, “zero”, “nil”, or “ten” to digits. Return a numeric value.

Serial Number

Extract a serial number. Preserve original separators and letter casing. Convert number-words to digits. Return uppercase with preserved separators.

Extract the serial number spoken. Convert phrases like “dash”, “slash”, “dot” to symbols. Convert number words to digits. Return uppercase with separators intact.

💡 Best Practices for Corrector Functions

To address such issues, you could optionally add the below recommended prompts to the “Description” field of your Custom Entity.

Corrector Function
Recommended Prompt

Resolve Phonetic Alphabet

"Replace NATO phonetic words (e.g., 'alpha', 'bravo') with their corresponding letters (e.g., 'a', 'b'). For example, "alpha tango lima" → "a t l""

Resolve Spelled Out Alphabet

"Convert phrases like 'a for anton' or 'b as in bertram' to just the letters (e.g., 'a b')

Resolve Phonetic Counters

"Expand phrases like '3 times 2' or 'double 4' into repeated digits (e.g., '222', '44')

Contract Single Characters

"Join sequences of single letters separated by spaces into words, keeping the rest unchanged. For example "my name is r a c h e l" > "my name is rachel"."

Resolve Spelled Out Numbers

"Replace all number words in the text with their corresponding numerical digits. For example, convert 'five and three hundred nineteen' into '5 319'.

Contract Number Groups

"Detect sequences of numbers that are separated by spaces and join them into a single continuous number, while preserving the rest of the sentence. For example, convert 'his number is 333 43 22 44' into 'his number is 333432244'."

Defining a Custom Entity with a Corrector Function

Recommended Format:

<Main entity description> + <Corrector function description>

Example: If you are trying to build a custom entity Names, your “Description” field of your Custom Entity could be:

“Extract the spoken name or nickname. Account for possible ASR errors. Return it capitalized. Convert phrases like 'a for anton' or 'b as in bertram' to just the letters (e.g., 'a b')”


💡Best Practices for Using Hybrid NLU Effectively for Entity Extraction

Do
Don't

Define custom entities with a clear, natural-language Description (up to 500 characters). Think of it as writing a prompt for the AI - the more precise and detailed you are, the more accurate the extraction will be.

Example:

entity name: delivery_method

description: “The way the item is sent, such as mail, email, or fax.”

❌ No description or vague labels like "method" - poor prompts = poor extraction.

Use both Closed Lists and Descriptions for critical entities when maximum precision is needed.

Example: ✅ Closed list: “email, mail, fax” + description: “A method of communication.”

❌ Don’t write robotic, keyword-stuffed expressions - Hybrid NLU understands real conversation.

Test your entities thoroughly using the VA Tester after each major update.

Example:Simulate user input like “Can I get a transcript from last semester?” to verify behavior.

❌ Don’t assume the VA behaves the same as Traditional NLU - always revalidate.

Example of a custom entity in Hybrid NLU

Create Your Entity

  1. In the left navigation, click on Properties > Entities.

  2. A drawer is going to open on the right, click ‘Create Entity’ on the top right.

  3. Name the entity - for example, “size” and click ‘Add new Entity Value’.

  4. Add new entity values - for example, “small”, “medium”, and “large”, and if there are synonyms (see explanation below) add them to each value to help the agent identify more types of inputs (i.e. synonym for “large” can be “big”, "max", etc.).

  5. To save a value, press anywhere on the screen to save.

  6. Don't forget to hit "save" once you're done adding new values.

Synonyms

Sometimes there is more than one or two words that have the same or nearly the same meaning. For example, if asked "What pizza size do you want?", you can answer “large” or “big” and even “huge”. To accommodate any possible user response, it’s important to add as many synonyms as you can.

Entity Recordings

Only relevant for voice agents.

If your agent is utilizing human voice recordings instead of the available robotic voices, it only makes sense to also add recordings to your entity values. Either add the recording on the spot or select it from the drop-down, which shows all recordings from the Recordings Property.

Afterwards, you will be able to use these recordings throughout the flow. E.g. in a Speak node.

The agent will ask the user, "Which pizza size is right for you today?" and the user might answer "large". If you wanted to confirm the user's choice with "I got that you want to order a large pizza, is that correct?", the agent will be able to use the entity value of "large" using the attached recording.


Import an Entity

  1. When in the entities window, click 'Import Entity' on the top right.

  2. The AI Studio will prompt you to select the relevant file from your device. The format of the file should be CSV. Make sure you format the file in a way that is compatible with the agent. Please see the correct format below. The name of your file will be the name of the entity.

  3. If needed, you can always make changes to the entity later on. Don't forget to hit "save" once you're done adding new values.


Export an Entity

You can export an entity by clicking on the little export symbol on the right of the entity. This will export a CSV file containing all values and synonyms of the entity.

Example of Entity with Hybrid NLU

Custom Entities for Traditional NLU

Within Traditional NLU, a Custom Entity has to be defined by using the “Training Set” only, which is equivalent to the “Closed List” within Hybrid NLU. Under this Training Set, users could:

  • Add new entity values - for example, “small”, “medium”, and “large”, and if there are synonyms (see explanation below) add them to each value to help the agent identify more types of inputs (i.e. synonym for “large” can be “big”, "max", etc.).

  • Add Entity Recordings following the similar process as in Hybrid NLU.

  • Import Entity & Export Entity following the similar process as in Hybrid NLU.

Last updated

Was this helpful?