GATHER (information collection)

The GATHER: section defines structured information that the agent needs to collect from the user during a conversation. Each field specifies a data type, prompt, validation rules, and collection behavior. The runtime orchestrates multi-turn collection, extracting values from natural conversation and prompting for missing fields.

Syntax

At the top level of an agent document, GATHER: defines fields as named blocks:

GATHER:
  source_account:
    prompt: "Which account would you like to use?"
    type: string
    required: true

  amount:
    prompt: "How much would you like to transfer?"
    type: number
    required: true
    validate: "^[1-9][0-9]*$"

  currency:
    prompt: "What currency?"
    type: string
    required: true
    default: "USD"
    infer: true

Within a FLOW: step, gather uses a different syntax. See GATHER within FLOW.

A top-level field here can carry an ASR: listening-settings block (vocabulary, provider, language, no-input timeout) for round-trip compatibility, but it has no effect: the reasoning agent has no per-field prompt turn to apply it to, so the call’s existing listening settings are used instead, and the compiler warns GATHER_ASR_REASONING_UNSUPPORTED. ASR: only takes effect on a field gathered inside a FLOW: step — see Field-level listening settings.

A VOICE block with BARGE_IN and STREAMING is read only on a field of a FLOW step GATHER:. On a field of this top-level section it is not read and gives warning W170. See Voice delivery for a field.

Field properties

Property	Type	Required	Default	Description
`prompt`	`string`	No	field name	The question shown to the user to collect this field. Without it, the runtime uses the field name. A silent `extract_only` field needs none.
`message_key`	`string`	No	none	Locale catalog key used to localize the `prompt`
`description`	`string`	No	none	Semantic, model-facing description of what the value represents (distinct from `prompt`). Overrides a referenced entity’s description.
`type`	`string`	No	`"string"`	Data type for the field value (see Field types)
`required`	`boolean`	No	`true`	Whether the field must be collected before proceeding. Write lowercase `true` or `false`. Any other spelling, such as `yes` or `True`, reads as `false` without an error.
`default`	`any`	No	none	A field with a default counts as filled when the runtime checks completeness. The runtime does not write the default into the field.
`entity_ref`	`string`	No	none	Bind to a named entity from the `ENTITIES:` section (see Entity binding)
`options`	`string[]`	No	none	Allowed values for enum-style fields (see Enum options)
`validate`	`string`	No	none	Validation expression (see Validation). `validation` is also accepted.
`validation_process`	`"REGEX"` , `"CODE"` , `"LLM"`	No	none	How validation is performed
`retry_prompt`	`string`	No	none	Custom prompt shown when validation fails
`max_retries`	`number`	No	none	Maximum validation retry attempts
`infer`	`boolean`	No	`false`	Allow the LLM to infer the value from context
`infer_confidence`	`number`	No	`0.8`	Minimum confidence threshold for accepting inferred values (0.0—1.0)
`infer_confirm`	`boolean`	No	`true`	Whether to confirm inferred values with the user
`prompt_mode`	`"ask"` , `"extract_only"`	No	`"ask"`	Whether the prompt is shown to the user or used only for LLM extraction
`range`	`boolean`	No	`false`	Collect as a range `{low, high}` instead of a scalar
`list`	`boolean`	No	`false`	Collect as an array instead of a scalar
`preferences`	`boolean`	No	`false`	Marks a preference field. See Preference collection
`activation`	`string` , `{when: string}`	No	`"required"`	Activation mode (see Progressive activation)
`depends_on`	`string[]`	No	none	Fields that must be collected before this field activates
`satisfied_by`	`string[]`	No	none	Provenance classes allowed to satisfy this field (see Value provenance)
`sensitive`	`boolean`	No	`false`	Whether this field carries PII
`sensitive_display`	`"redact"` , `"mask"` , `"replace"`	No	none	How sensitive values are displayed outside the gather context
`mask_config`	`{show_first, show_last, char}`	No	none	Masking configuration when `sensitive_display` is `"mask"`. Write it as a block with snake_case keys.
`pii_type`	`string`	No	none	Explicit PII classification for shape-preserving masking: `email`, `phone`, `ssn`, `credit_card`, `address`, `name`, or `custom`. Any other value is ignored (see Sensitive fields)
`pii_pattern_ref`	`string`	No	none	Name of a project-defined PII pattern to bind this field to, instead of `pii_type` (see Sensitive fields)
`transient`	`boolean`	No	`false`	Whether PII auto-cleans after gather completes
`extraction_pattern`	`string`	No	none	Custom regex pattern for value extraction
`extraction_group`	`number`	No	`0`	Capture group index for `extraction_pattern`
`extraction_hints`	`string[]`	No	none	Example surface forms that guide LLM extraction. Merged on top of a referenced entity’s hints; an explicit empty list clears inherited hints.
`strategy`	`"auto"` , `"ml"` , `"llm"` , `"hybrid"` , `"pattern"`	No	none	Per-field extraction strategy override (see Extraction strategy).
`semantics`	`object`	No	none	Supplemental metadata about the value (see Semantics)

