Behavior profiles

​

File contract

behavior_profiles/voice_vip.behavior_profile.abl

{
  "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

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."

​

WHEN evaluation context and timing

• 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

​

Worked example

BEHAVIOR_PROFILE: voice-optimized
PRIORITY: 10
WHEN: channel.name == "voice"
INSTRUCTIONS: "Keep responses under 3 sentences. Use natural speech patterns."

BEHAVIOR_PROFILE: sdk-rich
PRIORITY: 5
WHEN: channel.name == "sdk_websocket" OR channel.name == "web_chat"

​

Profile blocks

​

CONSTRAINTS

CONSTRAINTS:
  - "Never reveal internal tool names."
  - "Always confirm amounts above $500."

​

RESPONSE

​

VOICE

​

TOOLS

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

​

CONVERSATION

• 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).
• interaction — dialogue behavior: answer_shape, detail, initiative, grounding, clarification, confirmation, uncertainty, empathy, repair, context, closure, assumption_handling, flow_mode, and more.

CONVERSATION:
  speaking:
    tone: warm
    max_sentences: 2
    one_thing_at_a_time: true
  listening:
    barge_in: allow
  interaction:
    clarification:
      max_questions: 1

​

Listening mode

• 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.
• 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.

CONVERSATION:
  listening:
    mode: turn_taking
    barge_in: allow

​

Voice turn-taking

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.

• 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.
• 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.
• 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.

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

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

CONVERSATION:
  listening:
    barge_in: allow
    barge_in_continuation:
      enabled: true
      window_ms: 700
      max_hold_ms: 4000
      max_merges: 4
      max_chars: 2000

​

GATHER

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

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."

​

Agent attachment

AGENT: Support_Agent
GOAL: "Resolve customer support requests"
USE BEHAVIOR_PROFILE: voice_vip

​

Where profiles apply

• A USE BEHAVIOR_PROFILE: or PERSONA: line inside a step, in FLOW: or in legacy STEPS:.
• A persona or use_behavior_profile key on a YAML flow step.

​

Compile and import behavior

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.