Sincronização incremental para agentes de IA

A base pode continuar mostrando um objeto que já foi removido

Uma equipe conecta um agente a uma coleção de documentos. A primeira carga funciona. Nas semanas seguintes, a integração busca arquivos novos, mas não acompanha exclusões. O agente continua recuperando conteúdo que deixou de existir na fonte.

A sincronização incremental mantém uma projeção local por meio das mudanças informadas pelo sistema de origem. Precisa incorporar criações, alterações e remoções, além de preservar um ponto confirmado de continuidade.

Este guia resolve a manutenção dessa projeção entre rodadas. A paginação de APIs cuida da travessia dentro de uma consulta. A sincronização decide de onde começa a próxima rodada e como a base permanece coerente ao longo do tempo.

Verifique o contrato de mudanças antes de escolher a arquitetura

Uma API de listagem comum não necessariamente oferece captura de mudanças. Filtrar por data de atualização pode deixar exclusões invisíveis, perder empates de horário ou ignorar alterações em relacionamentos.

Antes de implementar, confirme:

• quais recursos e propriedades participam do rastreamento;
• como obter a carga inicial;
• como continuar dentro de uma rodada;
• como pedir mudanças posteriores;
• qual representação indica remoção;
• se o retorno contém o objeto completo ou somente campos alterados;
• como tratar repetições e ordem;
• quando o token perde validade;
• quais permissões e limites se aplicam ao recurso.

No Microsoft Graph, a documentação de delta query descreve tokens opacos, URLs de continuação e uma URL para a próxima rodada. O suporte varia por recurso; alguns endpoints estão em beta. Não habilite uma integração de produção apenas porque o objeto principal existe na API estável.

Separe continuação de página e continuidade entre rodadas

No contrato geral do Graph, @odata.nextLink aponta para outra página da rodada atual. Uma resposta vazia com essa propriedade ainda exige continuação.

@odata.deltaLink encerra a rodada atual e fornece o endereço para consultar mudanças no futuro. As duas propriedades não aparecem juntas em uma mesma página segundo esse contrato.

O adaptador deve preservar a URL inteira, sem interpretar o token ou remontar seus parâmetros. Os parâmetros da consulta inicial ficam incorporados aos links. Isso não dispensa validar o destino e proteger a credencial antes da chamada.

Registre separadamente:

sincronizacao_id: recurso + tenant + perfil de consulta
projecao_ativa: geração atualmente consultável
rodada_id: tentativa de atualização em andamento
continuacao_pendente: próxima página, se existir
delta_confirmado: ponto da última rodada aplicada
estado: INICIALIZANDO | ATUALIZANDO | ATUAL | RECONSTRUINDO | BLOQUEADO
ultima_rodada_concluida_em: instante confirmado

Uma execução interrompida pode possuir páginas persistidas e uma continuação pendente. Ela ainda não autoriza divulgar que a projeção está atualizada até o final da rodada.

Aplique mudanças conforme a semântica do recurso

Um objeto pode aparecer várias vezes. Também pode trazer apenas parte de suas propriedades. Substituir a linha inteira por um payload parcial pode apagar informações válidas da projeção.

O contrato de dados deve distinguir campo ausente, valor nulo explícito e remoção de objeto. Cada condição precisa de tratamento próprio:

• campo ausente: preservar ou buscar o valor conforme o contrato do endpoint;
• campo presente: aplicar a alteração com sua semântica documentada;
• marcador de remoção: retirar o objeto do conjunto consultável ou marcá-lo indisponível;
• objeto repetido: processar conforme as regras de merge daquele recurso.

Evite inventar uma ordenação global por horário local. A documentação geral do Graph alerta que a mesma entidade pode aparecer em posições diferentes na sequência. A estratégia deve vir do endpoint, com testes para sua representação específica.

Delta query ajuda a manter estado. Não presuma que o feed contenha o histórico completo de todas as transições empresariais. Se a empresa precisa reconstruir cada evento, avalie um mecanismo próprio de event sourcing ou uma fonte de auditoria adequada.

Trate exclusão como parte do fluxo normal

O contrato geral do Graph representa determinadas remoções com ID e @removed; outros recursos podem usar outra estrutura. O significado do motivo também precisa ser lido na documentação específica.

Na arquitetura da empresa, a remoção deve alcançar os derivados que permitem recuperar o objeto. Isso pode incluir registro local, índice de busca, embeddings, cache e referências de contexto.

Mantenha um marcador mínimo de exclusão quando ele for necessário para bloquear reaparecimento por reentrega. Esse marcador precisa respeitar a política de retenção, sem conservar indefinidamente o conteúdo removido.

