Agendando tarefas recorrentes em fluxos de trabalho de agentes de IA

Quando você constrói um agente de IA que faz algo útil — resume documentos, monitora um feed, envia um relatório, sincroniza dados — você eventualmente se depara com a mesma pergunta: como faço para que ele execute em um cronograma? Não uma vez, acionado manualmente. Em um cronograma, de forma confiável, enquanto eu não estou assistindo.

A resposta parece óbvia: trabalho cron. Mas trabalhos cron para agentes de IA têm um conjunto específico de modos de falha que tarefas agendadas tradicionais não têm. Este post aborda o problema e como resolvê-lo de forma limpa.

Por que o agendamento de agentes de IA é diferente

Um trabalho cron tradicional executa um script determinístico. Ele tem sucesso ou falha. Você geralmente pode dizer qual a partir do código de saída ou da saída.

A execução de um agente de IA é diferente em três aspectos:

• Duração variável. A mesma tarefa do agente pode levar 8 segundos ou 4 minutos, dependendo do modelo, da entrada e se alguma ferramenta precisou de tentativas. Um tempo limite fixo ou mata execuções legítimas ou oculta aquelas que estão fora de controle.
• Sucesso parcial. O agente pode completar três de quatro etapas antes de falhar silenciosamente na quarta. O trabalho sai 0, mas o trabalho não foi concluído.
• Dependências a montante. Outros sistemas podem estar esperando pela saída do agente. Se a execução do agente for atrasada ou pulada, nada a montante é acionado — e nada te alerta.

Esses modos de falha tornam importante pensar cuidadosamente sobre como você agenda agentes, não apenas se você os agenda.

As opções de agendamento

Existem três abordagens comuns, cada uma com diferentes compensações.

Opção 1: Cron nativo da plataforma (Vercel, Railway, Render)

Se o seu agente é executado como uma função sem servidor ou um serviço hospedado, a plataforma geralmente oferece agendamento cron embutido. Você configura um cronograma, a plataforma envia uma solicitação HTTP para seu endpoint no momento certo.

Isso funciona até que não funcione. O cron da plataforma não tem histórico de execução, não alerta sobre falhas e não garante entrega exatamente uma vez. Se a plataforma tentar novamente a solicitação — o que ela fará, eventualmente — seu agente será executado duas vezes. Para tarefas idempotentes, isso é irritante. Para tarefas que enviam e-mails ou processam pagamentos, é um bug.

Opção 2: Uma fila com um agendador

Uma abordagem mais robusta: um agendador dedicado publica uma mensagem em uma fila no horário agendado. Um trabalhador retira da fila e executa o agente. Quem retirar a mensagem primeiro vence — a mensagem desaparece, então nenhum segundo trabalhador pode pegá-la.

Isso lhe dá semântica de exatamente uma vez por meio de operações atômicas de fila. O BRPOP do Redis é a implementação clássica: ele bloqueia até que uma mensagem chegue, depois a remove e a retorna para exatamente um chamador. Dez trabalhadores podem estar esperando — apenas um recebe o trabalho.

A compensação é a sobrecarga operacional: você precisa de uma fila, um agendador e trabalhadores, todos em execução e monitorados. Para um único agente, isso geralmente é exagerado.

Opção 3: Agendamento baseado em HTTP com histórico de execução

A abordagem que funciona bem para a maioria das implantações de agentes: um agendador externo envia um POST HTTP para o endpoint do seu agente no cronograma que você define. O agendador registra cada execução — cabeçalhos de solicitação, status de resposta, corpo da resposta, duração, se foi executado a tempo.

Quando a execução falha, você tem o registro completo: o que foi enviado, o que voltou, quanto tempo levou. Quando as execuções param de acontecer, você recebe um alerta. É isso que o Tickstem fornece.

curl -X POST https://api.tickstem.dev/v1/jobs \
  -H "Authorization: Bearer $TICKSTEM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "daily-summary-agent", "url": "https://your-app.com/agents/daily-summary", "schedule": "0 8 * * *", "timeout_secs": 300}'

O agendador dispara um POST para seu endpoint às 08:00 todos os dias. Seu endpoint executa o agente e retorna quando termina. A execução — código de status, corpo da resposta, duração — é registrada e disponível no painel ou via API.

Conectando com o servidor MCP

Se você está construindo com Claude Code ou outro agente compatível com MCP, o Tickstem expõe suas ferramentas de agendamento nativamente via MCP. O agente pode registrar seus próprios trabalhos cron sem sair do editor:

{
  "mcpServers": {
    "tickstem": {
      "command": "tsk-mcp",
      "env": { "TICKSTEM_API_KEY": "your-key" }
    }
  }
}

Com o servidor MCP em execução, o agente pode chamar create_job, list_jobs e get_executions como ferramentas nativas. Sem troca de contexto, sem visita a um painel separado para configurar o cronograma.

A integração com o MCP significa que o agente também pode inspecionar seu próprio histórico de execução. Se uma execução anterior falhou, o agente vê isso na próxima invocação e pode ajustar — tentar novamente uma etapa, notificar um humano ou registrar um erro mais específico.

Lidando com a duração variável do agente

Defina timeout_secs generosamente. Para um agente que geralmente leva 30 segundos, mas ocasionalmente leva 3 minutos em entradas pesadas, um tempo limite de 60 segundos gera falhas falsas. Comece com 5-10x sua duração típica, depois aperte uma vez que você tenha dados históricos de execução para trabalhar.

O Tickstem registra a duração real de cada execução. Após uma semana de execuções, você terá um p99 realista — use isso como sua linha de base de tempo limite.

Combinando agendamento com monitoramento de heartbeat

O agendamento informa quando o agente começa. Não informa se o agente realmente completou o trabalho que deveria ter feito.

Para isso, adicione um ping de heartbeat no final da tarefa do agente — após todo o trabalho real ser concluído, não antes. Se o ping parar de chegar, algo deu errado dentro da execução, mesmo que a resposta HTTP tenha sido 200.

# No final do manipulador de tarefas do seu agente
curl -s -X POST https://api.tickstem.dev/v1/heartbeats/$HEARTBEAT_TOKEN/ping

Agendamento + heartbeat juntos fornecem a imagem completa: o agendador confirma que o agente foi invocado a tempo, o heartbeat confirma que ele fez o que deveria ter feito. Veja monitoramento de heartbeat para trabalhos em segundo plano para o padrão completo.

Uma nota sobre exatamente uma vez para agentes

A maioria das tarefas de agentes não é naturalmente idempotente. Enviar um e-mail de resumo duas vezes, criar um duplicado...