Skip to main content

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.

Use GATHER to collect structured data from users through natural conversation. Instead of rigid form-filling, it lets the agent extract field values from user input in natural language — a user saying “I want to fly to Paris on March 10 for two people” can fill three fields at once. Fields can be validated, corrected, and inferred from context without restarting the flow. You can configure GATHER using the Gather Fields section in Studio or by editing the GATHER block directly in the ABL Editor.

​
Before You Begin

  • You must have an agent created in your project. See Create Agents.
  • To use inference and LLM-based validation, an LLM provider must be configured under Admin > Models.

​
Configure Gather Fields

​
In Studio

Navigate to your agent and select Gather Fields from the Capabilities group in the agent editor sidebar. Gather Fields in Studio The Gather Fields page lists all defined fields. Click any field to expand its configuration, or click + Add Field to define a new one. Each field has the following properties.
PropertyDescription
Field nameThe variable name used to reference the collected value in ABL and templates.
TypeThe data type to collect. See Field types.
RequiredWhether the agent must collect this field before proceeding.
PromptThe question the agent asks the user to collect this field.
Extraction hintsInstructions that guide the LLM on how to interpret ambiguous input for this field.
Infer from contextWhen enabled, the LLM extracts the value from prior conversation without asking the user again.
Sensitive (PII)When enabled, the field value is masked in logs and traces.
Extraction pattern (regex)A regex pattern for strict extraction. The field value must match this pattern.
Click Save changes after configuring fields.

​
In the ABL Editor

Define GATHER at the agent level for fields the LLM collects through natural conversation, or inside a flow step for deterministic collection. Agent-level GATHER: 
AGENT: Hotel_Search
GOAL: "Help users find hotels"

GATHER:
  destination:
    prompt: "Where would you like to stay?"
    type: string
    required: true
  checkin:
    prompt: "When is your check-in date?"
    type: date
    required: true
  checkout:
    prompt: "When is your check-out date?"
    type: date
    required: true
  guests:
    prompt: "How many guests?"
    type: number
    required: false
    default: 2
GATHER inside a flow step: 
collect_trip_info:
  REASONING: false
  GATHER:
    - destination: required
      prompt: "Where would you like to stay?"
    - checkin_date: required
      type: date
      prompt: "Check-in date?"
    - checkout_date: required
      type: date
      prompt: "Check-out date?"
    - num_guests:
      type: number
      default: 2
      prompt: "How many guests?"
  COMPLETE_WHEN: destination AND checkin_date AND checkout_date
  THEN: search_hotels
Agent-level GATHER uses a named field syntax. Flow step GATHER uses a compact list syntax. COMPLETE_WHEN defines when the step has enough data to advance.

​
Field properties

PropertyTypeRequiredDefaultDescription
promptstringYes—The question or instruction shown to the user to collect this field
typestringNo”string”Data type for the field value
requiredbooleanNotrueWhether the field must be collected before proceeding
defaultanyNononeDefault value used if the user does not provide one
validatestringNononeValidation expression
validation_process”REGEX” | “CODE” | “LLM”NononeHow validation is performed
retry_promptstringNononeCustom prompt shown when validation fails
max_retriesnumberNononeMaximum validation retry attempts
inferbooleanNofalseAllow the LLM to infer the value from context
infer_confidencenumberNo0.8Minimum confidence threshold for accepting inferred values (0.0—1.0)
infer_confirmbooleanNotrueWhether to confirm inferred values with the user
extraction_hintsstring[]NononeHints 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
rangebooleanNofalseCollect as a range {low, high} instead of a scalar
listbooleanNofalseCollect as an array instead of a scalar
preferencesbooleanNofalseCategorize into accept/desire/avoid/refuse preference sets
activationstring | {when: string}No”required”Activation mode
depends_onstring[]NononeFields that must be collected before this field activates
sensitivebooleanNofalseWhether this field carries PII
sensitive_display”redact” | “mask” | “replace”NononeHow sensitive values are displayed outside the gather context
mask_config{showFirst, showLast, char}NononeMasking configuration when sensitive_display is “mask”
transientbooleanNofalseWhether PII auto-cleans after gather completes
extraction_patternstringNononeCustom regex pattern for value extraction
extraction_groupnumberNo0Capture group index for extraction_pattern
semanticsobjectNononeSupplemental metadata about the value

