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. Sub-keys: instructions, ssml, plain_text (same shape as the agent voice config).

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

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

​GATHER

​FLOW

​Agent attachment

​Compile and import behavior

File contract

Grammar

Profile blocks

CONSTRAINTS

RESPONSE

VOICE

TOOLS

CONVERSATION

GATHER

FLOW

Agent attachment

Compile and import behavior