Documentazione COLVO

COLVO testa gli agenti AI prima del lancio e protegge le loro azioni reali in produzione, verificando il risultato effettivo invece della risposta dell’agente. Questa è la documentazione per sviluppatori: il contratto HTTP verso il tuo agente, l’API che chiamano il tuo backend e il tuo agente, la CLI e il modo in cui vengono prese decisioni e verdetti.

Scritto a partire dal codice · aggiornato il 26 set 2026 · Manca qualcosa o c’è un errore? Scrivici

Due moduli, un solo contratto

COLVO Test riproduce gli scenari in un mondo Stripe simulato e isolato. Il tuo agente riceve un cliente, i suoi abbonamenti e pagamenti e un messaggio, e risponde come farebbe in produzione. Quando vuole agire, propone un’operazione a COLVO. Il verdetto si calcola dallo stato risultante: PASS, FAIL o INCONCLUSIVE.
COLVO Guard si mette davanti al tuo provider reale. Il tuo backend fidato registra un mandato (chi può fare cosa, con quali limiti); l’agente propone; COLVO decide ALLOW / REVIEW / HOLD / DENY, esegue una volta sola e verifica sul provider.

L’agente usa lo stesso piccolo contratto in entrambi i moduli e non possiede mai credenziali di scrittura del provider.

Da dove iniziare

Primi passi — dall’invito al primo test verde.
Collega il tuo agente — la richiesta che COLVO invia e la risposta che si aspetta.
Mandati e connessioni, poi l’API di Guard — quando vai in produzione.
CLI e blocco in CI — fai fallire la build su FAIL.

URL di base e versioni

Tutti gli endpoint stanno sotto https://colvo.app/v1. I body sono JSON. Le modifiche incompatibili ricevono un nuovo prefisso; i campi aggiuntivi possono comparire in qualsiasi momento, quindi ignora le chiavi sconosciute.

Autenticazione

Due credenziali, entrambe inviate come Authorization: Bearer …:

Chiave backend (cak_…, scope backend) — il tuo server fidato. Registra i mandati, avvia le esecuzioni, gestisce la configurazione.
Chiave agente (cak_…, scope agent) — l’agente stesso. Può solo proporre operazioni e leggerne lo stato. Durante un’esecuzione di test COLVO passa all’agente una chiave per singolo tentativo nella richiesta, quindi un agente in test non ha bisogno di segreti salvati.

Gli utenti della console agiscono con la propria sessione; il ruolo nell’organizzazione (owner / editor / viewer) decide cosa possono modificare. Le chiavi vengono mostrate una sola volta, sono salvate come hash e si possono revocare o ruotare da Impostazioni.

Primi passi →