​
Field Types

TypeExample values
stringAny text.
number42, 3.14
date2026-03-15, next Friday
emailuser@example.com
phone+1-555-0123
booleanyes, no, true

​
Collection Strategies

The collection strategy controls how the agent extracts field values from user input. 
collect_trip_info:
  REASONING: false
  GATHER:
    FIELDS:
      - checkin_date: required
      - checkout_date: required
      - num_guests: required
    STRATEGY: llm
  THEN: search_and_show
StrategyBehavior
llmLLM extracts values from natural language. This is the default.
patternStrict pattern matching only.
hybridTries pattern matching first, then falls back to LLM for unresolved fields.
Use hybrid when some fields have a predictable format (such as order IDs or phone numbers) but others are open-ended.

​
Field Validation

Add validation to enforce data formats, value ranges, and business rules before the agent proceeds.

​
Validate With an Expression

GATHER:
  email:
    prompt: "What is your email address?"
    type: email
    required: true
    validate: "value matches '^[\\w.+-]+@[\\w-]+\\.[\\w.-]+$'"

  age:
    prompt: "How old are you?"
    type: number
    required: true
    validate: "value >= 18 AND value <= 120"
The validate expression is evaluated at runtime. If it fails, the agent re-prompts the user.

​
Set the Validation Process

GATHER:
  order_id:
    prompt: "What is your order number? (Format: ORD-XXXXX)"
    type: string
    required: true
    validation: "^ORD-[A-Z0-9]{5}$"
    validation_process: REGEX

  address:
    prompt: "What is your shipping address?"
    type: string
    required: true
    validation: "Verify this is a valid US mailing address with street, city, state, and ZIP"
    validation_process: LLM
ProcessBehavior
REGEXMatches the value against a regular expression pattern.
CODERuns a code snippet for validation.
LLMAsks the LLM to evaluate whether the value is valid.

​
Customize Retry Behavior

GATHER:
  phone_number:
    prompt: "What is your phone number?"
    type: phone
    required: true
    validation: "^\\+?[1-9]\\d{1,14}$"
    validation_process: REGEX
    retry_prompt: "That does not look like a valid phone number. Please enter a number like +15551234567."
    max_retries: 3
retry_prompt replaces the default re-prompt message when validation fails. max_retries caps how many times the agent asks before moving on or escalating.

​
Validate enum Values

GATHER:
  cancellation_scope:
    prompt: "Would you like to cancel the entire order or specific items?"
    type: string
    required: true
    validate: enum(full, partial)
    infer: true
    extraction_hints:
      - "If user says 'all', 'everything', or 'whole order', infer 'full'"
      - "If user mentions specific items or says 'some', infer 'partial'"
enum() restricts accepted values to a defined set. Combined with infer: true, the LLM maps natural language input to the valid enum values.

​
Validate Across Fields

Validation expressions can reference other gathered fields for cross-field validation. 
GATHER:
  checkin_date:
    prompt: "Check-in date?"
    type: date
    required: true
    validate: "value >= today()"
    retry_prompt: "The check-in date must be today or later."

  checkout_date:
    prompt: "Check-out date?"
    type: date
    required: true
    validate: "value > checkin_date"
    retry_prompt: "Check-out must be after your check-in date of {{checkin_date}}."

​
Validate with CONSTRAINTS

For business rules that go beyond field format, use CONSTRAINTS alongside GATHER. 
CONSTRAINTS:
  - REQUIRE order_id matches "^ORD-[A-Z0-9]{5}$" OR email IS SET
    ON_FAIL: "Please provide a valid order number (format: ORD-XXXXX) or an email address."

  - REQUIRE lookup_attempts <= 3
    ON_FAIL: "I have been unable to find your order after several attempts. Let me connect you with a specialist."

