Skip to main content

Entities define structured data that the agent can collect from the user, such as a date of birth, phone number, or choice from a list.

Entities are used in flow steps to control what the agent should collect and what must be present before a condition can trigger. They can also be read in executed Python code.

​
Location

Entities are defined in: 
config/entities.yaml
Entities are listed under the entities key.

​
What an entity contains

Each entity has four main parts:
FieldDescription
nameIdentifier for the entity, typically in snake_case. Used in prompts as {{entity:entity_name}}.
descriptionExplains what the entity represents. This is shown to the model to guide extraction.
entity_typeThe type of entity being collected.
configType-specific settings for that entity.

​
Entity types

TypeConfig fieldsDescription
numerichas_decimal, has_range, min, maxNumbers such as account numbers or quantities
alphanumericenabled, validation_type, regular_expressionMixed text such as booking references
enumoptionsA fixed set of choices
daterelative_dateCalendar dates
phone_numberenabled, country_codesPhone numbers with country validation
timeenabled, start_time, end_timeTimes or time ranges
address{}Physical addresses
free_text{}Unstructured text input
name_config{}Person names

​
How entities are used

In flow prompts

Use {{entity:entity_name}} to reference a collected value.

In function steps

Read values using conv.entities.entity_name.value.

In default step conditions

Use required_entities to gate a condition until the listed entities have been collected.

In default steps

Use extracted_entities to tell the agent which entities to collect in that step.

​
In prompts

You can reference a collected entity value in prompts using: 
{{entity:entity_name}}
This allows a later step to reuse information that has already been collected.

​
In code

In function steps or related Python code, entity values can be read like this: 
conv.entities.entity_name.value
Before reading a value, check that the entity exists: 
if conv.entities.entity_name:
    ...

​
In flow conditions

Entities are important in default flow steps:
  • extracted_entities tells the agent what to collect in the current step
  • required_entities tells a condition what must already be available before it can trigger
This allows flows to wait until the necessary information has been gathered before progressing.
Automatic ASR biasingWhen entities are requested in a default step, ASR biasing is automatically configured based on the entity types being collected.

​
Example

entities:
  - name: date_of_birth
    description: The customer's date of birth
    entity_type: date
    config:
      relative_date: false

  - name: party_size
    description: Number of guests for the reservation
    entity_type: numeric
    config:
      has_decimal: false
      min: 1
      max: 20

  - name: meal_preference
    description: The customer's preferred meal type
    entity_type: enum
    config:
      options:
        - vegetarian
        - vegan
        - standard
        - halal

​
Best practices

  • use clear, descriptive snake_case names
  • keep descriptions specific enough to guide extraction well
  • choose the most precise entity type available
  • use required_entities to control when a step condition is allowed to fire
  • use extracted_entities to make collection explicit in default steps

Flows

Learn how entities fit into default steps, conditions, and step transitions.

Variables

Compare collected entities with state variables used elsewhere in the project.

Conversation object reference (platform)

Full reference for conv.entities — accessing collected values, checking presence, and entity object shape.
Last modified on July 9, 2026