Entities

Define and validate structured data types like names, dates, and phone numbers in flow steps.

Entities are structured values the agent can collect and reuse during a flow. Each entity has a type that determines what validation is applied. Entity names must be unique across all entities in your project.

Mark an entity as required on a condition so the LLM won’t consider that condition satisfied without a valid value. In Function steps, you must enforce this yourself in code.

Entity types and configuration

Free text

Open-ended responses with no validation. Use when you need to capture unstructured input like comments or descriptions.

Number (numeric)

Numeric values. Configure:

• Decimal — toggle to accept decimal values (float) or restrict to integers
• Range — optionally set a minimum and maximum value (up to 1,000,000)

Alphanumeric

Any mix of letters and numbers. Useful for booking references, confirmation codes, or postal codes. Configure:

• Validation type — choose a built-in preset or custom regex:
  • Zip code — US zip code format (e.g. 12345 or 12345-6789)
  • Postal code — UK postal code format
  • Custom — your own regular expression

Phone number

Telephone numbers. Configure:

• Country codes — restrict to specific countries (26 supported, including US, CA, GB, AU, DE, FR, and others)

Date

Calendar dates. No additional configuration.

Time

Clock times. Configure:

• Time range — set a start and end time to restrict valid values

Multiple choice (enum)

Selection from a predefined list. Configure:

• Options — the accepted values the caller can choose from

Name

Personal names (first name, last name, or both). No additional configuration.

Address

Street addresses or locations. No additional configuration.

Entity visibility in a step

Entities extracted in a step are immediately available in that same step. You can:

• Reference entities in the prompt using {{entity:entity_name}} – the system resolves the value at runtime, so the prompt can adapt based on what the caller just provided.
• Use entities in redirect conditions – mark an entity as a required entity on a condition so the LLM won’t activate that path until the entity has been collected and validated.

Extraction and evaluation happen in the same step execution – you do not need a separate step to use an entity you just collected.

Entity extraction is a flow-only feature. Managed Topics don’t support entity extraction directly. To collect structured data when a topic is matched, use the topic’s action to trigger a flow and configure entity extraction in that flow’s steps.

When entities count as “collected”

An entity only counts as collected once it passes validation. If a caller provides a value in the wrong format or outside the allowed range, the agent asks them to try again – and any condition that requires that entity will not activate until a valid value is provided.

This means a condition with required entities will only trigger after every required entity has a valid value. If you are debugging why a condition is not firing, check whether the entity passed validation – not just whether the caller said something.

In Conversation Review, system-generated events show entity validation and condition evaluation results, helping you identify whether an entity was rejected or a condition was skipped.

Validation and retries

Depending on the entity type:

• Valid values allow the flow to continue.
• Invalid values trigger re-asking or fallback routing.

Because there is no automatic cap on retries, always design your flow with a fallback condition (e.g. “caller unable to provide”) so the conversation can exit the step gracefully if collection stalls.

If a branch depends on an entity being present, always include a clear fallback path for when it is not collected or fails validation.

Accessing entities in code

Entities collected earlier in a flow are available in Function steps through conv.entities.entity_name.value.

Entity values are always strings, even for numeric types. You must cast to int() or float() before numeric comparisons, otherwise string comparison rules apply and "9" > "10" evaluates to True.

# Correct – cast before comparing
party_size = int(conv.entities.number_of_guests.value)
if party_size > 15:
    flow.goto_step("Group Booking")

# Incorrect – string comparison
if conv.entities.number_of_guests.value > "15":  # "9" > "15" is True!
    flow.goto_step("Group Booking")

See no-code flows – accessing entities in a function for more examples.

Related pages

No-code flows overview

Step types, routing logic, and canvas controls.

Quickstart

Build your first no-code flow step by step.

Advanced steps

ASR biasing, DTMF, and rich text references.