Monitoramento de heartbeat para pipelines de agentes de IA

Você implanta um agente de IA para rodar à noite. Ele resume dados, escreve um relatório, envia uma mensagem no Slack. Você configura o monitoramento de tempo de atividade no endpoint. O monitor permanece verde. Três dias depois, você percebe que as mensagens do Slack pararam. O agente não foi executado desde terça-feira — e nada o alertou.

Este é o modo de falha que o monitoramento de batimento cardíaco foi projetado para detectar. Aqui está como funciona e por que é particularmente importante para pipelines de agentes de IA.

O padrão do interruptor de segurança

Um interruptor de segurança alerta quando algo para de acontecer. O monitoramento tradicional alerta quando algo começa a acontecer — um servidor cai, uma taxa de erro aumenta, um tempo de resposta aumenta.

Para agentes de IA, a falha perigosa é o silêncio. O agente para de rodar. Nenhum erro é gerado. Nenhum endpoint cai. O trabalho simplesmente cessa silenciosamente. Um interruptor de segurança captura isso ao esperar um sinal regular — se o sinal parar, algo está errado.

A implementação é simples: ao final de cada execução bem-sucedida do agente, após o trabalho real ser concluído, envie um ping para uma URL de batimento cardíaco. Se o ping parar de chegar dentro da janela esperada, você recebe um alerta.

Por que os agentes de IA precisam disso mais do que trabalhos tradicionais

Trabalhos cron tradicionais falham de forma barulhenta — um código de saída diferente de zero, uma exceção nos logs, uma gravação de banco de dados falhada. Você geralmente sabe que algo deu errado.

Agentes de IA falham silenciosamente. O modelo pode atingir um limite de taxa e retornar uma resposta de fallback graciosa. Uma chamada de ferramenta pode falhar silenciosamente e o agente continua sem ela. A tarefa pode ser concluída, mas produzir saída vazia ou corrompida — e seu código de aplicativo nunca gera um erro porque recebeu uma resposta HTTP válida.

Em todos esses casos, o endpoint está ativo, o trabalho "executou" e o monitoramento tradicional não vê nada. O batimento cardíaco vê tudo — porque o próprio agente decide se deve enviar o ping, e ele só envia o ping em caso de sucesso genuíno.

Conectando tudo

Crie o batimento uma vez e salve o token:

curl -X POST https://api.tickstem.dev/v1/heartbeats \
  -H "Authorization: Bearer $TICKSTEM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "nightly-summary-agent", "interval_secs": 86400, "grace_secs": 3600}'
# → {"token": "your-64-char-token", ...}

Então, no manipulador de tarefas do seu agente, envie o ping apenas após todo o trabalho real ser verificado como concluído:

async function runNightlySummaryAgent() {
  const summary = await generateSummary()

  if (!summary || summary.length < 100) {
    throw new Error("falha na geração do resumo ou retorno de saída vazia")
  }

  await postToSlack(summary)
  await writeToDatabase(summary)

  // só envie o ping após tudo ter sido bem-sucedido
  await fetch(`https://api.tickstem.dev/v1/heartbeats/${HEARTBEAT_TOKEN}/ping`, {
    method: "POST"
  }).catch(err => console.error("falha no ping do batimento cardíaco:", err)) // não fatal
}

O ping é fire-and-forget — um erro de rede no ping nunca deve bloquear seu agente de retornar.

Definindo o intervalo e a janela de graça corretos

O intervalo é com que frequência você espera que o agente execute. A janela de graça absorve a variação.

Um ponto de partida prático:

• Agentes horários: intervalo 3600s, graça 600s
• Agentes diários: intervalo 86400s, graça 3600s
• Agentes semanais: intervalo 604800s, graça 7200s

Após uma semana de execuções, verifique suas durações reais de execução e ajuste a janela de graça para 2-3x seu tempo de execução p95.

Pipelines de múltiplas etapas

Para agentes que executam um pipeline — buscar dados, processá-los, escrever resultados, notificar a parte posterior — considere um batimento por etapa se alguma etapa puder falhar silenciosamente. Um batimento no final do pipeline completo informa que o pipeline foi concluído. Batimentos de etapas individuais informam exatamente onde parou.

Uma regra útil: o ping do batimento deve ser enviado apenas após seu agente ter verificado sua própria saída — gravação no banco de dados bem-sucedida, mensagem do Slack entregue, saída passa por uma verificação de sanidade. Não antes.

Pausando durante implantações

Implantações são a fonte mais comum de falsos alertas de batimento cardíaco. Pause antes de implantar:

# antes da implantação
curl -s -X POST https://api.tickstem.dev/v1/heartbeats/$HEARTBEAT_ID/pause \
  -H "Authorization: Bearer $TICKSTEM_API_KEY"

# após a conclusão da implantação
curl -s -X POST https://api.tickstem.dev/v1/heartbeats/$HEARTBEAT_ID/resume \
  -H "Authorization: Bearer $TICKSTEM_API_KEY"

Via MCP

Se você estiver usando Claude Code ou outro cliente compatível com MCP, o servidor Tickstem MCP expõe create_heartbeat e ping_heartbeat como ferramentas nativas. O agente pode configurar seu próprio interruptor de segurança durante a etapa inicial de estruturação.

Tickstem fornece monitoramento de batimento cardíaco, verificações de tempo de atividade, agendamento de cron e verificação de e-mail sob uma única chave de API. Camada gratuita em app.tickstem.dev — sem necessidade de cartão de crédito.