Heartbeat em tarefas longas de agentes de IA

O processo está vivo. O trabalho, talvez não

Um worker começou a analisar um pacote de documentos. O processo continua respondendo, a conexão permanece aberta e nenhuma exceção foi registrada. Quarenta minutos depois, a tarefa ainda mostra em_execucao.

Ela pode estar processando um arquivo grande. Também pode ter parado numa dependência, entrado num loop ou perdido a capacidade de salvar o resultado. Ver somente que o processo existe não permite decidir se a equipe espera, cancela ou recupera a unidade.

Um heartbeat é um sinal periódico enviado por uma atividade para informar que a execução continua sob controle. O sinal ganha valor quando carrega progresso observável e um checkpoint que outra tentativa consegue usar.

Este artigo trata da saúde de uma atividade longa. O guia sobre visibility timeout em filas governa a posse temporária da mensagem. A página sobre agentes para tarefas longas cobre o fluxo completo, com estado, limites e retomada. Aqui, a pergunta é mais estreita: como detectar trabalho parado sem confundir processo vivo com tarefa saudável.

Separe quatro sinais diferentes

Misturar vida, progresso, posse e conclusão produz recuperação errada.

Vida do processo

Mostra que a instância responde a uma verificação técnica. Um health check pode confirmar que o worker está conectado e consegue receber trabalho. Isso não prova que uma atividade específica avançou.

Heartbeat da atividade

Mostra que uma unidade em execução alcançou um ponto conhecido dentro do intervalo esperado. O sinal pertence à atividade, não ao servidor inteiro.

Posse da mensagem

Indica que um consumidor ainda possui o direito temporário de processar uma mensagem. Filas podem chamar esse mecanismo de visibility timeout, acknowledgment deadline ou lock.

Conclusão confirmada

Prova que a saída passou pelos critérios e que os efeitos externos esperados foram confirmados. Heartbeat nenhum substitui esse desfecho.

Um worker pode estar saudável enquanto uma atividade está travada. A atividade pode emitir heartbeat e já ter perdido a posse da mensagem. Também pode concluir o cálculo e ainda deixar a escrita no CRM em estado incerto.

Use heartbeat somente em trabalho que precisa dele

Atividades curtas e idempotentes costumam ser recuperadas com timeout e nova tentativa. Heartbeat acrescenta utilidade quando o trabalho:

demora o suficiente para tornar a detecção tardia cara;
possui etapas ou lotes observáveis;
pode preservar progresso parcial;
precisa responder a cancelamento durante a execução;
depende de arquivo grande, ferramenta externa ou processamento variável;
perderia muito trabalho se toda falha exigisse recomeçar;
mantém recurso exclusivo, credencial curta ou reserva de capacidade.

Exemplos incluem processar centenas de documentos, acompanhar uma exportação, esperar retorno de um job externo, executar uma migração em lotes ou preparar um dossiê com várias fontes.

Não transforme cada chamada curta em atividade com heartbeat. O sinal cria estado, política e monitoramento adicionais. Ele precisa reduzir uma incerteza operacional concreta.

Heartbeat útil carrega progresso verificável

Enviar apenas ainda_vivo comprova pouco. Um processo preso no mesmo loop pode repetir essa mensagem para sempre.

Registre detalhes que permitam responder:

qual unidade está sendo processada;
qual versão da entrada continua vigente;
qual etapa terminou;
até onde o trabalho foi persistido;
quantos itens foram concluídos e quantos faltam;
qual dependência está ativa;
quando ocorreu o último avanço material;
qual checkpoint permite retomada;
se novas ações externas continuam autorizadas;
qual condição deve cancelar a execução.

Um payload conceitual pode ser:

{
  "job_id": "dossie-2026-09-28-017",
  "attempt_id": "tentativa-02",
  "input_version": "v4",
  "stage": "extracao",
  "processed_items": 36,
  "total_items": 80,
  "last_item_id": "doc-036",
  "checkpoint_id": "cp-036",
  "external_effect": "nao_iniciado",
  "business_deadline": "2026-09-28T18:00:00Z"
}