​
Validate Payment Fields in a Flow Step

collect_payment:
  REASONING: false
  GATHER:
    - card_number: required
      validation: "^[0-9]{13,19}$"
      validation_process: REGEX
      retry_prompt: "Please enter a valid card number (13-19 digits)."
      max_retries: 3
    - expiry: required
      validation: "^(0[1-9]|1[0-2])\\/([0-9]{2})$"
      validation_process: REGEX
      retry_prompt: "Please enter expiry as MM/YY."
    - cvv: required
      validation: "^[0-9]{3,4}$"
      validation_process: REGEX
      retry_prompt: "CVV must be 3 or 4 digits."
  THEN: process_payment

​
LLM Inference

LLM inference lets the agent fill field values from conversational context without asking the user explicitly.

​
Enable Inference on a Field

GATHER:
  cancellation_reason:
    prompt: "May I ask the reason for the cancellation?"
    type: string
    required: false
    infer: true
With infer: true, if the user already said “I do not need the order anymore,” the agent fills cancellation_reason without prompting again.

​
Control Inference Confidence

GATHER:
  destination:
    prompt: "Where would you like to travel?"
    type: string
    required: true
    infer: true
    infer_confidence: 0.9
    infer_confirm: true
PropertyDefaultPurpose
inferfalseAllow the LLM to extract the value from context.
infer_confidence0.8Minimum confidence score to accept an inferred value.
infer_confirmtrueAsk the user to confirm inferred values before proceeding.
When infer_confirm: true, the agent confirms with the user before accepting — for example, “It sounds like you want to travel to Paris. Is that correct?”

​
Add Extraction Hints

Extraction hints guide the LLM on how to map natural language input into structured values. 
GATHER:
  cancellation_scope:
    prompt: "Would you like to cancel the entire order or specific items?"
    type: string
    required: false
    infer: true
    extraction_hints:
      - "If user says 'all', 'everything', 'whole order', infer 'full'"
      - "If user mentions specific items or says 'some', infer 'partial'"

  selected_items:
    prompt: "Which items would you like to cancel?"
    type: string
    required: false
    extraction_hints:
      - "Only needed for partial cancellations"
      - "Match user input to item names from the order"
Extraction hints are especially useful for domain-specific terminology and ambiguous phrases.

​
Silent Extraction Without Prompting

Use prompt_mode: extract_only when the prompt is an instruction to the LLM, not a question for the user. The agent silently extracts the value from context. 
GATHER:
  sentiment:
    prompt: "Assess the customer's emotional state from the conversation"
    type: string
    required: false
    infer: true
    prompt_mode: extract_only

​
Activate Fields Conditionally

Use depends_on and activation to collect a field only when another field meets a condition. 
GATHER:
  trip_type:
    prompt: "Is this a round trip or one way?"
    type: string
    required: true
    infer: true
    extraction_hints:
      - "If user mentions return date, infer 'round_trip'"
      - "If user says 'one way' or mentions only departure, infer 'one_way'"

  return_date:
    prompt: "When would you like to return?"
    type: date
    required: false
    infer: true
    depends_on: [trip_type]
    activation:
      when: "trip_type == 'round_trip'"
return_date is only collected when trip_type is round_trip. If the user says “I need a round trip to London, leaving March 10 and returning March 17,” both fields are inferred from a single message. Use activation: progressive to activate a field only after its dependencies are met, letting the conversation unfold naturally. 
GATHER:
  budget:
    prompt: "What is your budget?"
    type: string
    required: true

  luxury_preferences:
    prompt: "Any specific luxury amenities you want?"
    type: string
    activation: progressive
    depends_on: [budget]

​
High-confidence Inference without Confirmation

Set infer_confirm: false for fields where the inferred value is obvious from context — for example, detecting language from how the user writes. 
GATHER:
  language_preference:
    prompt: "What language do you prefer?"
    type: string
    required: false
    infer: true
    infer_confidence: 0.95
    infer_confirm: false
