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 beh

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

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	"[e-mail]"
phone	Phone number	"[phone]"

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

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:

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:

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

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
    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 — tool definitions (tools and gather work together)
• FLOW — GATHER within flow steps uses a different syntax
• Language overview — syntax rules for lists and blocks