Automazioni
Le automazioni eseguono un'istruzione secondo una pianificazione e consegnano il risultato come una normale sessione di chat. Un riepilogo quotidiano delle notizie, una revisione settimanale, un rapporto mensile: ogni esecuzione avviene senza interfaccia sul server, compare nell'elenco delle chat e può essere aperta e proseguita come qualsiasi altra conversazione.
Anatomia
Un'automazione comprende un nome, istruzioni in testo libero, uno o più trigger, un modello facoltativo (vuoto significa Auto: il tuo modello di chat predefinito al momento dell'esecuzione), una destinazione di esecuzione e una preferenza per le notifiche (nell'app oppure disattivate). La destinazione decide che cosa produce un'esecuzione: Sessione di chat (valore predefinito) accoda le istruzioni come conversazione, mentre Attività Work avvia un ambiente isolato Work con le istruzioni come messaggio iniziale, eventualmente soggetto a un criterio Work denominato scelto nel modulo. Con le notifiche attive, un'esecuzione non riuscita compare anche nella casella delle notifiche, così gli errori ti raggiungono anche quando la pagina Automazioni è chiusa. Nomi e istruzioni sono cifrati a riposo. Ogni automazione appartiene all'utente che l'ha creata.
I trigger riutilizzano il modello condiviso del calendario: once, hourly, daily,
weekly, monthly, yearly; un'automazione può contenerne fino a cinque. La
prossima esecuzione è sempre la ricorrenza futura più vicina tra tutti i trigger,
calcolata nel fuso orario locale del server.
Esecuzione
Un tick del pianificatore viene eseguito ogni minuto dietro un lease di coordinamento, così una sola
replica fa avanzare le pianificazioni. Quando un'automazione è pronta, il tick registra
un'esecuzione, accoda un job duraturo automation.run.v1 e fa avanzare next_run_at
con un confronto e impostazione, affinché ogni ricorrenza si attivi al massimo una volta. Il job crea
una sessione di chat intitolata come l'automazione, quindi accoda l'istruzione
attraverso la stessa pipeline duratura di generazione delle chat usata da ogni conversazione,
inclusi instradamento dei provider, valori predefiniti dei personaggi e persistenza.
Se il server non era in esecuzione quando è trascorsa una ricorrenza, il tick successivo la avvia una volta e salta tutte quelle precedenti mancate. La sospensione di un'automazione ne cancella la pianificazione; la ripresa o la modifica la ricalcola dal momento attuale. L'eliminazione di un'automazione rimuove la relativa cronologia delle esecuzioni tramite una cascata di chiavi esterne.
Gli esiti delle esecuzioni derivano dal registro dei job duraturi: riuscita quando è terminata la generazione
della chat, non riuscita quando il job viene spostato tra quelli irrecuperabili e non riuscita come stalled quando
un'esecuzione in coda non inizia entro 30 minuti.
Le esecuzioni destinate a Work si comportano allo stesso modo, sostituendo al job di chat il ciclo di vita
di Work: l'esecuzione registra l'attività creata (la scheda Esecuzioni vi rimanda direttamente),
riesce quando l'agente termina oppure si arresta per chiedere un input e non riesce quando
l'attività fallisce o viene annullata. L'accesso a Work viene verificato quando parte la pianificazione,
quindi la revoca dell'accesso Work a un utente disattiva anche le relative automazioni destinate a Work;
l'esecuzione non riesce come work-access-denied, anziché essere saltata senza avviso. Il criterio selezionato
viene convalidato quando si salva l'automazione e la relativa impostazione di rete predefinita e i limiti
di risorse si applicano a ogni attività avviata dall'automazione. In Work vengono eseguiti soltanto provider
di modelli diretti e il modello deve supportare gli strumenti: sono le stesse regole del compositore Work.
Routine degli agenti
Un'automazione destinata a Work può invece essere associata a un'attività Work esistente tramite
workTaskId: è la struttura su cui si basa la sezione Routine del
pannello dei dettagli di un agente. Una routine associata non crea una
nuova attività a ogni attivazione: ogni ricorrenza avvia un'esecuzione all'interno dell'area di lavoro e della
conversazione dell'attività, usando modello, provider e criterio del runtime di quest'ultima; pertanto
i campi modello e criterio a livello di automazione non si applicano e qualsiasi criterio specificato viene
rimosso al momento del salvataggio. L'associazione viene convalidata quando si salva l'automazione
(l'attività deve esistere e appartenere al chiamante). Al momento dell'attivazione, un'attività eliminata fa fallire
l'esecuzione come work-task-missing, mentre un'attività già in esecuzione o con un'anteprima attiva
fa fallire correttamente la ricorrenza come work-task-busy, senza accodarla.
Trigger webhook
Oltre alla pianificazione, un'automazione può essere avviata da un sistema esterno: una pipeline CI, un servizio cron, la domotica. Nella finestra di modifica dell'automazione, Trigger webhook → Abilita genera un segreto specifico per quell'automazione; ne viene memorizzato solo l'hash SHA-256, quindi il testo in chiaro è mostrato esattamente una volta. La rotazione del segreto invalida immediatamente quello precedente e la disattivazione del webhook richiude l'endpoint.
Il sistema esterno avvia l'automazione con:
curl -X POST https://your-host/api/automations/<automationId>/webhook \
-H "Authorization: Bearer lwh_..."
(X-Libre-Webhook-Secret: lwh_... funziona come intestazione alternativa.) La
risposta è 202 con l'ID dell'esecuzione accodata: è lo stesso percorso di
esecuzione manuale di Esegui ora, quindi le esecuzioni si concludono,
notificano e compaiono nella cronologia in modo identico. Il confronto del
segreto avviene a tempo costante, un'automazione inesistente e un segreto
errato rispondono in modo identico (nessun oracolo sugli ID delle automazioni)
e un'automazione sospesa risponde 409: a differenza di Esegui ora del
proprietario, un chiamante esterno non può attivarla superando una sospensione.
API
Tutti gli endpoint tranne l'attivazione via webhook richiedono autenticazione e operano solo sulle automazioni del chiamante; l'attivazione via webhook si autentica invece con il segreto specifico dell'automazione.
| Metodo | Percorso | Scopo |
|---|---|---|
GET | /api/automations | Elenca le automazioni |
POST | /api/automations | Crea un'automazione |
GET | /api/automations/occurrences?from=&to= | Ricorrenze future calcolate |
GET | /api/automations/runs | Cronologia esecuzioni (filtrabile) |
GET | /api/automations/runs/summary | Conteggio non visti + intervalli di 30 giorni |
POST | /api/automations/runs/seen | Contrassegna come viste le esecuzioni concluse |
GET | /api/automations/:automationId | Legge un'automazione |
PUT | /api/automations/:automationId | Aggiorna un'automazione |
DELETE | /api/automations/:automationId | Elimina un'automazione |
POST | /api/automations/:automationId/pause | Sospende la pianificazione |
POST | /api/automations/:automationId/resume | Riprende la pianificazione |
POST | /api/automations/:automationId/run | Esegue ora (202 con un ID esecuzione) |
POST | /api/automations/:automationId/webhook | Attiva tramite segreto (202) |
POST | /api/automations/:automationId/webhook-secret | Genera o ruota il segreto |
DELETE | /api/automations/:automationId/webhook-secret | Disattiva il webhook |
Un utente può conservare fino a 50 automazioni; i nomi sono limitati a 200 caratteri e le istruzioni a 20.000.