Claim Check em agentes de IA: payload fora da fila

A fila recebeu o contrato inteiro

Um agente analisa contratos enviados por clientes. Cada evento carrega o PDF, metadados, instruções e contexto acumulado. Quando o volume sobe, a fila passa a transportar arquivos grandes, as retentativas repetem o conteúdo e ferramentas de observabilidade recebem cópias que nunca precisariam ver o documento.

O fluxo ganhou um problema de capacidade e outro de exposição. A fila deveria coordenar o trabalho. Agora também virou repositório temporário de conteúdo sensível.

O padrão Claim Check separa essas responsabilidades. O payload fica em armazenamento apropriado, e a mensagem leva uma referência opaca que permite ao consumidor autorizado recuperar a versão correta. A referência funciona como comprovante de retirada, com escopo, validade e integridade verificáveis.

Este guia trata a passagem de documentos e payloads entre filas, workers e agentes. O artigo sobre minimização de dados decide quais campos precisam circular. Aqui, o objeto é o transporte seguro do conteúdo que continua necessário, mas não deveria viajar dentro de cada mensagem.

O que o padrão Claim Check resolve

Sistemas de mensageria costumam ser otimizados para muitas mensagens pequenas. Arquivos, imagens, gravações, planilhas e pacotes extensos pressionam limites de tamanho, throughput, retenção e custo.

O fluxo básico possui cinco movimentos:

o produtor grava o payload em um armazenamento protegido;
o armazenamento devolve um identificador da versão;
o produtor publica na fila uma mensagem com a referência;
o consumidor autorizado recupera o payload;
a política de ciclo de vida remove ou arquiva o objeto quando o trabalho termina.

A mensagem continua carregando o necessário para roteamento e controle:

work_item_id
payload_ref
payload_version
content_type
content_length
checksum
classification
created_at
expires_at
tenant_id
purpose
correlation_id

O arquivo completo permanece fora do broker. Esse desenho pode reduzir pressão na fila e restringir o conteúdo aos componentes que realmente o processam.

Separe quatro identidades

Uma única URL não representa o contrato completo. O fluxo precisa distinguir:

Unidade de trabalho

É o pedido, contrato, nota, imagem ou pacote que a operação reconhece. O identificador deve permanecer estável entre tentativas, reentregas e versões do worker.

Objeto armazenado

É a cópia concreta do payload. Pode receber versão própria quando o conteúdo for corrigido, substituído ou reprocessado.

Mensagem

É a instrução transportada pela fila. Reentregas técnicas podem gerar várias tentativas relacionadas à mesma unidade.

Autorização de leitura

É o direito temporário de recuperar aquele objeto para uma finalidade. A referência localiza o conteúdo; ela não deveria funcionar como permissão permanente por si só.

Misturar essas identidades produz atalhos perigosos. Uma nova mensagem pode apontar para versão antiga. Uma URL vazada pode sobreviver ao prazo da tarefa. A exclusão da mensagem pode apagar um arquivo ainda necessário para outra etapa.

Decida quando usar Claim Check

O padrão acrescenta armazenamento, autorização, limpeza e mais uma dependência. Ele faz sentido quando existe um motivo concreto.

Payload acima do limite da fila

Documentos, imagens ou pacotes excedem o tamanho aceito pelo broker. A documentação do Amazon SQS, por exemplo, apresenta bibliotecas estendidas que armazenam payloads grandes no Amazon S3 e enviam apenas a referência na mensagem.

Throughput prejudicado por conteúdo volumoso

Mesmo abaixo do limite máximo, mensagens grandes aumentam serialização, transferência, retenção e reprocessamento. Um pequeno envelope permite que a fila volte a coordenar estado e prioridade.

Dados que poucos componentes podem acessar

A fila atravessa roteadores, painéis, conectores e equipes. Manter o conteúdo em armazenamento com política própria pode reduzir a superfície de exposição, desde que a referência e a autorização também sejam protegidas.

Conteúdo reutilizado por várias etapas

OCR, classificação, extração e revisão podem trabalhar sobre a mesma versão do arquivo. Uma referência estável evita copiar o payload para cada etapa.

