Documentazione

Come funziona PROMIVO

I concetti che servono per attivare un agente, costruire un flusso di lavoro e chiamare la piattaforma dai tuoi sistemi.

Agenti e versioni

Un agente è una scheda di catalogo più una o più versioni immutabili. Una versione contiene il prompt di sistema, la configurazione del modello, gli strumenti che può chiamare, gli schemi di input e output, i limiti di esecuzione e il suo limite di rischio automatico.

Pubblicare un aggiornamento crea una nuova versione e sposta il puntatore corrente. Una versione esistente non viene mai modificata, quindi un'esecuzione già in corso mantiene il comportamento con cui è partita.

Permessi e rischio

Ogni strumento dichiara un livello di rischio. Una versione di un agente dichiara il livello più alto che può eseguire senza una persona.

READRecupera, cerca, riassume. Non modifica nulla.
WRITEInvia un'email, pubblica un aggiornamento, crea o aggiorna un record.
DESTRUCTIVEElimina dati o spende denaro.

Una chiamata a uno strumento oltre il limite viene rifiutata, registrata come attività in attesa di approvazione e riportata al modello come non eseguita. L'esecuzione continua; l'effetto collaterale non avviene.

Nodi del flusso di lavoro

Nodo	Che cosa fa
`TRIGGER`	Punto di ingresso. Manuale, webhook, pianificazione o evento.
`AI`	Esegue un agente con un modello di input interpolato.
`HTTP`	Chiama un endpoint HTTP pubblico. Gli intervalli privati sono bloccati.
`CONDITION`	Si dirama in base a un valore nel contesto dell'esecuzione.
`TRANSFORM`	Rimodella i dati in un nuovo oggetto.
`EMAIL`	Invia un'email tramite il provider configurato.
`WEBHOOK`	Invia in uscita un payload JSON firmato con una POST.
`DELAY`	Attende fino a 300 secondi all'interno di un'esecuzione.
`DATABASE`	Registra una nota o legge le esecuzioni recenti.
`OUTPUT`	Definisce il risultato finale del flusso di lavoro.

Template

La configurazione di un nodo interpola valori dal contesto dell'esecuzione. Non c'è valutazione di espressioni, quindi un template non può mai eseguire codice.

{{trigger.email}}                  → the trigger payload
{{steps.qualify.output.score}}     → an earlier node result
{{workflow.name}}                  → workflow metadata

API pubblica

Crea una chiave con ambito definito nella pagina delle chiavi API. Il segreto viene mostrato una sola volta; viene salvato solo il suo hash.

POST /api/agents/run
Authorization: Bearer pmv_live_…
Content-Type: application/json

{ "agentId": "<uuid>", "input": { "topic": "Q4 planning" } }

Ogni risposta usa la stessa struttura:

{ "ok": true,  "data": { … } }
{ "ok": false, "error": { "code": "…", "message": "…" } }

Endpoint

GET /api/agents
POST /api/agents/run
GET /api/workflows
POST /api/workflows
POST /api/workflows/:id/run
GET /api/executions
GET /api/executions/:id
GET /api/usage

Trigger via webhook

Un flusso di lavoro attivato da webhook riceve un token pubblico e un segreto di firma, mostrato una sola volta alla creazione. Firma il corpo grezzo con quel segreto.

POST /api/webhooks/workflow/<token>
x-promivo-secret:    <signing secret>
x-promivo-signature: <hex HMAC-SHA256 of the raw body>
x-idempotency-key:   <optional; makes redelivery safe>

{ "email": "lead@example.com", "message": "…" }