Automatisations

Les automatisations exécutent une instruction selon une planification et livrent le résultat sous forme de session de chat normale. Une synthèse quotidienne de l’actualité, une révision hebdomadaire, un rapport mensuel : chaque exécution se déroule sans interface sur le serveur, apparaît dans votre liste de chats et peut être ouverte et poursuivie comme toute autre conversation.

Anatomie

Une automatisation possède un nom, des instructions en texte libre, un ou plusieurs déclencheurs, un modèle facultatif (une valeur vide signifie Auto : votre modèle de chat par défaut au moment de l’exécution), une cible d’exécution et une préférence de notification (dans l’application ou désactivée). La cible détermine ce que produit l’exécution : Session de chat (par défaut) place les instructions dans une conversation, tandis que Tâche Work lance un bac à sable Work isolé dont les instructions constituent le message initial, éventuellement sous une politique Work nommée choisie dans le formulaire. Lorsque les notifications sont activées, une exécution qui échoue apparaît aussi dans la boîte de notifications, afin que les échecs vous parviennent même lorsque la page Automatisations est fermée. Séparément, activer Résultats des automatisations sous Paramètres → Notifications → Notifications par e-mail vous envoie par e-mail le résultat de chaque exécution, une fois qu’un administrateur a configuré un serveur de messagerie sortant (voir Notifications). Les noms et instructions sont chiffrés au repos. Chaque automatisation appartient à l’utilisateur qui l’a créée.

Les déclencheurs réutilisent le modèle commun du calendrier — once, hourly, daily, weekly, monthly, yearly — et une automatisation peut en contenir jusqu’à cinq. La prochaine exécution est toujours la première occurrence à venir parmi tous ses déclencheurs, calculée dans le fuseau horaire local du serveur.

Déclencheurs par événement

Un septième type, event, ne dépend d’aucune horloge : il se déclenche quand l’une de vos notifications arrive.

{ "kind": "event", "event": "channel-mention", "match": "release" }

event accepte tout type de notification sauf automation-failed — une routine ne doit pas pouvoir se relancer elle-même à partir de son propre avis d’échec. Le champ facultatif match est un test de sous-chaîne insensible à la casse sur le titre de la notification ; en son absence, chaque notification de ce type déclenche la routine.

Un déclencheur par événement ne fournit jamais d’heure de prochaine exécution. Une automatisation dont tous les déclencheurs sont des événements n’affiche donc aucune prochaine exécution : la liste et la boîte de dialogue de modification indiquent S’exécute quand… à la place. Combiner un déclencheur par événement avec une planification fonctionne : les déclencheurs planifiés continuent de faire avancer l’horloge.

Deux garde-fous limitent le rayon d’action. Une routine se déclenche au plus une fois par minute à partir des événements, quelle que soit l’activité du flux, et la notification d’échec d’une exécution ne redéclenche jamais la routine qui l’a produite.

L’exécution reçoit ce qui l’a déclenchée, ajouté à la fin de ses instructions :

---
Trigger payload (JSON):
{"event":"channel-mention","title":"...","body":"...","href":"..."}

Exécution

Le planificateur se déclenche chaque minute derrière un bail de coordination, de sorte qu’une seule réplique fait progresser les planifications. Lorsqu’une automatisation arrive à échéance, le déclenchement consigne une exécution, met une tâche durable automation.run.v1 en file et avance next_run_at par comparaison et échange afin que chaque occurrence ne soit lancée qu’une fois au maximum. La tâche crée une session de chat portant le nom de l’automatisation, puis place l’instruction dans la file du même pipeline durable de génération de chat que toutes les conversations : routage des fournisseurs, valeurs par défaut des personas et persistance compris.

Si le serveur était arrêté au passage d’une occurrence, le déclenchement suivant lance cette occurrence une fois et ignore les créneaux antérieurs manqués. Suspendre une automatisation efface sa planification ; la reprendre ou la modifier la recalcule à partir du moment présent. Supprimer une automatisation supprime son historique d’exécutions par propagation de clé étrangère.

Les exécutions prennent leur état final dans le journal des tâches durables : réussite lorsque la génération du chat est terminée, échec lorsque l’une des tâches est placée dans la file des échecs définitifs, et échec avec l’état stalled lorsqu’une exécution en attente n’a pas démarré dans un délai de 30 minutes.

Les exécutions ciblant Work se comportent de la même façon, avec le cycle de vie Work à la place de la tâche de chat : l’exécution consigne la tâche qu’elle a créée (l’onglet Exécutions y renvoie directement), réussit lorsque l’agent termine ou s’arrête pour demander une intervention, et échoue si la tâche échoue ou est annulée. L’e-mail de résultat d’une exécution ciblant Work transporte le résumé que l’exécution Work elle-même a conservé — le même texte que l’historique des exécutions de la tâche affiche — et retombe sur la ligne d’état en une phrase de la tâche lorsqu’une exécution est antérieure aux résumés persistés. L’accès à Work est vérifié au déclenchement de la planification : retirer à un utilisateur son accès à Work désactive donc aussi ses automatisations ciblant Work ; l’exécution échoue alors avec work-access-denied au lieu d’être silencieusement ignorée. La politique sélectionnée est validée lors de l’enregistrement de l’automatisation, et ses paramètres réseau et limites de ressources par défaut s’appliquent à toutes les tâches lancées par l’automatisation. Seuls les fournisseurs directs de modèles s’exécutent dans Work, et le modèle doit prendre en charge les outils, comme dans la zone de rédaction Work.

Routines d’agent

Une automatisation ciblant Work peut plutôt être liée à une tâche Work existante au moyen de workTaskId — c’est la structure utilisée par la section Routines du panneau de détails d’un agent. Une routine liée ne crée pas une nouvelle tâche à chaque déclenchement : chaque occurrence démarre une exécution dans l’espace de travail et la conversation propres à cette tâche, avec le modèle, le fournisseur et la politique d’environnement d’exécution de la tâche. Les champs de modèle et de politique de l’automatisation ne s’appliquent donc pas, et toute politique fournie est retirée lors de l’enregistrement. La liaison est validée à l’enregistrement de l’automatisation : la tâche doit exister et appartenir à l’appelant. Au déclenchement, une tâche supprimée fait échouer l’exécution avec work-task-missing. Une tâche déjà en cours d’exécution — ou disposant d’un aperçu actif — fait échouer honnêtement l’occurrence avec work-task-busy au lieu de la placer en attente.

Déclencheurs par webhook

Au-delà de la planification, une automatisation peut être déclenchée par un système externe : chaîne d’intégration continue, service cron, domotique. Dans la boîte de dialogue de modification de l’automatisation, Déclencheur webhook → Activer génère un secret propre à l’automatisation ; seul son SHA-256 est conservé, le texte en clair n’est donc affiché qu’une seule fois. Renouveler le secret invalide immédiatement le précédent, et désactiver le webhook referme le point de terminaison.

Le système externe déclenche l’automatisation ainsi :

curl -X POST https://your-host/api/automations/<automationId>/webhook \
  -H "Authorization: Bearer lwh_..."

(X-Libre-Webhook-Secret: lwh_... fonctionne comme en-tête de remplacement.) La réponse est 202 avec l’identifiant de l’exécution mise en file : c’est le même chemin d’exécution manuelle que Exécuter maintenant, si bien que les exécutions se règlent, notifient et apparaissent dans l’historique de manière identique. La comparaison du secret s’effectue en temps constant, une automatisation inexistante et un secret erroné reçoivent la même réponse (aucun oracle sur les identifiants d’automatisation), et une automatisation suspendue répond 409 : contrairement au propriétaire qui utilise Exécuter maintenant, un appelant externe ne peut pas déclencher malgré une suspension.

Un objet JSON dans le corps de la requête accompagne l’exécution comme charge utile de déclenchement, afin que la routine puisse voir à quoi elle réagit :

curl -X POST https://your-host/api/automations/<automationId>/webhook \
  -H "Authorization: Bearer lwh_..." \
  -H "Content-Type: application/json" \
  -d '{"commit":"abc123","branch":"main"}'

La charge utile est ajoutée à la fin des instructions que l’exécution exécute, sous un en-tête Trigger payload (JSON): — pour les exécutions de chat, les nouvelles tâches Work et les routines liées à une tâche, de la même façon. Seuls les objets JSON sont transportés (les tableaux et les valeurs scalaires sont ignorés), et une charge utile dont la forme sérialisée dépasse 4 000 caractères est abandonnée plutôt que tronquée, avec un avertissement dans le journal du serveur. Un déclenchement sans corps se comporte exactement comme avant.

API

Tous les points de terminaison, sauf le déclenchement par webhook, exigent une authentification et n’agissent que sur les automatisations appartenant à l’appelant ; le déclenchement par webhook s’authentifie à la place avec le secret propre à l’automatisation.

Méthode	Chemin	Fonction
GET	/api/automations	Répertorier les automatisations
POST	/api/automations	Créer une automatisation
GET	/api/automations/occurrences?from=&to=	Occurrences calculées à venir
GET	/api/automations/runs	Historique des exécutions (filtrable)
GET	/api/automations/runs/summary	Nombre non consulté et groupes sur 30 jours
POST	/api/automations/runs/seen	Marquer les exécutions terminées comme consultées
GET	/api/automations/:automationId	Lire une automatisation
PUT	/api/automations/:automationId	Mettre à jour une automatisation
DELETE	/api/automations/:automationId	Supprimer une automatisation
POST	/api/automations/:automationId/pause	Suspendre la planification
POST	/api/automations/:automationId/resume	Reprendre la planification
POST	/api/automations/:automationId/run	Exécuter maintenant (202 avec un identifiant d’exécution)
POST	/api/automations/:automationId/webhook	Déclencher via le secret (202)
POST	/api/automations/:automationId/webhook-secret	Générer ou renouveler le secret
DELETE	/api/automations/:automationId/webhook-secret	Désactiver le webhook

Un utilisateur peut conserver jusqu’à 50 automatisations ; les noms sont limités à 200 caractères et les instructions à 20,000.