> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://poly-ai.ferndocs.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://poly-ai.ferndocs.com/_mcp/server.

# 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](/agent-studio/flows/no-code/overview#conditions) 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.

> **Note**
>
> Entity extraction is a flow-only feature. [FAQs](/agent-studio/knowledge/fa-qs/fa-qs) don't support entity extraction directly. To collect structured data when a topic is matched, use the topic's action to [trigger a flow](/agent-studio/flows/triggering-flows) 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](/agent-studio/conversations/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

Validated entities are available in Function steps two ways:

* `conv.state.entity_name` -- the value coerced to its native Python type. Recommended for new code.
* `conv.entities.entity_name.value` -- the raw string value, with validation metadata on the surrounding object. Use when you need the original string or the [`EntityValidationResult`](/agent-studio/tools/classes-and-objects/object#entities) fields.

Both are kept in sync. An entity only appears in `conv.state` after it passes validation, so failed extractions never overwrite earlier values.

### Native types in `conv.state`

The type stored in `conv.state` is derived from the entity's configuration:

| Entity type      | Stored as | Example                         |
| ---------------- | --------- | ------------------------------- |
| Number (integer) | `int`     | `conv.state.party_size == 4`    |
| Number (decimal) | `float`   | `conv.state.weight_kg == 12.5`  |
| Currency         | `float`   | `conv.state.amount == 19.99`    |
| Everything else  | `str`     | `conv.state.email == "a@b.com"` |

If coercion fails for any reason, the original string value is stored so your function still receives a value to work with.

```python
# Recommended – native int, no cast needed
if conv.state.party_size > 15:
    flow.goto_step("Group Booking")

# Still supported – raw string from conv.entities
party_size = int(conv.entities.party_size.value)
if party_size > 15:
    flow.goto_step("Group Booking")
```

> **Warning**
>
> `conv.entities.entity_name.value` is **always a string**, even for numeric types. Cast to `int()` or `float()` before numeric comparisons, otherwise string comparison rules apply and `"9" > "10"` evaluates to `True`. Use `conv.state.entity_name` to skip the cast.

See [no-code flows – accessing entities in a function](/agent-studio/flows/no-code/overview#accessing-collected-entities-in-a-function) for more examples.

## Related pages

#### [No-code flows overview](/agent-studio/flows/no-code/overview)

Step types, routing logic, and canvas controls.

#### [Quickstart](/agent-studio/flows/no-code/quickstart)

Build your first no-code flow step by step.

#### [Advanced steps](/agent-studio/flows/no-code/advanced-steps)

ASR biasing, DTMF, and rich text references.