Automatizaciones
Las automatizaciones ejecutan una instrucción según un horario y entregan el resultado como chat normal. Un resumen diario, una revisión semanal o un informe mensual: cada ejecución ocurre sin interfaz en el servidor, aparece en tu lista y puede abrirse y continuarse como cualquier conversación.
Anatomía
Una automatización tiene nombre, instrucciones libres, hasta cinco desencadenadores, un modelo opcional (vacío significa Auto: tu modelo predeterminado en ese momento), un destino y una preferencia de notificación. Sesión de chat es el destino predeterminado; Tarea de Work inicia un sandbox Work aislado, opcionalmente bajo una política elegida. Con notificaciones, los fallos llegan también a la bandeja. Nombres e instrucciones se cifran en reposo y pertenecen a su creador.
Los desencadenadores reutilizan once, hourly, daily, weekly, monthly y yearly. La siguiente ejecución
es siempre la ocurrencia futura más cercana, calculada en la zona horaria local del servidor.
Ejecución
El planificador actúa cada minuto tras un lease de coordinación, por lo que solo una réplica avanza horarios.
Cuando vence una automatización, registra una ejecución, encola automation.run.v1 y avanza next_run_at mediante
compare-and-set para que cada ocurrencia se dispare como máximo una vez. El trabajo crea un chat con el nombre de
la automatización y encola la instrucción mediante la misma canalización duradera, con enrutamiento, personas y persistencia.
Si el servidor estaba apagado, el siguiente tick ejecuta una vez la ocurrencia y omite las anteriores. Pausar borra el horario; reanudar o editar lo recalcula. Eliminar borra el historial mediante cascada de clave externa.
Las ejecuciones se resuelven desde el registro duradero: éxito al terminar la generación, fallo al llegar a dead-letter,
y stalled si no comienzan en 30 minutos.
Los destinos Work usan su ciclo de vida, guardan la tarea creada y terminan correctamente si el agente completa o pide
entrada. El acceso se comprueba al dispararse: si se revoca, falla como work-access-denied. La política seleccionada
se valida al guardar y aplica sus límites. Solo funcionan proveedores directos y modelos capaces de usar herramientas.
Rutinas de agentes
Una automatización dirigida a Work también puede vincularse a una tarea de Work
existente mediante workTaskId; es la estructura que utiliza la sección Rutinas
del panel de detalles de un agente. Una rutina vinculada no crea una
tarea nueva en cada activación: cada ocurrencia inicia una ejecución dentro del
espacio y la conversación propios de esa tarea, utilizando su modelo, proveedor y
política de entorno. Por tanto, los campos de modelo y política de la automatización
no se aplican, y cualquier política proporcionada se descarta al guardar. La
vinculación se valida al guardar la automatización (la tarea debe existir y pertenecer
al llamante). En el momento de la activación, una tarea eliminada hace fallar la
ejecución como work-task-missing; una tarea que ya se está ejecutando —o mantiene
una vista previa activa— hace fallar honestamente la ocurrencia como
work-task-busy, en vez de ponerla en cola.
Disparadores por webhook
Además del horario, un sistema externo puede disparar una automatización: una canalización de CI, un servicio cron, la domótica de casa. En el diálogo de edición de la automatización, Disparador de webhook → Habilitar genera un secreto propio de esa automatización; solo se guarda su SHA-256, así que el texto en claro se muestra exactamente una vez. Rotar el secreto invalida el anterior de inmediato, y desactivar el webhook vuelve a cerrar el endpoint.
El sistema externo dispara la automatización así:
curl -X POST https://your-host/api/automations/<automationId>/webhook \
-H "Authorization: Bearer lwh_..."
(X-Libre-Webhook-Secret: lwh_... funciona como cabecera alternativa). La respuesta es 202
con el ID de la ejecución encolada: es la misma ruta de ejecución manual que Ejecutar
ahora, de modo que las ejecuciones se resuelven, notifican y aparecen en el historial de
forma idéntica. La comparación del secreto es de tiempo constante, una automatización
inexistente y un secreto incorrecto responden igual (sin oráculo de identificadores de
automatización), y una automatización pausada responde 409: a diferencia del propietario con
Ejecutar ahora, quien llama desde fuera no puede disparar a través de una pausa.
API
Todos los endpoints salvo el disparo por webhook exigen autenticación y solo operan sobre recursos del llamante; el disparo por webhook se autentica con el secreto de la automatización.
| Método | Ruta | Propósito |
|---|---|---|
GET | /api/automations | Listar automatizaciones |
POST | /api/automations | Crear una automatización |
GET | /api/automations/occurrences?from=&to= | Próximas ocurrencias |
GET | /api/automations/runs | Historial filtrable |
GET | /api/automations/runs/summary | No vistos y grupos de 30 días |
POST | /api/automations/runs/seen | Marcar finalizadas como vistas |
GET | /api/automations/:automationId | Leer |
PUT | /api/automations/:automationId | Actualizar |
DELETE | /api/automations/:automationId | Eliminar |
POST | /api/automations/:automationId/pause | Pausar |
POST | /api/automations/:automationId/resume | Reanudar |
POST | /api/automations/:automationId/run | Ejecutar ahora (202 e ID) |
POST | /api/automations/:automationId/webhook | Disparar con el secreto (202) |
POST | /api/automations/:automationId/webhook-secret | Generar o rotar el secreto |
DELETE | /api/automations/:automationId/webhook-secret | Desactivar el webhook |
Cada usuario puede conservar 50 automatizaciones; los nombres admiten 200 caracteres y las instrucciones 20,000.