NLU (Natural Language Understanding)

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

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.

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.
`entities`	Active. Entity extraction and synonyms. See 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.

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

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. To add keyword patterns, use categories.

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

Syntax

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. 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:

NLU:
  intents:
    - NAME: product_inquiry
      PATTERNS: ["tell me about", "what is", "describe"]
      EXAMPLES_FILE: "./nlu/product_inquiry_examples.txt"

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

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.
`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:

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

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:

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

The language settings are parsed and compiled, and the runtime does not read them.

The sub-block has this shape:

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

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:

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

The evaluation sub-block is parsed and compiled, and the runtime does not read it.

The sub-block has this shape:

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

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:

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:

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

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.

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 (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.

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.

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.

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 for how detection works.

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.
`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.

The user-facing prompts for the disambiguate and primary_queue flows (the “I noticed more than one request…” text) are customizable via the MESSAGES: block (keys such as multi_intent_disambiguate_header and multi_intent_queued_notice).

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 — intent-based routing in Supervisors
Expressions and functions — expression syntax used in intent conditions
Memory and constraints — NLU results stored in session variables

Get started

ABL reference

NLU (Natural Language Understanding)

Overview

Runtime status of NLU sub-blocks

Intent classification

Syntax

Intent properties

Pattern matching

Example-based classification

Intent with external examples file

Categories

Entity extraction

Syntax

Entity types

Entity properties

Synonyms

Embeddings-based matching

Embeddings properties

Multi-language support

Multi-language properties

Model configuration

Evaluation configuration

Glossary

External NLU configuration

Complete example

Named entities (`ENTITIES:` section)

Intent categories (`INTENTS:` section)

Multi-intent handling (`MULTI_INTENT:`)

Properties

Multi-intent strategies

​Overview

​Runtime status of NLU sub-blocks

​Intent classification

​Syntax

​Intent properties

​Pattern matching

​Example-based classification

​Intent with external examples file

​Categories

​Entity extraction

​Syntax

​Entity types

​Entity properties

​Synonyms

​Embeddings-based matching

​Embeddings properties

​Multi-language support

​Multi-language properties

​Model configuration

​Evaluation configuration

​Glossary

​External NLU configuration

​Complete example

​Named entities (ENTITIES: section)

​Intent categories (INTENTS: section)

​Multi-intent handling (MULTI_INTENT:)

​Properties

​Multi-intent strategies

Overview

Runtime status of NLU sub-blocks

Intent classification

Syntax

Intent properties

Pattern matching

Example-based classification

Intent with external examples file

Categories

Entity extraction

Syntax

Entity types

Entity properties

Synonyms

Embeddings-based matching

Embeddings properties

Multi-language support

Multi-language properties

Model configuration

Evaluation configuration

Glossary

External NLU configuration

Complete example

Named entities (`ENTITIES:` section)

Intent categories (`INTENTS:` section)

Multi-intent handling (`MULTI_INTENT:`)

Properties

Multi-intent strategies