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. Além disso, ativar Resultados de automações em Configurações → Notificações → Notificações por e-mail envia por e-mail o resultado de cada execução, assim que um administrador configurar um servidor de saída de e-mail (veja Notificações). 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.

Gatilhos de eventos

Um sétimo tipo, event, não tem relógio algum: ele dispara quando uma das suas notificações chega.

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

event corresponde a qualquer tipo de notificação, exceto automation-failed — uma rotina não pode reiniciar a si mesma a partir do seu próprio aviso de falha. O match opcional é um teste de substring sem diferenciação de maiúsculas e minúsculas contra o título da notificação; sem ele, toda notificação desse tipo dispara a rotina.

Um gatilho de evento nunca contribui com um horário de próxima execução. Uma automação cujos gatilhos são todos eventos, portanto, não mostra próxima execução: a lista e a caixa de diálogo de edição dizem Executa quando… em vez disso. Combinar um gatilho de evento com uma programação funciona normalmente — os gatilhos programados continuam controlando o relógio.

Duas proteções limitam o raio de alcance. Uma rotina dispara no máximo uma vez por minuto a partir de eventos, por mais movimentado que esteja o fluxo, e a notificação de falha de uma execução nunca dispara de novo a rotina que a produziu.

A execução recebe o que a disparou, anexado às suas instruções:

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

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. Um e-mail de resultado para uma execução destinada ao Work carrega o resumo que a própria execução do Work persistiu — no que o agente terminou, o mesmo texto que o histórico de execuções da tarefa mostra — e recorre ao status de uma linha da tarefa quando uma execução é anterior aos resumos persistidos. 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.

Um objeto JSON no corpo da solicitação entra na execução como seu payload de gatilho, para que a rotina possa ver o que está motivando a reação:

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

O payload é anexado às instruções que a execução executa, sob um cabeçalho Trigger payload (JSON): — tanto para execuções de chat quanto para novas tarefas do Work e rotinas vinculadas a tarefas. Somente objetos JSON são transportados (arrays e escalares são ignorados), e um payload cuja forma serializada ultrapasse 4000 caracteres é descartado em vez de truncado, com um aviso no log do servidor. Um disparo sem corpo se comporta exatamente como antes.

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.