Papéis especialistas (agency-agents)

Dê a um agent run uma identidade especialista — um advogado, um analista de dados, um guardião de marca — extraída da biblioteca agency-agents embutida. O papel molda quem o agent É para aquela tarefa (especialidade, regras, tom), antes do prompt base.

O que um papel faz

Um papel especialista (uma persona) é uma troca de identidade. Quando você passa o slug de um papel para um agent run, o agent adota a perspectiva daquela especialidade para a tarefa — seu conhecimento de domínio, regras de trabalho e estilo de comunicação — mantendo toda a sua capacidade de ferramentas e a marca Nexevo. É diferente de uma skill, que é um playbook de fluxo de trabalho que o agent aplica: um papel é quem o agent é.

Os papéis são inteiramente opt-in e manuais. Sem nenhum papel escolhido, o agent roda como Nexevo puro. Você escolhe um da biblioteca (ou do menu de papéis do compositor do app); não há roteamento automático para papéis.

Listar papéis disponíveis

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

a biblioteca de skills + papéis do workspace. Entradas com kind: "agency" são papéis especialistas; kind: "official" / "custom" são skills. Filtre por kind para obter somente papéis.

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,
#     ...
#   },
#   ...
# ]

Cada entrada de papel carrega: slug (o id que você passa para um run), name, description, category / division (a área do papel — engenharia, marketing, finanças, design…) e metadados de exibição (emoji, division_label, division_color). A biblioteca abrange 18 áreas com dezenas de papéis especialistas — de engineering-backend-architect a design-brand-guardian a finance-cfo.

Executar com um papel

Passe o slug do papel como persona_slug em um agent run. A identidade do papel é injetada como um cabeçalho no prompt do sistema; o agent mantém todas as suas ferramentas.

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": "…"}

No máximo um papel por run. Um persona_slug ausente ou desativado degrada silenciosamente para a identidade Nexevo de base — o run nunca falha por causa de uma busca de papel.

Um papel é uma identidade, não uma lista de permissões de ferramentas. O agent retém toda a sua capacidade (web, código, navegador, conectores); o papel molda como ele raciocina e se comunica, não o que ele pode fazer. Combine um papel com skills para o resultado mais forte — uma identidade de domínio mais um playbook de fluxo de trabalho.