Falha parcial em lotes de agentes de IA

Um item com erro pode fazer cem itens voltarem

Um agente recebe um lote de documentos, classifica cada entrada e grava o resultado no sistema oficial. Noventa e nove itens terminam. Um arquivo corrompido gera uma exceção. Se a execução responder apenas falhou, o sistema pode devolver o lote inteiro para a fila.

Na segunda passagem, os noventa e nove itens válidos voltam a consumir modelo, integração e capacidade. Se alguma gravação não estiver protegida, também podem surgir registros duplicados.

A falha parcial aparece quando unidades independentes compartilham a mesma chamada, janela ou worker, mas terminam com resultados diferentes. O lote precisa registrar o estado de cada item e confirmar separadamente o que pode ser encerrado, repetido ou encaminhado.

Este recorte complementa o guia sobre IA em tempo real ou processamento em lote. A página anterior ajuda a escolher o modo de execução. Aqui, a pergunta é outra: como encerrar um lote quando parte dele funciona e parte exige tratamento.

Defina o que o lote agrupa

Lote é uma embalagem de execução. Unidade de trabalho é o objeto que recebe estado, prazo e consequência.

Um lote de vinte contratos pode reduzir chamadas e aproveitar contexto comum. Cada contrato continua precisando de:

• identificador estável;
• versão da entrada;
• resultado esperado;
• prazo próprio;
• estado de processamento;
• confirmação no destino;
• condição de repetição;
• dono quando houver pendência.

Se o sistema só conhece o identificador do lote, não consegue afirmar quais contratos foram analisados nem repetir apenas os que falharam.

Também é preciso decidir se os itens são realmente independentes. Um lote de imagens para classificação costuma permitir conclusão por item. Um fechamento financeiro com totais encadeados pode exigir validação conjunta. A separação técnica não pode contrariar a unidade de decisão do processo.

Separe três resultados possíveis

Cada item deve terminar em um destes grupos:

Concluído e confirmado

A saída passou pelos critérios e o sistema de destino confirmou o efeito. O item pode ser encerrado e não volta por causa da falha de outro registro.

Pendente com causa conhecida

A execução sabe por que o item parou. Pode ser uma falha temporária, entrada inválida, permissão ausente, regra operacional ou necessidade de revisão humana. A causa determina a próxima rota.

Estado incerto

O agente enviou a ação, mas perdeu a confirmação. Esse item não é sucesso nem falha comum. Antes de repetir, a operação consulta o destino e reconcilia o efeito.

Forçar o terceiro caso para falhou cria duplicidade. Forçá-lo para concluído pode esconder uma ação que nunca aconteceu.

Não use o status HTTP como resultado do lote

Chamadas em lote podem retornar sucesso técnico e ainda conter falhas por item. A documentação da Amazon SQS alerta que ações em lote podem combinar resultados bem-sucedidos e malsucedidos mesmo quando a resposta HTTP é 200.

O consumidor precisa ler a lista de sucessos e falhas, associar cada resposta ao identificador enviado e verificar se todos os itens receberam um desfecho.

A mesma disciplina vale para ferramentas chamadas por um agente. Uma API pode aceitar a requisição e recusar duas entradas. Um modelo pode devolver uma lista com uma linha ausente. Uma importação pode gravar parte dos registros. O contrato da integração precisa representar resultado por item.

Uma resposta mínima pode seguir este formato conceitual:

{
  "batch_id": "lote-2026-09-25-01",
  "items": [
    {"item_id": "doc-101", "status": "concluido", "destination_id": "reg-882"},
    {"item_id": "doc-102", "status": "pendente", "error_class": "entrada_invalida"},
    {"item_id": "doc-103", "status": "estado_incerto", "attempt_id": "tent-443"}
  ]
}

O exemplo usa dados fictícios. O schema real deve incluir somente os campos necessários ao processo e à auditoria.

Confirme o efeito no nível do item

Terminar o cálculo dentro do worker ainda não confirma a consequência de negócio. O agente pode ter produzido a classificação correta e falhado ao gravá-la no CRM. Pode ter chamado a API de escrita e perdido a resposta.

Para cada item, preserve:

1. identificador da entrada;
2. versão e hash quando aplicável;
3. identificador da tentativa;
4. saída validada;
5. comando enviado;
6. identificador retornado pelo destino;
7. estado confirmado no sistema oficial;
8. horário da confirmação.

