Visibility timeout em filas de agentes de IA

A tarefa continuou, mas a fila entregou outra cópia

Um agente retira da fila um pedido para analisar documentos e atualizar um cadastro. A leitura dos arquivos demora mais que o esperado. Antes de o worker terminar, o prazo de invisibilidade da mensagem vence. A fila entrega a mesma unidade para outro worker.

As duas execuções agora trabalham sobre o mesmo pedido. Uma grava o resultado. A outra termina segundos depois e também tenta gravar. O problema começou antes da duplicidade: a arquitetura perdeu a noção de quem ainda possuía o direito temporário de processar aquela mensagem.

Visibility timeout é o intervalo em que uma mensagem recebida fica indisponível para outros consumidores. Em serviços que usam termos como acknowledgment deadline, message lock ou lease, o mecanismo cumpre função parecida: reservar temporariamente a unidade enquanto um consumidor trabalha.

A reserva reduz processamento concorrente da mesma mensagem. Ela não garante execução única, não confirma efeito externo e não substitui idempotência. O desenho seguro combina posse temporária, renovação controlada, confirmação do resultado e recuperação depois da perda da posse.

O que acontece entre receber e concluir

Uma fila com entrega pelo menos uma vez costuma separar quatro momentos:

a mensagem fica disponível;
um consumidor recebe a mensagem e obtém uma posse temporária;
o consumidor processa a unidade;
depois da conclusão válida, ele confirma ou remove a mensagem.

Se o consumidor falha antes da confirmação, a mensagem volta a ficar disponível. Essa reentrega permite recuperar trabalho depois de queda, indisponibilidade ou reinício.

O mesmo mecanismo também abre uma janela de duplicidade. A execução antiga pode continuar viva depois de perder a posse. A mensagem pode ser entregue outra vez. Uma confirmação pode chegar tarde. Por isso, o prazo da fila organiza disponibilidade, mas a aplicação ainda precisa controlar efeitos.

Na documentação do Amazon SQS, a mensagem recebida fica temporariamente invisível para outros consumidores. A exclusão ocorre depois do processamento. O Google Cloud Pub/Sub usa acknowledgment deadline e permite estender esse prazo por mensagem. Os nomes mudam; a decisão operacional permanece: por quanto tempo o sistema considera que um consumidor ainda trabalha sobre a unidade.

Visibility timeout, timeout de execução e prazo de negócio

Misturar esses relógios produz configurações frágeis.

Visibility timeout protege a posse da mensagem

Ele define quando outra execução pode receber a unidade. Um prazo curto demais aumenta reentregas durante trabalho saudável. Um prazo longo demais demora para recuperar mensagens abandonadas.

Timeout de execução limita o worker

Ele determina quanto tempo a atividade pode continuar antes de ser interrompida ou marcada como falha. Esse limite pertence ao executor ou ao orquestrador, não à fila.

Prazo de negócio limita a utilidade

Uma tarefa pode estar tecnicamente processável e já ter perdido valor. Um follow-up depois do fechamento da oportunidade, uma atualização sobre pedido cancelado ou um relatório depois da reunião exigem expiração ou nova decisão.

Os três prazos precisam conversar. A posse não deveria sobreviver ao prazo útil da tarefa. O worker não deveria continuar depois de perder autoridade. A reentrega não deveria executar uma intenção vencida.

Comece pela distribuição real do tempo de processamento

Escolher um número a partir da média costuma esconder a cauda. Se a maioria das mensagens termina em vinte segundos e uma parcela relevante leva dois minutos, um prazo de trinta segundos criará concorrência justamente nos casos mais difíceis.

Meça por classe de tarefa:

espera antes de começar;
tempo de leitura e preparação;
duração de chamadas ao modelo;
duração de ferramentas e APIs;
tempo de validação;
tempo até confirmação no destino;
percentis de duração, além da média;
quantidade de renovações;
perda de posse durante execução;
reentrega e duplicidade observada.

Separe classes com perfis muito diferentes. Um resumo curto e uma análise de cinquenta documentos não deveriam depender da mesma configuração apenas porque chegam pela mesma fila.

A página sobre latência em agentes de IA ajuda a decompor o tempo entre fila, modelo, ferramenta, revisão e confirmação. Para visibility timeout, a medida principal é o período durante o qual o consumidor precisa conservar autoridade sobre a mensagem.

Use renovação para trabalho de duração variável

Quando a duração varia bastante, um prazo fixo grande recupera falhas devagar. Um prazo fixo pequeno provoca reentrega durante execuções legítimas. A renovação permite começar com uma reserva limitada e estendê-la enquanto o worker continua saudável.

O Google Cloud chama esse controle de lease management. As bibliotecas de alto nível podem estender periodicamente o acknowledgment deadline de mensagens ainda não confirmadas. No Amazon SQS, a aplicação pode alterar o visibility timeout durante o processamento.

Uma política de renovação precisa declarar:

intervalo esperado entre renovações;
duração de cada extensão;
período total máximo de posse;
estado mínimo que prova progresso;
comportamento quando a renovação falha;
momento em que novas ações ficam proibidas;
destino da unidade depois do teto.

Renovar apenas porque o processo ainda existe pode esconder workers travados. A extensão deve acompanhar progresso observável, como lote concluído, etapa alterada ou checkpoint persistido.

Pare de agir quando a posse for perdida

O caso perigoso ocorre quando o worker perde a reserva e continua executando. Outro consumidor pode receber a mesma mensagem, enquanto o primeiro ainda possui credenciais e contexto para produzir efeitos.

Ao detectar perda de posse, a execução deve:

impedir novas chamadas externas;
preservar o último estado confiável;
registrar a etapa e o motivo;
não confirmar a mensagem;
identificar efeitos já iniciados;
encaminhar estados incertos para reconciliação;
encerrar ou aguardar uma decisão explícita.

Essa regra precisa existir no código que chama ferramentas. Uma instrução no prompt não retira autoridade técnica de um worker antigo.

Quando o sistema de destino aceita controle de versão ou token de cercamento, use essa proteção perto da escrita. O artigo sobre controle de concorrência em agentes de IA detalha como impedir que uma execução com posse vencida altere o estado atual.

Confirme a mensagem somente depois do resultado válido

Confirmar cedo demais transforma uma falha posterior em perda de trabalho. Confirmar tarde demais aumenta a chance de reentrega mesmo depois da conclusão.

Defina o que conta como conclusão para cada unidade. Em uma atualização de CRM, pode exigir:

saída validada;
política aplicada;
escrita aceita pelo CRM;
identificador do registro retornado;
consulta ou confirmação do estado final;
evidência persistida;
próxima ação conhecida.

Gerar um texto correto ainda não concluiu a tarefa quando a responsabilidade inclui alterar um sistema.

Também evite usar a confirmação da fila como prova de que o destino mudou. A fila conhece o estado da mensagem. O CRM, ERP, agenda ou sistema financeiro conhece o efeito empresarial.

Idempotência continua obrigatória

Mesmo com o prazo bem configurado, reentregas podem acontecer. Serviços de fila documentam comportamentos de entrega que exigem tolerância a duplicidade. Queda de rede, confirmação tardia, renovação perdida e reinício do consumidor continuam possíveis.

Associe cada efeito a uma chave estável, por exemplo:

tipo_de_fluxo + unidade_de_trabalho + etapa + versao_da_intencao

Antes de criar outra consequência, consulte o registro de processamento ou o sistema de destino. Se a ação já ocorreu, ligue a nova entrega ao efeito existente. Se o resultado ficou incerto, reconcilie antes de repetir.

O guia de idempotência em agentes de IA cobre a diferença entre comando enviado, efeito produzido e confirmação recebida.

Modele estados que expliquem a posse

Um status genérico processando não mostra se a execução ainda possui autoridade.

Use campos e estados como:

mensagem_recebida;
posse_valida_ate;
worker_id;
tentativa;
ultima_renovacao;
ultimo_checkpoint;
efeito_nao_iniciado;
efeito_em_confirmacao;
concluido_confirmado;
posse_perdida;
reentrega_detectada;
exige_reconciliacao;
expirado_por_validade.

Registre o identificador empresarial separado do identificador técnico da mensagem. Uma reentrega pode receber outro contexto técnico e continuar representando o mesmo pedido, oportunidade ou documento.

Exemplo: análise de documentos em segundo plano

Considere um agente que analisa um pacote de documentos e prepara campos para revisão.

Entrada

A mensagem contém caso_id, versão, referências protegidas dos arquivos, prazo e tipo de análise. Os documentos não são copiados integralmente para a fila.

Recebimento

O worker registra a tentativa, obtém a posse e verifica se o caso permanece aberto. Se outra execução já concluiu a mesma versão, encerra sem repetir.

Processamento

O trabalho ocorre em lotes. Depois de cada lote, o worker persiste checkpoint e renova a posse. O checkpoint guarda IDs processados, pendências e versão das instruções.

Escrita

Antes de salvar o resultado, o worker confirma que a posse continua válida e que o caso não mudou. A escrita usa versão esperada e chave idempotente.

Confirmação

A mensagem só é confirmada depois que o destino retorna o identificador e o sistema registra a evidência da conclusão.

Perda de posse

Se a renovação falha, o worker para antes de nova escrita. Uma chamada já enviada segue para confirmação ou reconciliação. A entrega seguinte retoma do checkpoint e consulta o destino antes de repetir.

Esse fluxo trata a fila como transporte durável. A verdade do caso e o controle dos efeitos permanecem nos sistemas responsáveis.

Erros comuns

Definir um prazo enorme para evitar duplicidade

O prazo grande reduz algumas reentregas, mas atrasa a recuperação quando o worker morre. Também mantém muitas mensagens em voo e pode esconder tarefas travadas.

Renovar sem comprovar progresso

Um processo vivo pode estar preso em loop, esperando uma dependência ou repetindo a mesma etapa. Renove com estado e teto.

Confirmar logo após receber

A fila perde a capacidade de recuperar a unidade se o worker falhar. Esse padrão só cabe quando outro mecanismo durável já assumiu integralmente o trabalho e a transferência foi confirmada.

Confiar que a fila entrega uma vez

A arquitetura deve tolerar reentrega. Mesmo recursos de exactly-once possuem escopo e condições próprias; eles não tornam efeitos externos automaticamente idempotentes.

Misturar posse da mensagem com aprovação de negócio

O worker pode possuir a mensagem e continuar sem autoridade para aprovar desconto, enviar comunicação ou alterar pagamento. A fila governa processamento técnico, não alçada empresarial.

Ignorar o trabalho depois da perda da posse

A execução antiga pode continuar. Sem verificação de autoridade perto da ferramenta, duas cópias alcançam o destino.

Métricas para operar o mecanismo

Acompanhe:

mensagens recebidas e confirmadas;
tempo de processamento por classe;
percentis de duração;
renovações por mensagem;
falhas de renovação;
perda de posse durante execução;
reentregas;
duas execuções ativas para a mesma unidade;
efeitos duplicados bloqueados;
efeitos duplicados que escaparam;
mensagens confirmadas sem resultado válido;
tempo até recuperar tarefa abandonada;
unidades vencidas antes da conclusão;
casos enviados para reconciliação;
volume em voo por fila e consumidor.

O alerta útil informa a consequência: “o worker perdeu a posse do pedido P-482 antes da atualização; nenhuma escrita nova foi permitida; o caso aguarda reconciliação”.

Checklist de visibility timeout

[ ] Cada mensagem representa uma unidade empresarial identificável?
[ ] O tempo de processamento foi medido por classe e percentil?
[ ] O prazo inicial equilibra reentrega rápida e execução normal?
[ ] Tarefas variáveis renovam a posse com progresso observável?
[ ] Existe período total máximo de renovação?
[ ] O worker para de produzir efeitos depois da perda da posse?
[ ] Checkpoints permitem retomada útil?
[ ] Escritas externas usam idempotência e controle de versão?
[ ] A confirmação ocorre somente depois do resultado válido?
[ ] Estado incerto segue para reconciliação?
[ ] Prazo de negócio pode expirar uma mensagem antiga?
[ ] Reentrega, perda de posse e duplicidade fazem parte dos testes?
[ ] Métricas ligam a mensagem ao objeto e ao efeito empresarial?

A fila precisa saber quando devolver o trabalho

Visibility timeout cria uma posse temporária, não uma garantia de exclusividade permanente. O prazo precisa acompanhar o tempo real da tarefa, ser renovado somente enquanto existe progresso e perder autoridade de forma efetiva quando expira.

Com confirmação tardia, idempotência, checkpoints e bloqueio de workers antigos, a reentrega volta a cumprir sua função: recuperar trabalho abandonado sem transformar duas execuções em duas consequências.

Fontes oficiais verificadas em 24 de setembro de 2026: