Acumulador de eventos para agentes de IA

O pedido mudou quatro vezes antes de o agente agir

Um cliente adiciona um item, corrige o endereço, aplica um cupom e escolhe o frete. Cada mudança gera um evento. Se o agente recalcula o pedido a cada mensagem, ele produz quatro análises sobre um estado ainda em formação e pressiona os mesmos sistemas repetidamente.

Esperar um lote fixo também cria problema. Alguns pedidos recebem dois eventos. Outros recebem vinte. O sistema desconhece antecipadamente quantas mudanças formarão uma unidade útil.

Um acumulador de eventos reúne sinais relacionados pela mesma chave, elimina reentregas e dispara o processamento quando o grupo fica sem novas entradas durante uma janela definida ou recebe um comando explícito de fechamento.

A pergunta operacional muda de “quantos eventos cabem no lote?” para “quais eventos pertencem à mesma unidade e quando existe evidência suficiente para processá-la?”.

O mecanismo resolve uma janela de chegada desconhecida

O acumulador trabalha com quatro elementos:

uma chave estável para identificar o grupo;
um identificador único por evento;
estado durável com os itens já aceitos;
uma condição de fechamento.

A condição pode ser uma pausa de dez segundos, o fim de uma sessão, a confirmação de pagamento, um horário limite ou um comando manual. A janela precisa refletir o comportamento do processo. Um número copiado de outra arquitetura só produz atraso com aparência técnica.

A documentação do Temporal descreve o padrão Event Accumulator com uma execução por chave, recebimento atômico do primeiro sinal, deduplicação e fechamento depois de um intervalo móvel de inatividade. Cada novo evento reinicia a espera. O estado sobrevive ao reinício dos workers.

Acumulador, lote, coalescing e fan-in têm trabalhos diferentes

Esses mecanismos aproximam eventos no tempo, mas protegem perguntas distintas.

Tamanho de lote limita uma execução

O tamanho de lote para agentes de IA define teto de itens, bytes, peso e espera para unidades já elegíveis. O acumulador decide quais eventos formam uma unidade antes desse dimensionamento.

Request coalescing compartilha o mesmo resultado

O request coalescing faz pedidos equivalentes aguardarem uma chamada comum. No acumulador, os eventos são diferentes e precisam permanecer identificáveis dentro do grupo.

Fan-in reúne ramos conhecidos

O fan-out e fan-in parte de um manifesto de ramos esperados. O acumulador recebe uma sequência cuja quantidade pode ser desconhecida até a janela fechar.

Event sourcing preserva o histórico oficial

O event sourcing mantém eventos como fonte de verdade. O acumulador pode consumir esse histórico, mas não deveria apagar, reescrever ou substituir o registro oficial. Seu estado serve ao processamento de uma janela.

A diferença concreta cabe numa frase: o acumulador fecha um grupo após observar sua chegada; ele não redefine o histórico nem transforma pedidos distintos na mesma resposta.

Escolha uma chave que represente a unidade empresarial

A chave liga eventos que podem ser avaliados juntos. Exemplos:

pedido;
solicitação de suporte;
oportunidade comercial;
sessão de atendimento;
ativo em manutenção;
documento em revisão;
cliente dentro de uma campanha;
ocorrência de uma rotina agendada.

Uma chave pode combinar:

tenant + tipo_de_objeto + objeto_id + versão_da_política + janela

Para um pedido:

empresa_aurora + pedido + PED-104 + politica_7 + 2026-10-16

Inclua cliente, finalidade e versão quando esses atributos alteram autorização ou interpretação. Duas empresas podem ter o mesmo número de pedido. Duas versões da política podem produzir decisões diferentes. A economia de processamento não autoriza misturar fronteiras.

Evite chaves baseadas apenas em texto semelhante. “Alteração de endereço” e “correção de endereço fiscal” podem ter efeitos e autoridades diferentes mesmo quando a linguagem parece próxima.

Dê identidade própria a cada evento

Entrega pelo menos uma vez significa que um evento pode reaparecer depois de timeout, reinício ou falha de confirmação. O acumulador precisa reconhecer a repetição antes de acrescentar outro item.

Um envelope mínimo pode carregar:

event_id: E2
bucket_key: empresa_aurora:pedido:PED-104
kind: endereco_atualizado
occurred_at: 2026-10-16T14:03:00Z
received_at: 2026-10-16T14:03:02Z
source: portal_pedidos
source_version: 184
policy_version: 7

event_id precisa permanecer estável em uma retentativa. Gerar outro identificador a cada envio transforma a mesma mudança em eventos aparentemente novos.

Defina também a política para um evento reenviado com o mesmo ID e conteúdo diferente. O sistema pode:

rejeitar como conflito;
manter a primeira versão;
aceitar a versão mais nova sob regra explícita;
encaminhar para reconciliação.

Substituição silenciosa enfraquece a auditoria.

Faça a primeira entrega criar ou localizar o grupo de forma atômica

Separar “criar acumulador” de “enviar primeiro evento” abre uma janela de perda. Dois produtores podem concluir que o grupo ainda não existe, ou o sinal pode chegar antes de a execução estar pronta.

Use uma operação atômica oferecida pela plataforma ou uma transação equivalente no armazenamento:

localizar o grupo pela chave;
criá-lo quando estiver ausente;
registrar o primeiro evento;
confirmar a mesma unidade.

No Temporal, o padrão usa Signal-With-Start para iniciar a execução quando necessário e entregar o sinal na mesma operação. Em outra plataforma, a garantia pode vir de uma chave única, transação, operação condicional ou consumidor serializado por partição.

O nome do recurso muda. A propriedade necessária permanece: o primeiro evento não pode cair no espaço entre descoberta e criação.

Modele a janela de inatividade

A janela móvel começa depois do evento aceito mais recente. Se outra entrada chega antes do limite, a contagem recomeça.

Exemplo com dez segundos de inatividade:

00s  E1 item_adicionado
03s  E2 endereco_atualizado
05s  E2 reentrega bloqueada
15s  E4 cupom_aplicado
25s  janela fecha sem novo evento

A escolha envolve um trade-off direto:

janela curta reduz espera e cria mais processamentos parciais;
janela longa reúne mais mudanças e aumenta latência;
janela sem teto pode permanecer aberta durante fluxo contínuo;
teto rígido demais pode cortar uma sequência legítima.

Combine a pausa com limites adicionais:

prazo máximo desde o primeiro evento;
quantidade máxima;
bytes ou peso acumulado;
evento terminal;
comando de flush;
horário de corte;
prazo restante da unidade.

Feche quando a primeira condição aplicável for atingida. Registre qual delas encerrou o grupo.

Preserve eventos que chegam no limite

A fronteira entre “entrou no lote atual” e “ficou para o próximo” precisa ser determinística.

Quando o timer dispara:

marque uma versão do grupo para fechamento;
pare de acrescentar itens naquela versão;
registre o manifesto aceito;
encaminhe eventos posteriores para nova janela ou regra definida;
processe somente o manifesto fechado.

Sem essa barreira, um evento pode entrar enquanto o agente já analisa a coleção. A entrada usada pelo modelo e o estado registrado deixam de coincidir.

Carregue no resultado:

bucket_key
window_id
window_version
first_event_at
last_event_at
closed_at
close_reason
event_ids
policy_version

A evidência permite reproduzir o que o agente realmente recebeu.

Separe coleta, interpretação e efeito

O acumulador organiza entrada. A execução seguinte ainda precisa validar o trabalho.

Uma sequência segura pode ser:

receber e deduplicar eventos;
fechar o manifesto;
recuperar o estado vigente no sistema oficial;
interpretar a sequência com regra e contexto aprovados;
preparar uma proposta de ação;
revalidar versão, permissão e prazo;
obter aprovação quando exigida;
executar com idempotência;
confirmar o efeito;
reconciliar divergências.

Os eventos explicam o que chegou. Eles podem estar atrasados, fora de ordem ou superados pelo estado oficial. Um endereço alterado e depois corrigido exige ler versão e sequência, não contar ocorrências.

Trate ordem, atraso e eventos tardios

Nem todo produtor entrega eventos na ordem em que aconteceram.

Defina por tipo de fluxo:

qual campo representa ordem;
se a fonte oferece sequência crescente;
quanto atraso a janela tolera;
quais eventos podem ser reorganizados;
quais eventos exigem reconsulta ao sistema oficial;
como um evento tardio reabre, corrige ou cria nova unidade.

Uma política possível:

evento dentro da janela e versão esperada -> aceitar
evento repetido -> ignorar com registro
evento anterior à versão já confirmada -> marcar como tardio
evento terminal -> fechar imediatamente
evento depois do fechamento -> abrir nova janela vinculada
evento incompatível -> fila de reconciliação

Não peça ao modelo para “resolver a ordem” sem dados de versão. Fluência narrativa pode esconder uma sequência impossível.

Limite crescimento e retenção

Um grupo com atividade contínua pode permanecer aberto e aumentar histórico, memória e custo.

Proteções úteis incluem:

teto de eventos por janela;
teto de bytes;
idade máxima;
flush parcial com continuação vinculada;
checkpoint durável;
compactação que preserva IDs e versão;
retenção separada entre payload e metadados;
alerta para grupos que nunca ficam inativos.

