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

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`
`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
`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)
`options`	`string[]`	No	none	Allowed values for enum-style fields (see Enum options)
`validate`	`string`	No	none	Validation expression (see 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)
`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`	`{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)
`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

The validate property defines a validation expression that the collected value must satisfy:

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

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.

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

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"].

Preference collection

When preferences: true, the field categorizes user input into preference sets:

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

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:

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:

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:
      showFirst: 0
      showLast: 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

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

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

​Syntax

​Field properties

​Field types

​Entity binding

​Enum options

​Value provenance

​Validation

​Validation expressions

​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 expressions

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