Colocar agentes em modo manutenção significa interromper a entrada de novas tarefas, permitir que o trabalho em andamento termine ou alcance um ponto seguro e somente então substituir a aplicação. Drenar é essa transição controlada. Desligar o processo de imediato deixa incerto o destino de chamadas externas, mensagens e alterações que estavam em execução.
O procedimento precisa coordenar o agendador, os consumidores da fila, o armazenamento de estado e as ferramentas do agente. Defina quem pode assumir cada tarefa, como comprovar uma ação já realizada e qual condição permite encerrar a versão antiga. Um aviso visual de manutenção, sozinho, não resolve essa coordenação.
Resumo rápido
- Bloqueie novas admissões antes de encerrar trabalhadores.
- Distinga tarefa recebida, reservada, executando e concluída.
- Finalize a etapa atual ou grave um checkpoint verificável.
- Trate ações externas sem confirmação como pendências de reconciliação.
- Teste a troca com tarefas longas, duplicidades e falhas de conexão.
O que precisa parar durante a manutenção
Uma aplicação de agentes pode receber trabalho por chat, formulário, webhook, agenda ou fila. Cada entrada exige uma decisão: rejeitar temporariamente, aceitar para processamento posterior ou encaminhar para outra instância. Documente a escolha por canal. Se a interface promete que o pedido foi recebido, ele precisa estar armazenado de forma durável antes dessa confirmação.
Separar admissão de execução evita uma armadilha frequente. A página deixa de aceitar usuários, mas um agendador continua criando tarefas e um consumidor continua reservando mensagens. O contador de tarefas ativas nunca chega a zero. O modo manutenção deve ser uma regra compartilhada, verificada por todos os pontos que iniciam trabalho.
Também determine o alcance: manutenção da aplicação inteira, de uma organização, de um tipo de ferramenta ou apenas de uma versão. Um bloqueio global pode ser desnecessário quando somente o conector de escrita precisa sair do ar. Por outro lado, bloquear apenas uma tela não protege uma migração incompatível do banco de dados.
O foco é a passagem entre versões. Conflitos durante operação normal pedem outros controles, discutidos em concorrência de agentes em registros de CRM. Na manutenção, esses controles continuam necessários porque a versão antiga e a nova podem coexistir por algum tempo.
Desenhe os estados e a posse da tarefa
Use uma máquina de estados simples, com transições permitidas pelo servidor. Uma proposta é: aguardando, reservada, executando, aguardando confirmação externa, concluída e falhou. “Em manutenção” descreve o trabalhador ou o serviço, não necessariamente a tarefa. Uma tarefa pode continuar executando enquanto o trabalhador está drenando.
| Estado observado | Conduta na drenagem | Evidência exigida |
|---|---|---|
| Aguardando | Manter na fila para a versão apta | Registro durável da solicitação |
| Reservada sem início | Liberar pela regra do consumidor | Confirmação de devolução |
| Executando leitura | Concluir ou salvar progresso | Checkpoint validado |
| Escrita externa pendente | Reconciliar antes de repetir | Recibo ou consulta ao destino |
| Concluída | Impedir reexecução | Resultado persistido e identificável |
Vincule a posse ao identificador da execução e à geração do trabalhador. Se uma reserva expirar e outro processo assumir, o processo antigo não deve continuar confirmando alterações. A aplicação pode validar uma geração crescente antes de gravar resultados. O objetivo é rejeitar a escrita de um trabalhador que perdeu a posse, mesmo quando sua conexão retorna depois.
Não confunda expiração com cancelamento real. Um temporizador pode liberar a tarefa enquanto uma requisição externa continua em andamento. Registre a operação iniciada, a chave de correlação e seu resultado conhecido. Se o desfecho estiver incerto, a retomada começa pela verificação do destino, não pela repetição automática.
Execute uma sequência de drenagem verificável
Comece registrando a intenção de manutenção e a versão afetada. Em seguida, impeça novas reservas por essa versão. A checagem precisa acontecer na admissão efetiva, de modo que uma corrida entre “verificar disponibilidade” e “reservar tarefa” não permita trabalho novo depois do bloqueio. Registre quando a barreira entrou em vigor.
Depois, retire a instância da distribuição de novas requisições e interrompa o consumo de novas mensagens conforme a tecnologia utilizada. Na documentação de consumidores do RabbitMQ, cancelar o consumidor interrompe novas entregas, mas não resolve as entregas já em trânsito. Por isso, monitore separadamente o que ainda está reservado e o que efetivamente começou.
Permita que as tarefas ativas terminem dentro de um prazo definido pela operação. Para trabalhos longos, escolha pontos de interrupção entre etapas, com estado já persistido. Um checkpoint útil identifica a entrada, a versão do fluxo, os passos confirmados e as pendências. Um parágrafo solto produzido pelo modelo não substitui esse registro.
Ao final do prazo, classifique cada tarefa restante. Ela pode continuar em uma janela maior, ser interrompida com segurança ou ir para revisão. Não reclassifique indiscriminadamente tudo como falha para alcançar zero. O contador deve representar a realidade e permitir localizar qualquer tarefa sem destino definido.
Antes da troca, confirme que não existem proprietários antigos autorizados a escrever, reservas sem tratamento ou operações externas sem responsável. Só então finalize a instância. A nova versão começa com admissão controlada e verifica se entende os checkpoints que poderá receber. Essa validação deve anteceder a abertura geral da fila.
Conecte fila, processo e efeitos externos
A documentação de confirmações do RabbitMQ diferencia a confirmação do consumidor da confirmação ao publicador. São mecanismos com papéis distintos. Na aplicação, confirme a mensagem apenas quando o tratamento previsto estiver assegurado. Uma confirmação antecipada pode esconder trabalho perdido; uma confirmação atrasada pode permitir nova entrega após uma desconexão.
Essa possibilidade exige idempotência: repetir a mesma solicitação deve encontrar a operação anterior ou produzir um efeito controlado. Defina uma chave por ação de negócio, como a criação de uma minuta, em vez de depender somente do identificador da chamada de rede. Quando o destino não oferece uma operação idempotente, mantenha um registro local e uma estratégia explícita de reconciliação.
Em Kubernetes, o ciclo de término do Pod oferece um período de encerramento antes da finalização forçada. Isso não significa que qualquer tarefa longa será concluída. O controlador da aplicação precisa reagir ao término e respeitar o tempo disponível. Configure a janela a partir do comportamento observado da carga, com margem para persistência e fechamento de conexões.
O guia de hooks de ciclo de vida esclarece que o tempo de preStop entra no mesmo orçamento de término. Um hook que ocupa toda a janela deixa pouco tempo ao processo principal. Mantenha suas ações previsíveis e evite fazer dele um segundo executor de tarefas sem supervisão.
Se o sistema usa Celery, o guia de trabalhadores distingue formas de encerramento, incluindo o término que aguarda tarefas em execução. Verifique o comportamento do sinal e da configuração realmente empregados. Um procedimento escrito para uma tecnologia não deve ser aplicado por analogia a outra.
Para ações que aguardam pessoas, como aprovação de uma proposta, mantenha a espera em um registro durável. Não mantenha um processo antigo vivo indefinidamente só porque falta uma decisão. A fila de aprovações humanas precisa permitir que uma versão compatível retome o fluxo depois da manutenção.
Exemplo: agência de turismo em Recife
Considere uma agência de turismo em Recife com um agente que organiza solicitações de passeios e prepara propostas. O cenário é ilustrativo. O agente consulta disponibilidade, monta uma minuta e deixa o envio para aprovação humana. A equipe precisa trocar a aplicação que integra o formulário ao sistema de atendimento.
Antes da troca, o formulário continua aceitando pedidos em uma caixa durável, mas informa que o processamento está temporariamente aguardando. O agendador deixa de distribuir novos pedidos à versão antiga. Os trabalhadores em drenagem concluem leituras já iniciadas e salvam minutas com a versão do roteiro utilizado.
Uma tarefa está aguardando a confirmação de criação de uma minuta no sistema externo. A conexão caiu depois do envio. A equipe não devolve essa tarefa imediatamente como se nada tivesse ocorrido. Primeiro consulta o destino pela referência da operação. Se a minuta existe, registra sua identificação; se não for possível determinar o resultado, mantém a tarefa em reconciliação com responsável identificado.
Outra tarefa aguarda aprovação da gerente. Seu estado passa para armazenamento durável e o trabalhador é liberado. A nova aplicação só oferece a continuação se conseguir interpretar a versão desse estado. Caso o formato tenha mudado, uma migração validada ou um encaminhamento humano resolve a diferença antes de qualquer envio.
O ensaio de aceitação inclui um pedido chegando exatamente durante o bloqueio, outro com leitura demorada e uma desconexão após escrita externa. Para cada um, a equipe verifica o destino e o histórico. O resultado esperado é que todo pedido esteja pendente, concluído ou explicitamente encaminhado, com um único responsável autorizado por vez.
Erros comuns
Parar apenas a interface. Webhooks, agendas e consumidores continuam sendo entradas. Faça um inventário dos produtores e teste cada caminho com a manutenção ativada.
Usar ausência de CPU como sinal de conclusão. Um trabalhador pode estar esperando uma resposta de rede ou aprovação. A condição de saída deve consultar estados de negócio e operações pendentes.
Retomar todo trabalho automaticamente. Uma etapa pode já ter produzido efeito no destino. A reconciliação precisa acontecer antes de qualquer repetição de escrita.
Migrar o banco enquanto a versão antiga ainda escreve. Planeje compatibilidade durante a coexistência ou bloqueie as operações afetadas. Verifique o comportamento da versão anterior antes de iniciar uma mudança estrutural.
Não ensaiar o retorno à versão anterior. Um rollback da aplicação pode encontrar estados gravados em formato novo. Teste a leitura desses estados ou estabeleça um ponto além do qual a recuperação segue outro procedimento.
Esquecer credenciais durante a espera. Uma tarefa retomada pode encontrar autenticação expirada. O fluxo deve renovar acesso pela regra do provedor e preservar o progresso, como discutido em credenciais temporárias para agentes.
Perguntas frequentes
Preciso esperar a fila ficar vazia?
Não necessariamente. A fila pode preservar pedidos para a nova versão. O requisito é que a versão antiga deixe de admitir trabalho e que suas tarefas reservadas ou em execução tenham destino conhecido. Diferencie tamanho da fila de tarefas sob sua responsabilidade.
Posso cancelar uma chamada ao modelo no meio?
Depende do cliente e do provedor. Mesmo quando a conexão é interrompida, registre o estado local e verifique o que poderá ser retomado. Não trate o cancelamento de uma conexão como prova de cancelamento de todas as operações externas associadas.
Como escolher o prazo de drenagem?
Meça duração de etapas, tempo de gravação e comportamento em falhas. Use esses dados para definir uma janela operacional e uma política para excedentes. Tarefas sem limite devem ser redesenhadas em etapas retomáveis ou encaminhadas explicitamente.
Uma manutenção pode conviver com a versão nova?
Sim, se filas, contratos de dados e permissões forem compatíveis. Identifique a versão de cada execução e impeça que duas instâncias assumam a mesma tarefa. Valide essa coexistência em um ensaio antes da troca em produção.
Qual prova demonstra que a drenagem funcionou?
Um relatório que reconcilie tarefas admitidas, concluídas, transferidas e pendentes, acompanhado dos identificadores das operações externas. O teste também precisa mostrar que nenhum trabalho novo começou na versão bloqueada após a barreira de manutenção.