Field types

The type property specifies the expected data type for the field value:

Type	Description	Example values
`string`	Free-text value	`"John Smith"`, `"USD"`
`text`	Longer free-text value	`"..."`
`free_text`	Unconstrained free text	`"..."`
`number`	Numeric value	`42`, `150.75`
`integer`	Whole number	`42`
`float`	Decimal number	`3.14`
`currency`	Monetary amount	`19.99`
`boolean`	True/false	`true`, `false`
`date`	Calendar date	`"2026-03-15"`
`datetime`	Date and time	`"2026-03-15T14:30:00"`
`email`	Email address	`"user@example.com"`
`phone`	Phone number	`"+1-555-123-4567"`
`enum`	One of a fixed set (see `options`)	`"domestic"`
`pattern`	Value matching a regex	`"AB1234"`
`location`	Geographic location	`"San Francisco, CA"`

Entity binding

Instead of declaring type, options, and validation inline, a field can reference a reusable named entity from the ENTITIES: section via entity_ref. The field then inherits the entity’s type, allowed values, synonyms, and validation.

GATHER:
  request:
    entity_ref: request_type    # defined in the ENTITIES: section
    prompt: "What type of request do you have?"

A field with entity_ref should not also declare type, options, or values — the referenced entity owns that contract.

Enum options

For enum-style fields, options lists the allowed values directly. Use it as an alternative to validate: enum(...). Both inline and block forms are accepted:

GATHER:
  plan:
    prompt: "Which plan would you like?"
    type: enum
    options: [basic, pro, enterprise]

  region:
    prompt: "Which region?"
    type: enum
    options:
      - "us-east"
      - "eu-west"

Value provenance

The satisfied_by property restricts which sources may satisfy a field — useful for fields that must come from an authoritative system rather than user claims.

GATHER:
  account_balance:
    prompt: "What is your current balance?"
    type: number
    satisfied_by: [authoritative_tool, system]

Value	Description
`user_input`	The value may be provided directly by the user.
`authoritative_tool`	The value may be supplied by an authoritative tool result.
`system`	The value may be set by the system/session.

Validation

validate is always a single-line string. What it’s read as depends on validation_process (default REGEX):

GATHER:
  routing_number:
    prompt: "What is the ABA routing number?"
    type: string
    required: true
    validate: "^\d{9}$"
    retry_prompt: "That doesn't look like a valid 9-digit routing number. Please re-enter."
    max_retries: 3

  transfer_type:
    prompt: "Domestic or international?"
    type: string
    required: true
    validate: enum(domestic, international)

Validation process

Value	Default	`validate` is read as
`REGEX`	Yes	A regular expression the collected value must match.
`LLM`	No	A natural-language instruction the model judges the value against.
`CODE`	No	Reserved for an expression check. It compiles and is carried in the IR, but no runtime check currently evaluates it — don’t rely on it to reject a value yet.

GATHER:
  city:
    prompt: "Which city?"
    type: string
    required: true
    validate: "Must be a valid, well-known city name"
    validation_process: LLM

enum(a, b, c) is the one special-cased validate expression: the compiler lowers it into the same allowed-values metadata as options — use whichever reads better for the field. Any other non-regex text (min(1), pattern(...), email(), and similar function-call-looking strings) is read literally as a regular expression, not evaluated as a function — it almost never matches what was intended, so don’t write validate that way. Write a regular expression with a single backslash, such as ^\d{9}$. A double backslash is kept as two characters and never matches. The same applies to extraction_pattern. A regular expression check rejects every value of type number, integer, currency, or boolean, because those values are not text. Do not put a regular expression validate on those types. Rely on the type, or collect the value as string. retry_prompt, max_retries, and validation_process need a validate rule. Without one the compiler reports GATHER_VALIDATION_RULE_REQUIRED. In a FLOW step GATHER, retry_prompt is the question the step asks again after a failed check, and max_retries counts failed attempts per field. When the limit is reached, the agent’s ON_ERROR handler for validation_error with SUBTYPE: max_retries_exceeded runs. In a top-level GATHER, the model receives retry_prompt as a hint and asks again. The platform counts the attempts and records a validation_max_retries trace event. It resolves a matching ON_ERROR handler and applies its SET assignments, but it does not run the handler’s RESPOND, ESCALATE, or COMPLETE action. To act on the limit, collect the field in a FLOW step.

