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

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

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

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

​Concept

​Minimal working example

​Standalone profile example

​How it works

​Common variations

​Recovery mode

​Channel mode

​Enterprise customer mode

​Verification

​Production readiness checklist

​Common mistakes

​Troubleshooting

​Related articles