> ## 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.
# 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:
```yaml theme={null}
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: min(1)
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](/agent-platform/abl-reference/flow#gather-in-flow-steps).
## Field properties
| Property | Type | Required | Default | Description |
| -------------------- | ----------------------------------- | -------- | ------------ | ---------------------------------------------------------------------------------------------------- |
| `prompt` | `string` | Yes | -- | The question or instruction shown to the user to collect this field |
| `message_key` | `string` | No | *none* | Locale catalog key used to localize the `prompt` |
| `type` | `string` | No | `"string"` | Data type for the field value (see [Field types](#field-types)) |
| `required` | `boolean` | No | `true` | Whether the field must be collected before proceeding |
| `default` | `any` | No | *none* | Default value used if the user does not provide one |
| `entity_ref` | `string` | No | *none* | Bind to a named entity from the `ENTITIES:` section (see [Entity binding](#entity-binding)) |
| `options` | `string[]` | No | *none* | Allowed values for enum-style fields (see [Enum options](#enum-options)) |
| `validate` | `string` | No | *none* | Validation expression (see [Validation](#validation)) |
| `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` | Categorize into accept/desire/avoid/refuse preference sets |
| `activation` | `string` , `{when: string}` | No | `"required"` | Activation mode (see [Progressive activation](#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](#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` | `{showFirst, showLast, char}` | No | *none* | Masking configuration when `sensitive_display` is `"mask"` |
| `pii_type` | `string` | No | *none* | Explicit PII classification for shape-preserving masking (see [Sensitive fields](#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` |
| `semantics` | `object` | No | *none* | Supplemental metadata about the value (see [Semantics](#semantics)) |
`extraction_hints` is a **flow-step gather** property, not a top-level `GATHER:` property — at the
top level it is not parsed. See [GATHER within FLOW](/agent-platform/abl-reference/flow#gather-in-flow-steps).
## 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:`](/agent-platform/abl-reference/nlu) section via `entity_ref`. The
field then inherits the entity's type, allowed values, synonyms, and validation.
```yaml theme={null}
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:
```yaml theme={null}
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.
```yaml theme={null}
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
The `validate` property defines a validation expression that the collected value must satisfy:
```yaml theme={null}
GATHER:
amount:
prompt: "How much?"
type: number
required: true
validate: min(1)
email:
prompt: "Your email address?"
type: string
required: true
validate: email()
transfer_type:
prompt: "Domestic or international?"
type: string
required: true
validate: enum(domestic, international)
```
### Validation expressions
| Expression | Description | Example |
| ---------------- | -------------------------------- | ----------------------------------------- |
| `min(n)` | Minimum numeric value | `validate: min(1)` |
| `max(n)` | Maximum numeric value | `validate: max(10000)` |
| `enum(a, b, c)` | Must be one of the listed values | `validate: enum(domestic, international)` |
| `email()` | Must be a valid email format | `validate: email()` |
| `pattern(regex)` | Must match a regex pattern | `validate: pattern(^\d{9}$)` |
### Validation process
The `validation_process` property controls how validation is executed:
| Value | Description |
| ------- | ------------------------------------------- |
| `REGEX` | Validate using a regular expression pattern |
| `CODE` | Validate using a code expression |
| `LLM` | Validate using LLM judgment |
```yaml theme={null}
GATHER:
routing_number:
prompt: "What is the ABA routing number?"
type: string
required: true
validate: pattern(^\d{9}$)
validation_process: REGEX
retry_prompt: "That doesn't look like a valid 9-digit routing number. Please re-enter."
max_retries: 3
```
## LLM inference
When `infer: true`, the LLM can extract or infer the field value from conversational context without explicitly asking the user. This enables natural, conversational information collection.
```yaml theme={null}
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 LLM must have to accept an inferred value |
| `infer_confirm` | `boolean` | `true` | Whether to ask the user to confirm inferred values |
When the LLM's confidence in an inferred value falls below `infer_confidence`, the runtime falls back to asking the user directly using the `prompt`.
To steer extraction with natural-language hints (`extraction_hints`), use a **flow-step** gather
field — see [GATHER within FLOW](/agent-platform/abl-reference/flow#gather-in-flow-steps).
## Range collection
When `range: true`, the field collects a range with `low` and `high` values instead of a single scalar:
```yaml theme={null}
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}`.
## List collection
When `list: true`, the field collects multiple values as an array:
```yaml theme={null}
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"]`.
## Preference collection
When `preferences: true`, the field categorizes user input into preference sets:
```yaml theme={null}
GATHER:
hotel_amenities:
prompt: "What amenities are important to you?"
type: string
required: false
preferences: true
```
The collected value is categorized into: `{accept: [], desire: [], avoid: [], refuse: []}`.
## 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 |
```yaml theme={null}
GATHER:
routing_number:
prompt: "What is the ABA routing number?"
type: string
required: true
activation: required
depends_on: [transfer_type]
swift_code:
prompt: "What is the SWIFT/BIC code?"
type: string
required: true
activation:
WHEN: "transfer_type == 'international'"
depends_on: [transfer_type]
```
### Field dependencies
The `depends_on` property lists fields that must be collected before this field activates. Combined with `activation`, this creates ordered collection flows:
```yaml theme={null}
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:
```yaml theme={null}
# Within a FLOW step
collect_details:
GATHER:
- name: required
- email: required
CORRECTIONS: true
```
See [FLOW](/agent-platform/abl-reference/flow) for the full flow step GATHER syntax.
## Transient and sensitive fields
### Sensitive fields
Fields marked `sensitive: true` carry PII and receive special handling:
```yaml theme={null}
GATHER:
ssn_last4:
prompt: "Last 4 digits of your Social Security Number?"
type: string
required: true
sensitive: true
sensitive_display: mask
mask_config:
showFirst: 0
showLast: 4
char: "*"
```
When the field name is non-canonical, add `pii_type` so the redactor can produce a shape-preserving
mask:
```yaml theme={null}
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
```
### 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 a generic description | `[SSN]` |
### Mask configuration
| Property | Type | Default | Description |
| ----------- | -------- | ------- | ----------------------------------------- |
| `showFirst` | `number` | `0` | Number of characters to show at the start |
| `showLast` | `number` | `4` | Number of characters to show at the end |
| `char` | `string` | `"*"` | Masking character |
### Transient fields
Fields marked `transient: true` are automatically cleared from the session after the gather phase completes. Use this for sensitive data that should not persist beyond its immediate use:
```yaml theme={null}
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:
```yaml theme={null}
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:
```yaml theme={null}
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
```yaml theme={null}
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
validate: min(1)
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
* [Tools](/agent-platform/abl-reference/tools) -- tool definitions (tools and gather work together)
* [FLOW](/agent-platform/abl-reference/flow) -- GATHER within flow steps uses a different syntax
* [Language overview](/agent-platform/abl-reference/language-overview) -- syntax rules for lists and blocks