validate must be one line. A multi-line validate: block, or an object/list value such as { pattern: "..." }, is not read as a rule: the top-level parser warns W170, and a FLOW step GATHER warns W174 (empty) or W175 (object/list shape) — the field is left unvalidated rather than failing the compile.

LLM inference

When infer: true, the runtime can fill the field from what the customer already said, without asking. In a FLOW step, inference runs once, when the step starts to collect. It reads the last few customer messages. It does not read assistant messages, tool results, or memory. The conversation_history_window setting in EXECUTION sets how many messages it reads. The default is 2, the maximum is 10, and 0 turns inference off. On a top-level GATHER, infer: true only makes the field eligible for extraction. The infer_confidence and infer_confirm properties have no effect there.

GATHER:
  transfer_type:
    prompt: "Is this domestic or international?"
    type: string
    required: true
    validate: enum(domestic, international)
    infer: true

  currency:
    prompt: "What currency?"
    type: string
    required: true
    default: "USD"
    infer: true
    infer_confidence: 0.9
    infer_confirm: false

Inference properties

Property	Type	Default	Description
`infer`	`boolean`	`false`	Enable LLM inference for this field
`infer_confidence`	`number`	`0.8`	Minimum confidence (0.0—1.0) the runtime accepts for an inferred value. The compiler does not check the range. `FLOW` steps only.
`infer_confirm`	`boolean`	`true`	Whether to ask the user to confirm inferred values. `FLOW` steps only. An accepted confirmation is a system write, so a field with `satisfied_by: [user_input]` rejects it.

When the confidence in an inferred value falls below infer_confidence, a FLOW step leaves the field empty and asks its prompt. Write infer, infer_confirm, and required as lowercase true or false. Any other spelling reads as false. Use extraction_hints to steer extraction with example surface forms:

GATHER:
  transfer_type:
    prompt: "Is this domestic or international?"
    type: string
    infer: true
    extraction_hints: ["If beneficiary country is US, infer domestic. Otherwise international."]

Extraction strategy

The strategy property selects how a value is extracted. It can be set per field, and the same enum is available as a block-level default on flow-step gather.

Value	Behavior
`auto`	Let the platform choose the best available strategy (default behavior when unset).
`ml`	Use the ML/NLU entity model.
`llm`	Use the LLM to extract the value.
`pattern`	Use pattern/regex extraction (pairs with `extraction_pattern`).
`hybrid`	Combine ML and LLM extraction.

GATHER:
  phone_number:
    prompt: "What is your phone number?"
    type: phone
    strategy: pattern
    extraction_pattern: "\d{3}-\d{3}-\d{4}"

Range collection

When range: true, the field collects a range with low and high values instead of a single scalar:

GATHER:
  budget:
    prompt: "What is your budget range?"
    type: number
    required: true
    range: true

The collected value is stored as an object: {low: number, high: number}. Either end can be missing, so test budget.low IS SET AND budget.high IS SET. Do not set both list and range on one field. The list wins and the range is dropped without a warning.

List collection

When list: true, the field collects multiple values as an array:

GATHER:
  dietary_restrictions:
    prompt: "Do you have any dietary restrictions?"
    type: string
    required: false
    list: true

The collected value is stored as an array: ["vegetarian", "no nuts"]. A text reply is split on commas. A {{dietary_restrictions}} template prints the array as JSON. Use "item" IN dietary_restrictions to test membership, because CONTAINS works on text only. Do not add validate to a list or range field. The rule applies to the whole value and rejects valid answers.

Preference collection

preferences: true marks a field that holds preferences:

GATHER:
  hotel_amenities:
    prompt: "What amenities are important to you?"
    type: string
    required: false
    preferences: true

The property does not change the stored value. The field holds the value as collected. A reasoning agent that has a memory store also scans each customer message for stated preferences and saves them under preferences.accept, preferences.desire, preferences.avoid, and preferences.refuse. That scan runs for top-level GATHER fields only.

Progressive activation

The activation property controls when a field becomes active for collection:

Value	Description
`"required"`	Always active, must be collected (default)
`"optional"`	Active but not required
`"progressive"`	Activated progressively as other fields are collected
`{when: "condition"}`	Activated only when the condition evaluates to true