A conclusão do lote deriva dessas confirmações. Ela não deve apagar o detalhe que a sustenta.

O artigo sobre idempotência em agentes de IA explica como manter a mesma chave entre tentativas e evitar que uma repetição gere outro efeito.

Escolha a política de processamento

Existem dois desenhos comuns.

Processar todos os itens independentes

O worker tenta cada unidade, preserva os sucessos e devolve somente as falhas. Esse caminho aproveita o lote quando a ordem entre registros não importa.

A AWS documenta respostas parciais para integrações entre Lambda e SQS. Com ReportBatchItemFailures, a função informa os identificadores que falharam e evita que mensagens já processadas voltem apenas porque outra mensagem do lote teve erro.

Parar depois da primeira falha relevante

Em filas ordenadas, continuar pode quebrar a sequência. A documentação da AWS recomenda que consumidores de filas FIFO parem depois da primeira falha e devolvam tanto o item que falhou quanto os itens ainda não processados. Assim, o próximo registro não ultrapassa uma dependência anterior.

A escolha precisa ser explícita. Paralelizar um lote ordenado para ganhar velocidade pode produzir uma sequência inválida mesmo quando cada chamada termina sem erro técnico.

O guia sobre ordem de mensagens em filas de agentes mostra como usar chaves por objeto, versões e tratamento de eventos atrasados.

Classifique antes de repetir

A unidade pendente precisa sair do lote com uma causa operacional.

Falha temporária

Timeout antes do envio, indisponibilidade breve ou limite de taxa podem permitir outra tentativa dentro do prazo. A política de retentativas em agentes de IA deve controlar intervalo, teto e custo.

Entrada inválida

Campo obrigatório ausente, arquivo corrompido ou formato incompatível voltam para correção. Repetir a mesma entrada não muda o resultado.

Regra ou estado do negócio

O objeto mudou, perdeu validade ou entrou numa condição que a regra atual não cobre. O agente deve reler a fonte oficial ou encaminhar uma decisão.

Permissão

Credencial vencida, escopo insuficiente ou política de acesso exigem correção da autorização. Se a causa afeta vários itens, suspenda o grupo em vez de produzir centenas de falhas iguais.

Saída fora do contrato

Campo ausente, categoria inválida ou evidência insuficiente podem admitir uma correção limitada. Repetições sem mudança de contexto ou versão tendem a reproduzir a falha.

Estado incerto

Ação possivelmente executada sem confirmação. O próximo passo é consultar o destino. Outra escrita fica bloqueada até a reconciliação.

Não misture falha de item com falha da infraestrutura

Um documento inválido afeta uma unidade. Uma credencial revogada pode afetar o lote inteiro. Uma queda do destino pode tornar todas as confirmações incertas.

Registre dois níveis:

• estado de cada item;
• saúde da execução compartilhada.

Quando a falha comum aparece, o sistema pode interromper novas tentativas, abrir o circuit breaker e preservar os itens ainda não iniciados. Continuar processando somente para preencher a lista de erros desperdiça capacidade e esconde a causa comum.

Também separe não processado de processado com falha. Um item que ficou depois do ponto de interrupção não consumiu modelo nem chamou ferramenta. Ele pode voltar com o mesmo estado de entrada, respeitando ordem e validade.

Faça o checkpoint avançar com prova

Em fluxos ordenados, o checkpoint indica até onde o processamento pode ser considerado seguro. Avançar além de uma falha sem entender dependências pode perder eventos. Manter o checkpoint antes de todos os sucessos pode repetir trabalho.

Defina:

• unidade do checkpoint;
• condição para avanço;
• comportamento diante de falha parcial;
• vínculo com a chave de ordenação;
• estado dos itens processados depois da falha;
• regra de retomada.

Filas, streams e jobs usam mecanismos diferentes. O princípio comum é simples: o ponto de retomada precisa corresponder ao último estado que a operação consegue provar.

Decida quando o lote termina

Um lote pode fechar como:

• concluido, quando todos os itens estão confirmados;
• concluido_com_pendencias, quando itens independentes terminaram e as exceções receberam rota e dono;
• aguardando_reconciliacao, quando existe efeito incerto;
• bloqueado_por_dependencia, quando uma causa comum impede continuação;
• cancelado_por_validade, quando o resultado perdeu utilidade;
• falha_total, quando nenhum item válido foi concluído.

