Behavior profiles - Kore.ai Docs

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:

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.

{
  "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 == voice",
      "used_by": ["Support_Agent"]
    }
  }
}

Grammar

BEHAVIOR_PROFILE: voice_vip
PRIORITY: 100
WHEN: channel == "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. Higher priority wins when profiles conflict.
`WHEN:`	yes	CEL expression evaluated against context (`WHEN: true` for a default profile).

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

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

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

CONVERSATION

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

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.
`relaxed_interval_ms`	`number`	Extended interval between retries.
`max_retries`	`number`	Maximum no-input retries.
`on_exhausted`	`"hangup"` , `"transfer"` , `"custom"`	Action when retries run out.
`exhausted_message`	`string`	Message when retries are exhausted.
`order`	`"sequence"` , `"random"`	Prompt play order.
`play_style`	`"looped"` , `"once"` , `"non_looped"`	Whether prompts repeat.
`messages`	`object[]`	Static re-prompt texts.
`generation`	`object`	Dynamic prompt generation (`mode: dynamic`): `enabled`, `model_source`, `model_id`, `prompt_ref`, `max_output_tokens`.

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

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

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

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`	—	Master switch. Defaults to on (platform default) 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.

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

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. A project-level default can be overlaid beneath this per-agent block.

GATHER

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

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.

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

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

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.

Compile and import behavior

During import preview, the platform:

Reads project.json and abl.lock.
Categorizes behavior_profiles/<name>.behavior_profile.abl as part of the core layer.
Parses the profile with the canonical ABL parser.
Compiles profiles before agents.
Resolves every USE BEHAVIOR_PROFILE reference against compiled profile names.
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.

​File contract

​Grammar

​Profile blocks

​CONSTRAINTS

​RESPONSE

​VOICE

​TOOLS

​CONVERSATION

​Voice turn-taking

​GATHER

​FLOW

​Agent attachment

​Compile and import behavior

File contract

Grammar

Profile blocks

CONSTRAINTS

RESPONSE

VOICE

TOOLS

CONVERSATION

Voice turn-taking

GATHER

FLOW

Agent attachment

Compile and import behavior