Uma remoção da coleção não explica, sozinha, a causa comercial. Não converta desaparecimento de um cadastro em cancelamento de contrato, perda de cliente ou autorização para apagar outros sistemas.

Confirme os dados antes de avançar o checkpoint

O ponto de continuidade representa mudanças já incorporadas. Se for salvo antes dos dados, uma falha pode fazer a próxima rodada começar depois de alterações que nunca chegaram à projeção.

Há duas opções comuns de implementação:

Aplicação transacional

Quando dados e checkpoint cabem no mesmo armazenamento, confirme as alterações e o avanço correspondente na mesma transação. Repetições precisam produzir o mesmo estado válido.

Área de preparação e promoção

Para uma reconstrução maior, monte uma geração separada, complete a coleta e confira cobertura antes de trocar a referência consultável. Preserve a geração anterior enquanto a candidata permanece incompleta.

Se o índice de busca vive em outro sistema, a confirmação do banco não prova que a recuperação já foi atualizada. Registre o progresso de cada destino e só anuncie o estado que pode verificar. A leitura após escrita detalha o intervalo em que uma gravação aceita ainda não aparece em todas as consultas.

Nenhum desses desenhos torna bancos, índices e APIs atomicamente consistentes por conveniência. Quando não houver transação comum, use estados explícitos e recuperação idempotente.

Recupere tokens inválidos sem fabricar cobertura

O Graph documenta possibilidade de 410 Gone, expiração de token e erros como syncStateNotFound. Prazo e comportamento dependem do recurso. Não copie uma duração de um tipo de objeto para todos os conectores.

Ao detectar perda do estado de sincronização:

1. marque a projeção como desatualizada ou em reconstrução;
2. preserve a última versão confirmada com sua data e limitações;
3. inicie a carga completa exigida pelo endpoint;
4. aplique todas as páginas na geração candidata;
5. trate remoções e valide o escopo;
6. promova a nova geração com seu checkpoint;
7. retome a coleta incremental.

Apagar o token e marcar sucesso esconderia justamente a janela sem cobertura. A decisão sobre continuar usando a projeção antiga depende do risco da tarefa. Uma pesquisa exploratória tolera uma limitação que uma ação sensível pode precisar bloquear.

Combine notificações com recuperação de mudanças

A documentação do Graph permite combinar notificações de alteração com delta query para recursos suportados. A notificação pode despertar o sincronizador; a consulta recupera as mudanças desde o ponto confirmado.

O webhook e o sincronizador devem manter responsabilidades distintas. Receber um aviso não comprova que a projeção foi atualizada. Também convém manter uma verificação periódica compatível com a validade do token e os limites do serviço, em vez de depender exclusivamente de cada notificação.

Laboratório sintético: atualização, exclusão e retomada

Em 20 de outubro de 2026, a Júpiter executou uma fixture local em Python, sem chamadas ao Graph ou a modelos. A projeção fictícia começava com dois objetos:

A: nome Atlas, estado open
B: nome Boreal
Checkpoint confirmado: d1

Primeira página da rodada:
A: estado closed, sem repetir o nome
B: marcador de remoção
Continuação: p2

Última página:
C: nome Cedro
Novo checkpoint: d2

O resultado manteve o nome Atlas, alterou seu estado para closed, removeu B, acrescentou C e confirmou d2. Reaplicar as mesmas páginas preservou o resultado.

Interromper antes da última página manteve a projeção anterior e d1. Uma falha simulada antes do compromisso também manteve esse estado; a repetição completa chegou ao resultado esperado.

A fixture usa merge simplificado e preparação em memória. Ela verifica essas regras sintéticas, sem comprovar durabilidade, ordenação ou semântica de um endpoint real. A homologação precisa repetir os casos no armazenamento e no conector usados em produção.

Evidência para liberar a projeção

O mantenedor deve conseguir mostrar a última rodada completa, seu escopo, checkpoint protegido, quantidade de alterações e exclusões, idade da projeção e pendências de cada destino derivado.

Monitore reinícios completos, tokens inválidos, atraso de aplicação e divergências encontradas por amostragem. Antes de uma ação de alto impacto, consulte novamente o objeto na fonte autorizada quando a política exigir estado atual.

O dono operacional define quanto atraso o processo tolera. A equipe técnica demonstra se a integração está dentro desse limite. Um agente que usa a projeção deve receber a indicação de atualidade junto com os dados.

Fonte oficial verificada em 20 de outubro de 2026

• Microsoft Graph: delta query overview, para continuidade, tokens, suporte por recurso, remoções, replays, atrasos e reinicialização.

Os estados operacionais, a promoção por geração e a fixture são propostas de arquitetura da Júpiter. Antes de implementar, confira a documentação do recurso escolhido e teste a perda do checkpoint, inclusive quando o serviço continua respondendo normalmente.