Agendamentos: os três tipos de gatilho

Camada funcional

O agente pode executar sozinho, na hora marcada. Três formatos, com semânticas bem diferentes — e escolher errado é o engano mais comum do módulo.

No formulário de criação, os cartões que aparecem são Agendamento, Recorrente e Evento de App — esse terceiro não é uma variação de horário, é o outro tipo de gatilho, disparado por um evento externo, coberto em outra página deste guia. O disparo único não tem cartão ali: ele é criado pelo próprio agente ou pela API, nunca escolhido nessa tela.

Regra de decisão: "faça isso na próxima segunda às 9h" é um gatilho de disparo único, não de agendamento. Um gatilho de agendamento marcado para segunda dispara toda segunda, para sempre.

Como o gatilho de disparo único se desativa após disparar, ele também é a peça certa para uma rotina que se reagenda a cada execução — a própria execução cria a próxima.

Fuso horário: uma decisão e uma armadilha fechada

O fuso padrão, quando não informado, é o de São Paulo, definido em um único lugar compartilhado por toda a plataforma — a interface, a API e a ferramenta usada pelo agente concordam por construção.

Para o disparo único, a data exige fuso explícito. Sem isso, a interpretação assumiria em silêncio o fuso do servidor e o gatilho dispararia no instante errado. O contrato de data com fuso é imposto de forma idêntica na interface, na API e na ferramenta usada pelo agente.

Além disso, quem agenda ainda precisa garantir que o instante está no futuro.

Como o disparo acontece

O despachante roda a cada minuto:

• Seleciona os gatilhos habilitados cujo próximo disparo já venceu, do mais antigo para o mais novo.
• Processa no máximo 50 por rodada.

Consequências práticas: a granularidade efetiva é de um minuto, e um acúmulo acima de 50 gatilhos vencidos é drenado ao longo de várias rodadas — sempre com prioridade para os mais atrasados.

O que dá para fazer

Um quarto caminho: o agente agenda a própria volta

Além da tela e da API, um agendamento também pode nascer de dentro de uma conversa: o próprio agente, durante a execução, decide marcar sua volta — sem que uma pessoa precise criar o gatilho manualmente.

Esse agendamento não é um quarto tipo: ele vira um dos três formatos que esta página já descreve, e passa a aparecer normalmente na lista de gatilhos do agente. Se o agente tentar pedir algo fora do que os três formatos representam — como vários horários no mesmo dia, ou um agendamento recorrente com dia do mês fixo —, o pedido é recusado em vez de aproximado: evita que alguém confie num horário que nunca vai disparar.

Duas garantias valem só para esse caminho:

• Cancelar é definitivo. Uma vez desligado, o agendamento não volta a ligar sozinho.
• O agente sempre enxerga o estado real. Quando ele mesmo consulta ou cancela o que agendou dessa forma, vê o que está de fato ativo na plataforma — mesmo depois de a conversa em que agendou ter terminado —, em vez de uma lista vazia por não "lembrar" daquela sessão.

[CORRIGIDO 20/08/2026] Esse quarto caminho perdia texto do prompt acima de 1000 caracteres

O ponto em que a plataforma capturava esse agendamento foi pensado para registro, não para reexecução: ele corta a mensagem em 1000 caracteres e marca o resto como omitido. Só que, para a plataforma, esse texto não é registro — é a mensagem que reinvoca a conversa no disparo. O agente retomava a execução com menos da metade da instrução que ele mesmo tinha escrito.

Medido em produção em 20/08/2026, antes do conserto: dos 269 gatilhos criados por esse caminho, 136 vieram cortados (nenhum passava de 1015 caracteres) — 133 desses já haviam disparado, em 3 organizações e 16 conversas, somando 180.616 caracteres de instrução perdidos.

O conserto passa a guardar a mensagem integral num momento anterior ao corte — momento que, por construção, sempre acontece antes dele no mesmo turno. No disparo, a mensagem é reconstruída a partir dessa cópia, não do texto cortado. A cópia expira sozinha depois de 26 horas, independente de o gatilho voltar a agendar: guardar o texto de trabalho do agente por mais tempo do que a reconstrução exige seria excesso.

Limites e modos de falha conhecidos

• Um gatilho recorrente pode, em certas condições, disparar em duplicidade.
• O teto de 50 por rodada protege o sistema, mas significa que um pico de gatilhos vencidos atrasa os últimos da fila.