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

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

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"

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

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

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

​WHEN evaluation context and timing

​Reference resolution at runtime reevaluation

​Worked example

​Profile blocks

​CONSTRAINTS

​RESPONSE

​VOICE

​TOOLS

​CONVERSATION

​Voice turn-taking

​GATHER

​FLOW

​Agent attachment

​Compile and import behavior

File contract

Grammar

WHEN evaluation context and timing

Reference resolution at runtime reevaluation

Worked example

Profile blocks

CONSTRAINTS

RESPONSE

VOICE

TOOLS

CONVERSATION

Voice turn-taking

GATHER

FLOW

Agent attachment

Compile and import behavior