API

Usa questa pagina per consultare metodi WebSocket, eventi ed errori esposti dal motore.

Il motore si pilota attraverso un'unica API. La riga di comando afe ne è un client, e più avanti lo sarà anche la UI web.

Il protocollo

L'API è JSON-RPC 2.0 su una WebSocket in /rpc. L'handshake deve portare Authorization: Bearer <token>, oppure un cookie di sessione valido con l'Origin del server stesso.

Metodo	Parametri	Risultato
flow.list	—	i flow con il loro Schema di ingresso, il workspace che serve, i progetti e la revisione corrente
flow.bpmn	flow, revision?	{xml}: il flow come BPMN 2.0 XML, senza layout
ticket.start	flow, input, project?, revision?, traceparent?	{ticket_id} appena il ticket è accettato
ticket.rerun	ticket_id	{ticket_id} di un nuovo ticket con stesso flow, input, progetto e revisione
revision.get	revision_id	{id, manifests}: la configurazione congelata
ticket.resume	ticket_id, answer? (action, comment?)	{ticket_id}
ticket.pause, ticket.cancel	ticket_id	null
ticket.get	ticket_id	stato, round, revisione, artefatti, consumi, domanda in attesa, ultimo errore
ticket.list	state?	i ticket con i consumi e la domanda in attesa di quelli che aspettano
ticket.events	ticket_id	gli eventi del ticket, in ordine
events.subscribe	ticket_id?	{subscription}, poi le notifiche events.event
events.unsubscribe	subscription	true o false
workers.status	—	metriche della coda (waiting, claimed) e i worker vivi

I ticket girano in background e i loro progressi arrivano come notifiche events.event sulla stessa connessione. Chi si iscrive in ritardo riceve prima gli eventi già avvenuti del ticket, poi quelli in diretta, senza duplicati.

Tipi di evento

Tipo	Significato
ticket_started	Il ticket è stato accettato e il motore lo ha avviato.
ticket_resumed	Una persona ha risposto, oppure il ticket è stato riavviato.
ticket_recovered	Un worker ha preso in carico un ticket il cui worker è morto.
ticket_cancelled	Il ticket è stato annullato.
ticket_done	Il flow ha raggiunto END.
node_started	Un nodo ha iniziato un'attivazione.
node_finished	Un nodo ha concluso un'attivazione.
budget_alert	Un budget ha superato una frazione di avviso o un limite; aspetta una persona.
loop_detected	La stessa chiamata a un tool si è ripetuta; aspetta una persona.
human_request	Un nodo human chiede a una persona.
human_response	Una persona ha risposto a un nodo human.
needs_human	Un passaggio di consegna; il ticket si ferma per una persona.
error	Il ticket è fallito; il payload porta state e error.

Errori

Codice di errore	Significato
-32602	Parametri non validi
-32001	Flow o ticket sconosciuto
-32002	Input non valido; data.fields indica il campo sbagliato
-32003	Azione non offerta
-32004	Il ticket è in esecuzione, oppure è chiuso
-32005	Revisione sconosciuta
-32006	Il ticket non ha una revisione (creato prima che le revisioni esistessero)

Vedi anche

• CLI per i comandi che chiamano l'API.
• Stati di un ticket per il ciclo di vita.
• Operations per salute e metriche.