Automações
As automações executam uma instrução de acordo com uma programação e entregam o resultado como uma sessão normal de chat. Um resumo diário de notícias, uma revisão semanal, um relatório mensal: cada execução ocorre sem interface no servidor, aparece na sua lista de conversas e pode ser aberta e continuada como qualquer outra conversa.
Anatomia
Uma automação tem nome, instruções em texto livre, um ou mais gatilhos, um modelo opcional (vazio significa Auto: seu modelo de chat padrão no momento da execução), um destino de execução e uma preferência de notificação (no aplicativo ou desativada). O destino determina o que uma execução produz: Sessão de chat (o padrão) coloca as instruções na fila como uma conversa, enquanto Tarefa do Work inicia um sandbox isolado do Work com as instruções como mensagem inicial, opcionalmente sob uma política nomeada do Work escolhida no formulário. Com as notificações ativadas, uma execução com falha também aparece na caixa de entrada de notificações, para que as falhas cheguem até você mesmo com a página Automações fechada. Nomes e instruções são criptografados em repouso. Cada automação pertence ao usuário que a criou.
Os gatilhos reutilizam o modelo compartilhado do calendário — once, hourly, daily,
weekly, monthly, yearly — e uma automação pode conter até cinco. A
próxima execução é sempre a ocorrência futura mais próxima entre seus gatilhos,
calculada no fuso horário local do servidor.
Execução
Uma rodada do agendador ocorre a cada minuto sob uma concessão de coordenação, de modo que exatamente
uma réplica avance as programações. Quando uma automação vence, a rodada registra uma
execução, enfileira uma tarefa durável automation.run.v1 e avança next_run_at
com compare-and-set, para que cada ocorrência seja disparada no máximo uma vez. A tarefa cria
uma sessão de chat com o título da automação e coloca a instrução na fila
por meio do mesmo pipeline durável de geração de chat usado por todas as conversas —
incluindo roteamento de provedor, padrões da persona e persistência.
Se o servidor estava inativo quando uma ocorrência passou, a rodada seguinte dispara essa ocorrência uma vez e ignora horários perdidos mais antigos. Pausar uma automação limpa sua programação; retomar ou editar a recalcula a partir do momento atual. Excluir uma automação remove seu histórico de execuções por meio de uma exclusão em cascata de chave estrangeira.
As execuções são encerradas com base no registro durável de tarefas: bem-sucedidas quando a geração da conversa
termina, com falha quando a tarefa entra em dead letter e com falha stalled quando
uma execução enfileirada não começa em até 30 minutos.
As execuções destinadas ao Work têm o mesmo comportamento, mas usam o ciclo de vida do Work no lugar da
tarefa de chat: a execução registra a tarefa criada (a aba Execuções leva diretamente
a ela), é bem-sucedida quando o agente conclui — ou para para solicitar entrada — e
falha quando a tarefa falha ou é cancelada. O acesso ao Work é verificado quando a
programação dispara; portanto, revogar o acesso de um usuário ao Work também silencia suas
automações destinadas ao Work. Nesse caso, a execução falha como work-access-denied, sem
ser ignorada silenciosamente. Uma política selecionada é validada quando a automação
é salva, e seu padrão de rede e seus limites de recursos se aplicam a todas as tarefas
iniciadas pela automação. Somente provedores diretos de modelos são executados no Work, e o
modelo precisa oferecer suporte a ferramentas — as mesmas regras do campo de composição do Work.
Rotinas de agente
Uma automação destinada ao Work também pode se vincular a uma tarefa existente do Work por meio de
workTaskId — a estrutura por trás da seção Rotinas no
painel de detalhes de um agente. Uma rotina vinculada não cria uma
nova tarefa a cada disparo: cada ocorrência inicia uma execução dentro do espaço de trabalho e da conversa
da própria tarefa, usando o modelo, o provedor e a política de ambiente de execução da tarefa;
portanto, os campos de modelo e política da automação não se aplicam, e qualquer
política informada é descartada ao salvar. O vínculo é validado quando a
automação é salva (a tarefa deve existir e pertencer ao solicitante). No momento do disparo,
uma tarefa excluída faz a execução falhar como work-task-missing, e uma tarefa que já esteja
em execução — ou que mantenha uma visualização ativa — faz a ocorrência falhar corretamente
como work-task-busy, em vez de colocá-la na fila.
Gatilhos de webhook
Além da programação, uma automação pode ser disparada por um sistema externo — um pipeline de CI, um serviço de cron, a automação residencial. Na caixa de diálogo de edição da automação, Gatilho de webhook → Ativar gera um segredo específico daquela automação; apenas o SHA-256 é armazenado, então o texto puro aparece exatamente uma vez. Girar o segredo invalida o anterior imediatamente, e desativar o webhook fecha o endpoint de novo.
O sistema externo dispara a automação com:
curl -X POST https://your-host/api/automations/<automationId>/webhook \
-H "Authorization: Bearer lwh_..."
(X-Libre-Webhook-Secret: lwh_... funciona como cabeçalho alternativo.) A resposta
é 202 com o id da execução enfileirada — o mesmo caminho de execução manual de
Executar agora, de modo que as execuções se encerram, notificam e aparecem no
histórico de forma idêntica. A comparação do segredo é de tempo constante, uma
automação inexistente e um segredo errado respondem de forma idêntica (sem revelar
ids de automação) e uma automação pausada responde 409: ao contrário do Executar
agora do proprietário, um chamador externo não dispara através de uma pausa.
API
Todos os endpoints, exceto o disparo por webhook, exigem autenticação e operam somente nas automações do próprio solicitante; o disparo por webhook autentica com o segredo específico da automação.
| Método | Caminho | Finalidade |
|---|---|---|
GET | /api/automations | Listar automações |
POST | /api/automations | Criar uma automação |
GET | /api/automations/occurrences?from=&to= | Próximas ocorrências calculadas |
GET | /api/automations/runs | Histórico de execuções (filtrável) |
GET | /api/automations/runs/summary | Contagem não vista + grupos de 30 dias |
POST | /api/automations/runs/seen | Marcar execuções concluídas como vistas |
GET | /api/automations/:automationId | Ler uma automação |
PUT | /api/automations/:automationId | Atualizar uma automação |
DELETE | /api/automations/:automationId | Excluir uma automação |
POST | /api/automations/:automationId/pause | Pausar a programação |
POST | /api/automations/:automationId/resume | Retomar a programação |
POST | /api/automations/:automationId/run | Executar agora (202 com um ID de execução) |
POST | /api/automations/:automationId/webhook | Disparar com o segredo (202) |
POST | /api/automations/:automationId/webhook-secret | Gerar ou girar o segredo |
DELETE | /api/automations/:automationId/webhook-secret | Desativar o webhook |
Um usuário pode manter até 50 automações; os nomes têm limite de 200 caracteres e as instruções, de 20.000.