Desligamento seguro de workers de agentes de IA

O deploy terminou e a tarefa ficou pela metade

Uma nova versão do agente entra em produção. O orquestrador encerra um worker antigo enquanto ele prepara um documento e aguarda a confirmação de uma atualização no CRM. A mensagem volta à fila. Outro worker repete a etapa porque não sabe se o efeito externo aconteceu.

O deploy parece saudável. A operação ganhou um documento incompleto e duas atualizações possíveis.

Desligamento seguro de workers de agentes de IA é o protocolo que retira uma instância de serviço sem aceitar novas tarefas, dá destino às execuções abertas, preserva checkpoints e confirma quais recursos e efeitos ainda exigem tratamento.

Esse protocolo é necessário em deploys, redução de escala, manutenção, reinício de servidor, preempção e encerramento de ambiente.

Desligar o worker e cancelar a tarefa são decisões diferentes

O worker é uma capacidade de processamento. A tarefa é uma unidade de trabalho empresarial.

Quando um worker recebe sinal de encerramento, a tarefa pode:

terminar dentro do prazo disponível;
salvar checkpoint e ser retomada por outra instância;
devolver a mensagem para a fila;
pausar em estado conhecido;
entrar em reconciliação;
falhar com causa explícita;
exigir intervenção humana.

O cancelamento de tarefas em agentes de IA encerra uma unidade cuja intenção perdeu validade. No desligamento do worker, a intenção pode continuar válida. O sistema precisa transferir ou concluir o trabalho sem tratar a manutenção como cancelamento do negócio.

Um kill forçado encerra o processo. Ele não confirma que tarefas, efeitos e leases chegaram a um estado seguro.

Modele o ciclo de retirada

Estados úteis para o worker incluem:

ativo
retirada_solicitada
fora_do_balanceador
sem_novas_entradas
drenando
aguardando_tarefas
pronto_para_encerrar
encerramento_forcado
encerrado

A transição deve responder:

quem iniciou a retirada;
motivo e versão do deploy;
quando o worker deixou de receber tráfego;
quando parou de buscar novas tarefas;
quais unidades estavam ativas;
prazo disponível;
checkpoints produzidos;
tarefas concluídas, devolvidas ou incertas;
recursos liberados;
sinais de encerramento recebidos;
condição que autorizou a saída.

Separar esses estados ajuda a distinguir um worker que ainda termina trabalho de outro que já pode desaparecer.

Pare a entrada antes de começar a drenar

A primeira regra é simples: uma instância em retirada não deveria continuar aumentando sua fila local.

A sequência costuma envolver:

marcar o worker como indisponível para novas requisições;
removê-lo do balanceamento ou falhar o readiness check;
interromper polling de novas tarefas;
preservar heartbeats das unidades já assumidas;
concluir, checkpointar ou devolver cada unidade;
liberar conexões, locks, credenciais e arquivos temporários;
registrar o estado final;
encerrar o processo.

A ordem precisa respeitar os componentes usados. Remover o tráfego HTTP não interrompe o consumidor da fila. Parar o polling não fecha chamadas já iniciadas. Encerrar a conexão com o banco antes de salvar checkpoints elimina justamente a evidência necessária para retomar.

Trate tráfego síncrono e trabalho assíncrono separadamente

Um serviço de agentes pode receber requisições pela web e consumir tarefas em segundo plano.

Requisições síncronas

A instância deixa de ser elegível para novas conexões. Requisições já abertas recebem prazo para concluir ou uma resposta que permita nova tentativa segura.

Filas

O worker interrompe a busca de mensagens. As unidades já recebidas mantêm posse apenas pelo período válido. Se não puderem concluir, precisam ser devolvidas ou ter a posse encerrada de forma conhecida.

Tarefas programadas

O agendador não deve iniciar nova ocorrência na instância em retirada. A identidade da ocorrência permite que outra instância assuma sem criar duas execuções.

Callbacks e webhooks

Callbacks esperados não podem depender de um endereço efêmero do worker. O retorno deve chegar a uma camada durável que localize a unidade de trabalho vigente.

Aprovações humanas

Uma execução aguardando pessoa não deve manter o processo vivo. Persista o estado e retome em outro worker quando a decisão chegar.

O artigo sobre agentes de IA para tarefas longas mostra como separar execução, espera e estado durável.

Dê um prazo de graça compatível com o trabalho

Plataformas de orquestração costumam oferecer uma janela entre o sinal de término e o corte forçado. No Kubernetes, a terminação graciosa de um Pod usa uma janela configurável, com valor padrão documentado de 30 segundos. Ao fim do período, processos restantes recebem encerramento forçado.

Trinta segundos não são um padrão de negócio. O prazo precisa considerar:

duração típica e de cauda das tarefas;
tempo para salvar checkpoint;
confirmação de efeitos externos;
encerramento de conexões;
atraso para retirar tráfego;
comportamento do orquestrador;
limite máximo aceitável para o deploy;
custo de repetir trabalho;
capacidade disponível nos outros workers.

