FLOW (structured execution steps)

The FLOW: section adds structured execution steps to any agent. It defines a step-by-step execution graph where each step declares actions (collect information, call tools, respond, branch) and transitions to other steps. Agents operate in reasoning mode by default, where the LLM autonomously decides actions based on the goal. Adding a FLOW: section gives an agent a structured step graph, with each step declaring whether it uses LLM reasoning or deterministic execution via the REASONING: toggle.

Flow structure

Basic syntax

FLOW:
  entry_point: start

  steps:
    - start
    - collect_info
    - process
    - complete

  start:
    REASONING: false
    SET:
      status = "pending"
    RESPOND: "Welcome! Let me help you get started."
    THEN: collect_info

  collect_info:
    REASONING: false
    GATHER:
      - name: required
        prompt: "What is your name?"
    THEN: process

  process:
    REASONING: false
    CALL: process_request
      WITH:
        name: name
      AS: result
    RESPOND: "Done! Your request has been processed."
    THEN: complete

  complete:
    REASONING: false
    RESPOND: "Thank you for using our service. Goodbye!"

Entry point

The entry_point: property declares which step the flow begins at:

FLOW:
  entry_point: greeting

Property	Type	Required	Default	Description
`entry_point`	`string`	No	First step in the `steps` list	The step name where execution begins

If omitted, execution starts at the first step listed in the steps array.

Step list

The steps: array declares the ordered list of step names. While steps can transition to any other step (not just the next in order), the list establishes the canonical ordering:

FLOW:
  steps:
    - greeting
    - collect_account
    - verify
    - process
    - complete

Step definitions

Each step is defined as a named block under FLOW: with its properties indented:

FLOW:
  greeting:
    REASONING: false
    RESPOND: "Hello! How can I help you today?"
    THEN: collect_account

Per-step REASONING toggle

Every step in a FLOW: section must declare REASONING: true or REASONING: false. This controls whether the step uses LLM reasoning or deterministic execution.

FLOW:
  analyze_request:
    REASONING: true
    GOAL: "Analyze the customer's request and determine the best course of action"
    AVAILABLE_TOOLS: [search_knowledge, classify_intent]
    EXIT_WHEN: intent_classified == true
    MAX_TURNS: 5
    THEN: route_request

  route_request:
    REASONING: false
    CHECK: intent == "billing"
    ON_FAIL: general_support
    THEN: billing_flow

Property	Type	Required	Default	Description
`REASONING`	`boolean`	Yes	—	`true` for LLM-driven reasoning, `false` for deterministic execution

Reasoning step properties

When REASONING: true, the following additional properties are available:

Property	Type	Required	Default	Description
`GOAL`	`string`	No	Agent-level `GOAL:`	Step-specific goal (overrides the agent’s goal for this step)
`AVAILABLE_TOOLS`	`string[]`	No	All agent tools	Subset of agent tools available in this step
`EXIT_WHEN`	`string`	No	none	Condition that ends the reasoning loop
`MAX_TURNS`	`number`	No	`10`	Maximum reasoning turns before forced exit
`STEP_CONSTRAINTS`	`string[]`	No	none	Constraints specific to this reasoning zone

Validation rules:

A step with REASONING: true must have either a step-level GOAL or an agent-level GOAL: defined.
A step with REASONING: false should not have a GOAL (it has no effect on deterministic steps).
A step with REASONING: false should not have AVAILABLE_TOOLS (use CALL to invoke tools deterministically).

Entry guards

The WHEN: property on a step defines a condition that must be true for the step to execute. If the condition is false, the step is skipped:

FLOW:
  international_details:
    REASONING: false
    WHEN: "transfer_type == 'international'"
    GATHER:
      - swift_code: required
        prompt: "What is the SWIFT/BIC code?"
    THEN: validate_details

Property	Type	Required	Default	Description
`WHEN`	`string`	No	none	Condition expression that must be true for the step to execute

Attempt limiting

Steps can limit the number of times they execute (useful for retry loops):

FLOW:
  collect_pin:
    REASONING: false
    MAX_ATTEMPTS: 3
    ON_EXHAUSTED: lockout
    GATHER:
      - pin: required
        prompt: "Enter your PIN."
    THEN: verify_pin

Property	Type	Required	Default	Description
`MAX_ATTEMPTS`	`number`	No	none	Maximum number of times this step can execute
`ON_EXHAUSTED`	`string`	No	none	Step to transition to after max attempts exhausted

Step actions

SAY / RESPOND

The RESPOND: action sends a message to the user. It supports template interpolation with {{variable}} syntax:

FLOW:
  greeting:
    REASONING: false
    RESPOND: "Hello, {{customer_name}}! Your balance is {{balance}}."
    THEN: next_step

Multi-line responses use pipe block syntax:

FLOW:
  summary:
    REASONING: false
    RESPOND: |
      Here is your transfer summary:
      From: {{source_account}}
      To: {{beneficiary_name}}
      Amount: {{amount}} {{currency}}
    THEN: confirm

MODEL_CONTEXT on a response

An optional MODEL_CONTEXT sits beside a FLOW step’s RESPOND (or a COMPLETE condition’s RESPOND) and replaces that response only in future model context — it never changes what’s actually sent to the user, the stored transcript, or session values:

FLOW:
  show_products:
    REASONING: false
    RESPOND: "{{products_widget}}"
    MODEL_CONTEXT: "Displayed products {{product_ids}}."
    THEN: next_step

This is useful when the delivered response carries a large presentation payload (a widget, a card, a big table) that would otherwise bloat every later model call for no benefit — MODEL_CONTEXT lets the model keep a short textual summary of what the customer saw instead. MODEL_CONTEXT is a text scalar; a non-text value fails validation (MODEL_CONTEXT_INVALID). An explicitly empty value omits the response from later model requests entirely. Omit the property to keep the historical full-response behavior. See also MODEL_CONTEXT on a tool result for the equivalent policy on a tool’s own result.

A successfully rendered, non-empty MODEL_CONTEXT view is preserved exactly through later history compaction, summarization, and automatic conversation windowing — it’s never auto-shortened, replaced with a summary, or dropped for being old. It’s evaluated once, when the response is produced; later turns reuse that same rendered text rather than re-evaluating the template against newer data. This doesn’t raise the model’s context window or bypass the usual budget: an authored view may exceed the ordinary per-value/aggregate soft budget, but must still fit the aggregate hard capacity, or the runtime reports AUTHORED_MODEL_CONTEXT_CAPACITY_EXCEEDED rather than silently shrinking it. Keep MODEL_CONTEXT to the identifiers, status, and decision facts a later turn actually needs, and fetch further detail through a read tool — a large preserved view repeats in every later prompt, which adds up in prompt size, model cost, and latency. (This guarantee needs a matching Runtime version on every process handling the session; a rollback or a mixed-version deployment can silently lose it.)

PRESENT

The PRESENT: action displays a formatted presentation before collection. It is used alongside GATHER: to show the user what has been collected so far:

FLOW:
  review:
    REASONING: false
    PRESENT: |
      Beneficiary: {{beneficiary_name}}
      Account: {{MASK(beneficiary_account, "last4")}}
      Bank: {{beneficiary_bank_name}}
    GATHER:
      - confirmation: required
    THEN: process

GATHER in flow steps

Within a flow step, GATHER: uses a list syntax different from the top-level GATHER: section:

FLOW:
  collect_details:
    REASONING: false
    GATHER:
      - source_account: required
        prompt: "Your account number?"
    THEN: next_step

Map form (alternate syntax)

Fields can also be written as a map, without the leading -. Each lower-case name one level under GATHER: starts a field, with the same properties, inline required/optional/default= values, and field-level VOICE:/ASR:/DTMF: blocks as the list form:

FLOW:
  collect_dates:
    REASONING: false
    GATHER:
      checkin:
        TYPE: date
        REQUIRED: true
        PROMPT: "When do you want to check in?"
      guests: default=2
    THEN: next_step

Upper-case keys at that level (PROMPT, STRATEGY, and other recognized GATHER-block keywords) stay GATHER block properties, not fields. Only a lower-case (or mixed-case) name that is not a recognized GATHER-block keyword is read as a new field header.

Multi-field collection

Collect multiple fields in a single step using the FIELDS: sub-block:

FLOW:
  collect_beneficiary:
    REASONING: false
    GATHER:
      FIELDS:
        - beneficiary_name: required
          prompt: "Full legal name on the account."
        - beneficiary_account: required
          prompt: "Account number or IBAN."
        - beneficiary_bank: required
          prompt: "Name of the bank."
        - country: required
          prompt: "Country of the bank."
          default: "US"
          infer: true
      STRATEGY: llm
    CORRECTIONS: true
    COMPLETE_WHEN: beneficiary_name AND beneficiary_account AND beneficiary_bank AND country
    THEN: validate