GATHER:
  routing_number:
    prompt: "What is the ABA routing number?"
    type: string
    required: true
    activation: progressive
    depends_on: [transfer_type]

  swift_code:
    prompt: "What is the SWIFT/BIC code?"
    type: string
    required: true
    activation:
      when: "transfer_type == 'international'"

A conditional activation needs a non-empty, valid executable expression.

A value that contains only a // line comment is invalid. It is not treated as an omitted activation.
Malformed expressions receive a compiler diagnostic. An unknown activation mode, such as sometimes, gets no diagnostic in line-based ABL, and a required field with that mode never completes. The YAML form reports error E175.
For a required field, default GATHER completion stays incomplete when its activation declaration is invalid, even if the field already has a collected or default value.
A valid condition that evaluates to false leaves the field inactive.
The independent required: false, optional, and progressive policies, and an explicitly authored COMPLETE_WHEN, keep their existing completion rules.
Write the condition as a block: activation: followed by when: on the next line. The one-line form activation: { when: "..." } is stored as text, and the field never activates.
Write when in lowercase. An uppercase WHEN: works only in line-based ABL.
depends_on gates a field only with activation: progressive. With required or no activation, it does not gate.
Write depends_on as a one-line list, such as [a, b]. A multi-line list is misread without an error.
Write the mode in lowercase in a top-level GATHER.

Field dependencies

The depends_on property lists fields that must be collected before this field activates. Combined with activation, this creates ordered collection flows:

GATHER:
  destination:
    prompt: "Where are you traveling?"
    type: string
    required: true

  hotel_class:
    prompt: "What class of hotel?"
    type: string
    required: true
    depends_on: [destination]
    activation: progressive

Corrections handling

In flow steps, the CORRECTIONS: true property enables natural corrections — the user can update previously collected values by stating corrections in natural language:

# Within a FLOW step
collect_details:
  GATHER:
    - name: required
    - email: required
  CORRECTIONS: true

See FLOW for the full flow step GATHER syntax.

Transient and sensitive fields

Sensitive fields

Fields marked sensitive: true carry PII and receive special handling:

Vault tokenization and prompt protection depend on the project PII protection setting. With protection off, sensitive: true does not stop the raw value from being stored or from appearing in the model prompt. Trace masking is always on.

sensitive: true controls how a value is displayed and stored afterward (masking, redaction) — the raw value is still extracted by the LLM and lands in session state during collection. For data that must never reach the model, transcript, session state, or logs at all — a full card number, CVV, and similar PCI-scoped values — use SECURE_INPUT instead of GATHER. SECURE_INPUT is currently a FLOW:-step-only action: it has no reasoning-mode/top-level form, so it’s only available to agents that have a FLOW: section — a pure reasoning-mode agent has no equivalent construct today.

GATHER:
  ssn_last4:
    prompt: "Last 4 digits of your Social Security Number?"
    type: string
    required: true
    sensitive: true
    sensitive_display: mask
    mask_config:
      show_first: 0
      show_last: 4
      char: "*"

When the field name is non-canonical, add pii_type so the redactor can produce a shape-preserving mask:

GATHER:
  member_id:
    prompt: "Your membership ID?"
    type: string
    sensitive: true
    sensitive_display: mask
    pii_type: custom      # email | phone | ssn | credit_card | address | name | custom (any other value is ignored)

Alternatively, bind the field to a named project PII pattern with pii_pattern_ref instead of pii_type:

GATHER:
  loyalty_number:
    prompt: "Your loyalty number?"
    type: string
    sensitive: true
    sensitive_display: mask
    pii_pattern_ref: loyalty_number_pattern

pii_pattern_ref is a free-form reference — the parser has no project scope, so it can’t validate that the named pattern exists. It’s resolved at runtime when the field is written; a reference that matches no configured pattern falls back to pii_type and emits pii_pattern_ref_unresolved. Studio also flags a dangling reference in the gather field editor.

Sensitive display modes

Mode	Description	Example output
`redact`	Replace entire value with placeholder	`[REDACTED]`
`mask`	Show partial value with masking characters	`****1234`
`replace`	Replace with the field name in capitals	`[SSN_LAST4]`

Mask configuration

Property	Type	Default	Description
`show_first`	`number`	`0`	Number of characters to show at the start
`show_last`	`number`	`4`	Number of characters to show at the end
`char`	`string`	`"*"`	Masking character