Use a high infer_confidence threshold to avoid silent mismatches when skipping confirmation.

​
Optional Fields and Defaults

Optional fields are collected only if the user provides them. Default values are used when the user skips the field. 
GATHER:
  priority:
    prompt: "What priority level? (low, medium, high)"
    type: string
    required: false
    default: "medium"
  notes:
    prompt: "Any additional notes?"
    type: string
    required: false

​
Collecting Ranges and Lists

By default, GATHER collects a single scalar value per field. Use range or list to collect structured multi-value input instead.

​
Collect a Range

Set range: true to collect a {low, high} pair — useful for price ranges, age brackets, date windows, and similar bounded inputs. 
GATHER:
  price_range:
    prompt: "What is your budget range? (e.g., $100 to $300)"
    type: number
    required: true
    range: true
The collected value is stored as an object: {low: number, high: number}.

​
Collect a List

Set list: true to collect multiple values of the same type as an array — useful for item selections, amenity preferences, or multiple destinations. 
GATHER:
  preferred_amenities:
    prompt: "Which amenities are important to you? (e.g., pool, gym, parking)"
    type: string
    required: false
    list: true
The collected value is stored as an array: ["val1", "val2", "val3"].

​
Handling Sensitive Fields

For PII and sensitive fields, use the sensitive property along with sensitive_display property to suggest how to show the sensitive fields. For full details on display modes and masking configuration, see Handling transient and sensitive fields.

​
Present Collected Values

