> ## Documentation Index
> Fetch the complete documentation index at: https://koreai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Behavior profiles

Behavior profiles are standalone ABL documents. Agents attach them with `USE BEHAVIOR_PROFILE: <name>`, and the compiler attaches the matching profile IR to that agent.

## File contract

Behavior profile files belong in `behavior_profiles/` and should use the `.behavior_profile.abl` suffix:

```text theme={null}
behavior_profiles/voice_vip.behavior_profile.abl
```

The manifest records them under `behavior_profiles`, while `layers_included` still uses `core`. Do'nt add `behavior_profiles` to `layers_included`.

The manifest entry is a pointer, not the profile definition. Import preview compiles the actual file at `behavior_profiles.<name>.path`. A package that only lists a profile in `project.json` but omits the referenced `.abl` file doesn't create the profile; agents with `USE BEHAVIOR_PROFILE: <name>` will fail resolution with a missing profile diagnosis.

```json theme={null}
{
  "format_version": "2.0",
  "layers_included": ["core"],
  "behavior_profiles": {
    "voice_vip": {
      "name": "voice_vip",
      "path": "behavior_profiles/voice_vip.behavior_profile.abl",
      "priority": 100,
      "when_summary": "channel.name == voice",
      "used_by": ["Support_Agent"]
    }
  }
}
```

## Grammar

```yaml expandable=true theme={null}
BEHAVIOR_PROFILE: voice_vip
PRIORITY: 100
WHEN: channel.name == "voice"

INSTRUCTIONS: |
  Speak concisely and confirm one thing at a time.

CONVERSATION:
  speaking:
    tone: warm
    max_sentences: 2

VOICE:
  instructions: "Use a calm voice with clear pauses."

TOOLS:
  HIDE: [internal_debug_tool]

GATHER:
  FIELD_OVERRIDES:
    account_id:
      prompt: "Please say or enter your account number."
```

Required declarations:

| Declaration | Required | Notes |
| - | - | - |
| `BEHAVIOR_PROFILE:` | yes | Case-sensitive profile name |
| `PRIORITY:` | yes | Non-negative integer. Within a scope, profiles apply in ascending priority, so a higher priority wins when profiles conflict. See [Resolution order](#resolution-order). |
| `WHEN:` | yes | CEL expression evaluated against context (`WHEN: true` for a default profile). |
| `APPLIES_TO:` | no | `all_agents` attaches the profile to every agent in the project. See [Attach a profile to every agent](#attach-a-profile-to-every-agent). |

## WHEN evaluation context and timing

Session creation and pre-session policy checks evaluate metadata only: `channel`, `caller`, `session`, `interaction`, and `env`.

At runtime, the platform reevaluates profiles at each reasoning turn, agent activation, parent restoration, and cold session restoration boundary. These later evaluations also read the active session's accepted expression values.

A declared memory `INITIAL` value can select a profile at the first runtime reevaluation. It does not select a business-state-dependent profile during the metadata-only creation check.

A `SET`, GATHER answer, or tool result becomes visible when the next existing evaluation boundary runs. It does not trigger an immediate profile reevaluation by itself.

`session.is_new` belongs to the creation check, while `session.turn_count` retains its reasoning-invocation count.

The runtime expression values include:

* Declared session memory
* Accepted GATHER fields
* Values saved by authored tool-result mappings
* The stamped current `input`
* The structured `intent` object, when present

### Reference resolution at runtime reevaluation

| Reference | Meaning at runtime reevaluation |
| - | - |
| `customer_tier` or `context.customer_tier` | The same accepted session value |
| `channel.name`, `caller.identity_tier`, `interaction.sentiment_label` | Profile metadata; session values cannot replace these namespaces |
| `session.customer_tier`, `env.business_region` | Accepted fields already stored inside the corresponding session/env object |
| `session.is_new`, `session.language`, `session.turn_count` | Profile metadata wins over colliding stored fields |
| `env.deployment_region`, `env.timestamp` | Profile metadata wins over colliding stored fields |
| `context.channel`, `context.caller`, `context.interaction`, `context.session`, `context.env` | The expression namespace's original values, before profile metadata is overlaid |
| `context.session_id`, `context.project_id`, `context.tenant_id`, `context.user_id` | Existing stored identifier values, with runtime fallback when absent |
| `input`, `intent.category` | The stamped accepted input and existing structured intent, when present |

Every ordinary accepted expression value is available directly and through `context`. For example, `customer_tier` and `context.customer_tier` resolve to the same value, as do `input` and `context.input`.

Top-level `channel`, `caller`, and `interaction` retain profile metadata. Use `context.channel`, `context.caller`, and `context.interaction` for colliding business values.

> [!WARNING]
>
> Match the channel with `channel.name`. A `context.channel` condition doesn't match the channel, and the profile then does nothing. List every voice transport you use, for example `WHEN: channel.name in ["voice", "voice_realtime", "voice_pipeline", "korevg"]`. Check the name on a real session. Studio's test chat is `web_debug`, so test a profile on its own channel.

Nested keys, including a business object's own `context` property, remain ordinary accepted state.

Identifier references `session_id`, `project_id`, `tenant_id`, and `user_id` follow the existing expression projection: an accepted stored value wins, and the corresponding runtime identifier supplies a fallback when that value is absent. Adding an alias does not grant access to another session, project, or agent's private state.

Conditions read session-visible config/env values. Secret values held exclusively for tool execution remain unavailable to conditions and their `context` aliases.

Tokenized PII comparisons use the active session's comparator.

The evaluation map is not persisted or published as profile trace data, model instructions, or responses.

Missing references and invalid conditions skip the affected profile. They do not crash the session or become implicit string literals.

These expression values are comparison data, not authorization grants or proof of tenant/project ownership. Conditions use the accepted values; they do not classify text, synthesize intent, or fall back to older conversation history when `input` is absent.

### Worked example

After an authored GATHER or tool mapping saves `customer_tier` as `"gold"`, `WHEN: context.customer_tier == "gold"` matches at the next runtime reevaluation. When the accepted value is `"standard"`, the profile does not match. A channel predicate such as `WHEN: channel.name == "voice"` continues to read channel metadata even if a business field is named `channel`.

```yaml theme={null}
BEHAVIOR_PROFILE: voice-optimized
PRIORITY: 10
WHEN: channel.name == "voice"
INSTRUCTIONS: "Keep responses under 3 sentences. Use natural speech patterns."
```

```yaml theme={null}
BEHAVIOR_PROFILE: sdk-rich
PRIORITY: 5
WHEN: channel.name == "sdk_websocket" OR channel.name == "web_chat"
```

> [!NOTE]
>
> After a profile matches, its instruction overlay applies to the main reasoning prompt and reasoning
> inside a FLOW step. The step keeps its own goal and constraints. This instruction projection does
> not introduce another profile evaluation boundary.

## Profile blocks

Beyond the required declarations, a profile can override several aspects of agent behavior. All
blocks are optional.

### CONSTRAINTS

Adds business-rule constraints while the profile is active (a list of strings).

```yaml theme={null}
CONSTRAINTS:
  - "Never reveal internal tool names."
  - "Always confirm amounts above $500."
```

### RESPONSE

Shapes response rendering.

| Sub-key | Type | Description |
| - | - | - |
| `max_buttons` | `number` | Maximum interactive buttons to render. |
| `fallback_format` | `string` | Format to fall back to (for example. `text`). |
| `media_types` | `string[]` | Allowed media types. |
| `max_response_length` | `number` | Maximum response length. |

### VOICE

Voice (TTS) overrides while the profile is active. Accepts the full
[voice configuration](https://koreai.mintlify.site/agent-platform/abl/reference/rich-content.md#voice-configuration)
— `instructions`, `ssml`, `plain_text`, `provider`, `voice_id`, `speed`, `pace`, `temperature`, and
`auto_tts_language_switch`.

### TOOLS

`HIDE:` removes tools from the agent's tool set; `ADD:` injects new tool definitions while the
profile is active.

```yaml theme={null}
TOOLS:
  HIDE: [internal_debug_tool]
  ADD:
    priority_callback(reason: string) -> {ticket_id: string}
      description: "Open a VIP priority callback ticket"
      PARAMETERS:
        - reason: string
```

### CONVERSATION

> [!NOTE]
>
> `CONVERSATION:` is also a valid **top-level agent section** — an agent can declare it directly
> (`doc.conversation`) with the exact same grammar shown here. Use the profile form to apply
> conversation overrides conditionally (via the profile's `WHEN`), or the top-level form to set an
> agent's baseline conversation behavior.

Conversation-style overrides, organized into three sub-sections:

* **`speaking`** — output style: `style`, `tone`, `emotion`, `pace`, `variety`, `max_sentences`, `one_thing_at_a_time`, `language_policy` (`interaction_context` / `agent_default` / `fixed`), `fixed_language`, `tool_lead_in`, `tool_results`, `readback`, `handoffs`, `phrases_ref`, `pronunciations_ref`.
* **`listening`** — input handling: `barge_in`, `backchannels`, `on_pause`, `on_overlap`, `on_unclear_audio`, `on_self_correction`, `use_audio_cues`, and the voice sub-blocks `on_no_input`, `on_caller_backchannel`, `on_hold`, and `barge_in_continuation` (see [Voice turn-taking](#voice-turn-taking)).
* **`interaction`** — dialogue behavior: `answer_shape`, `detail`, `initiative`, `grounding`, `clarification`, `confirmation`, `uncertainty`, `empathy`, `repair`, `context`, `closure`, `assumption_handling`, `flow_mode`, and more.

```yaml theme={null}
CONVERSATION:
  speaking:
    tone: warm
    max_sentences: 2
    one_thing_at_a_time: true
  listening:
    barge_in: allow
  interaction:
    clarification:
      max_questions: 1
```

#### Listening mode

On KoreVG pipeline voice, the **listening mode** is fixed for the whole call. **Barge-in** and **streaming** are decided for each spoken output, inside that mode. An agent or channel that authors none of these keys behaves as before.

| Setting | Values | Resolved |
| - | - | - |
| Listening mode | `background`, `turn_taking` | Once, at call start |
| Barge-in | `allow`, `disallow` | Per output |
| Streaming | `true`, `false` | Per output |

* **`background`.** A sticky background gather listens during and after speech.
* **`turn_taking`.** Each agent turn is its own foreground gather that listens for the caller's answer.
* **Resolution, most specific first.** The channel's explicit `listeningMode`. The entry agent's `CONVERSATION.listening.mode`, layered across behavior profiles and the agent. The derived mode: `background` when the entry agent's `listening.barge_in` (otherwise `on_overlap`) allows interruption, or, when the agent sets neither, when the channel's barge-in checkbox is on. Otherwise `turn_taking`.
* **Fixed for the call.** A handoff, a FLOW step, a reply or a tool cannot change the mode. A later agent's `listening.mode` is ignored.
* **No per-turn key.** `LISTENING` in any `VOICE` block is the compile error [`VOICE_LISTENING_CALL_LEVEL_ONLY`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#voice_listening_call_level_only).
* **Default barge-in.** It comes from `listening.barge_in`, otherwise `listening.on_overlap`. The `on_overlap` values `stop_and_listen`, `listen`, `yield` and `yield_to_user` allow. The values `ignore_overlap`, `continue` and `talk_over` disallow.

```yaml theme={null}
CONVERSATION:
  listening:
    mode: turn_taking
    barge_in: allow
```

Two warnings apply to the mode. [`CONVERSATION_BACKGROUND_DISALLOW_DEFAULT`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#conversation_background_disallow_default) flags `background` with a default of `disallow`. [`CONVERSATION_BACKGROUND_ONLY_WITH_TURN_TAKING`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#conversation_background_only_with_turn_taking) flags caller back-channel phrases or `barge_in_continuation` with `turn_taking`. A behavior profile that sets `listening.mode` gets the same two warnings.

An agent that sets `listening.mode` is published with the IR marker `voice_listening_mode`. A runtime without the marker refuses the agent. Per-output placements are described in [Scoped barge-in](https://koreai.mintlify.site/agent-platform/abl/reference/flow.md#scoped-barge-in), [Voice delivery for a field](https://koreai.mintlify.site/agent-platform/abl/reference/flow.md#voice-delivery-for-a-field) and [Voice reply policy](https://koreai.mintlify.site/agent-platform/abl/reference/tools.md#voice-reply-policy).

#### Voice turn-taking

For voice/telephony channels, four `listening` sub-blocks control turn-taking behavior:

**`on_no_input`** — handle caller silence.

| Field | Type | Description |
| - | - | - |
| `enabled` | `boolean` | Toggle no-input handling. |
| `mode` | `"static"` , `"dynamic"` | Static prompts vs. LLM-generated re-prompts. |
| `timeout_ms` | `number` | Silence duration before triggering. Whole milliseconds, 1 to 60000. |
| `relaxed_interval_ms` | `number` | Extended interval between retries. Whole milliseconds, 1 to 120000. |
| `max_retries` | `number` | Maximum no-input prompts before exhaustion. Integer from 0 to 20. Default `3`. |
| `on_exhausted` | `"hangup"` , `"transfer"` , `"custom"` , `"hook"` | Action when retries run out. `hook` runs the agent's `on_no_input_exhausted` hook. See [on\_no\_input\_exhausted](https://koreai.mintlify.site/agent-platform/abl/reference/lifecycle-and-hooks.md#on_no_input_exhausted). A behavior profile takes action words only. |
| `exhausted_message` | `string` | Message when retries are exhausted. |
| `exhausted_ssml` | `string` or locale map | SSML version of the final message. See the SSML notes below. |
| `barge_in` | `"allow"` , `"disallow"` | Whether a reprompt or the exhausted message can be interrupted. Inherits the owning step, then the turn default. |
| `streaming` | `boolean` | Whether a reprompt or the exhausted message is streamed. Inherits the owning step, then the turn default. |
| `order` | `"sequence"` , `"random"` | Prompt play order. |
| `play_style` | `"looped"` , `"once"` , `"non_looped"` | Whether prompts repeat. |
| `messages` | `object[]` | Static re-prompt texts. Each message has `text` and can also have `ssml`. The compiler requires at least one message when the block declares `enabled: true` and `mode: static`. |
| `generation` | `object` | Dynamic prompt generation (`mode: dynamic`): `enabled`, `model_source`, `model_id`, `prompt_ref`, `max_output_tokens` (whole number, 1 to 512). |

A no-input message can author `ssml` as a string or a locale-to-string map, next to `text`:

```yaml theme={null}
messages:
  - text: "Are you still there?"
    ssml: '<speak><prosody rate="slow">Are you still there?</prosody></speak>'
```

* The compiler requires a well-formed XML `<speak>` document. It rejects document declarations, processing instructions, and nested speech documents.
* The speech provider checks voice and style availability.
* Values substituted into the markup are XML-escaped after output protection.
* When `text` is absent, the runtime derives readable text from the rendered SSML for transcripts and for vendors without SSML delivery.
* Azure pipeline voice plays the markup through buffered speech. Other vendors and realtime voice use the plain text.
* `exhausted_message` stays plain text. It is the transcript and vendor fallback for the final message.
* `exhausted_ssml` is an optional SSML version of the final message. It takes a string or a locale-to-string map. It follows the same XML checks, escaping, and Azure buffered playback as retry SSML. When `exhausted_message` is absent, the runtime derives readable text from the rendered SSML. Markup that is invalid or cannot render falls back to the plain message, then to the built-in final message.
* After the final message, the runtime runs the configured `on_exhausted` action. A hang-up opens no new listener. A route action goes on to the flow step or agent, with no built-in farewell unless you wrote one.

Silence and keypad input interact as follows:

* Recognized speech or speech barge-in resets the retry sequence. Accepted non-empty DTMF input also resets it. An ASR partial only restarts the silence window. It keeps the retry count until an answer is accepted, so partials that never commit (noise, abandoned speech) still exhaust the retries.
* Caller input that the runtime accepted but has not yet run is not silence. The same holds for input still arriving over a reply the caller has not heard. The silence window waits instead of reprompting or ending the call.
* The first ASR partial reaches the runtime almost a second after the caller starts to speak. When the runtime-owned background window runs out, the runtime waits one more second before it reprompts or runs `on_exhausted`. A partial in that second restarts the window. With real silence, the prompt or exhausted action comes one second after `timeout_ms`. A gateway no-input timeout acts at once.
* Forwarded native voice activity detection (VAD) activity pauses the background silence window without resetting retries or accepting an answer. When the activity stops, the configured window starts again.
* DTMF barge-in stops the silence timer without resetting the retry sequence.
* While the caller keys digits, the background silence window waits. The voice gateway reports each accepted key, and each report restarts the window. The window is the longer of `timeout_ms` and the gateway's pending-entry time plus one second. If the gateway reports no pending-entry time, the normal window applies, so the wait stays bounded. A reported key is caller activity only. It does not reset the retry sequence. That happens when digits are accepted.
* A gather that receives no digits and no speech restarts the timer with the existing retry count. This includes a press of the finish key alone.
* A keypad-only gather, such as a secure card entry, never receives a speech end-of-speech timeout, whatever pause timeout the call has. Speech and mixed gathers keep it.
* The final line the caller hears before a hang-up is recorded in the Conversation as an assistant turn, like every reprompt. This covers the `exhausted_message`, the fallback line when a `transfer` has no target, and the closing line of a flow target that could not run. If the voice gateway does not confirm that the line finished, the row is marked as playback unconfirmed. If only part of a long line played, it is also marked partial. A line the gateway never received is not recorded.

Realtime voice for Gemini, Nova, and OpenAI uses the same effective configuration for static prompts. Dynamic no-input generation is available on pipeline voice only. Provider activity, transfer, and channel-capability gates still apply. OpenAI also honors the channel's `realtimeNoInputEnabled: false` setting. A resolved configuration with an invalid value, such as a retry count outside 0 to 20, disables no-input handling for the session. Pipeline voice emits `voice_no_input_config_dropped`. Realtime voice reports a `status_update` with `operation: no_input` and `source: invalid`, or `source: dynamic_unsupported` when it rejects dynamic mode.

**`dtmf`**: set the default grouping of keypad digits for every KoreVG pipeline voice turn of the agent or profile. It takes the same keys as a FLOW field `DTMF:` block.

| Key | Values | Description |
| - | - | - |
| `digits` | `min..max`, 1 to 32 | Number of digits in one answer. |
| `finishOnKey` | `"#"`, `"*"`, `"none"` | Key that ends the entry. |
| `interDigitTimeoutMs` | 500 to 30000 | Pause between key presses that ends the entry. |
| `finishKeyAlone` | `"no_input"`, `"input"` | What a finish key pressed alone does. Use `value` only on a FLOW field. See [Finish key pressed alone](https://koreai.mintlify.site/agent-platform/abl/reference/flow.md#finish-key-pressed-alone-finishkeyalone). |

```yaml theme={null}
CONVERSATION:
  listening:
    barge_in: allow
    dtmf:
      digits: 1..12
      finishOnKey: "#"
      interDigitTimeoutMs: 5000
```

* Each key resolves on its own, in this order: `SECURE_INPUT` `COLLECT`, field `DTMF:`, active behavior profile, agent, project, platform default. The platform default is 2 seconds between key presses, `#` as the finish key, and 1 to 12 digits. `digits` counts as one unit.
* A project sets the same defaults in Studio (**Settings > Runtime Config > Listening**) or as Runtime Config `voiceListening.dtmf` (`minDigits`, `maxDigits`, `finishOnKey`, `interDigitTimeoutMs`, `finishKeyAlone`). Set `minDigits` and `maxDigits` together. `voiceListening: null` clears the setting.
* A minimum above 1 produces a warning at agent, profile, and project level. It applies to every keypad answer, including one-key menu choices. A pause does not end an entry shorter than the minimum, so the short entry is lost after the no-input timeout. Keep the minimum at 1 here and set a longer one on the fields that need it.
* `finishOnKey: "*"` produces a warning at these levels, because `*` then ends every keypad answer, menus included.
* A profile that turns on or off, a handoff, a return, or a language switch applies from the next caller turn. A profile that changes keypad settings on every turn restarts the listener every turn, so keep profile settings stable.
* An agent that uses these keys is published with the IR marker `voice_listening`. A runtime without the marker refuses to publish, deploy, or run the agent, so upgrade every runtime first. Speech settings above field level (`listening.asr`) add the marker `voice_listening_asr`. A Studio import into a project whose runtime does not report this marker drops the speech block and reports [`LISTENING_KEY_NEEDS_NEWER_RUNTIME`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#listening_key_needs_newer_runtime).

**`on_caller_backchannel`** — recognize caller acknowledgements ("uh-huh", "okay") without treating them as a turn: `enabled`, `phrases`, `max_words`.

The KoreVG gateway can also decide that caller speech over a playing prompt is a back-channel, using its barge-in model or its phrase list. The runtime accepts that decision without checking the words against your phrases, and also when you wrote no phrases. The prompt keeps playing, the words get no reply, and the transcript saves them as a hidden caller message. This holds in every listening mode, including `turn_taking`, where only your phrases are inactive. The runtime treats the words as a normal turn in two cases: the agent's audio stopped more than 1.5 seconds before they arrived, or a voice tool is waiting for the caller's answer.

> [!WARNING]
>
> `max_duration_ms` on `on_caller_backchannel` is accepted but has **no effect** — the voice gateway cannot enforce a back-channel duration cap, so back-channels are matched on the phrase list alone. Authoring it now emits a compile warning ([`CONVERSATION_BACKCHANNEL_DURATION_CAP_IGNORED`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#conversation_backchannel_duration_cap_ignored)); remove it.

**`on_hold`** — handle caller hold requests ("hold on a sec"): `enabled`, `phrases`, `phrases_by_locale`, `grace_ms`, `max_holds`, `suppress_response`. `phrases_by_locale` is a `{ <BCP-47 tag>: string[] }` map of additional hold phrases selected by the caller's detected locale; its phrases are unioned with the language-neutral `phrases` list rather than replacing them. Locale keys are canonicalized at parse time (`en_us` → `en-US`).

```yaml expandable=true theme={null}
CONVERSATION:
  listening:
    on_no_input:
      enabled: true
      mode: static
      timeout_ms: 5000
      max_retries: 2
      on_exhausted: transfer
      messages:
        - text: "Are you still there?"
    on_caller_backchannel:
      enabled: true
      phrases: ["uh-huh", "okay", "go on"]
    on_hold:
      enabled: true
      phrases: ["hold on", "give me a sec"]
      phrases_by_locale:
        es-MX: ["un momento", "espérame un segundo"]
        fr-CA: ["un instant", "attends une seconde"]
      grace_ms: 15000
```

> [!NOTE]
>
> `phrases_by_locale` is currently authored only in the `.agent.yaml` format (`CONVERSATION.listening.on_hold.phrases_by_locale`); the legacy `.agent.abl` parser does not yet accept this key.

**`barge_in_continuation`** — when a caller barges in over the bot and the speech recognizer segments their continuous speech into multiple phrase-finals (for example "change to 2 years" then, without a real pause, "recalculate the EMI"), hold each eligible final briefly and merge a following one into a single turn instead of committing each phrase as its own turn.

| Field | Type | Range | Description |
| - | - | - | - |
| `enabled` | Boolean | — | Main switch. Defaults to `on` when the block is omitted entirely. |
| `window_ms` | Number | 300–2000 | Silence window held after a final before committing it, waiting for a possible continuation. |
| `max_hold_ms` | Number | 500–8000 | Absolute ceiling on how long one turn may be held, regardless of how many finals merge into it. |
| `max_merges` | Number | 1–20 | Maximum number of finals folded into one committed turn. |
| `max_chars` | Number | 1–20000 | Maximum merged-transcript length before forcing a commit. |

```yaml theme={null}
CONVERSATION:
  listening:
    barge_in: allow
    barge_in_continuation:
      enabled: true
      window_ms: 700
      max_hold_ms: 4000
      max_merges: 4
      max_chars: 2000
```

> [!NOTE]
>
> `barge_in_continuation` refines what happens to an *already-allowed* interruption's speech segmentation — it's a sibling of, not a replacement for, the scalar `barge_in: allow`/`disallow` policy above, and distinct from the per-output scoped `BARGE_IN` covered in [Scoped barge-in](https://koreai.mintlify.site/agent-platform/abl/reference/flow.md#scoped-barge-in). A project-level default can be overlaid beneath this per-agent block.

### Project defaults for silence and speech recognition

Two project settings apply to KoreVG voice calls when the agent sets nothing.

**When silence retries run out (`voiceNoInput`).** Set `onExhausted` in the project Runtime Config API, or under **When Retries Run Out** in Studio. It applies to every agent and step that leaves `on_exhausted` unset.

| `onExhausted` | Target field | What the silent caller gets |
| - | - | - |
| `hangup` | None | The final message, then the call ends. This is the default. |
| `transfer` | `transferTarget`: `sip` or `pstn` | The `exhaustedMessage`, then a transfer to that Agent Transfer target. |
| `handoff` | `handoffTarget`: an agent name | The `exhaustedMessage`, then a handoff to that agent, with no caller message. |

```yaml theme={null}
voiceNoInput:
  enabled: true
  maxRetries: 2
  exhaustedMessage: "Let me get you some help."
  onExhausted: handoff
  handoffTarget: Recovery_Desk
```

* An `on_exhausted` on the agent, a behavior profile, or the step replaces the project choice, target included.
* A handoff grants no route. The current agent must already declare a `HANDOFF` or routing rule to the target. Without one, the call plays the final message and ends.
* A transfer uses Agent Transfer. If the target is gone when the call runs, or the transfer fails, the call plays the final message and ends.
* The action and its target save together. Saving is refused with a `400` for a `transfer` with no `transferTarget`, a `handoff` with no `handoffTarget`, a target that does not match the action, or a `handoffTarget` that is not an agent of the project. Choosing `hangup` removes the stored target.
* It runs once per silence. A repeated report of the same silence runs it once, and a call that already tried to transfer does not transfer again.
* Pipeline voice only. On realtime voice and Twilio it acts as `custom`.

**STT minimum confidence (`sttMinConfidence`).** Set it on the channel connection, or in project runtime config as `voice.sttMinConfidence`. It takes a value from 0 to 1. Pipeline voice discards a recognition scored below it, so the agent never receives it. The channel value wins over the project value, and `0` at channel level turns the check off. The runtime also passes the value to the KoreVG recognizer.

### GATHER

Overrides gather behavior. Top-level keys `validation_style` and `confirmation`, plus a
`FIELD_OVERRIDES:` block (note the uppercase keyword) that adjusts individual fields.

```yaml theme={null}
GATHER:
  validation_style: lenient
  confirmation: always
  FIELD_OVERRIDES:
    account_id:
      prompt: "Please say or enter your account number."
      required: true
      skip: false
      validation: "len(account_id) == 10"
      extraction_hints: ["Read digits individually on voice"]
```

### FLOW

Overrides the agent's flow while the profile is active.

| Sub-keyword | Shape | Description |
| - | - | - |
| `SKIP` | `string[]` | Step names to skip. |
| `REPLACE` | `string` | Replace the flow with a named flow. |
| `OVERRIDES` | per-step `{ respond?, transition?, VOICE?, RICH_CONTENT? }` | Override specific steps (alias `OVERRIDE`). |
| `INSERTIONS` | list of `- BEFORE: <step>` / `- AFTER: <step>` + step body | Insert steps relative to existing ones. |

```yaml theme={null}
FLOW:
  SKIP: [upsell_step]
  OVERRIDES:
    greeting:
      respond: "Welcome back — I'll keep this quick."
  INSERTIONS:
    - BEFORE: payment
      REASONING: false
      RESPOND: "Confirming your VIP discount first."
```

> [!NOTE]
>
> An **inline** `BEHAVIOR_PROFILE:` declared inside an agent file (rather than as a standalone
> document) supports only `PRIORITY`, `WHEN`, `INSTRUCTIONS`, and `CONVERSATION`. The other blocks
> (`CONSTRAINTS`, `RESPONSE`, `VOICE`, `TOOLS`, `GATHER`, `FLOW`) are available only in standalone
> profile files.

## Agent attachment

```yaml theme={null}
AGENT: Support_Agent
GOAL: "Resolve customer support requests"
USE BEHAVIOR_PROFILE: voice_vip
```

The attached profile name must match the `BEHAVIOR_PROFILE:` header, not just the filename. Both
`USE BEHAVIOR_PROFILE:` (space) and `USE_BEHAVIOR_PROFILE:` (underscore) forms are accepted.

### Attach a profile to every agent

Add `APPLIES_TO: all_agents` to a standalone profile to attach it to every agent and supervisor in the project, including agents you add later. The result is the same as a `USE BEHAVIOR_PROFILE:` line in each agent, placed after the agent's own references. An agent that already references the profile attaches it once. No agent file changes.

```yaml theme={null}
BEHAVIOR_PROFILE: brand_voice
PRIORITY: 10
APPLIES_TO: all_agents
WHEN: true

INSTRUCTIONS: |
  Keep a friendly, professional tone.
```

* `all_agents` is the only supported value. Any other value is the error [`PROFILE_INVALID_APPLIES_TO`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#profile_invalid_applies_to).
* Without the line, a profile applies only to the agents that reference it.
* `WHEN` and `PRIORITY` keep their meaning. The attach-time checks run for each agent, as for a hand-written reference. Two attached profiles with the same priority report `PROFILE_PRIORITY_CONFLICT`. A profile that hides a tool the agent does not declare reports `PROFILE_UNKNOWN_TOOL`. A `FLOW` `SKIP` entry that names a step the agent does not declare reports `PROFILE_UNKNOWN_STEP` for that agent.
* Write the line at the top level of the profile, for example directly under the `BEHAVIOR_PROFILE:` header. Studio writes it there. Inside a multi-line block, the line is part of the block text.
* Inline profiles do not read `APPLIES_TO`. An inline profile belongs to the agent that declares it.
* The profile document must be in the compile set. A build path that does not load profile documents does not attach the profile.

## Where profiles apply

A profile attached at agent level applies to every model call the agent makes. That includes each turn of a reasoning agent and each `REASONING: true` step of a FLOW agent.

In a FLOW reasoning step, the matched profiles' `INSTRUCTIONS`, `CONSTRAINTS`, `VOICE` instructions (voice channels), and `CONVERSATION` (when a matched profile sets it) are added to the step prompt. They come before the step's own `GOAL`, `BEHAVIOR`, and `STEP_CONSTRAINTS`, which take precedence for that step. A FLOW agent with no matching profile gets no profile text in its steps. Literal `RESPOND` text in a `REASONING: false` step is sent as written.

### Resolution order

At runtime the platform collects the profiles whose `WHEN` is true within each scope. Within a scope it applies profiles in ascending `PRIORITY`. When priorities are equal, the later declaration wins for a single-valued field. The effective view layers four sources, from least to most specific:

1. The agent settings.
2. The matched agent-level profiles.
3. The matched step-level profiles.
4. The current step's inline keys.

The most specific value wins for each single-valued field. Constraints add up. A narrower scope cannot remove a constraint from a wider scope.

### Step attachment in a text FLOW

A text FLOW step can attach one or more profiles. Write one name per line. Both keyword spellings and the same profile-name rules apply as for agent-level references.

```yaml theme={null}
AGENT: Support_Agent
GOAL: "Help customers verify their identity"
FLOW:
  entry_point: verify_identity
  steps:
    - verify_identity
  verify_identity:
    REASONING: true
    USE BEHAVIOR_PROFILE: identity_check
    USE_BEHAVIOR_PROFILE: concise_support
    GOAL: "Confirm the customer's identity before continuing."
    THEN: COMPLETE
```

* Step profiles apply after agent profiles and before the step's inline keys.
* Their instructions appear in a labeled `Step-Specific Behavior` section. It comes after the agent profile sections and before the step goal.
* Profile constraints add to agent constraints.
* Tool hides add up. A step profile cannot restore a tool that an agent-level profile hides. The step `AVAILABLE_TOOLS` then narrows the tool list.
* TTS voice settings in a step profile apply to the output of that step. Its `CONVERSATION` listening fields layer after the agent profile fields and below the step's inline `VOICE` settings.
* `CONVERSATION.listening.mode` applies to the whole call. A step profile ignores it and the compiler reports `STEP_PROFILE_CALL_SCOPED_FIELD`.
* `RESPONSE_RULES`, `GATHER_OVERRIDES`, flow modifications, and `FLOW_REPLACE` do not apply at step scope. A step profile that contains one reports `STEP_PROFILE_UNSUPPORTED_FIELD`.
* A step that attaches a profile already attached at agent level changes nothing and reports `STEP_PROFILE_ALREADY_AGENT_LEVEL`.
* Realtime speech-to-speech does not refresh the provider prompt or tools when a FLOW step changes. Refresh happens only at handoff, and it uses the target agent's agent-level view. Step profile text is not included. The runtime still rejects a tool that a step hides.
* Step profile references need their profile documents in the compile set. CI/CD release builds and `compileToResolvedAgent` paths do not load profile documents. On those paths a step reference reports `STEP_PROFILE_NOT_FOUND` and is not applied. A missing step profile during project import is a warning and does not block the import.
* Studio shows `usedBySteps` in profile usage. It blocks rename and delete while a step uses the profile.
* For agents with step profile uses, the `profile_resolution` trace adds `scope`, `stepEvaluatedProfiles`, `stepMatchedProfiles`, `dedupedProfiles`, `toolsHiddenByStep`, and `stepAdditionalConstraints`. Step-scoped events name the step in `stepName`. A call-scoped `listening.mode` that a step profile ignores records the `step_profile_mode_ignored` trace. Agents without step uses keep their earlier trace shape.

The six step-path warnings are [`STEP_PROFILE_NOT_FOUND`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#step_profile_not_found), [`STEP_PROFILE_PRIORITY_CONFLICT`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#step_profile_priority_conflict), [`STEP_PROFILE_UNKNOWN_TOOL`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#step_profile_unknown_tool), [`STEP_PROFILE_UNSUPPORTED_FIELD`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#step_profile_unsupported_field), [`STEP_PROFILE_CALL_SCOPED_FIELD`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#step_profile_call_scoped_field), and [`STEP_PROFILE_ALREADY_AGENT_LEVEL`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#step_profile_already_agent_level).

A step `PERSONA:` line, step profile syntax in a YAML flow step (`persona` or `use_behavior_profile` keys), and step profile syntax in legacy `STEPS:` are still ignored. The compiler reports [`W498`](https://koreai.mintlify.site/agent-platform/abl/reference/errors-and-warnings#w498) for them. For one release, the language service also shows the informational notice `STEP_BEHAVIOR_PROFILE_APPLIED` on text FLOW step profile uses that now take effect.

Use the profile `WHEN` to target channels, callers, or languages.

> [!WARNING]
>
> Profile response rules, `GATHER` overrides, and flow modifications (`FLOW` skip, override, and replace) compile but the runtime does not apply them yet. Do not rely on them to change agent behavior.

## Compile and import behavior

During import preview, the platform:

1. Reads `project.json` and `abl.lock`.
2. Categorizes `behavior_profiles/<name>.behavior_profile.abl` as part of the `core` layer.
3. Parses the profile with the canonical ABL parser.
4. Compiles profiles before agents.
5. Resolves every `USE BEHAVIOR_PROFILE` reference against compiled profile names.
6. Reports missing or malformed profiles as import/compiler issues.

Common fixes:

| Symptom | Fix |
| - | - |
| `Unknown layer "behavior_profiles" in layers_included` | Remove it from `layers_included`; keep `core` and the manifest map. |
| Manifest has `behavior_profiles` but preview adds none | Include the referenced `behavior_profiles/<name>.behavior_profile.abl` file. |
| `Missing BEHAVIOR_PROFILE: header` | Start the profile file with `BEHAVIOR_PROFILE: <name>`. |
| `BEHAVIOR_PROFILE requires a PRIORITY declaration` | Add `PRIORITY: <number>`. |
| `BEHAVIOR_PROFILE requires a WHEN declaration` | Add `WHEN: <condition>`, or `WHEN: true` for a default profile. |
| Agent references a missing `profile_use` target | Add the standalone profile file or remove the `USE` reference. |
| `W498` on a step `PERSONA:` line, or on step profile syntax in a YAML flow step or legacy `STEPS:` | Remove the line. Attach the profile in a text FLOW step with `USE BEHAVIOR_PROFILE:`, or attach it at agent level and target it with `WHEN`. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.