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

<Badge icon="arrow-left" color="gray">[Back to how-to guides](/agent-platform/abl/how-to/overview#agent-architecture-and-design)</Badge>

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/how-to/write-agent-goals-personas-instructions).
* [How to design channel-specific welcome experiences](/agent-platform/abl/how-to/design-channel-specific-welcome).