Agent Roles

For everyone: The Roles page manages the role templates that appear when creating a new AI agent. Each role template is like a job description — it defines who the agent is, how it communicates, what tools it uses, and what it's an expert in. When you select a role in the Create Agent wizard, all of this gets auto-configured, saving you from building each agent from scratch.

For technical users: Role templates are stored in two places: 51 built-in templates in soul-templates.json and custom templates in the custom_roles database table (migration v32). Custom roles can be org-scoped via org_id. The /souls/by-category API merges both sources, so custom roles appear alongside built-in ones in the Create Agent wizard. Each template contains a full SOUL.md personality prompt, identity metadata (role title, tone, language), suggested skills, and tags for search.

1. Admin creates a role template via the Roles page — defining name, category, personality, skills, and tone.
2. Template appears in Create Agent wizard — Step 1 "Choose a Role Template" shows all built-in and custom templates grouped by category.
3. User selects the role — the wizard auto-fills the agent's personality (SOUL.md), job title, communication tone, suggested skills, and permission preset.
4. User customizes — all auto-filled fields can be edited before creating the agent.

Custom role templates are merged with built-in templates in real-time. When the wizard loads, it queries /api/engine/souls/by-category which returns both sources combined.

AgenticMail ships with 51 built-in role templates across 14 categories. These cover common enterprise agent roles from Customer Support Lead to Security Operations Analyst. Built-in roles:

• Cannot be edited or deleted (they're part of the core platform)
• Can be duplicated as a starting point for custom roles
• Are shown to all users regardless of organization
• Each has a comprehensive personality prompt with sections for Identity, Approach, Mental Models, Decision Framework, Communication Style, Expertise, Principles, and Boundaries

Click "Create Role" to open the role form with four tabs:

General Tab

• Role Name — e.g., "Customer Onboarding Specialist". Auto-generates a slug ID.
• Category — Which department this role belongs to (determines grouping in the wizard).
• Description — Brief summary shown in the role card.
• Job Title — The role title that appears in the agent's identity badges.
• Tone — Formal, Casual, Professional, or Friendly.
• Language — Language code (default: en).
• Organization Scope — Global or restricted to a specific client org.
• Tags — Keywords for searchability in the wizard.

Personality Tab

A large text editor for the full SOUL.md personality prompt. Aim for 500+ characters for a well-defined role. See Personality section.

Skills & Preset Tab

Select skills from the full catalog and optionally set a permission preset. See Skills section.

Preview Tab

See exactly how the role will appear in the Create Agent wizard — the "resume card" with badges, skills, and personality excerpt.

The personality is the most important part of a role template. It's a comprehensive prompt (typically 1000-5000 characters) that uses Markdown headings to define sections:

# Role Name

## Identity
You are the... (who this agent is, their core mission)

## Approach
You... (how they work, their methodology)

## Mental Models
... (frameworks they use to think about problems)

## Decision Framework
... (how they prioritize and make decisions)

## Communication Style
... (how they write, their tone in practice)

## Expertise
... (comma-separated areas of knowledge)

## Principles
- ... (operating rules they follow)

## Boundaries
- ... (what they won't do, limitations)

The Create Agent wizard parses these sections to display a rich "resume card" preview when the role is selected.

Each role template can suggest:

• Skills — Tools auto-enabled when the role is selected. Browse the full skill catalog organized by category and check the ones relevant to this role. Common skills include agenticmail, web-search, web-fetch, memory, summarize.
• Permission Preset — A named preset (e.g., "Customer Support Agent") that auto-configures tool permissions, rate limits, and risk levels.

These are suggestions — users can always modify skills and permissions after selecting the role template.

Custom roles can be scoped to control who sees them:

• Global (no org selected) — Visible to all users across all organizations in the Create Agent wizard.
• Org-scoped — Only visible to users who belong to that specific client organization.

Use org-scoping when different clients need different agent templates. For example, a law firm client might need a "Legal Intake Specialist" role that isn't relevant to your other clients.

The org switcher in the Roles page header lets you filter custom roles by organization.

The Preview tab shows the exact "resume card" that appears in the Create Agent wizard when a user selects this role. It includes:

• Role avatar (first letter), name, and description
• Identity badges: job title, tone, language, suggested preset
• Org-scoped indicator (if applicable)
• Suggested skills as colored pills
• Tags
• Personality excerpt (first 800 characters)

Use this preview to verify the role looks polished before saving.

• Duplicate built-in roles to customize. Start from a built-in template that's close to what you need, then modify the personality and skills.
• Write detailed personalities. The personality prompt is what makes each agent unique. Aim for 1000+ characters covering identity, approach, communication style, expertise, and boundaries.
• Use structured Markdown headings. The wizard parses ## Identity, ## Approach, ## Expertise etc. to create the rich preview card.
• Add relevant tags. Tags power the search in the Create Agent wizard. Add synonyms and related terms.
• Scope org-specific roles. Don't clutter the global role list — if a role is only for one client, scope it to their org.
• Select minimal skills. Only suggest skills the role actually needs. Users can always add more later.
• Review in Preview tab. Always check the preview before saving to ensure it looks professional.