Use PRESENT to show collected values back to the user as each field is filled. 
collect_trip_info:
  REASONING: false
  GATHER:
    - destination: required
      prompt: "Where would you like to stay?"
    - checkin_date: required
      type: date
    - checkout_date: required
      type: date

  PRESENT: |
    Here is what I have so far:
    {{#if destination}}Destination: {{destination}}{{/if}}
    {{#if checkin_date}}Check-in: {{checkin_date}}{{/if}}
    {{#if checkout_date}}Check-out: {{checkout_date}}{{/if}}

  COMPLETE_WHEN: destination AND checkin_date AND checkout_date
  THEN: search_hotels

​
Handling Corrections to Fields within a Flow

Enable corrections so users can change previously provided values without restarting the flow. This property is set at the flow level and not at the field level.

​
Enable Corrections on a Flow Step

collect_trip_info:
  REASONING: false
  GATHER:
    - destination: required
      prompt: "Where would you like to stay?"
    - checkin_date: required
      type: date
      prompt: "Check-in date?"
    - checkout_date: required
      type: date
      prompt: "Check-out date?"

  CORRECTIONS: true

  COMPLETE_WHEN: destination AND checkin_date AND checkout_date
  THEN: search_hotels
With CORRECTIONS: true, the user can say “actually, change the destination to London” at any point during collection, and the agent clears and re-collects that field.

​
Use SUB_INTENTS for Targeted Corrections

SUB_INTENTS define scoped intents valid only within a step. if a field is cleared by a sub intent, the agent re-collects it. 
collect_trip_info:
  REASONING: false
  GATHER:
    - destination: required
    - checkin_date: required
      type: date
    - checkout_date: required
      type: date

  SUB_INTENTS:
    - INTENT: "change destination"
      CLEAR: [destination]
      RESPOND: "Sure, what is the new destination?"
    - INTENT: "change dates"
      CLEAR: [checkin_date, checkout_date]
      RESPOND: "What are your new travel dates?"

  COMPLETE_WHEN: destination AND checkin_date AND checkout_date
  THEN: search_hotels

​
Use ON_INPUT for Deterministic Correction Branching

get_dates:
  REASONING: false
  GATHER:
    - checkin_date: required
      type: date
    - checkout_date: required
      type: date
  ON_INPUT:
    - IF: input == "back"
      THEN: get_destination
    - IF: input contains "change destination"
      THEN: get_destination
    - ELSE:
      THEN: get_guests

​
Handle Corrections at the Review Step with DIGRESSIONS

DIGRESSIONS allow jumping to any step in the flow from a review or confirmation step. Unlike SUB_INTENTS, digressions leave the current step entirely. 
review_booking:
  REASONING: false
  PRESENT: |
    Booking Summary:
    Hotel: {{selected_hotel.name}}
    Dates: {{checkin_date}} to {{checkout_date}}
    Guests: {{num_guests}}
    Guest: {{guest_name}} ({{guest_email}})
    Total: ${{total_price}}

    Type "confirm" to complete or "change [field]" to modify.

  DIGRESSIONS:
    - INTENT: "change hotel"
      GOTO: select_hotel
    - INTENT: "change dates"
      CLEAR: [checkin_date, checkout_date]
      GOTO: collect_trip_info
    - INTENT: "change guest"
      GOTO: collect_guest_info

  ON_INPUT:
    - IF: input == "confirm"
      THEN: confirm
    - ELSE:
      RESPOND: "Please type 'confirm' to proceed or 'change [field]' to modify."
      THEN: review_booking

​
Handle Exhausted Retries

MAX_ATTEMPTS on the step limits total retries. ON_EXHAUSTED defines the fallback step when the limit is reached. 
verify_identity:
  REASONING: false
  MAX_ATTEMPTS: 3
  ON_EXHAUSTED: connect_to_human
  GATHER:
    - verification_code:
        prompt: "Enter the 6-digit code sent to your phone."
        type: string
        required: true
        validation: "^[0-9]{6}$"
        validation_process: REGEX
        retry_prompt: "That code is not valid. Please enter exactly 6 digits."
        max_retries: 3
  CALL: verify_code(verification_code)
  ON_SUCCESS:
    THEN: authenticated
  ON_FAIL:
    RESPOND: "That code did not match. Please try again."
    THEN: verify_identity
MAX_ATTEMPTS counts entries to the step, not individual field retries. max_retries on a field counts field-level retries separately.

​
Apply Global Digressions Across All Flow Steps

Global digressions are available in every step. RESUME: true returns to the current step after handling the digression. 
FLOW:
  steps:
    - welcome
    - collect_info
    - search
    - confirm

  global_digressions:
    REASONING: false
    - INTENT: "cancel"
      RESPOND: "Booking cancelled. Would you like to start over?"
      GOTO: welcome
    - INTENT: "help"
      RESPOND: "I can help you find and book hotels. Tell me your destination and dates."
      RESUME: true
    - INTENT: "start over"
      GOTO: welcome
Without RESUME, the GOTO target becomes the new active step.

​
Troubleshooting

SymptomResolution
Fields not extracted from natural languageVerify STRATEGY: llm is set (or omitted, since llm is the default). Add extraction_hints for ambiguous fields.
Step advances before all required fields are collectedAdd COMPLETE_WHEN with explicit conditions listing all required fields.
Validation never passesCheck regex pattern escaping — in ABL, backslashes need to be doubled (\\d, not \d).
User stuck in retry loopSet max_retries to 2–3. After exhaustion, the agent proceeds or escalates rather than looping.
Cross-field validation runs before dependent field is collectedOrder GATHER fields so dependencies are listed first, or use COMPLETE_WHEN to control when validation evaluates.
Inference fills a field incorrectlyRaise infer_confidence to 0.9 or higher. Set infer_confirm: true to require explicit user confirmation.
Agent asks for a field the user already mentionedVerify infer: true is set on the field and STRATEGY is llm or hybrid (not pattern).
Extraction hints ignoredHints must be a list of strings. Each hint should be a clear, specific instruction — not a long paragraph.
User correction not detectedAdd explicit SUB_INTENTS or DIGRESSIONS for the correction patterns your users are likely to use.
Cleared field not re-collectedAfter CLEAR, the step must re-prompt. Verify GATHER includes the cleared field and COMPLETE_WHEN requires it.