How to collect information inside a FLOW step

Back to how-to guides Use this pattern when you need a fixed order of questions: collect a set of fields in one step, then move on to the next step.

Concept

A GATHER inside a FLOW step belongs to that step. The step stays active until its required fields are filled. Then the flow moves to the next step with THEN. This differs from a top-level GATHER in four ways:

	Top-level `GATHER`	`GATHER` in a `FLOW` step
Who decides what to ask	The model	The step. It asks for all missing required fields together.
Field syntax	Named blocks	A list of fields, a map, or an inline list
Order	Declaration order in the prompt	The step order
Corrections and attempt limits	Not available	`CORRECTIONS`, `MAX_ATTEMPTS`, and `ON_EXHAUSTED`

Set REASONING: false on a collection step for deterministic behavior. Collect in one step and read the answer in the next step. This keeps the branching in ON_INPUT separate from the collection. For the model-led alternative, see Collect information with global GATHER.

Minimal working example

An appointment agent collects contact details in one step and scheduling details in the next. The phone number and notes are optional. agents/appointment-booker.agent.abl

AGENT: Appointment_Booker
GOAL: "Book a service appointment by collecting contact and scheduling details."

PERSONA: |
  Friendly scheduling assistant. Keep questions short.

FLOW:
  entry_point: collect_contact

  steps:
    - collect_contact
    - collect_schedule
    - confirm

  collect_contact:
    REASONING: false
    GATHER:
      - full_name: required
        prompt: "What is your full name?"
      - email: required
        type: email
        prompt: "What email address should we send the confirmation to?"
      - phone: optional
        type: phone
        prompt: "Is there a phone number we can reach you on?"
    THEN: collect_schedule

  collect_schedule:
    REASONING: false
    GATHER:
      - service_type: required
        type: enum
        options: [repair, installation, inspection]
        prompt: "Which service do you need: repair, installation, or inspection?"
      - preferred_date: required
        type: date
        prompt: "Which date works for you?"
        semantics:
          temporal: future
      - notes: optional
        prompt: "Any notes for the technician?"
    THEN: confirm

  confirm:
    REASONING: false
    RESPOND: "Thanks {{full_name}}. Booked {{service_type}} for {{preferred_date}}. A confirmation goes to {{email}}."
    THEN: COMPLETE

Variable sources:

Every variable is a GATHER field. The customer supplies each one.
The confirm step reads full_name, service_type, preferred_date, and email. The optional fields are not read there.

How it works

The flow enters collect_contact. The step asks for the missing required fields. It joins the prompts, one per line, in declaration order.
The turn ends. The step waits for input.
The customer replies. The runtime extracts values for all the step’s fields, required and optional, in one pass. A customer can give several values in one message.
The runtime validates the values and stores the good ones.
If required fields are still missing, the step asks again. The repeat uses the field’s retry_prompt, then its prompt, then a fixed message.
When all required fields have values, the step falls through to its THEN.

Optional fields are never asked. The step checks only required fields. A step with only optional fields is complete on entry and passes straight through.

Field forms

Inside a step, write each field in one of these forms. The keys are case-insensitive.

Form	Example
List item with `required` or `optional`	`- email: required` followed by indented properties
List item with a default	`- notes: default=none` sets `required: false` and a default. The compiler warns `W822`.
Bare list item	`- email`. The field is required.
Map form	`email:` followed by indented properties
Inline	`GATHER: a, b` or `GATHER: [a, b]`

Inheriting a top-level field

A step field inherits the properties of a top-level GATHER field of the same name. The step overrides only the properties it sets. A step field that sets nothing but required or optional, such as - notes: optional, does not override required. The inherited value stays. Add another property, such as a prompt, to override it.

Common variations

Inherit, correct, and confirm

Declare the fields once at the top level. Reference them in the step. Turn on CORRECTIONS so the customer can change a value that was already collected. Confirm in the next step with ON_INPUT. agents/card-replacement.agent.abl

AGENT: Card_Replacement
GOAL: "Replace a lost or damaged card after the customer confirms the details."

PERSONA: |
  Calm banking assistant. Confirm details before acting.

GATHER:
  card_last4:
    prompt: "What are the last four digits of the card?"
    type: string
    validate: "^[0-9]{4}$"
    retry_prompt: "Enter exactly four digits."
    max_retries: 3
  replacement_reason:
    prompt: "Was the card lost, stolen, or damaged?"
    type: enum
    options: [lost, stolen, damaged]
  delivery_address:
    prompt: "What address should we ship the new card to?"
    type: string

