Watermarks e janelas temporais para agentes de IA

Uma venda da manhã pode aparecer no relatório da tarde

Um agente prepara o resumo de vendas a cada intervalo. Uma integração fica indisponível e entrega depois uma venda registrada antes do corte. Se o fluxo agrupa pelo horário de recebimento, essa venda entra no período errado. Se usa o horário da venda, precisa decidir quando pode encerrar cada período e o que fazer com uma entrada tardia.

Essa decisão exige um contrato temporal antes da interpretação pelo modelo. O agente deve receber um conjunto identificado, a situação da janela e os limites de cobertura. Um texto fluente não demonstra que todos os eventos esperados chegaram.

Watermarks são marcadores de progresso no tempo dos eventos usados por processadores de fluxo. Eles ajudam a decidir quando uma janela pode produzir resultado segundo a política do sistema. A garantia depende da origem do marcador e do tratamento de atrasos. Uma estimativa baseada nos eventos observados continua sujeita a eventos anteriores que apareçam depois.

Qual pergunta este guia resolve

O objeto deste artigo é o fechamento de intervalos pelo tempo em que os fatos ocorreram, com política explícita para entradas tardias e correções.

O guia de ordem de mensagens protege a sequência de alterações do mesmo objeto. O acumulador de eventos reúne um grupo até uma pausa, um evento terminal ou um limite. Já uma janela temporal precisa dizer se uma ocorrência pertence ao intervalo das 10h às 10h10, mesmo quando foi recebida depois.

Esses mecanismos podem coexistir. Uma mensagem pode chegar na ordem correta da fila e ainda pertencer a um período já publicado.

Preserve os relógios sem misturar seus significados

Registre, quando disponíveis:

• occurred_at: momento do fato declarado pela fonte;
• received_at: momento em que a infraestrutura recebeu o evento;
• processed_at: momento em que o consumidor executou o trabalho;
• versão do objeto e identificador do evento.

Normalize fuso e representação, preservando o valor original quando necessário para auditoria. Não substitua silenciosamente uma data inválida pelo horário atual.

O tempo do evento costuma atender perguntas como vendas por período de ocorrência ou quantidade de chamados abertos naquele intervalo. O tempo de chegada atende outras perguntas, como carga recebida pela integração. Os dois números podem estar corretos e responder a perguntas diferentes.

Para decidir qual estado do pedido vale agora, use também a versão emitida pela fonte autorizada. Timestamp isolado não resolve conflito de estado, relógio incorreto ou concorrência de escrita.

Defina a janela com fronteiras inequívocas

Uma janela fixa pode representar o intervalo 10:00 <= occurred_at < 10:10. O instante 10:10 pertence ao próximo intervalo. Essa regra precisa permanecer igual no consumidor, no relatório e na reexecução.

Documente:

1. campo temporal usado e fonte responsável por ele;
2. fuso e calendário de negócio;
3. duração e fronteiras do intervalo;
4. chave de agrupamento, incluindo empresa ou tenant;
5. política de deduplicação;
6. condição de publicação;
7. destino de eventos tardios;
8. retenção necessária para refazer a análise.

Janelas móveis e sessões possuem regras diferentes de sobreposição e fechamento. Comece pela pergunta empresarial. Um relatório de fechamento diário pode precisar do calendário da empresa; uma métrica de tráfego pode usar intervalos em UTC. Não altere a semântica apenas para aproveitar o padrão da ferramenta.

Watermark precisa ter um contrato de progresso

Na documentação do Azure Stream Analytics consultada em 20 de outubro de 2026, a geração de watermarks é heurística por partição. Quando há eventos, usa o maior tempo observado menos a tolerância a desordem. Na ausência de entradas, o serviço possui uma regra própria baseada em chegada estimada e tolerância de atraso.

Essas regras pertencem ao produto. Não assuma que outra plataforma usa o mesmo cálculo ou que um consumidor artesanal pode avançar o marcador com o relógio local sem consequências.

Como desenho operacional, defina o marcador como a fronteira a partir da qual o sistema deixa de esperar entradas anteriores na rota normal, sob as condições documentadas. Ao atravessar o final de uma janela, o processador pode fechar aquela janela. Entradas anteriores que chegarem depois seguem a política de atraso.

Em fontes particionadas, confira como o motor combina o progresso das partições relevantes. Uma partição silenciosa pode atrasar o fechamento; marcá-la como inativa pode permitir avanço e tornar suas próximas entradas tardias. Registre esse comportamento e seu impacto na cobertura.

Exemplo sintético de fechamento e correção

Considere uma análise de valores por ocorrência, na janela de 10h a 10h10. Os dados abaixo são fictícios. Valores servem somente ao exercício.

| Evento | Ocorrência | Chegada | Valor | |---|---|---|---:| | E1 | 10:01 | 10:01 | 40 | | E2 | 10:04 | 10:06 | 60 | | E3 | 10:11 | 10:11 | 20 | | E4 | 10:08 | 10:14 | 30 |