Uma janela longa demais prende deploys e reduções de escala. Uma janela curta demais converte toda manutenção em retentativa, desperdício e estado incerto.

O prazo também deve ser menor que timeouts externos relevantes ou coordenado com eles. Caso contrário, a infraestrutura mata o worker enquanto ele ainda acredita possuir autoridade.

Use o sinal como início do protocolo

Em contêineres Linux, o processo costuma receber SIGTERM antes de um corte forçado. O handler deve iniciar a retirada, não apenas chamar exit.

Ao receber o sinal:

marque a instância como drenando;
bloqueie novas unidades;
informe tarefas ativas;
propague cancelamento técnico para operações que suportam retomada;
solicite checkpoint em pontos seguros;
pare timers e novas retentativas locais;
aguarde até o prazo definido;
registre o que não terminou;
finalize recursos;
encerre com código coerente.

A documentação do Kubernetes também descreve hooks PreStop. O relógio da janela de terminação já está correndo quando o hook começa. Um hook demorado consome o tempo que o processo teria para encerrar. Por isso, ele deve executar somente o trabalho necessário para retirar a instância e iniciar a drenagem.

Hooks podem ser chamados mais de uma vez em situações raras. O procedimento de retirada precisa ser idempotente.

Checkpoints precisam existir antes do deploy

Salvar estado apenas quando o sinal de desligamento chega é frágil. O processo pode travar, perder rede ou receber corte abrupto.

Use checkpoints durante a execução, especialmente depois de:

leitura de lote;
extração cara;
chamada de ferramenta confirmada;
aprovação humana;
gravação no sistema oficial;
criação de arquivo;
conclusão de uma etapa difícil de repetir.

Quando a retirada começa, o worker usa o último checkpoint válido e registra o trecho ainda em andamento. Outra instância pode retomar sem reconstruir toda a tarefa.

O checkpoint deve indicar entrada, etapa, versão, saída, efeitos confirmados, pendências, ferramenta usada e condição para prosseguir. Um resumo livre sem identificadores não oferece base suficiente para recuperação.

Coordene a posse da mensagem

Uma fila pode tornar a mensagem visível novamente se o worker não concluir antes do prazo de posse. Durante o desligamento, a arquitetura precisa escolher entre:

Concluir e confirmar

Adequado quando a etapa restante cabe com margem na janela e não depende de espera imprevisível.

Renovar a posse

Pode fazer sentido quando o worker ainda progride e existe tempo para terminar. A renovação não deve ultrapassar a autoridade real da instância.

Devolver cedo

Permite que outro worker assuma. Antes, persista checkpoint e interrompa qualquer capacidade de produzir efeitos pela tentativa antiga.

Manter em estado incerto

Necessário quando uma chamada externa foi enviada e a confirmação não chegou. A próxima instância consulta o destino antes de repetir.

O guia sobre visibility timeout em filas de agentes de IA detalha posse, renovação e reentrega. No desligamento, essas regras precisam caber dentro do prazo da infraestrutura.

Retire a autoridade da execução antiga

Um processo pode continuar por alguns segundos depois de perder sua mensagem ou depois que outra instância começou a retomada. Duas cópias não devem possuir autoridade simultânea.

Use:

versão da execução;
lease com expiração;
token de cercamento;
condição de escrita;
chave idempotente;
confirmação no sistema de destino;
bloqueio de ferramentas para tentativa antiga.

Antes de uma consequência, a ferramenta verifica se a execução ainda possui a versão ou token vigente. Assim, um worker atrasado pode terminar cálculo local, mas não grava estado depois da transferência.

A página sobre controle de concorrência em agentes de IA explica como uma execução antiga perde poder após a mudança de posse.

Separe encerramento técnico de compensação empresarial

No desligamento, o worker pode fechar conexões, remover arquivos temporários, parar timers e liberar locks. Esses procedimentos são técnicos.

Uma mensagem enviada, uma cobrança criada ou um estágio alterado já pertence à operação. O encerramento não deveria tentar desfazer automaticamente esses efeitos.

Classifique cada ação aberta:

não iniciada;
iniciada e cancelável;
iniciada e não cancelável;
concluída e confirmada;
resultado incerto;
compensação autorizada;
decisão humana necessária.

O próximo worker consulta a fonte oficial e continua pelo estado observado. Repetir a etapa porque o processo morreu pode criar o mesmo efeito duas vezes.

A reconciliação em agentes de IA compara intenção, registro local e destino antes de corrigir ou repetir.

Workers duráveis precisam reconhecer o desligamento

A documentação da Temporal descreve que um worker em shutdown para de buscar novas tarefas e permite que atividades em andamento concluam durante o período de graça configurado. Depois desse prazo, contextos de atividades recebem cancelamento e o serviço pode reagendar o trabalho conforme timeouts e políticas.

Isso só funciona bem quando a atividade:

observa o contexto de cancelamento;
envia heartbeat quando necessário;
mantém etapas retomáveis;
não bloqueia indefinidamente;
usa idempotência em efeitos externos;
possui timeouts coerentes;
persiste progresso suficiente.

Uma biblioteca pode entregar o sinal. A semântica de recuperação continua pertencendo ao processo.

Redução de escala exige olhar a fila antes

Desligar metade dos workers durante um pico pode preservar todas as tarefas e ainda violar o prazo operacional.

Antes de reduzir capacidade, verifique:

tarefas ativas por worker;
idade da fila;
taxa de chegada e conclusão;
tempo estimado de drenagem;
atividades longas ou caras;
aprovações pendentes;
dependências degradadas;
capacidade dos workers restantes;
folga para retentativas;
janela útil das unidades.

A documentação de boas práticas da Temporal recomenda observar tarefas ativas antes do scale-down, principalmente quando existem atividades longas ou caras. A retirada deve considerar o custo de reexecutar, não apenas a utilização média.

O planejamento de capacidade para agentes de IA ajuda a ligar chegada, serviço, fila e prazo.

Exemplo: worker que prepara propostas

Um worker possui duas unidades abertas.

Unidade A

O documento foi gerado e salvo. O envio ainda não começou.

Unidade B

A atualização do CRM foi enviada, mas a confirmação não chegou.

O deploy inicia a retirada.

o worker sai do balanceador e para de buscar tarefas;
a unidade A grava checkpoint e conclui o arquivo dentro do prazo;
o envio permanece bloqueado para a nova versão da proposta;
a unidade B entra em aguardando_confirmacao_externa;
o worker registra o identificador da chamada ao CRM;
a mensagem B volta à fila com a mesma chave idempotente;
outro worker consulta o CRM antes de considerar nova escrita;
conexões e arquivos temporários são encerrados;
a instância informa que a drenagem terminou.

O deploy não cancelou as propostas. Ele preservou o trabalho concluído e transferiu a incerteza com evidência suficiente para continuar.

Teste o caminho de encerramento

Inclua cenários como:

sinal recebido sem tarefa ativa;
requisição síncrona em andamento;
mensagem recém-recebida;
atividade perto de concluir;
chamada ao modelo sem resposta;
escrita externa com confirmação perdida;
tarefa aguardando aprovação;
checkpoint que falha;
lease que vence durante a drenagem;
outro worker assumindo cedo;
dois sinais de encerramento;
hook executado mais de uma vez;
prazo de graça esgotado;
processo morto sem sinal;
scale-down durante pico;
deploy com versões incompatíveis de estado.

Para cada teste, confirme novas entradas, tarefas abertas, efeitos, checkpoints, mensagens reentregues, recursos liberados e evidência da saída.

Métricas para operar a retirada

Acompanhe:

workers ativos, drenando e encerrados;
tempo entre sinal e parada de entrada;
tarefas ativas no início da drenagem;
tarefas concluídas dentro do prazo;
checkpoints produzidos;
mensagens devolvidas;
execuções retomadas com sucesso;
tarefas repetidas desde o início;
efeitos duplicados bloqueados;
estados externos incertos;
encerramentos forçados;
hooks repetidos ou falhos;
leases perdidos durante a retirada;
duração total do deploy;
impacto na idade da fila;
prazo operacional violado após scale-down.

Um deploy rápido pode esconder reprocessamento caro. A métrica precisa mostrar o estado das unidades, não apenas o tempo até o contêiner desaparecer.

Checklist de desligamento seguro

[ ] O worker para de aceitar novas entradas antes de drenar?
[ ] Tráfego síncrono, filas e agendadores possuem controles próprios?
[ ] O sinal de encerramento inicia um protocolo conhecido?
[ ] A janela de graça comporta checkpoint e limpeza essenciais?
[ ] Hooks são leves e idempotentes?
[ ] Tarefas longas observam cancelamento técnico?
[ ] Checkpoints existem durante a execução normal?
[ ] A posse da mensagem cabe no prazo de retirada?
[ ] Execuções antigas perdem autoridade antes da retomada?
[ ] Efeitos externos usam confirmação e idempotência?
[ ] Estados incertos seguem para reconciliação?
[ ] Esperas humanas sobrevivem fora do processo?
[ ] Recursos temporários são liberados sem apagar evidência?
[ ] Scale-down considera fila, tarefas ativas e prazo?
[ ] O caminho forçado foi testado?

Encerrar uma instância não deveria abandonar o trabalho

A infraestrutura só enxerga processos e prazos. A operação enxerga propostas, pedidos, análises e decisões que precisam continuar válidos depois do deploy.

Um desligamento seguro para novas entradas, drena o que cabe, persiste o restante e retira a autoridade da tentativa antiga. Cada unidade termina concluída, retomável ou explicitamente incerta. Essa disciplina permite atualizar e redimensionar agentes sem transformar manutenção técnica em retrabalho invisível.

Fontes oficiais verificadas em 24 de setembro de 2026: