Roles de especialista (agency-agents)

Dale a una agent run una identidad de especialista (un abogado, un analista de datos, un guardián de marca) tomada de la librería agency-agents incluida. El rol define quién ES el agent en esa tarea (especialidad, reglas, tono), por delante del prompt base.

Lo que hace un rol

Un rol de especialista (un persona) es un cambio de identidad. Cuando pasas el slug de un rol a una agent run, el agent adopta la perspectiva de esa especialidad para la tarea (su conocimiento del dominio, reglas de trabajo y estilo de comunicación), pero conservando toda su capacidad de herramientas y la marca Nexevo. Es distinto de una skill, que es un guion de flujo de trabajo que el agent aplica: un rol define quién es el agent.

Los roles son completamente opt-in y manuales. Si no eliges ninguno, el agent se ejecuta como Nexevo puro. Eliges uno de la librería (o desde el menú de roles del composer de la app); no existe auto-enrutamiento a roles.

Listar los roles disponibles

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

la librería de skills y roles del workspace. Las entradas con kind: "agency" son roles de especialista; kind: "official" / "custom" son skills. Filtra por kind para obtener solo roles.

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 rol incluye: slug (el id que pasas a una run), name, description, category / division (el campo del rol: ingeniería, marketing, finanzas, diseño, …) y metadatos de visualización (emoji, division_label, division_color). La librería abarca 18 campos con decenas de roles de especialista, desde engineering-backend-architect hasta design-brand-guardian o finance-cfo.

Ejecutar con un rol

Pasa el slug del rol como persona_slug en una agent run. La identidad del rol se inyecta como una cabecera sobre el system prompt; el agent conserva todas sus herramientas.

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

Como máximo un rol por run. Un persona_slug ausente o deshabilitado degrada silenciosamente a la identidad base de Nexevo: la run nunca falla por una búsqueda de rol.

Un rol es una identidad, no una lista blanca de herramientas. El agent conserva toda su capacidad (web, código, navegador, connectors); el rol moldea cómo razona y se comunica, no qué puede hacer. Combina un rol con skills para el mejor resultado: una identidad de dominio más un guion de flujo de trabajo.