# Automacao e Agendamento

## Cron Jobs

Agende despertar de agentes com temporizacao precisa. Cron jobs persistem entre reinicializacoes do Gateway e suportam padroes flexiveis de agendamento.

### Tipos de Agendamento

| Tipo | Descricao | Exemplo |
|------|-----------|---------|
| **Expressao cron** | Sintaxe cron padrao com fuso horario | `0 7 * * *` (diariamente as 7h) |
| **Intervalo** | Repete em intervalos fixos | `30m`, `2h`, `1d` |
| **Unico** | Executa uma vez em um horario especifico | `2026-03-15T16:00:00Z` |

### Alvos de Sessao

- **Sessao principal** -- Enfileira como um evento de sistema na conversa principal do agente
- **Sessao isolada** -- Executa em uma sessao dedicada (`cron:<jobId>`) para evitar contaminar conversas principais

### Modos de Entrega

| Modo | Descricao |
|------|-----------|
| **Nenhum** | Execucao silenciosa (nenhuma saida postada) |
| **Anunciar** | Posta o resultado de volta em um canal especifico |
| **Webhook** | HTTP POST do resultado para uma URL externa |

### Lembretes Unicos

Defina um lembrete para um horario especifico. O agente acorda, processa o lembrete e opcionalmente exclui o job apos a execucao.

### Jobs Recorrentes

Agende tarefas repetitivas com expressoes cron e suporte a fuso horario. Jobs rastreiam seu historico de execucao (sucesso, falha, temporizacao).

---

## Webhooks

Receba eventos de servicos externos e roteie-os para agentes.

### Gmail Pub/Sub

Integre com o sistema de notificacoes push do Gmail para acionar acoes de agentes quando emails chegam:

1. Configure um topico e assinatura GCP Pub/Sub
2. Configure filtragem por label do Gmail
3. Aponte a entrega push para sua URL de webhook
4. Neotask recebe mensagens e enfileira eventos de agente

### Webhooks Personalizados

Registre endpoints HTTP que acionam turnos de agente quando chamados. Util para integrar com pipelines CI/CD, sistemas de monitoramento ou qualquer servico que possa enviar requisicoes HTTP.

---

## Eventos de Sistema

Eventos de sistema sao sinais que acordam um agente para processamento:

- **Imediato** -- Processa no proximo heartbeat
- **Proximo heartbeat** -- Enfileira para a proxima verificacao agendada

Use eventos de sistema para workflows reativos -- agentes acordam quando algo acontece em vez de em um agendamento fixo.

---

## Heartbeat

O heartbeat e um sinal periodico (padrao ~15 segundos) que da aos agentes uma oportunidade de processar trabalho pendente:

- Verificar novos eventos de sistema
- Processar mensagens enfileiradas
- Executar automacoes pendentes

O heartbeat pode ser habilitado, desabilitado ou configurado por agente.

---

## Hooks

Automacao orientada a eventos que aciona comandos shell ou scripts em resposta a eventos do Gateway:

- **Na mensagem** -- Executa quando uma mensagem e recebida
- **No turno do agente** -- Executa antes ou depois de um agente processar uma mensagem
- **No evento do canal** -- Executa em eventos especificos de canal (entrar, sair, reacao)

Hooks rodam no host do Gateway e tem acesso aos dados de contexto do evento.

---

## Casos de Uso

| Cenario | Solucao |
|---------|---------|
| Briefing matinal diario | Cron job as 7h → agente resume atualizacoes noturnas |
| Geracao de relatorio semanal | Cron job toda segunda → agente gera e envia relatorio por email |
| Monitoramento de email | Webhook do Gmail → agente processa emails recebidos |
| Notificacoes de build | Webhook CI/CD → agente anuncia resultados de build no Discord |
| Verificacao de dados a cada hora | Cron baseado em intervalo → agente verifica dashboard e alerta sobre anomalias |
| Posts sociais agendados | Cron job → agente redige e publica conteudo em horarios otimos |