Write mask_config as a block with snake_case keys. A camelCase key such as showLast gives warning W170 and the defaults apply. A one-line mask_config: {show_last: 2} is dropped without an error. Without a mask_config block, mask shows the last 3 characters. mask_config has no effect unless sensitive_display is mask. Write sensitive_display in lowercase. An unknown value, such as hide or MASK, shows the raw value.

Transient fields

Fields marked transient: true are cleared from the session when an agent with a top-level GATHER completes or hands off. The property is not applied to fields in a FLOW step GATHER. Use it for sensitive data that should not persist beyond its immediate use:

GATHER:
  card_number:
    prompt: "Card number for verification?"
    type: string
    required: true
    sensitive: true
    transient: true

Extraction patterns

The extraction_pattern property defines a custom regex for extracting structured values from user input. Combined with extraction_group, it specifies which capture group to use:

GATHER:
  routing_number:
    prompt: "What is the routing number?"
    type: string
    required: true
    extraction_pattern: "(?:routing|aba|transit).*?(\d{9})"
    extraction_group: 1

Property	Type	Default	Description
`extraction_pattern`	`string`	none	Regex pattern for value extraction
`extraction_group`	`number`	`0`	Capture group index (0 = full match)

Semantics

The semantics block provides supplemental metadata that helps the runtime interpret and process field values:

GATHER:
  address:
    prompt: "What is the delivery address?"
    type: string
    required: true
    semantics:
      format: "US postal address"
      components: [street, city, state, zip]

  transfer_amount:
    prompt: "How much to transfer?"
    type: number
    required: true
    semantics:
      unit: "USD"
      convert_to: "cents"

Semantics properties

Property	Type	Description
`format`	`string`	Expected format description
`components`	`string[]`	Sub-components of the value
`unit`	`string`	Unit of measurement
`lookup`	`string`	Lookup table reference for validation
`convert_to`	`string`	Target unit for conversion
`locale`	`string`	Locale for parsing
`temporal`	`string`	Temporal direction for date/datetime fields: `future`, `past`, or `any` (default). `future` biases to the next occurrence and rejects past dates; `past` rejects future dates.
`enum_set`	`string[]`	Allowed enumeration values (alternative to top-level `options`).
`kore_entity_type`	`string`	Kore entity type hint used for recognition.

Complete example

GATHER:
  source_account:
    prompt: "Which account would you like to send from?"
    type: string
    required: true

  transfer_type:
    prompt: "Is this a domestic or international wire?"
    type: string
    required: true
    validate: enum(domestic, international)
    infer: true

  beneficiary_name:
    prompt: "Full legal name on the beneficiary's account?"
    type: string
    required: true

  amount:
    prompt: "How much would you like to send?"
    type: number
    required: true

  currency:
    prompt: "What currency? (for example. USD, EUR, GBP)"
    type: string
    required: true
    default: "USD"
    infer: true

  purpose_code:
    prompt: "Purpose of this transfer?"
    type: string
    required: true
    infer: true

  reference:
    prompt: "Reference or memo for the beneficiary? (optional)"
    type: string
    required: false

Related articles:

Tools — tool definitions (tools and gather work together)
FLOW — GATHER within flow steps uses a different syntax
Language overview — syntax rules for lists and blocks

Get started

ABL reference

GATHER (information collection)

Syntax

Field properties

Field types

Entity binding

Enum options

Value provenance

Validation

Validation process

LLM inference

Inference properties

Extraction strategy

Range collection

List collection

Preference collection

Progressive activation

Field dependencies

Corrections handling

Transient and sensitive fields

Sensitive fields

Sensitive display modes

Mask configuration

Transient fields

Extraction patterns

Semantics

Semantics properties

Complete example

​Syntax

​Field properties

​Field types

​Entity binding

​Enum options

​Value provenance

​Validation

​Validation process

​LLM inference

​Inference properties

​Extraction strategy

​Range collection

​List collection

​Preference collection

​Progressive activation

​Field dependencies

​Corrections handling

​Transient and sensitive fields

​Sensitive fields

​Sensitive display modes

​Mask configuration

​Transient fields

​Extraction patterns

​Semantics

​Semantics properties

​Complete example

Syntax

Field properties

Field types

Entity binding

Enum options

Value provenance

Validation

Validation process

LLM inference

Inference properties

Extraction strategy

Range collection

List collection

Preference collection

Progressive activation

Field dependencies

Corrections handling

Transient and sensitive fields

Sensitive fields

Sensitive display modes

Mask configuration

Transient fields

Extraction patterns

Semantics

Semantics properties

Complete example