Flow gather field properties

Each field in a flow GATHER: supports these properties:

Property	Type	Required	Default	Description
`required` / optional value after name	`boolean`	No	`true`	Whether the field must be collected
`prompt`	`string`	No	none	Question shown to the user
`type`	`string`	No	`"string"`	Data type
`default`	`any`	No	none	Default value
`validation`	`string`	No	none	Validation expression
`infer`	`boolean`	No	`false`	Allow LLM inference
`infer_confidence`	`number`	No	`0.8`	Minimum inference confidence
`infer_confirm`	`boolean`	No	`true`	Confirm inferred values
`extraction_hints`	`string[]`	No	none	LLM extraction guidance
`range`	`boolean`	No	`false`	Collect as range
`list`	`boolean`	No	`false`	Collect as array
`activation`	`string` , `{when: string}`	No	none	Activation mode
`depends_on`	`string[]`	No	none	Field dependencies
`prompt_mode`	`"ask"` , `"extract_only"`	No	`"ask"`	Prompt usage mode

Flow gather fields also accept the same additional properties as top-level GATHER fields: entity_ref, options, message_key, satisfied_by, validation_process, retry_prompt, max_retries, preferences, sensitive, sensitive_display, mask_config, pii_type, transient, extraction_pattern, extraction_group, and semantics. In addition, a flow gather field may carry rich_content format variants for its prompt. Note that flow gather uses validation: where the top-level section uses validate:.

Field-level listening settings (`ASR:`)

An ASR: block — a sibling of VOICE: on a single field — sets how the bot listens while that one field is being asked on a KoreVG voice call. Once the field is no longer being asked, the call’s normal listening settings return automatically:

FLOW:
  get_county:
    REASONING: false
    GATHER:
      - county: required
        prompt: "Which county is the dig site in?"
        ASR:
          vocabulary:
            mode: replace
            terms: [Guilford, Mecklenburg, Wake]
          no_input_timeout_ms: 8000
  get_street:
    REASONING: false
    GATHER:
      - street_name: required
        prompt: "What is the street name?"
        ASR:
          provider: deepgram
          model: nova-3
          vocabulary:
            mode: extend
            terms:
              default: [Boulevard]
              en: [{ phrase: Parkway, boost: 40 }]
              es-MX: [Privada]

Key	Meaning
`provider`	Speech engine for this field (for example `deepgram`, `google`, `azure`) — must already be configured on the project’s voice channel.
`model`	Recognizer model for the field. Not validated at deploy; a model the engine rejects falls back to the normal settings.
`language`	Listening language for this question only — doesn’t change the conversation language.
`vocabulary.mode`	`replace` (only this field’s words), `extend` (the call’s words plus this field’s, field words kept first under a limit), or `none` (no special words). Without `vocabulary`, the call’s words are unchanged.
`vocabulary.terms`	A plain list of words for every language, or a map of language tag (or `default`) to a list. Each entry is a string or `{ phrase, boost: 0-100 }`. The list is picked by exact tag, then base language, then `default` — lists are never merged across languages.
`no_input_timeout_ms`	Silence wait for this question, `1000`-`60000` ms. Has no effect when no-input handling is off for the channel.

Rules:

Keys are strict — an unknown key is a compile error (GATHER_ASR_UNKNOWN_KEY). Credentials and service IDs never go in ABL.
At most 500 vocabulary entries per field across every language, each at most 100 characters.
One listening-settings field per step. ASR: applies only when its field is asked on its own; a field sharing its step with other required fields gets warning GATHER_ASR_SHARED_STEP and uses the normal settings when asked together.
FLOW steps only. ASR: on a top-level (reasoning) GATHER field is preserved but has no effect, with compile warning GATHER_ASR_REASONING_UNSUPPORTED.
Deploy checks. A provider that no voice channel bound to the target environment supports blocks create/promote (GATHER_ASR_PROVIDER_UNRESOLVED); restore/rollback warn instead. An unsupported channel (non-KoreVG voice, realtime speech-to-speech), an unsupported language, too many words for the engine, a no-input wait with no-input off, or an uncovered language list are deploy warnings.
At runtime, anything that can’t be applied (an unknown engine, a rejected setting, a gateway that doesn’t confirm the change) falls back silently to the call’s normal listening settings — the call continues.
There’s no platform switch for this feature; to stop using it, remove the ASR: block and redeploy.

Session-value vocabulary (`vocabulary.terms` binding)

vocabulary.terms can read its words from a session value set earlier in the call, so the recognizer hears the specific names, streets, or codes a tool returned for this caller. Write one language’s list (or the whole list) as a single quoted "{{path}}" reference:

FLOW:
  lookup_streets:
    REASONING: false
    CALL: list_streets
      WITH:
        county: county
      AS: streetResult
    ON_RESULT:
      - IF: has(streetResult.streets)
        SET:
          street_keyterms = streetResult.streets
        THEN: get_street
      - ELSE:
        THEN: get_street
  get_street:
    REASONING: false
    GATHER:
      - street_name: required
        prompt: "What is the street name?"
        ASR:
          vocabulary:
            mode: replace
            terms:
              en-US: "{{street_keyterms}}"
              default: [Main Street]
    THEN: COMPLETE

Rules:

The value is read each time the field is asked (first prompt, retries, rechecks). A list that changes between turns is used as it is at that moment. It applies only while that field is asked.
The reference must be exactly one quoted "{{path}}": dotted names with optional [n] indexes, at most 8 parts and 128 characters. Surrounding text, two references, filters, an unquoted {{...}}, or a reference inside a list are all compile errors (GATHER_ASR_TERMS_BINDING_INVALID).
Some values can never be bound (GATHER_ASR_TERMS_BINDING_FORBIDDEN): session identity and runtime values (session, config, env, history, messages, tenant_id, project_id, user_id, session_id, session_principal_id), the protected email aliases, any root starting with _, and any path through __proto__, prototype, constructor, _secret, or _secrets. A user.* value is personal data and needs restore_pii: true (see below).
The value can be a string (one word) or a list of strings and { phrase, boost } entries. On the Deepgram keyterm path a boost has no effect.
Each word is checked when read. A word that is missing, empty, longer than 100 characters, contains a comma/semicolon/line break, duplicates an earlier word, holds a redaction placeholder or a held secret value, or holds protected personal data is left out. The question is still asked. A field never fails because of its word list.
Words already present for a language come first. A language whose reference resolves to nothing stays empty for that question. It does NOT fall back to default.
Limits per field per question: 2,000 entries read, 64 KiB of text read, 500 words total including literal ones. On Deepgram, a list that includes session words is held to 400 estimated tokens (literal-only lists keep 500), and the gateway accepts at most 100 keyterms.
Only the KoreVG voice pipeline uses these words. Other channels and realtime speech-to-speech calls ignore the reference without reading the value.

Keep the list short and spoken-form (20 to 50 words is the range Deepgram recommends). Rank or cut the list in the tool, expand abbreviations, and use the form a caller says (“North Main Street”, not “N MAIN ST”). Never put session data in deepgramOptions.tag.

Personal data in bound words (`restore_pii`)

Values the platform has tokenized as personal data (names, phone numbers, emails) are left out by default. To send the original value to the speech engine, BOTH of these are required:

The field sets vocabulary.restore_pii: true.
The project’s PII pattern for that kind of data has an explicit speech_provider rule set to Original (PII Protection in Studio). A pattern whose default mode is Original does not count; without the rule the word is left out.

A restored word is sent only to the recognizer, never written to traces or logs, and each restore is recorded in the PII audit log without the value. On Deepgram, a call that sends a restored word also opts the request out of Deepgram’s model-improvement program. restore_pii on a field with no session-value reference is ignored with a warning.

Field-level keypad settings (`DTMF:`)

A DTMF: block, a sibling of ASR: under a single GATHER field in a FLOW step, sets how the bot collects a number the caller types on the phone keypad while that field is being asked on a KoreVG voice call. When the field is no longer being asked, the call’s normal keypad settings come back automatically (2 seconds between key presses, finish key #, up to 12 digits). A field without DTMF: behaves exactly as before. The caller can still answer by speaking; DTMF: changes only how typed digits are grouped into one answer:

FLOW:
  get_mobile:
    REASONING: false
    GATHER:
      - mobile_number: required
        type: string
        prompt: "Please say or enter your 10-digit registered mobile number."
        DTMF: { digits: 1..10, finishOnKey: "#", interDigitTimeoutMs: 5000 }
        VALIDATE: "^[0-9]{10}$"
        RETRY_PROMPT: "That didn't look like a 10-digit number. Please say it or enter it on the keypad again."
        MAX_RETRIES: 3
    THEN: verify_customer

The block can also be written over several lines (DTMF: followed by indented digits:, finishOnKey:, interDigitTimeoutMs: lines).

Key	Meaning
`digits`	`min..max`, both whole numbers 1-32. The answer finishes as soon as the caller types `max` digits. A pause finishes it only after at least `min` digits. Keep `min` at 1 unless a short entry should end only by the finish key.
`finishOnKey`	`"#"`, `"*"`, or `"none"`. Pressing the key finishes the answer at once; the key itself is not part of the answer. `"none"` means no finish key.
`interDigitTimeoutMs`	Longest pause between two key presses, 500-30000 ms. A longer pause finishes the answer.

Rules:

Keys are strict: an unknown key, a malformed value, or an out-of-range value is a compile error. min above max is a compile error. A DTMF: block with no settings is a compile error.
min above 1 is a compile warning: a caller who stops early is not finished by the pause.
One keypad-settings field per step. A field with DTMF: must be the only field in its step. Split other fields into their own steps.
FLOW steps only. DTMF: on a top-level (reasoning) GATHER field is reported as an unknown key (W170) and has no effect.
VALIDATE checks the stored value. A type: phone field is stored in international format (e.g. +919876543210), so ^[0-9]{10}$ never matches it. Use type: string to check digits exactly as typed, or write the pattern for the international format.
DTMF: does not change validation or retries: use VALIDATE, RETRY_PROMPT, MAX_RETRIES on the same field, plus the agent’s ON_ERROR handler for validation_error with SUBTYPE: max_retries_exceeded.
DTMF: collects ordinary data. The typed number reaches the agent, its memory, and the transcript like any GATHER value. For secrets (card numbers, security codes, PINs), use SECURE_INPUT instead.
Explicit keypad collections (SECURE_INPUT, the ivr_digit_input tool, voice surveys) keep their own settings and are unaffected.
At runtime, settings apply with the field’s listening settings (same mechanism as ASR:). If they can’t be applied (e.g. a realtime speech-to-speech channel, or a gateway that doesn’t confirm the change), the call keeps its normal keypad settings and continues.

GATHER block properties

Alongside FIELDS:, a flow GATHER: block accepts these block-level properties:

Property	Type	Description
`STRATEGY`	`"auto"` , `"ml"` , `"llm"` , `"hybrid"` , `"pattern"`	Collection approach (see below). Also settable per field.
`PROMPT`	`string`	A single prompt used to collect the whole block.
`MESSAGE_KEY`	`string`	Locale catalog key for the block prompt.

The STRATEGY: value controls the collection approach:

Value	Description
`auto`	Let the platform choose the best available strategy
`ml`	Use the ML/NLU entity model
`llm`	Use LLM to extract values from natural conversation
`pattern`	Use pattern matching and extraction rules
`hybrid`	Combine ML and LLM extraction

CORRECTIONS

When CORRECTIONS: true, the user can naturally correct previously collected values without restarting the step:

FLOW:
  collect_info:
    REASONING: false
    GATHER:
      - name: required
      - email: required
    CORRECTIONS: true
    THEN: next_step

COMPLETE_WHEN

The COMPLETE_WHEN: condition specifies when the gather step is considered complete:

FLOW:
  collect_all:
    REASONING: false
    GATHER:
      FIELDS:
        - field_a: required
        - field_b: required
        - field_c: optional
    COMPLETE_WHEN: field_a AND field_b
    THEN: process

CALL…WITH…AS

The CALL: action invokes a tool. Use WITH: to pass parameters and AS: to bind the result to a variable:

FLOW:
  verify_step:
    REASONING: false
    CALL: verify_account
      WITH:
        account_id: source_account
      AS: acctResult
    RESPOND: "Account verified: {{acctResult.owner_name}}"
    THEN: next_step

Property	Type	Required	Default	Description
`CALL`	`string`	—	—	Tool name to invoke
`WITH`	`Record<string, string>`	No	none	Key-value parameter mapping
`AS`	`string`	No	none	Variable name to bind the tool result

WITH parameters

The WITH: block maps tool parameter names to values or variable references:

CALL: calculate_fees
  WITH:
    transfer_type: transfer_type
    amount: amount
    currency: currency
    destination_country: beneficiary_country
  AS: feeResult

Values can be:

Variable references: amount (resolves the session variable amount)
Literal strings: "domestic"
Expressions: COALESCE(reference, "")
Nested objects — a key with no inline value followed by an indented sub-block becomes a nested object argument, for tools whose schema requires object parameters:

CALL: ivr_digit_input
  WITH:
    prompt: "Enter your account number"
    noInputConfig:
      timeoutMs: 5000
      maxRetries: 2
    noMatchConfig:
      message: "That didn't match. Please try again."
  AS: digitResult

Nesting is preserved by indentation. Scalar leaves keep their raw form and are coerced at runtime ("30" → 30, "[15, 16]" → [15, 16]).

Localized WITH arguments

A WITH value can take its text from the project’s locale files (locales/<locale>/<agent>.json or locales/<locale>/_shared.json) with "{{locale.KEY}}", or a bare locale.KEY. The text is chosen for the caller’s current interaction locale (with the same fallback chain as MESSAGE_KEY — for example hi-IN, then hi), and {{…}} placeholders inside the locale text are rendered too:

FLOW:
  collect_card_number:
    REASONING: false
    CALL: ivr_digit_input
      WITH:
        prompt: "{{locale.CARD_PROMPT}}"
        maxDigits: 19
        endingKeyPress: "#"
        noInputConfig:
          timeout: 30
          maxRetries: 2
          message: "{{locale.CARD_NO_INPUT}}"
      AS: cardNumberResult
    ON_RESULT:
      - IF: cardNumberResult.success == false
        THEN: payment_input_failed
      - ELSE:
          THEN: validate_card_number

If a referenced key isn’t defined for the caller’s locale (and no less-specific locale in the chain provides it), the tool is not called — the CALL result is success: false with error.code: "LOCALE_KEY_MISSING", so the step’s failure branch runs and raw {{locale.KEY}} text never reaches the tool or the caller. Only authored text is treated as a locale reference; a session value that happens to contain {{locale.…}} passes through as plain data. Supported forms are "{{locale.KEY}}" (optionally with filters, like "{{locale.KEY | upper}}", and mixed with other text) and a bare locale.KEY; an expression such as locale["KEY"] or locale.KEY + "!" is not supported and the CALL is not run.

SET

The SET: action assigns values to session variables:

FLOW:
  init:
    REASONING: false
    SET:
      status = "pending"
      retry_count = 0
      sanctions_clear = false
    THEN: next_step

Each assignment uses variable = expression syntax. The expression is resolved at execution time and can reference:

Literal values: "pending", 0, true, false
Variable references: acctResult.balance
Function calls: FORMAT_CURRENCY(amount, "USD"), COALESCE(value, "default"), ADD(a, b), SUB(a, b), ROUND(n, decimals)
Unique ID generation: UNIQUE_ID(12)
Current timestamp: NOW()

An unquoted JSON array or object literal is stored as a structured value. A JSON string’s string-typed leaves may contain {{variable}} templates — the collection is parsed first, then its string values are rendered, so substituted data is never reinterpreted as JSON:

SET:
  filters = [{"field":"customer","operator":"in","value":["Public", "{{employer_name}}"]}]

This stores an array of objects correctly even when employer_name contains quotes or backslashes. Prefer a direct variable reference when constructing a computed collection instead of interpolating one into JSON-shaped text:

SET:
  filters = [{"field":"customer","operator":"in","value":["Public", employer_name]}]

Surround the whole value with quotes when JSON-shaped text is intentional — SET: payload_text = '[{"customer":"{{employer_name}}"}]' stores a string, not a structured value. A session TYPE declaration alone doesn’t validate every SET write; validate structured arguments at the tool boundary (pass the variable to a typed parameter, such as filters: object[], through WITH).

CHECK

The CHECK: action evaluates a condition. If the condition is false, execution transitions to the ON_FAIL: step:

FLOW:
  check_limits:
    REASONING: false
    CHECK: amount <= available_balance AND ADD(daily_used, amount) <= daily_limit
    ON_FAIL: over_limit
    THEN: proceed

Property	Type	Required	Default	Description
`CHECK`	`string`	—	—	Condition expression to evaluate
`ON_FAIL`	`string`	No	none	Step to go to if the condition is false

CLEAR

The CLEAR: action removes variables from the session context:

FLOW:
  reset_beneficiary:
    REASONING: false
    CLEAR: [beneficiary_name, beneficiary_account, beneficiary_id]
    THEN: collect_beneficiary

TRANSFORM

The TRANSFORM: action filters, maps, sorts, and limits an array from the session context:

FLOW:
  filter_results:
    REASONING: false
    TRANSFORM:
      SOURCE: search_results
      AS: hotel
      INTO: filtered_hotels
      FILTER: "hotel.rating >= 4"
      MAP:
        name: hotel.name
        price: hotel.price_per_night
        rating: hotel.rating
      SORT_BY: price asc
      LIMIT: 5
    THEN: show_results

Property	Type	Required	Default	Description
`SOURCE`	`string`	Yes	—	Dot-path to the source array
`AS`	`string`	Yes	—	Loop variable name
`INTO`	`string`	Yes	—	Output variable name
`FILTER`	`string`	No	none	Condition expression using the loop variable
`MAP`	`Record<string, string>`	No	none	Field mapping expressions
`SORT_BY`	`string`	No	none	Sort field and direction (`asc` or `desc`)
`LIMIT`	`number`	No	none	Maximum number of items in the output

LOG

The LOG: action emits a trace-only diagnostic (not shown to the user). Use the inline or block form:

FLOW:
  audit:
    REASONING: false
    LOG: "Entering audit step"
    # or, with a level:
    # LOG:
    #   MESSAGE: "Balance below threshold"
    #   LEVEL: warn          # debug | info | warn | error
    THEN: next_step

AWAIT_ATTACHMENT

The AWAIT_ATTACHMENT: action pauses the step until the user uploads a file.

FLOW:
  collect_id_doc:
    REASONING: false
    AWAIT_ATTACHMENT:
      NAME: id_document
      PROMPT: "Please upload a photo of your ID."
      CATEGORY: image        # image | document | audio | video
      REQUIRED: true
      TIMEOUT: 120
      ON_TIMEOUT: manual_review
    THEN: verify_id

Property	Type	Description
`NAME`	`string`	Variable the uploaded attachment is stored under.
`PROMPT`	`string`	Message asking the user to upload.
`CATEGORY`	`string`	`image`, `document`, `audio`, or `video`.
`REQUIRED`	`boolean`	Whether the upload is mandatory.
`TIMEOUT`	`number`	Seconds to wait for the upload.
`ON_TIMEOUT`	`string`	Step to transition to if the upload times out.

SECURE_INPUT

The SECURE_INPUT: action pauses the step to collect one or more sensitive values — a card number, CVV, or similar — via DTMF and/or speech, and delivers them directly to one tool, without the raw values ever passing through the LLM, transcript, session state, logs, call recordings, or traces: speech recognition is suppressed and recording is paused while the caller enters them, and the values are wiped from memory once the delivery call returns. It’s the PCI-safe alternative to GATHER for data that must never reach the model.

SECURE_INPUT is currently authored only in the legacy .agent.abl (line-based) format. The .agent.yaml parser does not yet accept this action. It also requires a live voice call and the SECURE_INPUT_ENABLED runtime setting (off by default): without a live voice session the step takes ON_FAIL; with the setting off, the step is skipped entirely. Both the delivery CALL and any validation CALL must be HTTP project tools (configured in Project Tools, not the agent’s own TOOLS: section) that send a JSON body.

FLOW:
  collect_card:
    REASONING: false
    SECURE_INPUT:
      MODE: [dtmf]                          # dtmf | speech, one or both
      FIELDS:
        - card_number:
            PROMPT: { en: "Please enter your 16-digit card number." }
            COLLECT: { digits: 13..19, finishOnKey: "#" }
            VALIDATE: [ luhn ]
        - cvv:
            PROMPT: { en: "And the 3-digit security code." }
            COLLECT: { digits: 3..4 }
      MAX_ATTEMPTS: 3
      CANCEL: { dtmf_key: "*" }
      CALL charge_card WITH: { pan: "{{secure.card_number}}", cvv: "{{secure.cvv}}" }
        AS: payment_result
        RESULT_FIELDS: [Status, TransactionIdentifier]
        SUCCESS_WHEN: { Status: "Success" }
      ON_SUCCESS: confirm
      ON_TIMEOUT: retry_by_agent
      ON_CANCEL: retry_by_agent
      ON_FAIL: human_agent
    THEN: confirm

  confirm:
    REASONING: false
    RESPOND: "Your payment is complete. Reference: {{payment_result.TransactionIdentifier}}."

Property	Type	Description
`MODE`	`("dtmf" \| "speech")[]`	Which collection channel(s) are accepted. Required; at least one.
`FIELDS`	list	One or more fields to collect, in order. Each is a `- <name>:` entry with `PROMPT`, `COLLECT`, and optional `VALIDATE`.
`MAX_ATTEMPTS`	`number`	Failed collection attempts allowed before `ON_FAIL` (default 3).
`CANCEL`	`object`	Cancellation trigger: `dtmf_key` and/or `keywords` (a keyword must be spoken as its own word).
`CALL <tool> WITH: {...}`	—	The delivery call — the single tool invoked with the collected values. Only the inline-object `WITH:` form is supported. Reference a collected field as a whole-value placeholder `{{secure.<name>}}`.
`AS`	`string`	Session variable that receives the delivery response. Requires `RESULT_FIELDS`.
`RESULT_FIELDS`	`string[]` (with `AS`)	Top-level response fields that may be bound to `AS`; nothing else in the response is ever read. Exact top-level keys only — nested paths aren’t supported.
`SUCCESS_WHEN`	`object`	`{ Field: "value" }` or `{ Field: [value1, value2] }` — which delivery responses count as success. See below.
`ON_SUCCESS`	`string`	Step to transition to after successful collection and delivery.
`ON_TIMEOUT`	`string`	Step to transition to if collection times out.
`ON_CANCEL`	`string`	Step to transition to if the caller cancels.
`ON_FAIL`	`string`	Step to transition to if validation runs out of attempts, delivery fails, or `SUCCESS_WHEN` doesn’t match.

AS, RESULT_FIELDS, and SUCCESS_WHEN may be written indented under the CALL line or beside it; AS: <name> may also end the CALL line itself.

Every outcome route (ON_SUCCESS, ON_TIMEOUT, ON_CANCEL, ON_FAIL) takes a step name only — a RESPOND or any other block indented under a route isn’t part of SECURE_INPUT; the parser reports the ignored line (W208) and an empty route is a compile error (SECURE_INPUT_EMPTY_OUTCOME_ROUTE). Put the response in the step the route names, as in the confirm step above.

Success. Without SUCCESS_WHEN, any 2xx delivery response takes ON_SUCCESS; a non-2xx status, a network failure, a timeout, or an unreadable body takes ON_FAIL. With SUCCESS_WHEN, a 2xx response must also match every listed field (compared as text, no case folding) or the step takes ON_FAIL — use this when an API can report a decline inside an HTTP 200. A delivery that timed out after the request was sent also takes ON_FAIL, even though the charge may have gone through — don’t retry payment from that step. Reading the response. AS binds only the RESULT_FIELDS the response contains, as top-level scalar values. A field is dropped (never bound) when its value contains any collected value’s digits, contains a valid card number, or is an object or list — the step’s trace names the bound/dropped fields, never their values. The bound fields are then ordinary session values for later steps, as {{payment_result.Status}} above.

Field properties

Property	Type	Description
`PROMPT`	`{ <locale>: string }` or `{ template: string }`	Locale-keyed prompt text, or a reference to a named template. At least one non-empty entry is required. A locale reference such as `"{{locale.KEY}}"` also works.
`COLLECT`	`object`	`digits: N..M` (min/max digit count), `finishOnKey`, `interDigitTimeoutMs`, `asrTimeoutMs` (spoken-path silence window).
`VALIDATE`	list	Validation rules: a bare rule name (`luhn`), an inline object (`{ length: 4..4 }`, `{ date_mmYY: "not_past" }`), or a delegated `CALL <tool> WITH: {...}` rule.

A failed check asks for the field again, up to MAX_ATTEMPTS. A CALL validation rule passes only when the tool returns valid: true, and may reference the field being checked plus any fields collected before it. A field accepts only PROMPT, COLLECT, and VALIDATE — anything else is ignored with a warning (W210). References inside the delivery WITH: block must be a whole-value placeholder — pan: "{{secure.card_number}}" is valid; embedding it in a larger string (pan: "card:{{secure.card_number}}") or referencing an undeclared field is a compile error.

Every collected value lives only in a local secure buffer for the duration of the gate and is zeroized on every exit path (success, timeout, cancel, or failure) — it is never written to session state, so it cannot be referenced by {{ }} outside the delivery/validation calls, and it never appears in a trace, span, or log.

Diagnostic	Fires when
`SECURE_INPUT_INVALID_MODE`	`MODE` is missing, empty, or contains a value other than `dtmf`/`speech`.
`SECURE_INPUT_MISSING_DELIVER_TOOL`	No delivery `CALL`.
`SECURE_INPUT_MISSING_PROMPT`	No `FIELDS` are declared, or a field’s `PROMPT` has neither a locale entry nor a `template` reference.
`SECURE_EMBEDDED_PLACEHOLDER`	A `{{secure.*}}` reference is part of a longer argument string instead of the whole value.
`SECURE_UNKNOWN_FIELD`	A `{{secure.*}}` reference names a field the step doesn’t collect.
`SECURE_INPUT_EMPTY_OUTCOME_ROUTE`	An outcome route (`ON_SUCCESS`/`ON_FAIL`/`ON_TIMEOUT`/`ON_CANCEL`) is written without a step name.
`SECURE_INPUT_INVALID_RESULT_CONTRACT`	`AS` that isn’t a plain variable name, `AS` without `RESULT_FIELDS` (or the reverse), a nested or repeated field name, an empty `SUCCESS_WHEN`, or a `SUCCESS_WHEN` field with no value.
`RESERVED_VARIABLE_NAME` / `IMMUTABLE_SYSTEM_IDENTIFIER`	`AS` names a reserved or system-owned variable such as `session_id`.
`W208` / `W210`	A line inside the block, or a field property, that `SECURE_INPUT` doesn’t read — it’s ignored.
`W211`	`RESULT_FIELDS` or `SUCCESS_WHEN` written across several lines; write them inline.

MESSAGE_KEY and BEHAVIOR

Two additional step-level properties:

MESSAGE_KEY: — a locale catalog key used to localize the step’s RESPOND: message.
BEHAVIOR: — free-form guidance text appended to the step’s reasoning goal (a convenience alias that folds into GOAL).

RESOLVE_SIP_DESTINATION

RESOLVE_SIP_DESTINATION: is a step action that computes a dynamic SIP transfer authority (VDN/host/port) before a call_transfer step runs. It runs a feeder — a workflow tool or a session memory key — matches the candidate against the approved_authorities allow-list declared on the call_transfer tool’s sipTransferId parameter, and commits the approved authority to a trusted server-side routing channel that the transfer then reads. The model never sees or sets the destination.

FLOW:
  resolve_destination:
    REASONING: false
    RESOLVE_SIP_DESTINATION:
      FROM_WORKFLOW: "lookup_vdn_by_region_language"   # or: FROM_MEMORY: routing_decision
      TIMEOUT_MS: 1500
    THEN: transfer_step

  transfer_step:
    REASONING: false
    CALL: call_transfer(callTransferType: "sip")
    THEN: COMPLETE

Sub-key	Type	Description
`FROM_WORKFLOW`	`string`	Name of a workflow tool invoked as the destination feeder.
`FROM_MEMORY`	`string`	Session memory key to read as the feeder (use instead of `FROM_WORKFLOW`).
`TIMEOUT_MS`	`number`	Hard timeout for the feeder, in milliseconds.

The feeder’s result supplies the {{route.vdn}} / {{route.ip}} / {{route.port}} values for the sipTransferId template. The two-zone template and the approved_authorities allow-list are declared on the tool parameter — see Dynamic destinations in the tools reference.

Branching and control flow

THEN / ON_FAIL

The most basic branching: THEN: specifies the next step on success, and ON_FAIL: specifies the step on failure:

FLOW:
  check_status:
    REASONING: false
    CHECK: account_status == "active"
    ON_FAIL: inactive_account
    THEN: proceed

ON_FAIL: also accepts a structured block for recovery flows — COLLECT: (fields to re-collect), GOTO: (step), RETRY: true, RESPOND:, and THEN::

FLOW:
  validate_details:
    REASONING: false
    CHECK: routing_number_valid == true
    ON_FAIL:
      RESPOND: "That routing number looks off — let's try again."
      COLLECT: [routing_number]
      GOTO: collect_routing

ON_RESULT

ON_RESULT: provides multi-way branching based on the result of a CALL: action. Each branch has an IF: condition, optional actions, and a THEN: transition:

FLOW:
  verify_step:
    REASONING: false
    CALL: verify_account
      WITH:
        account_id: source_account
      AS: acctResult
    ON_RESULT:
      - IF: acctResult.status == "active"
        SET:
          customer_name = acctResult.owner_name
          balance = acctResult.available_balance
        RESPOND: "Account verified. Hello, {{customer_name}}."
        THEN: next_step
      - IF: acctResult.status == "frozen"
        RESPOND: "Your account is frozen. Please contact your branch."
        THEN: end
      - ELSE:
        RESPOND: "Account not found. Please check the number."
        THEN: collect_account

ON_RESULT branch properties

Property	Type	Required	Default	Description
`IF`	`string`	No	—	Condition expression. Omit for `ELSE` branch.
`RESPOND`	`string`	No	none	Message to display
`SET`	`Record<string, string>`	No	none	Variable assignments
`CALL`	`string`	No	none	Optional nested tool call
`THEN`	`string`	Yes	—	Next step

The ELSE branch (a branch with no IF condition) matches when no other condition is true.

ON_SUCCESS / ON_FAIL

An alternative to ON_RESULT: for simpler success/failure branching:

FLOW:
  call_api:
    REASONING: false
    CALL: submit_request
      WITH:
        data: request_data
      AS: result
    ON_SUCCESS:
      RESPOND: "Request submitted: {{result.id}}"
      THEN: done
    ON_FAIL:
      RESPOND: "Request failed. Please try again."
      THEN: retry_step

Both ON_SUCCESS: and ON_FAIL: support conditional branches:

FLOW:
  process:
    REASONING: false
    CALL: process_order
      AS: orderResult
    ON_SUCCESS:
      - IF: orderResult.express == true
        RESPOND: "Express order confirmed!"
        THEN: express_fulfillment
      - ELSE:
        RESPOND: "Order confirmed."
        THEN: standard_fulfillment
    ON_FAIL:
      - IF: orderResult.error == "out_of_stock"
        RESPOND: "Item is out of stock."
        THEN: suggest_alternatives
      - ELSE:
        RESPOND: "An error occurred."
        THEN: error_handling

ON_INPUT

ON_INPUT: provides branching based on user input, typically used after a GATHER: action:

FLOW:
  confirm:
    REASONING: false
    GATHER:
      - confirmation: required
    ON_INPUT:
      - IF: input.contains("yes") OR input.contains("confirm")
        THEN: execute
      - IF: input.contains("no") OR input.contains("cancel")
        RESPOND: "Cancelled."
        THEN: cleanup
      - ELSE:
        RESPOND: "Please type 'yes' to confirm or 'no' to cancel."
        THEN: confirm

A step that has only ON_INPUT branches — no RESPOND/prompt and no default (ELSE) branch — traps any unmatched input on the same step forever. The compiler warns (FLOW_PROMPTLESS_ON_INPUT_UNMATCHED_TRAP): add a default ELSE route or an authored prompt unless the wait is intentional.

Digressions

Digressions are intent-based escapes that can interrupt the current step. They match user intent patterns and respond accordingly:

FLOW:
  collect_details:
    REASONING: false
    GATHER:
      - account: required

    DIGRESSIONS:
      - INTENT: "what is swift"
        RESPOND: "A SWIFT code is an 8 or 11 character code identifying a bank internationally."
        RESUME: true
      - INTENT: "cancel"
        RESPOND: "Transaction cancelled."
        GOTO: cleanup
      - INTENT: "speak to agent"
        RESPOND: "Connecting you with a specialist."
        DELEGATE: Live_Agent

Digression properties

Property	Type	Required	Default	Description
`INTENT`	`string`	Yes	—	Intent pattern to match
`KEYWORDS`	`string[]`	No	none	Explicit keywords for matching
`CONDITION`	`string`	No	none	Additional condition to check
`RESPOND`	`string`	No	none	Response message
`MESSAGE_KEY`	`string`	No	none	Locale catalog key for the response
`SET`	`Record<string,string>`	No	none	Variable assignments (within the `DO:` block)
`RESUME`	`boolean`	No	`false`	Return to the current step after handling
`GOTO`	`string`	No	none	Transition to a specific step
`HANDOFF`	`string`	No	none	Hand off to another agent (supports `RETURN:` / `ON_RETURN:`)
`DELEGATE`	`string`	No	none	Delegate to another agent (requires `RETURN: true`)
`CALL`	`string`	No	none	Tool to invoke
`CLEAR`	`string[]`	No	none	Variables to clear

When RESUME: true, the user returns to the interrupted step after the digression response. When GOTO: is specified, the flow transitions to that step instead. RESUME, GOTO, and HANDOFF are terminal.

For multiple ordered actions, use the canonical DO: block instead of flat keys. Each list item is an action (RESPOND, SET, CLEAR, CALL, HANDOFF, DELEGATE, GOTO, RESUME), and HANDOFF/DELEGATE may carry RETURN: and ON_RETURN: (with MAP:). Mixing flat keys with a DO: block is discouraged.

DIGRESSIONS:
  - INTENT: "check balance"
    DO:
      - RESPOND: "Let me pull that up."
      - HANDOFF: Account_Info
        RETURN: true
      - RESUME: true

Global digressions

Digressions declared at the flow level (under global_digressions:) are available at every step:

FLOW:
  global_digressions:
    - INTENT: "cancel"
      RESPOND: "Transaction cancelled."
      GOTO: cleanup

    - INTENT: "help"
      RESPOND: "I can help with account inquiries, transfers, and balance checks."
      RESUME: true

    - INTENT: "speak to agent"
      RESPOND: "Connecting you with a live agent."
      DELEGATE: Live_Agent_Transfer

Sub-intents

Sub-intents are scoped intents valid only within a specific step. They handle step-specific user requests like corrections or clarifications:

FLOW:
  collect_beneficiary:
    REASONING: false
    GATHER:
      FIELDS:
        - name: required
        - account: required
        - bank: required

    SUB_INTENTS:
      - INTENT: "change name"
        CLEAR: [name]
        RESPOND: "What is the correct name?"
      - INTENT: "change account"
        CLEAR: [account]
        RESPOND: "What is the correct account number?"
      - INTENT: "change bank"
        CLEAR: [bank, routing_code]
        RESPOND: "What is the correct bank name?"

Sub-intent properties

Property	Type	Required	Default	Description
`INTENT`	`string`	Yes	—	Intent pattern to match
`RESPOND`	`string`	No	none	Response message
`MESSAGE_KEY`	`string`	No	none	Locale catalog key for the response
`CLEAR`	`string[]`	No	none	Variables to clear (triggers re-collection)
`SET`	`Record<string, string>`	No	none	Variables to set
`CALL`	`string`	No	none	Tool to invoke
`RESUME`	`boolean`	No	`true`	Stay in the current step

Interactive actions

Flow steps can present interactive UI elements (buttons, selects, inputs) to the user. These are attached to RESPOND: messages and handled with ON_ACTION: callbacks.

Action elements

Interactive actions are defined in an ACTIONS: block within a step:

FLOW:
  choose_option:
    REASONING: false
    RESPOND: "How would you like to proceed?"
    ACTIONS:
      - id: "option_transfer"
        type: button
        label: "Wire Transfer"
        value: "wire"
      - id: "option_ach"
        type: button
        label: "ACH Transfer"
        value: "ach"
      - id: "option_check"
        type: button
        label: "Send a Check"
        value: "check"
    ON_ACTION:
      - ACTION: "option_transfer"
        SET:
          transfer_method = "wire"
        THEN: wire_flow
      - ACTION: "option_ach"
        SET:
          transfer_method = "ach"
        THEN: ach_flow
      - ACTION: "option_check"
        SET:
          transfer_method = "check"
        THEN: check_flow

Element types

Buttons

ACTIONS:
  - id: "confirm_btn"
    type: button
    label: "Confirm"
    value: "confirmed"

ACTIONS:
  - id: "currency_select"
    type: select
    label: "Select currency"
    options:
      - id: "usd"
        label: "US Dollar"
        description: "United States Dollar"
      - id: "eur"
        label: "Euro"
        description: "European Union Euro"
      - id: "gbp"
        label: "British Pound"

Input fields

ACTIONS:
  - id: "amount_input"
    type: input
    label: "Enter amount"
    inputType: number
    placeholder: "0.00"
    required: true

Action element properties

Property	Type	Required	Default	Description
`id`	`string`	Yes	—	Unique identifier for the action element
`type`	`"button"` , `"select"` , `"input"`	Yes	—	Element type
`label`	`string`	Yes	—	Display label
`value`	`string`	No	none	Hidden value sent when the element is interacted with
`description`	`string`	No	none	Subtitle or helper text
`options`	`{id, label, description?}[]`	No	none	Options for `select` type
`inputType`	`"text"` , `"number"` , `"date"` , `"time"` , `"email"`	No	`"text"`	Input field type (for `input` type)
`placeholder`	`string`	No	none	Placeholder text (for `input` type)
`required`	`boolean`	No	`false`	Whether the input is required (for `input` type)

Form submission

When a step contains input type elements, you can configure a form submission button:

ACTIONS:
  - id: "name_input"
    type: input
    label: "Your name"
    inputType: text
    required: true
  - id: "email_input"
    type: input
    label: "Your email"
    inputType: email
    required: true
  SUBMIT_LABEL: "Submit"
  SUBMIT_ID: "form_submit"

The ACTIONS: block also accepts an optional RENDER_ID: to give the whole action set a stable identifier for rendering/telemetry.

ON_ACTION callbacks

The ON_ACTION: block defines handlers for user interactions with action elements:

ON_ACTION:
  - ACTION: "confirm_btn"
    RESPOND: "Confirmed! Processing your request."
    SET:
      confirmed = true
    THEN: process_step
  - ACTION: "cancel_btn"
    RESPOND: "Cancelled."
    THEN: cleanup

ON_ACTION handler properties

Property	Type	Required	Default	Description
`ACTION`	`string`	Yes	—	The `id` of the action element that triggered this handler
`CONDITION`	`string`	No	none	Optional value-based condition
`RESPOND`	`string`	No	none	Response message
`SET`	`Record<string, string>`	No	none	Variable assignments
`CLEAR`	`string[]`	No	none	Variables to clear
`CALL`	`string`	No	none	Tool to invoke (requires `AS`)
`LOG`	`string`	No	none	Trace-only diagnostic
`HANDOFF`	`string`	No	none	Hand off to another agent
`DELEGATE`	`string`	No	none	Delegate to another agent (`RETURN:`/`ON_RETURN:` supported)
`COMPLETE`	`boolean`	No	none	Terminal — mark the flow complete
`THEN` / `GOTO` / `TRANSITION`	`string`	No	none	Step to transition to (three interchangeable keywords)

For multiple ordered actions in one handler, use a canonical DO: block whose list items are actions (SET, CLEAR, LOG, RESPOND, CALL, GOTO/TRANSITION/THEN, HANDOFF, DELEGATE, COMPLETE).

Rich content

Steps can include rich content in multiple formats alongside RESPOND: messages. The runtime selects the appropriate format based on the channel. The block keyword is RICH_CONTENT: (canonical) or FORMATS: (original spelling, still accepted); the .agent.yaml format accepts rich_content or formats the same way.

FLOW:
  show_summary:
    REASONING: false
    RESPOND: "Here is your transfer summary."
    FORMATS:
      MARKDOWN: |
        ## Wire Transfer Summary
        | Field | Value |
        |-------|-------|
        | From | {{source_account}} |
        | To | {{beneficiary_name}} |
        | Amount | {{amount}} {{currency}} |
      ADAPTIVE_CARD: |
        {"type": "AdaptiveCard", "body": [...]}

Rich content format properties

The runtime recognizes these format keys. In addition to the messaging formats, several structured template types are available (see Rich content for their schemas):

Format	Description
`MARKDOWN`	Formatted markdown text
`ADAPTIVE_CARD`	Microsoft Adaptive Cards JSON
`HTML`	HTML content
`SLACK`	Slack Block Kit JSON
`AG_UI`	AG-UI / CopilotKit event JSON
`WHATSAPP`	WhatsApp interactive message JSON
`CAROUSEL`	Scrollable cards (title/subtitle/image/buttons); can also be authored as a standalone block after `RESPOND:`
`QUICK_REPLIES`	Quick-reply chips
`LIST`	Vertical list of items
`IMAGE`	Image with caption/alt
`VIDEO`	Video with caption/alt
`AUDIO`	Audio with caption/alt
`FILE`	File attachment
`KPI`	KPI metric tile
`TABLE`	Columns + rows
`CHART`	Bar/line/pie chart
`FORM`	Form fields + submit
`PROGRESS`	Progress bar/circle
`FEEDBACK`	Thumbs/stars/scale feedback

Voice configuration

Steps can include voice-specific overrides for text-to-speech engines:

FLOW:
  greeting:
    REASONING: false
    RESPOND: "Welcome to wire transfer services."
    VOICE:
      SSML: |
        <speak>
          Welcome to <emphasis>wire transfer</emphasis> services.
        </speak>
      INSTRUCTIONS: "Speak in a warm, professional tone."
      PLAIN_TEXT: "Welcome to wire transfer services."

Property	Type	Description
`SSML`	`string`	W3C SSML markup for TTS engines
`INSTRUCTIONS`	`string`	Natural language voice style instructions
`PLAIN_TEXT`	`string`	Voice-optimized plaintext (fallback for all engines)
`BARGE_IN`	`"allow"` \| `"disallow"`	Whether the caller may interrupt (barge in on) this spoken output.
`STREAMING`	`boolean`	TTS delivery mode for this spoken output. Omitted defaults to `true` (streaming).
`END_OF_SPEECH_TURN_TYPE`	`string`	Expected shape of the caller’s next answer, used to pick an end-of-speech (pause) timeout. See Per-turn endpointing.
`END_OF_SPEECH_TIMEOUT_MS`	`number`	Explicit end-of-speech timeout in milliseconds, overriding the preset.
`TURN_DETECTION`	`object`	Gateway turn detection: `enabled` and an optional `eou_threshold` (0.3-0.9). See Gateway turn detection.

Per-turn endpointing

END_OF_SPEECH_TURN_TYPE is a small, deliberately-closed vocabulary describing what kind of answer the caller is expected to give next — the runtime resolves it to a concrete end-of-speech (silence/pause) timeout for the active speech recognizer, so authors don’t have to guess a millisecond value per turn:

Value	Use for
`simple_confirmation`	A yes/no or short acknowledgement.
`structured_value`	A structured value like an account number or date.
`open_ended_question`	An open-ended question expecting a longer, free-form answer.
`complex_explanation`	A caller explanation that may take a while to finish.
`anything_else`	Anything not covered above.

It can be set at any VOICE scope — agent-wide under EXECUTION.voice, on a behavior profile, on a flow step, or per RESPOND — with the narrowest scope winning, same as BARGE_IN/STREAMING:

FLOW:
  collect_value:
    REASONING: false
    VOICE:
      END_OF_SPEECH_TURN_TYPE: structured_value
      END_OF_SPEECH_TIMEOUT_MS: 900
    RESPOND: "Please provide the value."
      VOICE:
        END_OF_SPEECH_TURN_TYPE: open_ended_question   # per-RESPOND override
        END_OF_SPEECH_TIMEOUT_MS: 1400

END_OF_SPEECH_TIMEOUT_MS overrides the preset’s timeout with an explicit millisecond value when set alongside (or instead of) END_OF_SPEECH_TURN_TYPE.

Per-turn endpointing applies to the platform’s own speech-recognition pipeline. It does not affect TTS streaming, and is ignored on native realtime/speech-to-speech voice models where the provider owns turn detection. Omit it to fall back to the agent’s conversation-level pause configuration.

Scoped barge-in

barge_in (values allow / disallow) sets whether the caller can interrupt a specific spoken output — for example, forcing a compliance disclosure to finish. It may be authored at three scopes, from broadest to narrowest, with the narrower winning:

FLOW:
  notice:
    REASONING: false
    BARGE_IN: disallow            # step-wide: applies to this step's outputs
    RESPOND: "This required notice must play in full."
      VOICE:
        BARGE_IN: allow           # per-RESPOND override for this output

It can also be set on a named template’s VOICE: block. Placing barge_in on the agent-wide EXECUTION.voice block, or on branch/handler voice blocks, is rejected (VOICE_BARGE_IN_ILLEGAL_PLACEMENT); an invalid value is VOICE_INVALID_BARGE_IN.

This scoped, per-output policy is distinct from the agent-wide barge-in behavior authored under CONVERSATION → listening. Use scoped barge_in to protect (or open up) individual utterances.

Scoped streaming

streaming (true / false) sets the TTS delivery mode for a specific spoken output — whether audio starts playing as soon as the first tokens are ready (streaming, the default) or the runtime waits for the complete response before speaking it (non-streaming). It follows the same authoring scopes as barge_in: step-wide, per-RESPOND, or on a named template’s VOICE: block, with the narrower scope winning.

FLOW:
  read_confirmation_code:
    REASONING: false
    STREAMING: false               # step-wide: wait for the full utterance before speaking it
    RESPOND: "Your confirmation code is {{confirmation_code}}."
      VOICE:
        STREAMING: false           # equivalent per-RESPOND override

Omitting streaming defaults to true (streaming) at every scope.

Step-level no-input (caller silence)

A FLOW step can carry its own caller-silence policy in its own VOICE: block, as ON_NO_INPUT. It takes the same keys as CONVERSATION.listening.on_no_input (agent/project-wide) and applies on KoreVG pipeline voice while that step is the one waiting on the caller:

CONVERSATION:
  listening:
    on_no_input:
      enabled: true
      mode: static
      timeout_ms: 5000
      max_retries: 3
      messages:
        - text: "Are you still there?"
        - text: "Hello?"

FLOW:
  ask_account:
    REASONING: false
    RESPOND: "What's your account number?"
    GATHER:
      - account_number: required
    VOICE:
      ON_NO_INPUT:
        timeout_ms: 10000
        messages:
          - text: "Could you tell me your account number, {{memo_name}}?"
    THEN: complete

Owner. When the silence timer starts, the step currently waiting owns the window. The block applies only to that step; after COMPLETE/ESCALATE, or on a step with no block, the agent/project policy applies as usual.
Merging. Fields merge one at a time over the project and agent policy — a step can override just timeout_ms and inherit everything else. max_retries, relaxed_interval_ms, on_exhausted, and exhausted_message all follow the same rule, and enabled: true on a step turns silence handling on for that step even when the agent has it off.
Messages. Step messages don’t replace the agent-level list — each silence plays agent message N followed by step message N as one utterance (“Are you still there? Could you tell me your account number, Sam?”). Once the step’s own list is used up, the agent message plays alone (or the platform default, if the agent has none), so a step block never ends the call sooner than the agent alone would.
Retry count. Restarts when the caller speaks, and when a different step (or the same step entered again) takes ownership of the window.
Variables. {{var}} placeholders render in agent messages, step messages, and exhausted_message. A step message with a missing variable is skipped; an agent or exhausted message with a missing variable falls back to the platform default text.

ON_NO_INPUT is only legal directly in a FLOW step’s own VOICE: block. Placed under a GATHER field, RESPOND, a branch, a handler, or a response format, it’s a compile error (VOICE_NO_INPUT_ILLEGAL_PLACEMENT). The YAML format uses a step-level on_no_input: key.

Gateway turn detection

TURN_DETECTION turns KoreVG gateway turn detection on or off for a level and sets its patience. With it on, the voice gateway decides when the caller finished speaking (voice activity, acoustic/text end-of-turn models, speech-provider finals) instead of the speech provider’s silence timer. It can be set at any VOICE scope: a concrete RESPOND’s VOICE block, a flow-step VOICE block, a GATHER field VOICE block, a behavior-profile VOICE block, or EXECUTION.voice:

EXECUTION:
  voice:
    turn_detection:
      enabled: true
      eou_threshold: 0.6

FLOW:
  ask_account:
    REASONING: false
    VOICE:
      turn_detection: { enabled: false }
    GATHER:
      - account_number:
          TYPE: string
          PROMPT: "What is your account number?"

Key	Type	Values	Description
`enabled`	`boolean`	`true`, `false`	Required. `false` turns it off at this level, even when the channel has it on.
`eou_threshold`	`number`	`0.3`-`0.9` in steps of 0.1	Patience: `0.3` answers fastest; `0.8` (Dictation) waits through long pauses like card numbers; `0.9` (Slow dictation) waits longest, for letter-by-letter spelling and long reference numbers. Omitted: falls through to the next level’s value, else `0.5`.

Precedence, most specific first: the response (or step, or field) that asks the caller something, the active behavior profile, EXECUTION.voice, the voice channel’s own turn-detection setting, off. A response/step value applies to the caller’s answer to it and holds while the step re-asks (retries); the next answered response with no key falls back up the chain. On a REASONING: true step (model writes the replies), the step’s own turn_detection applies to every caller turn while the conversation stays in that step (only turn_detection is taken from that step’s VOICE, nothing else). An invalid value is a compile error (VOICE_INVALID_TURN_DETECTION) and is never applied. A KoreVG gateway without the Dictation/Slow dictation profile uses its most patient profile instead (0.9 falls to 0.8, or 0.7 if 0.8 is also missing).

Gateway turn detection applies to KoreVG pipeline calls only, never realtime (speech-to-speech), other voice transports, or the PCI SECURE_INPUT gather. While turn detection is on, the gateway ignores the end-of-speech timeout, so a block that turns it on AND also sets END_OF_SPEECH_TURN_TYPE or END_OF_SPEECH_TIMEOUT_MS gets a compile warning VOICE_TURN_DETECTION_WITH_END_OF_SPEECH.

Step-level error handling

Steps can define local error handlers that override agent-level ON_ERROR: handlers:

FLOW:
  call_external:
    REASONING: false
    CALL: external_api
      WITH:
        query: user_query
      AS: apiResult
    ON_ERROR:
      tool_error:
        RESPOND: "The service is responding slowly. Retrying..."
        SUBTYPE: tool_timeout
        RETRY: 2
        RETRY_DELAY: 1000
        RETRY_BACKOFF: exponential
        RETRY_MAX_DELAY: 8000
        THEN: CONTINUE
      validation_error:
        RESPOND: "An error occurred. Let me try a different approach."
        THEN: RETRY_STEP

The error type (the handler’s key) is matched against a fixed, canonical set — default, llm_error, tool_error, routing_error, validation_error, timeout_error, and unknown_error. A key outside this set (for example the older tool_timeout, invalid_input, or api_error) is flagged at compile time (ON_ERROR_HANDLER_TYPE_DRIFT) and never matches at runtime — see Error types for the full table and the deprecated-name mapping. Narrow tool_error with SUBTYPE/SUBTYPES (known values: rate_limit, auth_failure, network_error, tool_timeout).

Step ON_ERROR handler properties

Property	Type	Description
`SUBTYPE`	`string`	Narrow the handler to a specific error subtype.
`RESPOND`	`string`	Message to show when the error fires.
`RETRY`	`number`	Retry attempts before giving up.
`RETRY_DELAY`	`number`	Delay (ms) between retries.
`RETRY_BACKOFF`	`string`	Backoff strategy: `fixed`, `exponential`, or `linear`.
`RETRY_MAX_DELAY`	`number`	Maximum delay (ms) between retries.
`BACKTRACK_TO`	`string`	Step to backtrack to (used with `THEN: BACKTRACK`).
`HANDOFF_TARGET`	`string`	Target agent (used with `THEN: HANDOFF`).
`THEN`	`string`	Next action: `CONTINUE`, `COMPLETE`, `ESCALATE`, `BACKTRACK`, `RETRY_STEP`, or `HANDOFF`. A step name is not a valid value here — a flow step’s own `THEN:` navigates to a step, but an `ON_ERROR` handler’s `THEN:` takes only one of these six actions.

Complete example

AGENT: Simple_Order
VERSION: "1.0.0"

GOAL: "Help customers place orders."

PERSONA: "Friendly order assistant."

TOOLS:
  check_inventory(product_id: string) -> {available: boolean, quantity: number}
    description: "Check product availability"
    type: http
    endpoint: "/api/inventory/check"
    method: GET

  place_order(product_id: string, quantity: number) -> {order_id: string, total: number}
    description: "Place an order"
    type: http
    endpoint: "/api/orders"
    method: POST

FLOW:
  entry_point: welcome

  steps:
    - welcome
    - collect_product
    - check_stock
    - out_of_stock
    - collect_quantity
    - confirm
    - place
    - done

  global_digressions:
    - INTENT: "cancel"
      RESPOND: "Order cancelled."
      GOTO: done

  welcome:
    REASONING: false
    RESPOND: "Welcome! What product are you looking for?"
    THEN: collect_product

  collect_product:
    REASONING: false
    GATHER:
      - product_id: required
        prompt: "What is the product ID?"
    THEN: check_stock

  check_stock:
    REASONING: false
    CALL: check_inventory
      WITH:
        product_id: product_id
      AS: stockResult
    ON_RESULT:
      - IF: stockResult.available == true
        SET:
          stock_quantity = stockResult.quantity
        RESPOND: "Great news! We have {{stock_quantity}} in stock."
        THEN: collect_quantity
      - ELSE:
        THEN: out_of_stock

  out_of_stock:
    REASONING: false
    RESPOND: "Sorry, that product is currently out of stock."
    THEN: done

  collect_quantity:
    REASONING: false
    GATHER:
      - quantity: required
        type: number
        prompt: "How many would you like to order?"
    CHECK: quantity <= stock_quantity
    ON_FAIL: collect_quantity
    THEN: confirm

  confirm:
    REASONING: false
    RESPOND: "You'd like to order {{quantity}} of {{product_id}}. Confirm?"
    ACTIONS:
      - id: "yes"
        type: button
        label: "Confirm"
      - id: "no"
        type: button
        label: "Cancel"
    ON_ACTION:
      - ACTION: "yes"
        THEN: place
      - ACTION: "no"
        RESPOND: "Order cancelled."
        THEN: done

  place:
    REASONING: false
    CALL: place_order
      WITH:
        product_id: product_id
        quantity: quantity
      AS: orderResult
    ON_SUCCESS:
      RESPOND: "Order placed! Order ID: {{orderResult.order_id}}, Total: {{orderResult.total}}"
      THEN: done
    ON_FAIL:
      RESPOND: "Failed to place order. Please try again later."
      THEN: done

  done:
    REASONING: false
    RESPOND: "Thank you for using our service!"

Related articles:

Language overview — syntax rules and auto-detection
Tools — tool definitions used by CALL actions
GATHER — top-level gather field definitions
Agent declaration — GOAL used by REASONING: true steps, max_flow_iterations and model settings

​Flow structure

​Basic syntax

​Entry point

​Step list

​Step definitions

​Per-step REASONING toggle

​Reasoning step properties

​Entry guards

​Attempt limiting

​Step actions

​SAY / RESPOND

​MODEL_CONTEXT on a response

​PRESENT

​GATHER in flow steps

​Map form (alternate syntax)

​Multi-field collection

​Flow gather field properties

​Field-level listening settings (ASR:)

Session-value vocabulary (vocabulary.terms binding)

Personal data in bound words (restore_pii)

​Field-level keypad settings (DTMF:)

​GATHER block properties

​CORRECTIONS

​COMPLETE_WHEN

​CALL…WITH…AS

​WITH parameters

​Localized WITH arguments

​SET

​CHECK

​CLEAR

​TRANSFORM

​LOG

​AWAIT_ATTACHMENT

​SECURE_INPUT

​Field properties

​MESSAGE_KEY and BEHAVIOR

​RESOLVE_SIP_DESTINATION

​Branching and control flow

​THEN / ON_FAIL

​ON_RESULT

​ON_RESULT branch properties

​ON_SUCCESS / ON_FAIL

​ON_INPUT

​Digressions

​Digression properties

​Global digressions

​Sub-intents

​Sub-intent properties

​Interactive actions

​Action elements

​Element types

​Buttons

​Select (dropdown)

​Input fields

​Action element properties

​Form submission

​ON_ACTION callbacks

​ON_ACTION handler properties

​Rich content

​Rich content format properties

​Voice configuration

​Per-turn endpointing

​Scoped barge-in

​Scoped streaming

​Step-level no-input (caller silence)

​Gateway turn detection

​Step-level error handling

​Step ON_ERROR handler properties

​Complete example

Flow structure

Basic syntax

Entry point

Step list

Step definitions

Per-step REASONING toggle

Reasoning step properties

Entry guards

Attempt limiting

Step actions

SAY / RESPOND

MODEL_CONTEXT on a response

PRESENT

GATHER in flow steps

Map form (alternate syntax)

Multi-field collection

Flow gather field properties

Field-level listening settings (`ASR:`)

Session-value vocabulary (`vocabulary.terms` binding)

Personal data in bound words (`restore_pii`)

Field-level keypad settings (`DTMF:`)

GATHER block properties

CORRECTIONS

COMPLETE_WHEN

CALL…WITH…AS

WITH parameters

Localized WITH arguments

SET

CHECK

CLEAR

TRANSFORM

LOG

AWAIT_ATTACHMENT

SECURE_INPUT

Field properties

MESSAGE_KEY and BEHAVIOR

RESOLVE_SIP_DESTINATION

Branching and control flow

THEN / ON_FAIL

ON_RESULT

ON_RESULT branch properties

ON_SUCCESS / ON_FAIL

ON_INPUT

Digressions

Digression properties

Global digressions

Sub-intents

Sub-intent properties

Interactive actions

Action elements

Element types

Buttons

Select (dropdown)

Input fields

Action element properties

Form submission

ON_ACTION callbacks

ON_ACTION handler properties

Rich content

Rich content format properties

Voice configuration

Per-turn endpointing

Scoped barge-in

Scoped streaming

Step-level no-input (caller silence)

Gateway turn detection

Step-level error handling

Step ON_ERROR handler properties

Complete example