FLOW:
  entry_point: collect_card

  steps:
    - collect_card
    - confirm
    - submit

  collect_card:
    REASONING: false
    GATHER:
      - card_last4: required
      - replacement_reason: required
      - delivery_address: required
    CORRECTIONS: true
    THEN: confirm

  confirm:
    REASONING: false
    RESPOND: "Replace card ending {{card_last4}} ({{replacement_reason}}) and ship to {{delivery_address}}. Say yes to confirm or no to change."
    ON_INPUT:
      - IF: input.contains("yes")
        THEN: submit
      - ELSE:
        RESPOND: "Okay, let us update the details."
        THEN: collect_card

  submit:
    REASONING: false
    RESPOND: "Your replacement card is on its way."
    THEN: COMPLETE

Shape the step prompt

Set PRESENT for an introduction. Set PROMPT for the question text. Use {{_missingList}} or {{_missing}} for the names of the missing fields. See Collect multiple fields across a natural conversation.

Limit attempts

Set MAX_ATTEMPTS and ON_EXHAUSTED on the step. After that many failed collection attempts, the flow moves to the step you name. Use it to hand off to a person.

Per-field retry limit

max_retries counts failed validations for one field. When it runs out, the flow follows ON_ERROR for validation_error with the subtype max_retries_exceeded.

Verification

Run the validator. Expect no errors and no warnings.
Start the conversation. Expect the first step to ask for the name and the email together, and not for the phone number.
Reply with the name and the email in one message. Expect the flow to move to the schedule step.
Reply with an invalid email. Expect the step to ask again.
In the card example, say “no” at the confirmation. Expect the flow to return to collect_card.
In the trace, open the dsl_prompt events with the mode gather. missingFields lists what the step asked for.
Open the dsl_collect events with the mode gather. They list the extracted fields.

Production readiness checklist

Each collection step sets REASONING: false.
Each step that must ask for a field marks it required.
Each field has a prompt.
Each step has a THEN, so the flow does not stall after collection.
Collection and ON_INPUT branching are in separate steps.
A step that can loop has MAX_ATTEMPTS and ON_EXHAUSTED.
Tests cover all values in one message, one value at a time, a bad value, and a correction.

Common mistakes

Mistake	Why it happens	How to avoid it
Expecting an optional field to be asked	The step lists it.	Make the field required, or ask for it in a separate prompt. Optional fields are only captured when volunteered.
Writing `- notes: optional` and expecting to override a required top-level field	The shorthand looks like an override.	Add another property, such as `prompt`.
Writing `- notes: optional # comment`	Comments are common.	Put comments on their own line. The comment makes the shorthand unreadable, and the field stays required.
Putting `ON_INPUT` in the same step as `GATHER`	It looks efficient.	Move branching to the next step. The compiler warns `FLOW_ON_INPUT_GATHER_ORDER_AMBIGUITY`.
Using `default=value` and expecting a clean compile	The shorthand sets `required: false`.	It always warns `W822`. Use a top-level `default` instead, or accept the warning.
Writing a multi-line `validate` block	YAML blocks look natural.	Write `validate` on one line. The block form is ignored with warning `W174`.

Troubleshooting

Symptom	Likely cause	What to check
A step passes without asking	All its fields are optional.	The field `required` values.
An optional field stays empty	The customer never volunteered it.	The extraction results in `dsl_collect`.
The step asks “Please provide the required information to continue.”	The step has no prompt for the missing fields.	The field `prompt` values.
A field you marked optional is still required	It inherited `required` from a top-level field.	The top-level `GATHER` and the step field properties.
The flow loops forever	The customer cannot satisfy a field, and no limit is set.	`MAX_ATTEMPTS` and `ON_EXHAUSTED`.
The compile warns `FLOW_PROMPTLESS_ON_INPUT_UNMATCHED_TRAP`	A step with `ON_INPUT` has no prompt.	Add a prompt, or move the branching to a step that asks.

Related articles:

Get started

Build

Test and evaluate

Deploy

Analytics and insights

References

How to collect information inside a FLOW step

Concept

Minimal working example

How it works

Field forms

Inheriting a top-level field

Common variations

Inherit, correct, and confirm

Shape the step prompt

Limit attempts

Per-field retry limit

Verification

Production readiness checklist

Common mistakes

Troubleshooting

​Concept

​Minimal working example

​How it works

​Field forms

​Inheriting a top-level field

​Common variations

​Inherit, correct, and confirm

​Shape the step prompt

​Limit attempts

​Per-field retry limit

​Verification

​Production readiness checklist

​Common mistakes

​Troubleshooting

Concept

Minimal working example

How it works

Field forms

Inheriting a top-level field

Common variations

Inherit, correct, and confirm

Shape the step prompt

Limit attempts

Per-field retry limit

Verification

Production readiness checklist

Common mistakes

Troubleshooting