Os dados são fictícios. Num sistema real, o heartbeat deve carregar referências mínimas. Documentos, segredos e conteúdo sensível permanecem nas fontes autorizadas.

Defina o intervalo pela falha que precisa ser detectada

O intervalo não nasce de um número confortável. Ele precisa considerar:

quanto tempo a atividade passa legitimamente sem avanço visível;
quanto tempo a operação tolera uma tarefa parada;
custo de recomeçar ou recuperar;
frequência suportada pelo orquestrador;
latência e instabilidade da rede;
tempo necessário para salvar um checkpoint;
capacidade disponível para outra tentativa;
prazo útil da tarefa.

Um intervalo curto detecta falha cedo, mas aumenta tráfego e pode gerar falsos vencimentos durante uma operação legítima. Um intervalo longo reduz ruído e mantém capacidade presa quando o worker desaparece.

Meça por classe. Processar uma página e converter um vídeo possuem distribuições diferentes. Use percentis do intervalo entre avanços, além da duração total.

A documentação da Temporal define Heartbeat Timeout como o tempo máximo entre heartbeats de uma Activity. A AWS Step Functions separa o limite de heartbeat do timeout máximo da tarefa: enviar heartbeat reinicia o relógio de heartbeat, mas não amplia indefinidamente a duração total permitida.

Mantenha um teto total

Heartbeat não deve renovar a atividade para sempre.

Além do intervalo entre sinais, defina:

timeout total da atividade;
prazo da tarefa empresarial;
número máximo de itens ou páginas;
teto de custo;
limite de tentativas;
validade da entrada e da autorização;
comportamento quando o teto é atingido.

Uma atividade pode emitir sinais regulares e ainda consumir capacidade sem entregar valor. O teto total obriga o sistema a concluir, salvar estado, reduzir escopo ou encaminhar a unidade.

Salve antes de anunciar progresso

O heartbeat deve descrever trabalho já persistido, não uma intenção.

Use esta ordem:

processe uma unidade ou etapa;
valide a saída intermediária;
salve o checkpoint durável;
registre a versão da entrada;
envie o heartbeat com referência ao checkpoint;
avance para a próxima unidade.

Se o sinal informa 36 de 80 e o checkpoint salvo termina no item 29, a recuperação acreditará num progresso que não existe. O novo worker pode pular sete documentos.

Também evite salvar todo o conteúdo dentro do heartbeat. O sinal aponta para o estado durável. Ele não vira outra base de documentos sem política de acesso e retenção.

Faça a retomada partir do checkpoint confirmado

Quando o heartbeat vence, o orquestrador pode marcar a tentativa como falha e iniciar outra conforme a política de retentativa.

A nova tentativa precisa:

carregar a mesma identidade empresarial da tarefa;
localizar o último checkpoint confirmado;
validar versão, prazo e autorização;
consultar efeitos externos iniciados;
retomar somente o trabalho elegível;
criar outro attempt_id sem apagar o anterior;
manter a mesma chave idempotente para o mesmo efeito.

O detalhe do heartbeat reduz trabalho repetido. Ele não prova que uma chamada externa terminou. Se a tentativa anterior enviou uma atualização e caiu antes da confirmação, a recuperação consulta o destino ou abre reconciliação antes de repetir.

O artigo sobre idempotência em agentes de IA aprofunda essa diferença entre comando, efeito e confirmação.

Use heartbeat para entregar cancelamento

Em orquestradores de workflow, heartbeats também podem ser o ponto em que a atividade recebe uma solicitação de cancelamento.

Para responder de forma segura:

envie sinais durante esperas e loops longos;
verifique cancelamento antes de abrir outra unidade;
pare novas chamadas externas;
termine ou abandone somente em ponto seguro;
persista o último estado válido;
libere locks, arquivos e recursos temporários;
classifique efeitos em andamento;
confirme o encerramento ao orquestrador.

