Fila de erros para agentes de IA: como usar uma DLQ

Tentar de novo não resolve toda falha

Um agente recebe um documento, extrai campos e tenta atualizar o ERP. A integração falha. O sistema repete a tarefa. A credencial continua inválida, o cadastro permanece incompatível e cada nova tentativa ocupa capacidade sem mudar a causa.

Outro caso falha por um motivo menos óbvio: a ação foi concluída, mas a confirmação se perdeu. Reprocessar pode duplicar um pedido, uma cobrança ou uma mensagem.

Depois que uma unidade esgota as tentativas seguras, ela precisa sair do fluxo normal. A fila de erros, também chamada de dead letter queue ou DLQ, guarda esse trabalho com contexto suficiente para diagnóstico, correção e decisão de reprocessamento.

Uma DLQ útil evita dois extremos: abandonar tarefas que ainda têm valor ou devolvê-las automaticamente ao mesmo erro.

O que é uma DLQ

A fila principal recebe unidades prontas para processamento. Quando uma tarefa falha além do limite ou encontra uma condição que exige intervenção, ela é movida para uma fila separada.

A DLQ deve preservar a tarefa e explicar por que ela saiu do fluxo. Depois, uma rotina técnica e operacional decide entre:

corrigir a entrada;
ajustar credencial ou integração;
atualizar regra;
reprocessar com a mesma versão;
migrar para uma versão nova;
concluir manualmente;
cancelar por perda de validade;
registrar incidente;
manter em quarentena para investigação.

A fila não corrige nada sozinha. Ela cria uma fronteira para que uma falha persistente pare de consumir o caminho saudável e possa ser tratada com evidência.

Fila de erros, retentativa e contingência

Retentativa serve para falhas temporárias. Um timeout breve, uma indisponibilidade curta ou um limite de taxa podem desaparecer depois de um intervalo. O processo deve usar backoff, variação entre tentativas e teto conhecido.

A DLQ recebe unidades que ultrapassaram esse teto ou encontraram uma causa que não melhora com repetição. Ela organiza exceções por tarefa.

O plano de contingência para agentes de IA mantém o serviço durante uma indisponibilidade mais ampla. Ele define modos degradados, capacidade manual, prioridade e reconciliação. Uma operação em contingência pode usar filas normais e DLQs, mas o plano cobre o processo completo.

Também existe diferença para a resposta a incidentes. Uma tarefa malformada pode ir para a DLQ sem representar um incidente. Mistura de dados entre clientes, ação financeira indevida ou vazamento de informação exige contenção, investigação e decisão de retorno pelo plano de resposta a incidentes de IA.

Defina a unidade de trabalho antes da fila

Uma DLQ só é útil quando cada item representa uma unidade conhecida. “Processar o fechamento” é amplo demais. “Conciliar o lote 2026-07-31 da conta X” pode receber identificador, prazo, estado e resultado esperado.

Exemplos de unidades:

documento extraído;
lead qualificado;
oportunidade atualizada;
pedido validado;
mensagem preparada;
cobrança conferida;
ticket classificado;
relatório gerado;
reunião registrada.

Cada unidade deve ter um identificador estável que sobreviva entre fila principal, tentativas, DLQ e sistema de destino. Esse identificador permite descobrir se a ação já aconteceu e evita criar outra consequência para o mesmo trabalho.

Quais falhas devem ir para a DLQ

Mover tudo para a fila de erros produz acúmulo e esconde causas. O roteamento precisa distinguir tipos de falha.

Entrada inválida

Campo obrigatório ausente, arquivo ilegível, formato incompatível, identificador inexistente ou dado fora da faixa. A unidade aguarda correção da origem ou intervenção.

Permissão ou credencial

Acesso negado, token vencido, escopo insuficiente ou conta bloqueada. Várias unidades podem compartilhar a mesma causa. Depois de detectar o padrão, o sistema deve evitar inundar a DLQ com cópias sem agrupamento.

Regra de negócio

O destino rejeita a ação porque o estado mudou, o prazo expirou, o limite foi ultrapassado ou uma condição não foi atendida. Repetir sem reler a fonte oficial tende a falhar de novo.

Saída fora do contrato

O modelo omite campo, usa tipo inválido, retorna categoria inexistente ou produz conteúdo sem evidência obrigatória. Uma correção limitada pode ser tentada. Depois do teto, a unidade segue para análise de qualidade.

Integração indisponível por tempo excessivo

Timeouts e erros temporários ultrapassaram a janela em que a tarefa ainda pode esperar. O caso pode entrar na DLQ ou em uma fila de adiamento, conforme validade e criticidade.

Estado ambíguo

A chamada expirou e não existe confirmação sobre o efeito externo. Essa classe pede reconciliação antes de qualquer nova execução.

Falha crítica

A unidade indica possível violação de dados, permissão, cliente, valor ou política. Ela entra em quarentena e pode acionar controles de incidente. Reprocessamento automático deve ficar bloqueado.