Às 10h12, suponha que o processador tenha um marcador de progresso em 10h09. A soma conhecida da primeira janela é 100, mas a janela ainda permanece aberta. O evento E3 pertence à janela seguinte, embora já tenha chegado.

Às 10h13, suponha que a infraestrutura avance o marcador para 10h12 segundo seu contrato. A primeira janela pode ser publicada na versão 1, com total 100. O exemplo fornece esses marcadores explicitamente; não os deduz dos quatro eventos nem reproduz o algoritmo do Azure.

E4 chega às 10h14 com ocorrência às 10h08. A política fictícia deste exercício mantém uma rota de correção: reconstitui a janela, inclui E4 uma única vez e publica a versão 2 com total 130. A versão anterior permanece vinculada à correção.

A Júpiter conferiu localmente as somas e as fronteiras declaradas. A checagem não executou Azure Stream Analytics, broker, persistência, agente ou mecanismo real de watermark. Ela demonstra somente a coerência do exemplo.

Escolha como tratar o que chega tarde

Uma política pode encaminhar a entrada para revisão, descartá-la com evidência ou produzir uma correção. A escolha depende da consequência e das capacidades do motor.

Se o resultado for um painel exploratório, uma atualização versionada pode ser suficiente. Se já tiver causado cobrança, mensagem ao cliente ou decisão sensível, alterar a soma não desfaz o efeito. A correção precisa localizar as consequências anteriores e passar pela autoridade adequada.

No Azure Stream Analytics, a documentação descreve opções para descartar eventos ou ajustar o timestamp utilizado pelo processamento, conforme a tolerância configurada. O campo temporal original pode continuar diferente de System.Timestamp. Preserve essa distinção na evidência. Não apresente a política de versões do exemplo como recurso nativo desse serviço: a documentação informa que agregados parciais de janela não são atualmente suportados no produto.

Um contrato de atraso deve informar destino, prazo de tratamento, responsável, possibilidade de correção e o que acontece quando a retenção necessária já venceu.

Entregue ao agente um manifesto da janela

Antes de pedir resumo ou diagnóstico, prepare uma estrutura conferível:

window_id: vendas:empresa_ficticia:10h00
interval: [10:00, 10:10)
time_basis: occurred_at
timezone: UTC
result_version: 2
previous_result_version: 1
status: corrigida
accepted_event_ids: E1, E2, E4
late_event_ids: E4
progress_marker_at_closure: 10:12
policy_version: temporal_3
verified_total: 130

Os horários abreviados servem à leitura do exemplo. Em produção, use data completa, fuso e precisão definidos no contrato.

O modelo pode explicar a variação entre versões, desde que preserve os IDs e a causa documentada. Ele não deve concluir que as vendas cresceram por desempenho comercial quando a mudança veio de uma entrega atrasada da integração.

A linhagem de dados para agentes ajuda a ligar a análise às entradas. A idempotência protege a publicação ou consequência contra repetição. Identifique o efeito por janela, versão e finalidade, respeitando se a operação é uma nova correção ou uma repetição da mesma versão.

Teste o contrato temporal antes da produção

Inclua entradas exatamente no corte, eventos fora de ordem, duplicidades, timestamps inválidos e relógios no futuro. Teste também partição silenciosa, retorno de uma origem inativa, reinício durante fechamento e evento tardio depois de uma consequência externa.

Confira se a mesma entrada e a mesma política reproduzem o resultado esperado. Verifique quais metadados e versões precisam permanecer armazenados para isso. Uma reexecução com regra de fuso diferente pode mudar o período mesmo quando os eventos são idênticos.

Monitore atraso entre ocorrência e chegada, idade das janelas abertas, eventos descartados ou ajustados, correções por janela e consequências pendentes de revisão. Limites devem nascer do processo e de medições autorizadas, sem percentuais universais.

Checklist de decisão

• O relatório informa qual relógio responde à pergunta?
• Fronteiras, fuso e chave de empresa estão definidos?
• O watermark tem origem e regra documentadas?
• Partições silenciosas possuem tratamento conhecido?
• O resultado distingue aberto, publicado e corrigido?
• Eventos tardios têm destino e dono?
• A correção mantém vínculo com o resultado anterior?
• Efeitos externos exigem revisão própria quando necessário?
• Testes cobrem fronteiras, atraso, repetição e retomada?

Fonte oficial e limites

Fonte consultada em 20 de outubro de 2026: Microsoft Learn, tratamento de tempo no Azure Stream Analytics.

A fonte sustenta as distinções temporais e o comportamento específico do Azure descrito acima. O manifesto, a política de correção e os critérios de operação são recomendações de arquitetura da Júpiter, não garantias universais de um fornecedor. O responsável técnico deve conferir a versão e o contrato da plataforma escolhida antes de implementar.