Uma atividade que passa vinte minutos numa biblioteca bloqueante sem emitir sinal pode atrasar a percepção de cancelamento. Divida o trabalho ou use uma forma de acompanhar a operação sem fingir granularidade que a ferramenta não oferece.

O guia de cancelamento de tarefas em agentes de IA mostra como propagar a decisão para filhos, filas e ferramentas.

Não use heartbeat como token de autoridade

Receber heartbeats recentes não concede permissão empresarial.

Antes de uma ação externa, revalide:

tarefa ainda aberta;
versão da intenção ainda atual;
autorização ainda válida;
prazo empresarial não vencido;
posse técnica quando aplicável;
limite de custo e volume;
aprovação exigida;
ausência de conclusão anterior.

A execução pode estar viva e a oportunidade já ter sido fechada manualmente. Também pode continuar processando depois que um contrato, preço ou permissão mudou.

Coloque a verificação perto da ferramenta. Texto no prompt não impede tecnicamente uma tentativa antiga de produzir efeito.

Modele estados que distingam espera de falha

Uma atividade sem heartbeat recente pode representar situações diferentes:

worker caiu;
processo travou;
rede impediu o sinal;
dependência está lenta;
atividade terminou, mas a confirmação falhou;
checkpoint falhou antes do sinal;
tarefa perdeu validade;
cancelamento ainda não foi observado.

Estados úteis incluem:

em_execucao_com_progresso;
aguardando_dependencia;
heartbeat_atrasado;
heartbeat_vencido;
cancelamento_solicitado;
checkpoint_confirmado;
efeito_externo_incerto;
elegivel_para_retentativa;
exige_reconciliacao;
expirado_por_negocio;
concluido_confirmado.

A classificação determina a próxima ação. Repetir automaticamente toda atividade com sinal vencido pode duplicar a etapa mais sensível.

Exemplo: análise de oitenta documentos

Considere um agente que extrai campos de oitenta documentos e prepara um pacote para revisão humana.

Antes de iniciar

O orquestrador registra job_id, versão, lista dos documentos, critérios, prazo, permissões, custo máximo e política de retomada.

Durante cada lote

O worker processa quatro documentos, valida o schema, salva os resultados e envia heartbeat com contagem e checkpoint_id.

Numa dependência lenta

O worker informa a etapa e o identificador da operação externa, sem declarar item concluído. O timeout total continua valendo.

Se o heartbeat vencer

A tentativa é marcada como falha. Antes de outra começar, o sistema lê o último checkpoint, confirma que a tarefa ainda é útil e consulta operações externas pendentes.

Na retomada

A nova tentativa começa depois do último item persistido. Resultados já aprovados não são recalculados. Um documento que ficou em estado incerto segue para conferência.

Na conclusão

O pacote passa pelo critério de aceite, recebe referência durável e entra na fila de revisão. Só então a tarefa termina como concluido_confirmado.

Teste falhas no ponto em que o sinal engana

Inclua cenários como:

worker cai antes do primeiro heartbeat;
processo permanece vivo sem avançar;
heartbeat chega depois do timeout;
checkpoint falha e o sinal não deve afirmar progresso;
rede perde dois sinais e volta;
cancelamento chega durante um lote;
entrada muda durante a atividade;
prazo empresarial vence com worker saudável;
chamada externa termina sem confirmação;
nova tentativa começa enquanto a anterior ainda executa;
checkpoint está corrompido;
atividade atinge o timeout total mesmo com heartbeats;
volume real ultrapassa o limite;
resultado já existe no destino.

Verifique estado, chamadas, efeitos, retomada, tempo de detecção e ausência de duplicidade.

Métricas para operar heartbeats

Acompanhe por classe de atividade:

atividades iniciadas e concluídas;
intervalo entre heartbeats;
heartbeats atrasados e vencidos;
tempo entre último progresso e detecção;
tarefas com sinal repetido sem avanço material;
checkpoints válidos e inválidos;
itens recuperados sem reprocessamento;
trabalho repetido depois da retomada;
cancelamentos observados no heartbeat;
efeitos externos incertos;
retentativas abertas por timeout;
duas tentativas ativas para a mesma unidade;
duração total e tempo parado por dependência;
tarefas vencidas pelo prazo empresarial.

O alerta precisa explicar o caso: atividade doc-017 não avança há 8 minutos; último checkpoint cp-036; nenhuma escrita externa iniciada; retentativa aguardando expiração da tentativa anterior.

Erros comuns

Emitir sinal num timer separado

Um timer continua enviando vivo enquanto a rotina principal está presa. O heartbeat deixa de representar progresso.

Enviar antes de salvar

A recuperação pula trabalho que existia apenas na memória da tentativa perdida.

Usar a mesma configuração para toda atividade

Classes com duração e custo diferentes produzem falsos alarmes ou recuperação tardia.

Renovar além do prazo útil

O sistema mantém trabalho tecnicamente ativo depois que o resultado perdeu valor.

Repetir sem conferir o destino

A tentativa anterior pode ter produzido o efeito e falhado somente na confirmação.

Confundir heartbeat com health check

O servidor responde, mas a unidade continua travada.

Colocar conteúdo sensível no sinal

O mecanismo de controle vira uma cópia adicional de dados empresariais.

Checklist de implementação

[ ] A atividade realmente precisa de heartbeat?
[ ] O sinal pertence a uma unidade identificada?
[ ] Existe diferença explícita entre vida, progresso, posse e conclusão?
[ ] O heartbeat descreve avanço persistido?
[ ] O checkpoint é salvo antes do sinal?
[ ] Intervalo e timeout foram definidos por classe?
[ ] Existe timeout total mesmo com sinais regulares?
[ ] Prazo de negócio pode encerrar trabalho ainda saudável?
[ ] A retomada usa identidade e versão estáveis?
[ ] Efeitos externos são consultados antes da repetição?
[ ] Cancelamento chega à atividade em pontos seguros?
[ ] A execução perde autoridade quando versão ou permissão muda?
[ ] Estados incertos seguem para reconciliação?
[ ] Alertas mostram checkpoint, consequência e próxima ação?
[ ] Testes incluem worker vivo sem progresso?

Fontes oficiais verificadas em 28 de setembro de 2026

Detecting Activity failures, Temporal Documentation. A página diferencia timeouts de Activity e descreve Heartbeat Timeout e detalhes usados na retomada.
Activity Timeouts no SDK Python, Temporal Documentation. A página mostra heartbeats, Heartbeat Timeout e uso durante Activities.
SendTaskHeartbeat, AWS Step Functions API Reference. A documentação explica que o sinal reinicia o relógio de heartbeat, enquanto o timeout máximo da tarefa continua limitando a duração.
Handling errors in Step Functions workflows, AWS Step Functions Developer Guide. A página documenta erros de heartbeat e timeout em workflows.

Nomes, limites e comportamento de cancelamento variam entre plataformas e SDKs. Valide a implementação escolhida no ambiente de teste e preserve a política empresarial fora de defaults do fornecedor.

O sinal precisa provar que ainda existe trabalho governado

Heartbeat ajuda a detectar falha antes que uma tarefa longa mantenha capacidade presa por horas. O sinal fica confiável quando aponta para progresso persistido, respeita um teto total e conduz a uma recuperação conhecida.

A arquitetura continua responsável por identidade, prazo, autorização, idempotência e confirmação no destino. Com esses controles, o heartbeat deixa de ser um simples estou vivo e passa a responder o que a operação precisa saber: até onde avançou, o que pode ser retomado e qual efeito ainda exige cuidado.