O que registrar em cada item

Guardar apenas o payload original transfere a investigação para quem abrir a fila. Um item precisa chegar com contexto operacional.

Registre:

identificador da unidade;
tipo de processo;
cliente, conta ou objeto dentro do escopo permitido;
versão do fluxo;
versão das instruções e do modelo;
evento de origem;
horário da primeira entrada;
etapa em que falhou;
estado anterior confirmado;
entrada usada na etapa;
saída produzida;
ferramenta chamada;
código e mensagem de erro;
classe de falha;
tentativas e intervalos;
custo acumulado;
prazo e validade;
efeito externo possível;
fontes consultadas;
aprovações existentes;
proprietário do processo;
próxima ação recomendada;
restrição para reprocessamento.

Dados sensíveis precisam seguir política de acesso e retenção. A DLQ não deve virar uma cópia irrestrita de documentos, conversas ou credenciais. Quando possível, guarde referências protegidas em vez do conteúdo completo.

O artigo sobre retenção de dados em agentes de IA ajuda a definir prazo, finalidade, acesso e descarte desse material.

Separe filas por risco e tratamento

Uma única DLQ global pode misturar erros simples com casos sensíveis. Isso dificulta prioridade, permissão e automação.

Uma estrutura possível separa:

Corrigível pela origem

Entrada incompleta ou inválida. A equipe ou o sistema de origem recebe uma pendência clara.

Dependência técnica

Credencial, API, timeout persistente ou contrato de integração. O responsável técnico trata a causa compartilhada.

Qualidade do agente

Saída fora do esquema, falta de evidência, classificação incorreta ou conflito não resolvido. Esses casos alimentam avaliação e regressão.

Regra operacional

Exceção que o processo ainda não documentou ou estado do negócio incompatível. O dono operacional decide a regra.

Estado incerto

Existe dúvida sobre ação externa. A unidade fica bloqueada até consulta ao sistema oficial ou revisão humana.

Risco crítico

Possível efeito indevido, mistura de contexto ou violação de política. Acesso restrito e reprocessamento manualmente autorizado.

A separação pode ocorrer em filas distintas ou por classe dentro de um sistema com controle de acesso. A arquitetura deve permitir que cada responsável veja o que precisa sem ampliar exposição.

Evite a DLQ como depósito permanente

Uma fila de erros cresce silenciosamente quando ninguém possui a rotina. O painel mostra tarefas preservadas, mas o prazo de negócio continua correndo.

Defina:

dono por classe de falha;
frequência de triagem;
prazo máximo sem decisão;
alerta por idade e volume;
regra de prioridade;
procedimento de correção;
autoridade para reprocessar;
critério de cancelamento;
retenção depois da conclusão;
indicador de reincidência.

Uma falha repetida em muitas unidades pode representar uma única causa. Agrupe por assinatura de erro, dependência, versão e etapa. Corrigir o problema compartilhado antes de abrir item por item reduz retrabalho.

Crie uma assinatura de falha

A assinatura ajuda a localizar padrões. Ela pode combinar campos estáveis, como:

processo + etapa + dependência + código_de_erro + versão_do_fluxo

Mensagens livres variam e podem conter identificadores específicos. Normalize o que for necessário antes de agrupar.

A assinatura permite responder:

quantas unidades falharam pela mesma causa;
qual versão introduziu o problema;
quais clientes ou processos foram afetados;
se a correção reduziu reincidência;
qual grupo deve ser reprocessado junto;
onde uma mudança merece teste de regressão.

Não use o agrupamento para apagar diferenças de risco. Duas unidades com o mesmo erro técnico podem ter prazos ou consequências diferentes.

Corrija a causa antes de reprocessar

O reprocessamento deve apontar para uma mudança verificável. Exemplos:

campo ausente foi preenchido;
arquivo foi substituído;
credencial foi renovada;
permissão foi ajustada;
endpoint voltou a responder;
regra foi aprovada;
versão corrigida passou em teste;
estado oficial foi reconciliado;
limite de capacidade foi ampliado com autorização.

“Vamos tentar novamente” não é causa corrigida.

Para erros de qualidade, transforme o caso em teste. A nova versão precisa produzir o resultado esperado no item e também preservar o desempenho em casos próximos. O guia como avaliar agentes de IA mostra como comparar versões com casos representativos e critérios definidos.

Reprocesse com idempotência

Antes de devolver uma unidade ao fluxo, consulte o destino e o registro de processamento. O objetivo é descobrir se houve efeito externo apesar do erro.

Pergunte:

Existe identificador retornado pela tentativa anterior?
O sistema oficial mostra a alteração?
O objeto está no estado esperado?
Outra pessoa ou automação concluiu a tarefa?
A entrada continua válida?
A ação ainda faz sentido no contexto atual?
A versão nova consegue interpretar o estado antigo?

