Skip to main content

Roles

Roles customize AI behavior based on user type. An admin sees different options than a viewer. A nurse gets different guidance than a doctor. Roles let you tailor the assistant experience without building separate assistants.

How Roles Work​

What Roles Control​

1. Prompt Instructions​

Add role-specific context to the AI's system prompt:

Admin role:

You are assisting an administrator. You can help with:
- User management
- System configuration
- Access control
- Audit logs
Be direct and technical in your responses.

Viewer role:

You are assisting a viewer with read-only access. You can help with:
- Viewing reports
- Searching data
- Exporting information
Do not suggest actions that modify data.

2. Tool Access​

Control which MCP tools each role can use:

Each role has two settings:

  • allowAllTools (boolean) — If true, the role has access to every tool. If false, only tools listed in allowedToolNames are accessible.
  • allowedToolNames (string[]) — An explicit list of tool names the role can use (only applies when allowAllTools is false).

Example:

RoleallowAllToolsallowedToolNames
Admintrue—
Editorfalsesearch_orders, get_order, create_order, update_order
Viewerfalsesearch_orders, get_order, list_reports

Tool names must match exactly — there is no wildcard or glob matching.

Role Resolution​

Roles are determined when a session starts:

From User Resolver​

Your User Resolver webhook returns user roles:

{
  "userId": "user_123",
  "displayName": "John Doe",
  "roles": ["admin", "sales"]
}

From JWT Claims​

If using JWT, roles can be extracted from token claims:

{
  "sub": "user_123",
  "roles": ["admin", "sales"],
  "permissions": ["read", "write", "delete"]
}

Default Role​

If no roles match or user resolver fails:

{
  defaultRole: "viewer"  // Fallback role
}

Role Priority​

When a user has multiple roles, priority determines which config applies:

// Role configs with priorities
[
  { role: "super_admin", priority: 100 },  // Highest
  { role: "admin", priority: 50 },
  { role: "editor", priority: 30 },
  { role: "viewer", priority: 10 }         // Lowest
]

// User with roles: ["editor", "admin"]
// Applied role: "admin" (higher priority)

For tool access, if any of the user's roles has allowAllTools: true, the user gets access to all tools. Otherwise, the allowed tool names from all roles are combined (union).

Example Role Configurations​

Healthcare System​

// Doctor role
{
  roleName: "doctor",
  displayName: "Doctor",
  priority: 80,
  promptInstructions: `
    You are assisting a physician. You can:
    - Access full patient records
    - Order tests and prescriptions
    - View lab results
    Use clinical terminology.
  `,
  allowAllTools: true
}

// Nurse role
{
  roleName: "nurse",
  displayName: "Nurse",
  priority: 60,
  promptInstructions: `
    You are assisting a nurse. You can:
    - View patient vitals and care plans
    - Update patient status
    - Access medication schedules
    Do not prescribe medications or order tests.
  `,
  allowAllTools: false,
  allowedToolNames: [
    "get_patient_vitals", "get_care_plan", "search_patients",
    "update_patient_status", "view_medications"
  ]
}

// Receptionist role
{
  roleName: "receptionist",
  displayName: "Receptionist",
  priority: 30,
  promptInstructions: `
    You are assisting front desk staff. You can:
    - Schedule appointments
    - Check patient check-in status
    - View basic contact information
    Do not access medical records.
  `,
  allowAllTools: false,
  allowedToolNames: [
    "schedule_appointment", "checkin_patient",
    "get_contact_info", "search_appointments"
  ]
}

E-commerce System​

// Store Manager
{
  roleName: "store_manager",
  promptInstructions: `
    You are assisting a store manager. You can:
    - Manage inventory
    - Process refunds
    - View sales reports
    - Manage staff schedules
  `,
  allowAllTools: true
}

// Customer Service
{
  roleName: "customer_service",
  promptInstructions: `
    You are assisting customer service. You can:
    - Look up orders
    - Process returns (under $100)
    - Update shipping addresses
    Be empathetic and helpful.
  `,
  allowAllTools: false,
  allowedToolNames: [
    "get_order", "search_orders", "get_customer",
    "search_customers", "update_shipping_address",
    "create_support_ticket"
  ]
}

// Customer (Self-Service)
{
  roleName: "customer",
  promptInstructions: `
    You are helping a customer with their account. You can:
    - View their orders
    - Track shipments
    - Update their profile
    Only access data belonging to this customer.
  `,
  allowAllTools: false,
  allowedToolNames: [
    "get_my_orders", "track_order", "update_my_profile"
  ]
}

Role Hierarchy​

Roles don't have built-in inheritance. Instead, use priority to determine which role's prompt instructions apply when a user has multiple roles. For tool access, all roles' allowed tools are combined.

Testing Roles​

To test different roles during development:

In Admin Portal​

Use the "Test as Role" feature to simulate different user roles.

Via API​

// Create test session with specific role
POST /api/sessions
{
  "testMode": true,
  "overrideRoles": ["nurse"]
}

In Browser​

// Override roles for testing (development only)
diosc('config', {
  debug: true,
  overrideRoles: ['viewer']
});

Best Practices​

1. Start Restrictive​

Begin with minimal permissions and add as needed:

// Start with viewer-level access
{
  allowAllTools: false,
  allowedToolNames: ["get_order", "search_orders", "list_reports"]
}

2. Use Clear Role Names​

Match your application's existing role terminology:

// ✅ Good - matches existing roles
["admin", "editor", "viewer"]

// ❌ Bad - confusing, doesn't match app
["role_1", "power_user", "basic"]

3. Document Role Capabilities​

Keep prompt instructions clear about what each role can do:

promptInstructions: `
  You are assisting an EDITOR. You CAN:
  - Create and edit content
  - Publish to staging

  You CANNOT:
  - Delete content
  - Publish to production
  - Manage users
`

4. Test Edge Cases​

  • User with no roles (should fall back to default)
  • User with conflicting roles
  • Role config changes mid-session

Next Steps​