Specialist roles (agency-agents)

Give an agent run a specialist identity — a lawyer, a data analyst, a brand guardian — drawn from the bundled agency-agents library. The role shapes who the agent IS for that task (specialty, rules, tone), ahead of the base prompt.

What a role does

A specialist role (a persona) is an identity switch. When you pass a role's slug to an agent run, the agent adopts that specialty's perspective for the task — its domain knowledge, working rules, and communication style — while keeping its full tool capability and the Nexevo brand. It is different from a skill, which is a workflow playbook the agent applies: a role is who the agent is.

Roles are entirely opt-in and manual. With no role picked, the agent runs as plain Nexevo. You pick one from the library (or the app's composer role menu); there is no auto-routing to roles.

List available roles

GET/v1/workspaces/{workspace_id}/skill-library —

the workspace's skill + role library. Entries with kind: "agency" are specialist roles; kind: "official" / "custom" are skills. Filter on kind to get roles only.

bash

curl https://nexevo.ai/v1/workspaces/$NEXEVO_WORKSPACE/skill-library \
  -H "Authorization: Bearer $NEXEVO_API_KEY"
# [
#   {
#     "slug": "engineering-ai-engineer",
#     "name": "AI Engineer",
#     "description": "Expert AI/ML engineer ...",
#     "kind": "agency",
#     "category": "engineering",
#     "emoji": "🤖",
#     "division": "engineering",
#     "division_label": "Engineering",
#     "enabled": true,
#     ...
#   },
#   ...
# ]

Each role entry carries: slug (the id you pass to a run), name, description, category / division (the role's field — engineering, marketing, finance, design, …), and display metadata (emoji, division_label, division_color). The library spans 18 fields with dozens of specialist roles — from engineering-backend-architect to design-brand-guardian to finance-cfo.

Run with a role

Pass the role's slug as persona_slug in an agent run. The role's identity is injected as a head on the system prompt; the agent keeps all its tools.

bash

curl https://nexevo.ai/v1/workspaces/$NEXEVO_WORKSPACE/agent/runs \
  -H "Authorization: Bearer $NEXEVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "Review our checkout flow for drop-off points and propose 3 fixes.",
    "persona_slug": "design-ux-architect"
  }'
# -> {"run_id": "…", "trace_id": "…"}

At most one role per run. A missing or disabled persona_slug silently degrades to the baseline Nexevo identity — the run never fails because of a role lookup.

A role is an identity, not a tool whitelist. The agent retains its full capability (web, code, browser, connectors); the role shapes how it reasons and communicates, not what it can do. Pair a role with skills for the strongest result — a domain identity plus a workflow playbook.