Use a mesma chave de idempotência ao reprocessar. A página sobre idempotência em agentes de IA detalha reserva, confirmação, estado incerto e reconciliação.

Se a unidade passou por ação manual, registre essa conclusão antes de reabrir o consumo automático.

Não devolva todo o lote de uma vez

Uma correção pode liberar milhares de itens. Recolocar tudo na fila principal cria pico, pressiona a dependência e pode repetir a falha em escala.

Faça a retomada por lotes controlados:

selecione casos representativos;
valide a correção em ambiente de teste;
reprocese um lote pequeno;
confira efeitos no sistema de destino;
monitore erro, latência e duplicidade;
aumente o volume gradualmente;
pause ao detectar reincidência;
preserve itens ainda não tratados.

Aplique rate limit e limite de concorrência durante a recuperação. Priorize tarefas válidas próximas do prazo. Itens vencidos devem ser cancelados ou reavaliados, não executados por inércia.

Defina estados legíveis

Uma unidade não deveria alternar apenas entre “erro” e “processando”. Estados mais precisos ajudam operação e auditoria.

Exemplo:

recebido_na_dlq;
classificado;
aguardando_correcao_de_entrada;
aguardando_responsavel_tecnico;
aguardando_decisao_operacional;
em_investigacao;
correcao_validada;
autorizado_para_reprocessar;
reprocessando;
concluido;
concluido_manualmente;
cancelado_por_validade;
incidente_aberto.

Cada transição deve registrar ator, data, motivo e evidência. A autorização para reprocessar uma falha crítica não deve ser implícita.

Monitore fila e causa

Acompanhe pelo menos:

entradas na DLQ por período;
unidades abertas;
idade da unidade mais antiga;
tempo médio e extremo até triagem;
falhas por processo, etapa, dependência e versão;
causas compartilhadas;
unidades próximas do prazo;
reprocessamentos autorizados;
taxa de sucesso após reprocessamento;
reincidência da mesma assinatura;
duplicidades detectadas;
conclusões manuais;
cancelamentos por perda de validade;
incidentes originados da fila;
volume e prazo por responsável.

A taxa de reprocessamento bem-sucedido sozinha pode enganar. Uma fila que resolve tudo depois de cinco dias ainda falha quando o processo exige resposta no mesmo dia.

Alertas devem dizer o que aconteceu, quais unidades foram afetadas, por que importa, quem age e até quando. O monitoramento de agentes em produção conecta esses sinais à saúde do serviço.

Teste o caminho de erro

Equipes costumam testar o fluxo feliz e descobrir a DLQ durante a primeira falha real. Inclua cenários como:

entrada sem campo obrigatório;
arquivo corrompido;
credencial expirada;
resposta fora do esquema;
timeout persistente;
ação concluída com confirmação perdida;
regra de negócio alterada durante a espera;
item vencido na fila;
múltiplas unidades com a mesma causa;
reprocessamento com versão nova;
conclusão manual antes da retomada;
lote grande liberado depois da correção;
falha crítica que exige bloqueio;
item com dado sensível e acesso restrito;
erro na própria rotina de reprocessamento.

Verifique se a tarefa chega com contexto, o responsável recebe alerta, a causa pode ser agrupada, o efeito externo é consultado e o reprocessamento respeita idempotência e capacidade.

O ambiente de teste para agentes de IA ajuda a simular integrações, falhas e estados sem usar produção.

Checklist para implementar uma DLQ

Antes de colocar a fila em operação, confirme:

[ ] cada item representa uma unidade com identificador estável;
[ ] retentativas temporárias têm intervalo e teto;
[ ] falhas permanentes param cedo;
[ ] classes de erro determinam tratamento e responsável;
[ ] payload, etapa, versão, erro e estado anterior ficam preservados;
[ ] dados sensíveis possuem acesso e retenção adequados;
[ ] falhas compartilhadas podem ser agrupadas;
[ ] idade, prazo e validade são monitorados;
[ ] toda classe tem dono e cadência de triagem;
[ ] reprocessamento exige uma causa corrigida;
[ ] ações externas são consultadas antes de repetir;
[ ] a mesma chave de idempotência acompanha a unidade;
[ ] tarefas concluídas manualmente ficam bloqueadas para repetição;
[ ] lotes voltam gradualmente ao fluxo;
[ ] estados e transições possuem evidência;
[ ] falhas críticas exigem autorização específica;
[ ] casos recorrentes alimentam testes e correções de arquitetura.

A fila de erros precisa produzir decisão

Uma DLQ preserva tarefas problemáticas sem permitir que elas consumam indefinidamente o fluxo normal. O ganho aparece quando cada item chega com causa, contexto, responsável e prazo.

Com classificação de falhas, evidência, idempotência e reprocessamento gradual, a empresa consegue recuperar trabalho válido sem repetir efeitos ou esconder exceções. A fila deixa de ser um cemitério técnico e passa a sustentar uma rotina operacional de correção.