A documentação do Temporal recomenda Continue-As-New quando o histórico cresce. O estado necessário precisa ser passado para a nova execução, inclusive chaves já vistas quando elas ainda protegem a transição. O guia sobre Continue-As-New em agentes de IA detalha a renovação do histórico sem perder identidade lógica.

Resumos não devem apagar a capacidade de provar quais eventos entraram. Mantenha referências ao registro autorizado, hashes ou IDs conforme a política de dados.

Simulação local do comportamento

A Júpiter executou uma simulação determinística em 16 de outubro de 2026 com dados sintéticos:

oito entregas;
dois pedidos;
uma reentrega com ID repetido;
janela de inatividade de dez segundos;
sete eventos únicos aceitos;
cinco fechamentos de janela;
uma duplicidade bloqueada.

A simulação confirmou agrupamento, reinício da janela e deduplicação. Ela não testou Temporal, broker, banco, latência de rede ou agente em produção. Cada plataforma precisa provar atomicidade, persistência e recuperação no ambiente adotado.

Teste falhas antes de liberar

Inclua casos como:

dois produtores enviam o primeiro evento ao mesmo tempo;
a confirmação se perde e o produtor repete;
o worker reinicia com a janela aberta;
um evento chega exatamente no vencimento;
o timer dispara duas vezes;
o evento terminal chega antes de eventos atrasados;
o grupo atinge teto sem período de silêncio;
o processamento falha depois do fechamento;
um evento chega durante a passagem para nova execução;
a política muda com grupos abertos;
duas empresas usam o mesmo identificador local;
um payload excede o limite;
a fonte envia o mesmo ID com conteúdo diferente;
o destino confirma o efeito e a resposta se perde.

Confira eventos aceitos, eventos recusados, manifesto, motivo de fechamento, quantidade de efeitos, estado depois do reinício e isolamento entre clientes.

A idempotência para agentes de IA protege a repetição do efeito depois do fechamento. A deduplicação no acumulador protege a composição da entrada. As duas camadas cobrem momentos diferentes.

Métricas que mostram o processo

Acompanhe por chave e tipo:

eventos recebidos e únicos;
reentregas bloqueadas;
grupos abertos;
idade do grupo mais antigo;
tamanho em itens e bytes;
motivo de fechamento;
tempo do primeiro evento ao flush;
eventos tardios;
conflitos de versão;
grupos que atingiram teto;
janelas reabertas;
processamento por manifesto;
falhas depois do fechamento;
efeitos confirmados e incertos;
custo por unidade concluída;
prazo operacional cumprido.

Um alerta útil informa: “o pedido PED-104 atingiu a idade máxima com quatro eventos; o manifesto foi fechado; um evento tardio abriu nova janela; nenhuma alteração foi aplicada automaticamente”.

Checklist de implementação

[ ] A chave representa uma unidade empresarial e inclui tenant quando necessário?
[ ] Cada evento possui ID estável em retentativas?
[ ] Criar ou localizar o grupo e aceitar o primeiro evento é atômico?
[ ] A janela de inatividade nasceu do comportamento medido?
[ ] Existe idade, quantidade ou peso máximo?
[ ] O fechamento fixa um manifesto versionado?
[ ] Eventos tardios possuem rota explícita?
[ ] Ordem e versão vêm da fonte autorizada?
[ ] Reinícios preservam itens e chaves deduplicadas?
[ ] Coleta, interpretação e efeito estão separados?
[ ] A execução revalida o estado oficial antes da consequência?
[ ] Efeitos usam idempotência e confirmação?
[ ] Dados de clientes permanecem isolados?
[ ] Logs evitam payload sensível desnecessário?
[ ] Testes cobrem concorrência, atraso, reinício e transição?

Fontes oficiais verificadas em 16 de outubro de 2026

Temporal: Event Accumulator Pattern, para chave de grupo, Signal-With-Start, deduplicação, janela móvel, flush e Continue-As-New.
Microsoft Azure Architecture Center: Event-Driven Architecture Style, para produtores, canais, consumidores e agregação de eventos em janelas.

As fontes descrevem mecanismos de plataformas e arquitetura. A janela, a chave, a ordem, a retenção e as garantias do destino precisam ser testadas no processo real.

O silêncio precisa virar uma condição verificável

Um acumulador permite que o agente trabalhe sobre uma unidade coerente quando a quantidade de eventos ainda é desconhecida. O ganho aparece com chave correta, identidade por evento, fechamento versionado e recuperação durável.

A pausa no fluxo serve como sinal operacional, não como prova absoluta de que o mundo parou de mudar. Depois do fechamento, consulte a fonte oficial, preserve o manifesto e valide a consequência. É assim que vários sinais viram uma decisão auditável.