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

# How to use behavior profiles to change agent behavior by context

Use behavior profiles when the same agent should keep its core responsibility but change style, constraints, tools, gathering behavior, or channel handling for a specific context.

## Concept

A behavior profile is conditional behavior layered onto an agent. It has a name, a `PRIORITY`, a `WHEN` condition, and one or more behavior changes such as `INSTRUCTIONS`, `CONVERSATION`, `RESPONSE`, `VOICE`, `TOOLS`, `GATHER`, or `FLOW`.

Use behavior profiles for context-sensitive adaptation, not for changing the agent's core job. If the responsibility changes, create another agent. If only the delivery mode or handling style changes, use a behavior profile.

The compiler attaches profiles to the agent IR and execution contract. When profiles contain guidance, that guidance is represented as behavior-profile instructions for execution. Profiles can be inline in an agent or standalone and attached with `USE BEHAVIOR_PROFILE`.

## Minimal working example

```yaml theme={null}
AGENT: Support_Assistant
GOAL: "Resolve support questions with behavior matched to customer context"
PERSONA: "Helpful support assistant"

BEHAVIOR_PROFILE: recovery_mode
PRIORITY: 10
WHEN: sentiment == "frustrated" OR repeat_contact == true
INSTRUCTIONS: |
  Acknowledge the customer's prior effort before asking for more information.
  Keep the next step concrete and do not list more than two actions.

BEHAVIOR_PROFILE: concise_mode
PRIORITY: 3
WHEN: channel == "sms"
INSTRUCTIONS: "Use short plain-text responses suitable for SMS."
```

## Standalone profile example

```yaml theme={null}
BEHAVIOR_PROFILE: voice_support_mode
PRIORITY: 8
WHEN: channel == "voice"
INSTRUCTIONS: |
  Speak in short sentences and confirm important identifiers one digit group at a time.

VOICE:
  provider: elevenlabs
  speed: 0.95
```

```yaml theme={null}
AGENT: Voice_Support_Assistant
GOAL: "Resolve support questions on voice channels"
PERSONA: "Clear phone support assistant"

USE BEHAVIOR_PROFILE: voice_support_mode
```

## How it works

`PRIORITY` decides which profile should win when multiple profiles match. `WHEN` decides whether a profile applies. Keep conditions based on values your project actually provides, such as channel, sentiment, customer tier, locale, or repeat-contact state.

Inline profiles are useful when the behavior belongs only to one agent. Standalone profiles are useful when several agents share the same channel or customer-context rule.

## Common variations

### Recovery mode

Use a high-priority recovery profile for frustrated users, repeated failures, or repeat contacts.

### Channel mode

Use channel profiles for SMS, voice, WhatsApp, or web when response length, formatting, or speech pacing changes.

### Enterprise customer mode

Use customer-tier profiles when premium or enterprise users require a different tone, faster escalation, or more formal explanations.

## Verification

* Test each `WHEN` condition with a context value that should match and one that should not.
* Confirm higher-priority profiles override lower-priority profiles when both are true.
* Inspect the compiled agent behavior profiles and execution contract for the expected profile count.
* Test channel-specific outputs, especially voice and SMS, in the target channel rather than only in text chat.

## Production readiness checklist

* Every profile has a non-negative integer `PRIORITY`.
* Every profile has a `WHEN` condition.
* Conditions reference context values that are reliably populated.
* Shared standalone profiles are versioned and reviewed because changing one can affect multiple agents.
* Tests cover overlapping profiles, no-match behavior, and channel-specific response constraints.

## Common mistakes

| Mistake                               | Why it happens                                        | How to avoid it                                      |
| ------------------------------------- | ----------------------------------------------------- | ---------------------------------------------------- |
| Using profiles as hidden agents       | The profile starts changing the job, not the behavior | Split into another agent when responsibility changes |
| Missing `PRIORITY` or `WHEN`          | The profile looks like a simple instruction block     | Add both fields to every behavior profile            |
| Referencing unavailable context       | Conditions never match                                | Document where each condition value is set           |
| Overlapping profiles fight each other | Multiple profiles match the same turn                 | Use clear priorities and test overlap                |

## Troubleshooting

| Symptom                              | Likely cause                                         | What to check                                    |
| ------------------------------------ | ---------------------------------------------------- | ------------------------------------------------ |
| Profile never applies                | `WHEN` references an unset value                     | Confirm the context value exists at runtime      |
| Wrong profile wins                   | Priority order is wrong                              | Compare all matching profile priorities          |
| Shared behavior changed unexpectedly | A standalone profile is reused                       | Find all agents using the profile before editing |
| Voice behavior is inconsistent       | Text profile does not define voice-specific settings | Add `VOICE` or channel-specific instructions     |

## Related articles

* [How to write effective agent goals, personas, instructions, and limitations](/agent-platform/abl/howto/write-agent-goals-personas-instructions).
* [How to design channel-specific welcome experiences](/agent-platform/abl/howto/design-channel-specific-welcome).