Retenção diferente entre mensagem e evidência

A mensagem pode expirar em horas, enquanto o documento segue uma política contratual. Em outro processo, a evidência pode precisar ser removida logo após a conclusão, embora o histórico técnico da unidade permaneça.

Para mensagens pequenas, pouco sensíveis e usadas por um único consumidor, o transporte direto pode ser mais simples. A Microsoft recomenda aplicação condicional do padrão quando tamanho, desempenho, segurança ou roteamento justificarem a separação.

Grave o payload antes de publicar a mensagem

A ordem evita que um consumidor receba uma referência sem conteúdo disponível.

Uma sequência segura pode seguir:

validar formato, tamanho e classificação;
gerar work_item_id e versão;
gravar o objeto em estado provisório;
calcular ou confirmar checksum;
registrar metadados, proprietário e prazo;
publicar a mensagem com a referência;
marcar a referência como ativa somente depois da confirmação da publicação;
limpar objetos provisórios cujo evento nunca foi publicado.

Falhas podem ocorrer entre qualquer par de etapas. Se o upload conclui e a publicação falha, sobra um objeto órfão. Se a mensagem aparece antes da gravação ficar disponível, o consumidor encontra uma referência quebrada.

Use um padrão outbox quando a criação do registro empresarial e a publicação precisarem permanecer coordenadas. Uma rotina de reconciliação deve localizar objetos sem mensagem e mensagens sem objeto.

Crie uma referência opaca e específica

Evite referências previsíveis como cliente/contrato-final.pdf. Nomes legíveis podem expor identidade, permitir enumeração e confundir versões.

Uma boa referência deve:

ser difícil de adivinhar;
apontar para um único objeto ou versão;
não conter dado pessoal no texto;
permanecer vinculada ao tenant e ao ambiente;
suportar revogação;
permitir auditoria sem revelar o payload;
sobreviver à reentrega da mesma unidade;
ser diferente entre teste e produção.

O consumidor recebe a referência no envelope. Um adaptador confiável resolve o local físico e aplica a política. O modelo não precisa enxergar bucket, caminho interno ou credencial.

Mantenha autorização fora do prompt

Uma instrução como “acesse somente o arquivo indicado” orienta o agente, mas não limita tecnicamente a conta usada pelo worker.

Antes de liberar o conteúdo, valide:

identidade do serviço;
tenant da execução;
finalidade declarada;
unidade de trabalho;
ambiente;
classificação do dado;
versão solicitada;
prazo de validade;
política de região e retenção;
estado atual da tarefa.

Prefira credenciais temporárias e permissões estreitas. Quando usar URL assinada, limite prazo, método, objeto e finalidade possível. Evite registrar a URL completa em logs, porque o token pode conceder acesso enquanto estiver válido.

O guia sobre identidade e credenciais para agentes detalha identidades de workload, emissão temporária, rotação e revogação. Em operação multicliente, aplique também o isolamento entre clientes antes da leitura.

Verifique integridade e versão

Recuperar algum arquivo não prova que o worker recebeu o conteúdo publicado pelo produtor.

A mensagem pode carregar:

payload_ref: ref_7f2c...
payload_version: 4
content_type: application/pdf
content_length: 1842331
checksum_algorithm: sha256
checksum: <valor esperado>

O consumidor confere tipo, tamanho e checksum antes de processar. Também valida metadados do armazenamento, tenant e estado do objeto.

Essa verificação detecta:

upload incompleto;
substituição no mesmo caminho;
referência para versão antiga;
arquivo corrompido;
tipo incompatível;
conteúdo alterado depois da aprovação;
objeto pertencente a outro escopo.

Quando o payload muda, publique uma nova versão e uma nova intenção. Alterar silenciosamente o objeto atrás da mesma referência faz tentativas diferentes processarem conteúdos diferentes com a mesma identidade.

Trate a ausência do payload como estado próprio

Um 404 pode ter várias causas:

a gravação ainda não ficou disponível;
a referência está errada;
a versão foi removida cedo;
a autorização expirou;
a política bloqueou o consumidor;
o objeto está em região ou ambiente diferente;
a limpeza rodou antes da conclusão;
o produtor nunca terminou a gravação.

Registre estados como:

payload_em_preparacao;
referencia_publicada;
payload_disponivel;
acesso_negado;
integridade_reprovada;
payload_ausente;
processamento_concluido;
limpeza_pendente;
payload_removido.

Retentar cegamente pode esconder exclusão prematura ou erro de escopo. Classifique a causa, preserve a mensagem e encaminhe para a fila de erros quando a condição ultrapassar o teto seguro.

Coordene confirmação e limpeza

A fila e o armazenamento possuem ciclos diferentes. O momento de apagar precisa ser explícito.

Limpeza síncrona

O consumidor remove o objeto depois de confirmar resultado e antes de encerrar a mensagem. O vínculo fica simples, mas a exclusão adiciona latência e pode falhar dentro da etapa crítica.

Limpeza assíncrona

Uma rotina posterior remove objetos elegíveis. O processamento principal termina mais rápido, porém exige estado, monitoramento e idempotência para evitar acúmulo.

Retenção por política

O objeto permanece pelo prazo empresarial, contratual ou regulatório. A conclusão da tarefa apenas retira o acesso operacional do agente.

A escolha depende de finalidade, auditoria, contestação, privacidade e recuperação. Defina pelo menos:

evento que torna o objeto elegível para remoção;
prazo mínimo e máximo;
consumidores que ainda dependem dele;
retenção para falha ou disputa;
responsável pela limpeza;
prova de exclusão;
comportamento quando a mensagem reaparece;
exceção para investigação autorizada.

A política de retenção de dados deve governar o prazo. TTL técnico sem contexto pode remover evidência cedo demais ou manter conteúdo depois da finalidade.

Preserve idempotência entre fila e armazenamento

Reentregas fazem parte de sistemas assíncronos. O mesmo consumidor pode recuperar o payload outra vez. Dois workers podem tentar processar a mesma referência durante uma falha de posse.

Use:

work_item_id estável;
versão imutável do payload;
chave de idempotência por efeito;
registro de tentativas;
controle de concorrência no destino;
confirmação do efeito antes de apagar;
leitura repetível enquanto a referência estiver válida.

Baixar o mesmo arquivo duas vezes costuma ser reversível. Criar duas tarefas, enviar duas mensagens ou gravar duas análises no sistema oficial pode não ser. A proteção precisa alcançar cada consequência externa.

O artigo sobre visibility timeout cobre a posse temporária da mensagem. Claim Check preserva o acesso ao conteúdo; idempotência e versão continuam responsáveis pelos efeitos.

Evite transformar o armazenamento em uma fila paralela

Pastas com arquivos novos às vezes viram um mecanismo informal de disparo. Workers varrem o diretório e inferem o que processar pela presença do objeto.

Esse atalho perde informações importantes:

prioridade;
tentativa;
prazo;
unidade empresarial;
motivo da execução;
tenant;
versão da política;
estado de aprovação;
confirmação;
rota de erro.

Mantenha o broker como coordenador do trabalho. O armazenamento conserva o payload. A mensagem carrega a intenção e os metadados operacionais.

Exemplo: agente que analisa contratos

Uma empresa recebe contratos em PDF e usa um agente para extrair obrigações e preparar revisão.

Entrada

O portal valida extensão, tamanho, cliente e finalidade. O arquivo recebe document_id, versão e checksum. A gravação ocorre em armazenamento privado.

Publicação

A fila recebe:

work_item_id: REVISAO-482
payload_ref: ref_b91d...
payload_version: 2
tenant_id: CLIENTE-31
purpose: extrair_obrigacoes
classification: confidencial
expires_at: 2026-10-04T18:00:00Z

Consumo

O worker autentica com identidade própria, confirma tenant e finalidade, recupera a versão 2 e verifica checksum. O agente recebe somente as páginas necessárias para a etapa.

Saída

