> ## Documentation Index
> Fetch the complete documentation index at: https://koreai.mintlify.app/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     |
| `type`               | `string`                              | No       | `"string"`   | Data type for the field value                                           |
| `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                     |
| `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                        |
| `extraction_hints`   | `string[]`                            | No       | *none*       | Hints to guide the LLM's value extraction                               |
| `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               |
| `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"`              |
| `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))     |

## 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"` |
| `number`  | Numeric value   | `42`, `150.75`          |
| `boolean` | True/false      | `true`, `false`         |
| `date`    | Calendar date   | `"2026-03-15"`          |
| `email`   | Email address   | `"user@example.com"`    |
| `phone`   | Phone number    | `"+1-555-123-4567"`     |

## 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
    extraction_hints: ["If beneficiary country is US, infer domestic. Otherwise international."]

  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                          |
| `extraction_hints` | `string[]` | *none*  | Natural-language hints guiding the LLM's extraction logic                   |

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

## 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: "*"
```

### 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                    |

## 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
    extraction_hints: ["If beneficiary country is US, infer domestic. Otherwise international."]

  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? (e.g., USD, EUR, GBP)"
    type: string
    required: true
    default: "USD"
    infer: true

  purpose_code:
    prompt: "Purpose of this transfer?"
    type: string
    required: true
    infer: true
    extraction_hints: ["Map descriptions to standard purpose codes."]

  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