Endpoint Persona API

Riferimento completo per gli endpoint REST API delle persona - elenca, crea, aggiorna, elimina, duplica, attiva/disattiva e visualizza le analytics delle persona degli agenti IA.

8 min letto
apipersonasagents

Le persona definiscono la personalità, le competenze e le preferenze di modello degli agenti di coding IA. Ogni persona può essere assegnata a step della pipeline di workflow per controllare il comportamento degli agenti durante l’esecuzione. La Persona API fornisce 9 endpoint per la gestione completa del ciclo di vita.

Endpoint

GET /api/v1/personas/list

Elenca tutte le persona del progetto.

curl -H "Authorization: Bearer cc_live_..." \
  https://<deployment>.convex.site/api/v1/personas/list

GET /api/v1/personas/get

Recupera una singola persona per ID.

Parametri di query:

  • id (obbligatorio) - L’ID del documento persona
curl -H "Authorization: Bearer cc_live_..." \
  "https://<deployment>.convex.site/api/v1/personas/get?id=..."

GET /api/v1/personas/analytics

Visualizza le analytics e le statistiche di utilizzo di una persona.

Parametri di query:

  • id (obbligatorio) - L’ID del documento persona
  • days (opzionale) - Numero di giorni di lookback (predefinito: intera cronologia)

POST /api/v1/personas/create

Crea una nuova persona.

curl -X POST -H "Authorization: Bearer cc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Senior Architect",
    "description": "Expert in system design and code review",
    "type": "checker",
    "cliId": "claude_code",
    "model": "claude-sonnet-4-20250514",
    "thinkingEffort": "high",
    "instructions": "Focus on architecture, performance, and security.",
    "selectedSkills": ["code-review", "architecture"],
    "isEnabled": true
  }' \
  https://<deployment>.convex.site/api/v1/personas/create

Campi del body:

  • name (string, obbligatorio) - Nome visualizzato
  • description (string, opzionale) - Descrizione leggibile
  • type (string, obbligatorio) - Tipo di persona (ad es., designer, checker, optimizer)
  • cliId (string, opzionale) - Identificatore dello strumento CLI
  • model (string, opzionale) - ID del modello LLM
  • thinkingEffort (string, opzionale) - Livello di sforzo di ragionamento
  • instructions (string, opzionale) - Istruzioni personalizzate
  • selectedSkills (array, opzionale) - Identificatori di skill
  • isEnabled (boolean, opzionale) - Se la persona è attiva

POST /api/v1/personas/update

Aggiorna una persona esistente. Tutti i campi del body tranne personaId sono opzionali.

{
  "personaId": "...",
  "name": "Updated Name",
  "model": "claude-opus-4-20250514",
  "learningsEnabled": true
}

Campi aggiuntivi: description, type, thinkingEffort, instructions, selectedSkills, isEnabled, learningsEnabled.

POST /api/v1/personas/delete

Elimina una persona.

{ "personaId": "..." }

POST /api/v1/personas/duplicate

Crea una copia di una persona esistente.

{ "personaId": "..." }

POST /api/v1/personas/toggle

Attiva/disattiva lo stato di una persona.

{ "personaId": "..." }

POST /api/v1/personas/bulk-delete

Elimina più persona in un’unica richiesta.

{ "personaIds": ["id1", "id2", "id3"] }