A extração gera campos estruturados, referências de página e pendências. Nenhuma aprovação contratual é concedida. Uma pessoa confere as cláusulas antes de qualquer registro operacional.

Conclusão

O resultado validado é gravado com chave idempotente. A mensagem é confirmada. A referência operacional expira, enquanto o documento original segue a política do repositório contratual.

Falha

Se a integridade divergir, o worker bloqueia a análise, preserva metadados e envia o caso para investigação. Ele não tenta “aproveitar” o PDF diferente disponível no caminho.

Teste o padrão antes de produção

Inclua casos como:

payload pequeno enviado diretamente;
payload acima do limiar enviado por referência;
arquivo maior que o limite aceito;
tipo proibido;
upload concluído e publicação perdida;
mensagem publicada e objeto ausente;
referência de outro tenant;
checksum divergente;
versão substituída durante o processamento;
credencial expirada;
URL assinada registrada indevidamente;
duas entregas da mesma mensagem;
dois consumidores sobre a mesma unidade;
exclusão antes da confirmação;
limpeza assíncrona indisponível;
tarefa concluída com objeto órfão;
mensagem em DLQ depois do prazo de retenção;
revogação durante investigação.

Confira fila, armazenamento, logs, permissões, estado final, quantidade de efeitos e prova de limpeza.

Métricas para operar Claim Check

Acompanhe:

tamanho das mensagens e dos payloads;
percentual que usa referência;
tempo de gravação e recuperação;
falhas de upload;
referências sem objeto;
objetos sem mensagem;
acessos negados por escopo;
divergências de checksum;
versões incorretas bloqueadas;
reentregas por unidade;
custo de armazenamento e transferência;
objetos elegíveis para limpeza;
idade dos objetos órfãos;
exclusões concluídas e reprovadas;
conteúdo sensível encontrado em logs;
prazo entre conclusão e retirada de acesso.

Um alerta útil informa a consequência: “o contrato da revisão REVISAO-482 foi gravado, mas a publicação não foi confirmada; nenhum worker recebeu acesso; o objeto provisório será removido em uma hora”.

Checklist de implementação

[ ] Existe um motivo concreto para tirar o payload da fila?
[ ] A unidade, o objeto, a mensagem e a autorização possuem identidades separadas?
[ ] O payload é gravado antes da publicação?
[ ] Objetos provisórios podem ser reconciliados e removidos?
[ ] A referência é opaca, específica e sem dado pessoal?
[ ] O acesso valida identidade, tenant, finalidade, ambiente e prazo?
[ ] O modelo fica sem credencial e caminho interno?
[ ] Tipo, tamanho, versão e checksum são conferidos?
[ ] Alterações do conteúdo geram nova versão?
[ ] Ausência, negação e integridade reprovada possuem estados próprios?
[ ] Reentregas recuperam a mesma versão enquanto válida?
[ ] Efeitos externos usam idempotência?
[ ] Limpeza possui evento, prazo, dono e evidência?
[ ] Logs evitam payloads e URLs assinadas?
[ ] Testes cobrem objetos órfãos, exclusão precoce e acesso cruzado?

A fila deve transportar intenção

Filas coordenam prioridade, tentativa, estado e recuperação. Documentos grandes ou sensíveis pedem armazenamento com controles próprios.

Claim Check mantém a mensagem pequena e o payload sob política de acesso, integridade e retenção. O ganho depende do contrato completo: referência opaca, versão imutável, autorização temporária, confirmação do efeito e limpeza verificável.

Fontes oficiais verificadas em 2 de outubro de 2026:

Microsoft Learn: Claim-Check pattern, para separação entre payload e mensagem, aplicação condicional, segurança e estratégias de exclusão.
Amazon SQS: mensagens grandes com Extended Client Library, para armazenamento do payload no Amazon S3 e envio da referência por filas standard ou FIFO.
Amazon SQS: Extended Client Library para Python, para configuração, recuperação e remoção de payloads externos.

As fontes descrevem padrões e recursos de plataforma. Tamanho máximo, consistência, criptografia, região, custo, retenção e permissões precisam ser confirmados no ambiente adotado.