# Configuring department-specific AI Personas

_Troubleshooting_

AI Personas let admins create department-specific AI assistants — a Finance persona, an HR persona, an Ops persona — each with its own tone, system-prompt scope, knowledge corpus, tool allowlist, and disabled-feature carve-outs. Users default to one persona but can switch in the AI Bar dropdown. Personas are an OWNER/ADMIN feature; non-admins consume the persona their admin (or team) assigned to them.

## Steps
1. Navigate to Settings → AI Agents (or /dashboard/agent-config). Each row in the agents list is a persona.
2. Click + Create new agent to start a fresh persona, or click an existing one to edit. Open the Persona tab on the editor.
3. Persona type: pick "Internal" for a department persona (Finance/HR/Ops/Sales/Support). Pick "Public web" or "Public voice" only if this row drives the website chat widget or inbound phone calls.
4. Description: write one sentence explaining what this persona is for — shows up in the AI Bar picker. Example: "Finance assistant — invoices, AR, bookkeeping questions".
5. Tone (under the Setup tab): set the persona's personality — "professional but friendly", "warm and empathetic", "formal and corporate", etc. The AI rewrites every response in this voice.
6. Knowledge scope: restrict which KB articles + memory tags + suite slugs this persona can search. Leaving any field blank = "see everything" (the back-compat default).
7. Disabled features: tick AI features the persona refuses to attempt — e.g. an HR persona has no business running lead-scoring on contacts.
8. Save. Assignment is self-service — each user picks their own persona under Settings > AI Usage > My AI Persona. There is no admin per-user or per-team assignment; guide each person to select the persona that matches their role.
9. Users see the new persona in their AI Bar dropdown the next time they open it (60-second cache TTL). The persona's name + tone show in the chat header.

## Tips
- OWNER and ADMIN can always pick any persona regardless of assignment — necessary for testing personas without juggling alt accounts.
- A user with no explicit default falls back to: their team's default → the org's default agent (the row marked isDefault). Zero-disruption upgrade for existing orgs.
- Personas stack with visibilityMode — the Finance persona on an "owned" org sees only that user's own records, even if the persona itself is unrestricted.
- Public web / public voice rows still route by slug + publicApiKey — the persona-router only governs the in-app AI Bar.
- Personas don't add cost — they share the same CRMown AI engine and model tier as your org's base AI configuration.
- New in Phase 3 (2026-05-08): the Persona tab has a "Quick start — apply a preset" row with five starter templates (Finance, HR, Ops, Sales, Support). Click one and the form pre-fills tone, knowledge scope, tool allowlist, and disabled-feature carve-outs — you still tweak before saving.
- Per-persona approval rules override (Phase 3) — the Persona tab takes a JSON blob that replaces your org's aiApprovalRules when an action runs under that persona. Useful when Finance should require OWNER approval on send_email even if Sales auto-approves it. Leave blank to inherit the org default.

## Example
Acme has 80 users across Finance (12), HR (4), Ops (8), Sales (40), and Support (16). The OWNER creates 5 personas with matching descriptions, knowledge scopes, and disabled-feature carve-outs. Each user selects their department's persona once under Settings > AI Usage > My AI Persona (self-service — there is no team-wide auto-assignment). Sales reps still get the full pipeline-aware AI Bar; Finance reps get a persona that pulls from invoicing + accounting KB articles only and refuses to draft sales follow-ups. The Q3 NPS survey shows AI usefulness scores up 38% vs. the previous quarter when everyone shared one generic agent.

## Troubleshooting
- **My AI Bar still shows the old generic agent** — You haven't selected a persona yet, or the org admin hasn't flipped any agent rows to "Internal" purpose. Fix: Pick your persona under Settings > AI Usage > My AI Persona.
- **I picked a persona but the AI is answering exactly the same way** — The persona's system-prompt overrides (tone, description, disabled features) hadn't propagated yet — there's a 60-second cache. Fix: Wait 60 seconds and try again. Hard-refresh the dashboard if needed. Verify the persona's Personality + Description are non-default values.
- **A user can pick a persona they shouldn't have access to** — In v1, every internal persona in the org is visible to every user. Per-user persona restrictions ship in Phase 2. Fix: Make sensitive personas inactive (isActive=false) when you don't want them surfaced. Or scope their knowledge corpus tightly so they refuse out-of-scope questions.
- **Voice agent stopped working after I changed its purpose** — Public-voice routing requires purpose=public_voice. If you flipped a Twilio-connected agent to "Internal", inbound calls now hit the fallback agent. Fix: Edit the agent → Persona tab → set purpose back to "Public voice".
- **Callers hear a robotic voice on the AI phone agent** — The natural-voice engine (CRMown AI voice) needs the platform text-to-speech key configured; without it calls fall back to the built-in telephony voice. Fix: Numbers provisioned in CRMown are wired for voice automatically. If calls still sound robotic, contact support — the natural-voice engine may not be enabled for your environment. The call flow works either way.