Concluído com pendências só é aceitável quando a saída mostra quais itens faltam, por que faltam e quem assume cada um. Esconder exceções numa contagem agregada produz um sucesso administrativo e um problema operacional.

Encaminhe exceções sem devolver o lote

Depois que as tentativas seguras acabam, a unidade segue para uma fila de erros ou para a fila humana adequada. O item leva:

• payload ou referência protegida;
• causa classificada;
• histórico de tentativas;
• versão do fluxo;
• efeito externo conhecido;
• prazo restante;
• condição necessária para reprocessar;
• responsável pela decisão.

A DLQ governa o ciclo posterior da exceção. A resposta parcial governa o encerramento do lote atual. Misturar os dois momentos costuma fazer o lote esperar indefinidamente ou mandar sucessos para a fila de erros.

Teste com falhas deliberadas

Antes da produção, execute uma matriz que inclua:

1. todos os itens válidos;
2. um item inválido no início;
3. um item inválido no meio;
4. falha temporária em uma unidade;
5. falha compartilhada da credencial;
6. escrita concluída com confirmação perdida;
7. repetição do mesmo lote;
8. item vencido durante a espera;
9. fila ordenada com falha no segundo item;
10. resposta técnica 200 com erro por item;
11. worker interrompido depois de alguns sucessos;
12. erro ao registrar o próprio resultado parcial.

Confira quantidade de chamadas, efeitos no destino, itens encerrados, pendências, checkpoint e ausência de duplicidade. O ambiente de teste para agentes de IA ajuda a simular essas condições sem tocar produção.

Métricas que mostram o comportamento real

Acompanhe:

• lotes completos e lotes com pendência;
• itens por estado final;
• itens repetidos sem necessidade;
• custo e tempo de reprocessamento;
• falhas por posição no lote;
• confirmações perdidas;
• duplicidades bloqueadas e ocorridas;
• idade das pendências;
• falhas compartilhadas por dependência;
• tempo até reconciliação;
• unidades enviadas para DLQ;
• lotes encerrados sem dono para as exceções.

Uma taxa alta de lotes com falha pode vir de um único item ruim em cada grupo. A métrica por item mostra a extensão. A métrica por lote mostra o impacto sobre a execução e o prazo. As duas são necessárias.

Checklist de implementação

• [ ] O lote e a unidade de trabalho possuem identificadores separados?
• [ ] Cada item recebe estado, prazo e confirmação próprios?
• [ ] Sucesso técnico da chamada está separado de sucesso por item?
• [ ] Itens independentes podem terminar sem esperar a exceção?
• [ ] Fluxos ordenados param no ponto correto?
• [ ] Itens não processados são distintos dos que falharam?
• [ ] Retentativas usam a mesma chave de idempotência?
• [ ] Estado incerto bloqueia nova escrita até reconciliação?
• [ ] Falhas compartilhadas interrompem consumo desnecessário?
• [ ] O checkpoint avança somente com evidência?
• [ ] Pendências recebem causa, rota, dono e prazo?
• [ ] Repetir o lote não repete efeitos confirmados?
• [ ] Testes cobrem resposta 200 com falhas internas?

Fontes oficiais verificadas em 25 de setembro de 2026

• Handling errors for an SQS event source in Lambda, AWS Lambda Developer Guide.
• Using Lambda with Amazon SQS, AWS Lambda Developer Guide.
• Amazon SQS batch actions, Amazon SQS Developer Guide.

Os recursos citados pertencem à AWS e possuem configuração própria. O padrão operacional deste artigo também pode ser aplicado a outras plataformas, desde que seus contratos de confirmação, ordem, repetição e checkpoint sejam verificados na documentação correspondente.

O lote precisa terminar sem apagar as exceções

Falha parcial exige estado por item. O sistema encerra os sucessos confirmados, isola as pendências e bloqueia repetições quando o efeito ainda é incerto.

Com identificadores estáveis, resposta por unidade, idempotência e checkpoint verificável, um arquivo ruim deixa de arrastar o lote inteiro. A operação recupera somente o trabalho que ainda precisa de ação.