> ## Documentation Index
> Fetch the complete documentation index at: https://koreai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# NLU (Natural Language Understanding)

The `NLU:` block holds keyword patterns for intent categories and entity definitions for extraction.

> [!WARNING]
>
> In this release the runtime reads only two parts of the `NLU:` block: `categories` (keyword patterns) and `entities`. The other sub-blocks are parsed and compiled, and they raise no warning, but nothing at run time reads them. They are `intents`, `embeddings`, `glossary`, `models`, `languages`, `language_models`, `evaluation`, and `config_file`. Do not rely on them to change routing or extraction. See [Runtime status of NLU sub-blocks](#runtime-status-of-nlu-sub-blocks).

## Overview

ABL's NLU configuration supports these active features:

* **Keyword patterns** for intent categories, through `categories`. They act as a fallback when the classifier is unavailable.
* **Entity extraction** with typed extractors (enum, pattern, location, date, number, free text).
* **Synonyms** for normalizing variant expressions to canonical values.

The block also accepts the sub-blocks below. They compile, and the runtime does not read them:

* `intents` with example utterances.
* `embeddings` for semantic similarity.
* `languages`, `language_models`, and `models` for per-language and per-model settings.
* `glossary` for domain terminology.
* `evaluation` and `config_file`.

### Runtime status of NLU sub-blocks

| Sub-block | Runtime effect |
| - | - |
| `categories` | Active. Keyword patterns for the fallback match. See [Categories](#categories). |
| `entities` | Active. Entity extraction and synonyms. See [Entity extraction](#entity-extraction). |
| `intents` | None. The keywords and examples are not read. |
| `embeddings` | None. |
| `glossary` | None. |
| `models`, `languages`, `language_models`, `allow_code_switching`, `default_language` | None. |
| `evaluation`, `config_file` | None. |

To improve how the language model classifies a request, write a precise description in the `INTENTS:` section. See [Intent categories](#intent-categories-intents-section).

```yaml expandable=true theme={null}
NLU:
  intents:
    - NAME: send_wire
      PATTERNS: ["wire transfer", "send money", "wire funds"]
      EXAMPLES: ["I need to wire $50,000 to Germany", "Can I send a domestic wire?"]

  entities:
    - NAME: currency_code
      TYPE: enum
      VALUES: [USD, EUR, GBP, JPY]
      SYNONYMS:
        USD: [dollars, usd, bucks]
        EUR: [euros, eur]

  glossary:
    - "SWIFT/BIC -- Code identifying a bank globally"
    - "Fedwire -- Federal Reserve real-time settlement system"
```

## Intent classification

> [!WARNING]
>
> The `intents` sub-block is parsed and compiled, and the runtime does not read it. Its `PATTERNS`, `EXAMPLES`, `EXAMPLES_FILE`, and `ENTITIES` have no effect on routing. To define routing categories, use the [`INTENTS:` section](#intent-categories-intents-section). To add keyword patterns, use [`categories`](#categories).

Intents represent categories of user messages. Each intent has a name, keyword patterns, and optional example utterances.

### Syntax

```yaml theme={null}
NLU:
  intents:
    - NAME: book_flight
      PATTERNS: ["book flight", "find flights", "search flights", "fly to"]
      EXAMPLES:
        - "I want to fly to Paris next Tuesday"
        - "Find me a round trip to London"
        - "Book two seats on the morning flight to NYC"
      ENTITIES: [destination, travel_date, passenger_count]
```

### Intent properties

| Property | Type | Required | Default | Description |
| - | - | - | - | - |
| `NAME` | `string` | Yes | -- | Unique intent identifier. |
| `PATTERNS` | `string[]` | Yes | -- | Keyword patterns. Parsed, not read by the runtime. |
| `EXAMPLES` | `string[]` | No | -- | Example utterances. Parsed, not read by the runtime. |
| `EXAMPLES_FILE` | `string` | No | -- | Path to an external file containing example utterances (one per line). |
| `ENTITIES` | `string[]` | No | -- | Entity types expected to co-occur with this intent. |

### Pattern matching

Keyword patterns that the runtime reads come from [`categories`](#categories). They match whole words and phrases, without regard to case. They do not match part of a word and they do not stem words, so "cancel order" does not match "cancel orders". Add each form you need.

### Example-based classification

The runtime does not classify with `EXAMPLES`. The language model classifier reads the category name and the description from the `INTENTS:` section. Write contrasting examples inside that description.

### Intent with external examples file

For intents with many examples, reference an external file:

```yaml theme={null}
NLU:
  intents:
    - NAME: product_inquiry
      PATTERNS: ["tell me about", "what is", "describe"]
      EXAMPLES_FILE: "./nlu/product_inquiry_examples.txt"
```

## Categories

The `categories:` sub-block declares keyword patterns for intent categories. It is the only source of keywords that the runtime reads.

* The keywords run only as a fallback. They apply when the classifier is off or unavailable, and the `LEXICAL_FALLBACK` setting of the `INTENTS:` section allows it. The default is `when_unavailable`.
* A keyword match sets `intent.category` with a fixed confidence of 0.5. That is below the default short-circuit threshold of 0.85.
* If the category has no description in `INTENTS:`, the compiler writes one from the patterns, such as "Examples: invoice, refund".
* Write the keys in uppercase, and write `PATTERNS` as a one-line list. A multi-line list is silently empty. A trailing comment on the line corrupts the list, and a comma inside a quoted pattern splits it.
* The `NAME` uses letters, digits, and underscores. A name with a hyphen is dropped.

```yaml theme={null}
NLU:
  categories:
    - NAME: billing
      PATTERNS: ["invoice", "charge", "refund", "payment"]
    - NAME: technical
      PATTERNS: ["error", "bug", "not working", "broken"]
```

| Property | Type | Required | Default | Description |
| - | - | - | - | - |
| `NAME` | `string` | Yes | -- | Unique category identifier. |
| `PATTERNS` | `string[]` | Yes | -- | Keyword patterns for matching. |

## Entity extraction

Entities are structured values extracted from user messages. ABL supports six entity types.

### Syntax

```yaml expandable=true theme={null}
NLU:
  entities:
    - NAME: currency_code
      TYPE: enum
      VALUES: [USD, EUR, GBP, JPY, CHF, CAD, AUD]
      SYNONYMS:
        USD: [dollars, usd, bucks, us dollars]
        EUR: [euros, eur]
        GBP: [pounds, sterling, gbp, quid]

    - NAME: phone_number
      TYPE: pattern
      PATTERN: "\b\d{3}[-.]?\d{3}[-.]?\d{4}\b"
      VALIDATION: "Must be a valid US phone number"

    - NAME: destination
      TYPE: location

    - NAME: travel_date
      TYPE: date

    - NAME: passenger_count
      TYPE: number

    - NAME: special_request
      TYPE: free_text
```

### Entity types

| Type | Description | Additional properties |
| - | - | - |
| `enum` | Matches against a fixed set of values with optional synonyms. | `VALUES`, `SYNONYMS` |
| `pattern` | Matches against a regular expression. | `PATTERN`, `VALIDATION` |
| `location` | Extracts geographic locations (cities, countries, addresses). | -- |
| `date` | Extracts date and time references, including relative expressions ("next Tuesday"). | -- |
| `number` | Extracts numeric values. | -- |
| `free_text` | Captures arbitrary text spans. Useful for notes, descriptions, or comments. | -- |

### Entity properties

| Property | Type | Required | Default | Description |
| - | - | - | - | - |
| `NAME` | `string` | Yes | -- | Unique entity identifier. |
| `TYPE` | `string` | Yes | -- | Entity type. See [Entity types](#entity-types). |
| `VALUES` | `string[]` | No | -- | Valid values (for `enum` type). |
| `SYNONYMS` | `Record<string, string[]>` | No | -- | Synonym mappings. Keys are canonical values. |
| `PATTERN` | `string` | No | -- | Regular expression (for `pattern` type). Write a single backslash, such as `\d`. A double backslash is kept as two characters and never matches. |
| `VALIDATION` | `string` | No | -- | Validation description or expression. |
| `SENSITIVE` | `boolean` | No | `false` | Marks extracted values as PII for privacy-aware handling. |

### Synonyms

Synonyms map variant expressions to canonical values. When a synonym is detected, the runtime normalizes it to the canonical form before storing:

```yaml theme={null}
SYNONYMS:
  USD: [dollars, usd, bucks, us dollars]
  EUR: [euros, eur]
  GBP: [pounds, sterling, gbp, quid]
```

If the user says "100 bucks", the entity extraction yields `currency_code: "USD"`.

Write synonyms as a map of canonical values to inline lists. A block list, a flow map, and a key with a hyphen or a space are silently dropped. Quotes around a synonym in the top-level `ENTITIES:` section stay in the text, so the synonym never matches. The `NLU: entities:` form strips quotes.

A `pattern` entity extracts a value. It does not enforce the pattern when the value is stored. To reject a wrong format, add a `VALIDATE` rule to the `GATHER` field. A pattern searches the whole message, so do not anchor it with `^` and `$`.

## Embeddings-based matching

> [!WARNING]
>
> The `embeddings` sub-block is parsed and compiled, and the runtime does not read it. It does not turn on semantic matching. To improve routing, write precise descriptions in the `INTENTS:` section and tune the pipeline thresholds.

The sub-block has this shape:

```yaml theme={null}
NLU:
  embeddings:
    enabled: true
    provider: "bge-m3"
    model: "BAAI/bge-m3"
    threshold: 0.75
    cache_ttl: 3600
```

### Embeddings properties

| Property | Type | Required | Default | Description |
| - | - | - | - | - |
| `enabled` | `boolean` | Yes | -- | Whether embeddings-based matching is active. |
| `provider` | `string` | No | -- | Embedding model provider name. |
| `model` | `string` | No | -- | Specific model identifier. |
| `base_url` | `string` | No | -- | Custom endpoint URL for the embedding service. |
| `threshold` | `number` | No | -- | Similarity threshold (0.0--1.0). Below this, the match is rejected. |
| `cache_ttl` | `number` | No | -- | Cache duration in seconds for computed embeddings. |

## Multi-language support

> [!WARNING]
>
> The language settings are parsed and compiled, and the runtime does not read them.

The sub-block has this shape:

```yaml theme={null}
NLU:
  languages: [en, es, fr]
  default_language: en
  allow_code_switching: true
  language_models:
    en: "gpt-4o"
    es: "gpt-4o"
    fr: "gpt-4o"
```

### Multi-language properties

| Property | Type | Required | Default | Description |
| - | - | - | - | - |
| `languages` | `string[]` | No | -- | Supported language codes. |
| `default_language` | `string` | No | -- | Default language when detection is ambiguous. |
| `allow_code_switching` | `boolean` | No | `false` | Allow users to switch languages mid-conversation. |
| `language_models` | `Record<string,string>` | No | -- | Per-language model assignments for classification. |

## Model configuration

> [!WARNING]
>
> The `models` sub-block is parsed and compiled, and the runtime does not read it. The classifier model comes from the project runtime configuration.

The sub-block has this shape:

```yaml theme={null}
NLU:
  models:
    fast: "claude-haiku-4-5-20251001"
    balanced: "claude-sonnet-4-5-20250929"
```

| Property | Type | Required | Default | Description |
| - | - | - | - | - |
| `fast` | `string` | No | -- | Model for fast, low-latency classification. |
| `balanced` | `string` | No | -- | Model for higher-accuracy classification. |

## Evaluation configuration

> [!WARNING]
>
> The `evaluation` sub-block is parsed and compiled, and the runtime does not read it.

The sub-block has this shape:

```yaml theme={null}
NLU:
  evaluation:
    log_predictions: true
    ab_test: true
    confidence_threshold: 0.6
```

| Property | Type | Required | Default | Description |
| - | - | - | - | - |
| `log_predictions` | `boolean` | No | -- | Log all NLU predictions for analysis. |
| `ab_test` | `boolean` | No | -- | Enable A/B testing between NLU models. |
| `confidence_threshold` | `number` | No | -- | Minimum confidence score for accepting a prediction. |

## Glossary

> [!WARNING]
>
> The `glossary` sub-block is parsed and compiled, and the runtime does not read it. Its entries are not added to the model context. A top-level `GLOSSARY:` section is a compile error, `E105`.

The sub-block has this shape:

```yaml theme={null}
NLU:
  glossary:
    - "SWIFT/BIC -- Society for Worldwide Interbank Financial Telecommunication code"
    - "IBAN -- International Bank Account Number"
    - "Fedwire -- Federal Reserve real-time gross settlement system"
    - "OFAC -- Office of Foreign Assets Control"
    - "Beneficiary -- The person or entity receiving the wire transfer"
```

Each glossary entry is a plain string in `"term -- definition"` format.

## External NLU configuration

For complex NLU setups, reference an external configuration file:

```yaml theme={null}
NLU:
  config_file: "./nlu/config.yaml"
```

The external file is merged with any inline NLU configuration. Inline values take precedence. The runtime reads only `categories` and `entities` from the merged result.

## Complete example

> [!NOTE]
>
> This example shows every sub-block. Only `categories` and `entities` have a runtime effect. The `intents`, `embeddings`, `glossary`, `models`, and `languages` parts are shown for completeness.

```yaml expandable=true theme={null}
NLU:
  models:
    fast: "claude-haiku-4-5-20251001"
    balanced: "claude-sonnet-4-5-20250929"

  languages: [en, es]
  default_language: en
  allow_code_switching: true

  intents:
    - NAME: send_wire
      PATTERNS: ["wire transfer", "send money", "wire funds", "remittance"]
      EXAMPLES:
        - "I need to wire $50,000 to a vendor in Germany"
        - "Can I send a domestic wire from my business account?"

    - NAME: check_status
      PATTERNS: ["wire status", "where is my wire", "tracking"]
      EXAMPLES:
        - "What's the status of confirmation WR-2024-88431?"

    - NAME: cancel_wire
      PATTERNS: ["cancel the wire", "stop the transfer", "recall"]

  entities:
    - NAME: currency_code
      TYPE: enum
      VALUES: [USD, EUR, GBP, JPY, CHF, CAD, AUD]
      SYNONYMS:
        USD: [dollars, usd, bucks]
        EUR: [euros, eur]
        GBP: [pounds, sterling, quid]

    - NAME: transfer_type
      TYPE: enum
      VALUES: [domestic, international]
      SYNONYMS:
        domestic: [within the us, fedwire, local wire]
        international: [overseas, swift, cross-border]

  embeddings:
    enabled: true
    provider: "bge-m3"
    threshold: 0.75
    cache_ttl: 3600

  glossary:
    - "SWIFT/BIC -- Code identifying a bank globally"
    - "Fedwire -- Federal Reserve real-time settlement system"
    - "OFAC -- Office of Foreign Assets Control"
```

## Named entities (`ENTITIES:` section)

Separate from the `NLU:` block, the top-level `ENTITIES:` section defines **reusable** semantic entities that are shared by both NLU (for recognition) and [GATHER](https://koreai.mintlify.site/agent-platform/abl/reference/gather.md) (via `entity_ref`). Declaring an entity once lets multiple fields in the same agent file reuse the same type, allowed values, synonyms, and validation. Declare the entity in each agent file that uses it.

```yaml expandable=true theme={null}
ENTITIES:
  request_type:
    TYPE: enum
    VALUES: [REQ_REFUND, REQ_EXCHANGE, REQ_CANCEL]
    SYNONYMS:
      REQ_REFUND: [refund, money back, reimburse]
      REQ_EXCHANGE: [exchange, swap]

  booking_ref:
    TYPE: pattern
    PATTERN: "[A-Z]{2}[0-9]{4,6}"
    VALIDATION: "Two letters followed by 4-6 digits"
    SENSITIVE: false
```

| Property | Type | Required | Default | Description |
| - | - | - | - | - |
| `TYPE` | `string` | No | `"string"` | One of the 15 unified types (see below). |
| `VALUES` | `string[]` | No | -- | Canonical values (for `enum`). |
| `SYNONYMS` | `Record<string, string[]>` | No | -- | Canonical value → alternative forms. |
| `PATTERN` | `string` | No | -- | Regex (for `pattern`). |
| `VALIDATION` | `string` | No | -- | Intrinsic validation expression/description. |
| `SENSITIVE` | `boolean` | No | `false` | Marks the value as PII. |
| `DESCRIPTION` | `string` | No | -- | Semantic, model-facing description of what the entity value represents. A GATHER field's `entity_ref` inherits it. |
| `EXTRACTION_HINTS` | `string[]` | No | -- | Example surface forms that guide extraction. Inherited by GATHER fields that reference the entity. |

The parser reads only the properties in the table. An unknown property, such as `ALIASES`, is dropped without a message. Lowercase keys are accepted with warning `W171`. An unknown `TYPE` gives warning `W172`. Write `SENSITIVE` as lowercase `true` or `yes`.

Top-level entities accept the full unified type set: `string`, `text`, `free_text`, `number`,
`integer`, `float`, `currency`, `boolean`, `date`, `datetime`, `email`, `phone`, `enum`, `pattern`,
`location`.

> [!NOTE]
>
> This is a distinct section from `NLU: entities:`. Top-level `ENTITIES:` defaults `TYPE` to `string` and supports all 15 types, whereas the `NLU: entities:` sub-block defaults to `enum` and supports only 6 types (`enum`, `pattern`, `location`, `date`, `number`, `free_text`). A GATHER field's `entity_ref` points at a top-level `ENTITIES:` entry.

## Intent categories (`INTENTS:` section)

The top-level `INTENTS:` section declares supervisor routing categories (distinct from `NLU: intents:`). Each entry is a category name with an optional description, and the block can set a lexical-fallback mode.

```yaml theme={null}
INTENTS:
  LEXICAL_FALLBACK: when_unavailable
  new_booking: "Customer wants to book new travel"
  manage_booking: "Change or cancel an existing booking"
  billing
```

| Property | Type | Description |
| - | - | - |
| category name | `string` | Intent category identifier; optionally followed by `: "description"`. |
| `LEXICAL_FALLBACK` | `string` | When to fall back to lexical matching: `never`, `when_unavailable`, or `always`. The default is `when_unavailable`. An invalid value gives warning `W460`. |

The section takes only a category name, an optional quoted description, and `LEXICAL_FALLBACK`. It has no examples, keywords, patterns, or priority properties. The classifier reads the name and the description. Write the description on one line and in quotes. An unquoted description, a name with a hyphen, a trailing comment, or a block with `EXAMPLES:` or `KEYWORDS:` gives warning `W463`, and the compiler drops the entry. A duplicate category gives warning `W462`, and the first entry wins. If every entry is invalid, the section becomes an inferred list of the categories in your `WHEN` conditions.

## Multi-intent handling (`MULTI_INTENT:`)

The top-level `MULTI_INTENT:` section configures how the agent handles a single user message that contains **more than one intent** — for example, *"Book me a flight to NYC and also cancel my hotel reservation."* The reasoning pipeline classifier, or the routing model in one turn, detects the requests. The `strategy` controls how they are dispatched. See [Detect multiple intents in one user message](https://koreai.mintlify.site/agent-platform/abl/how-to/detect-multiple-intents) for how detection works.

```yaml theme={null}
MULTI_INTENT:
  strategy: primary_queue
  unknown_relationship_strategy: sequential
  max_intents: 5
  confidence_threshold: 0.7
  queue_max_age_ms: 300000
  enabled: true
```

### Properties

| Property | Type | Default | Description |
| - | - | - | - |
| `enabled` | `boolean` | `true` | Whether multi-intent handling is active. Detection by the classifier also needs the project reasoning pipeline on. When the pipeline is off, a supervisor runs its classifier fallback only when `enabled: true` is written in the agent. |
| `strategy` | `string` | `primary_queue` | How detected intents are dispatched. See [Strategies](#multi-intent-strategies). |
| `unknown_relationship_strategy` | `string` | `parallel` | Fallback strategy when the relationship between intents is unknown: `sequential`, `parallel`, or `disambiguate`. |
| `max_intents` | `number` | `3` | The most requests the queue holds and the most choices a `disambiguate` menu shows (1–10). It does not limit what the classifier detects, and it does not cap a `parallel` plan or the tasks of a `sequential` plan built from a classifier detection. |
| `confidence_threshold` | `number` | `0.6` | Minimum confidence (0.0–1.0) for a secondary intent to be accepted. A lower-confidence alternative is dropped without a trace event. |
| `queue_max_age_ms` | `number` | `600000` | Time-to-live for queued intents in milliseconds (0–3,600,000). After this, queued intents are dropped. |
| `advance_on_primary_response` | `boolean` | `true` | With `strategy: primary_queue`, whether the primary specialist's first delivered, non-blocking answer counts as done for queue purposes — advancing to the next queued intent in the same turn. Also applies to a `sequential` task resuming after a nested child returns, and to the option picked from a `disambiguate` menu. Set `false` to require an explicit completion signal (a `COMPLETE` condition, a terminal control, or return-to-parent) before advancing. See the note below for how a prose-only reply is judged. |

Write `MULTI_INTENT` keys in snake\_case. A camelCase key, an unknown key, or an empty block is ignored without a message. A repeated key keeps the last value.

### Multi-intent strategies

| Strategy | Behavior |
| - | - |
| `primary_queue` | Handle the highest-confidence intent immediately; queue the rest and surface them one-by-one after it completes. (Default.) |
| `sequential` | Execute the detected intents one at a time in order, carrying context forward between them. |
| `parallel` | Fan out to sub-agents simultaneously (supervisor agents only). |
| `disambiguate` | Present the detected intents to the user and ask which to handle first. |
| `auto` | Resolves at runtime from the assessed relationship between the intents: independent and dependent requests resolve to `sequential`, and ambiguous ones resolve to `disambiguate`. It never fans out — author `strategy: parallel` directly for that. |

With `primary_queue`, the runtime stores later items as durable pending work. It revalidates a queued item before replay. If the item has no executable target, the runtime asks for confirmation instead of deriving a destination from its label. Queue expiry stops stale work from resurfacing. Authors cannot read or change the queue from ABL.

> [!NOTE]
>
> The user-facing prompts for the `disambiguate` and `primary_queue` flows (the "I noticed more than one request…" text) are customizable via the [`MESSAGES:`](https://koreai.mintlify.site/agent-platform/abl/reference/lifecycle-and-hooks#messages) block (keys such as `multi_intent_disambiguate_header` and `multi_intent_queued_notice`).

> [!NOTE]
>
> A specialist with a missing required `GATHER` field, a pending input/tool confirmation, an authentication step, an escalation, or a still-waiting child keeps the floor regardless of `advance_on_primary_response`. A request whose tool/model call errored (and the customer was told) counts as finished, so the plan moves on. For a reply given only in prose (no `GATHER`) — the ambiguous case — the Runtime judges the reply itself: one that still waits on the customer (an unresolved follow-up question) keeps the floor, a finished-sounding one advances, and one the Runtime can't judge keeps the floor. Set `advance_on_primary_response: false` to keep the specialist in control regardless of what it replies.
>
> In a `sequential` plan, the last request's specialist keeps the customer's next reply when it answers without finishing (no `COMPLETE`, no return) — the same as after a single routed request — and may hand that reply back with `__return_to_parent__` when the supervisor's handoff to it declared `RETURN: true`.

***

**Related articles:**

* [Multi-agent and supervisor](https://koreai.mintlify.site/agent-platform/abl/reference/multi-agent-and-supervisor.md) -- intent-based routing in Supervisors
* [Expressions and functions](https://koreai.mintlify.site/agent-platform/abl/reference/expressions-and-functions.md) -- expression syntax used in intent conditions
* [Memory and constraints](https://koreai.mintlify.site/agent-platform/abl/reference/memory-and-constraints.md) -- NLU results stored in session variables


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.