Schema registry para eventos de agentes de IA

O produtor mudou um campo e a fila continuou entregando o passado

Um sistema comercial publica o evento proposta_aprovada. A primeira versão envia valor_total como número. A versão seguinte passa a enviar moeda, parcelas e condição de pagamento dentro de um objeto chamado condicoes.

O produtor novo funciona. O agente que prepara o contrato continua lendo mensagens criadas pela versão antiga. Outro consumidor ainda espera valor_total. Uma tarefa pausada volta dois dias depois com o formato anterior. A mudança aprovada no código criou três interpretações para o mesmo fato.

Um schema registry mantém versões formais dos formatos usados em eventos e aplica regras de compatibilidade antes que uma nova versão entre no fluxo. Ele ajuda produtores e consumidores a evoluir sem depender de uma troca simultânea de todos os componentes.

O foco deste guia é a fronteira assíncrona entre quem publica e quem consome eventos. O contrato de dados para agentes de IA cobre significado, qualidade, autoridade e responsabilidade em várias interfaces. Aqui, a pergunta é mais estreita: qual mudança pode ser publicada enquanto mensagens antigas, consumidores anteriores e reprocessamentos continuam existindo?

O registry governa o formato, não o significado inteiro

Um registry costuma armazenar schemas versionados, atribuir identificadores e comparar uma proposta com versões anteriores. Serializadores e consumidores podem usar o identificador para localizar a definição correta.

Essa camada consegue verificar aspectos como:

campos e tipos;
obrigatoriedade e valores padrão;
estruturas aninhadas;
enums e uniões permitidas;
versão ou identificador do schema;
regra de compatibilidade aplicada;
formato suportado pelo produto, como Avro, Protobuf ou JSON Schema.

Ela não prova que valor_total representa valor bruto, líquido ou aprovado. Também não confirma se o produtor possui autoridade para declarar uma proposta aprovada. Semântica, fonte oficial, finalidade e qualidade continuam no contrato operacional.

A validação estrutural impede parte das quebras. A operação ainda precisa testar se o evento correto produz a decisão correta.

Separe quatro versões que costumam ser misturadas

Uma mensagem pode atravessar mudanças em camadas diferentes.

Versão do evento

Identifica o contrato do payload. Define como interpretar campos, tipos e ausências.

Versão do produtor

Identifica o componente que criou a mensagem. Duas versões do produtor podem emitir o mesmo schema durante uma transição.

Versão do consumidor

Identifica o código que leu o evento e tomou uma ação. Esse registro ajuda a explicar por que mensagens iguais produziram resultados diferentes.

Versão da política

Representa a regra empresarial vigente. Um payload estruturalmente compatível pode chegar depois que a alçada, a validade ou o processo mudaram.

Guardar somente version: 2 deixa a investigação ambígua. Um envelope mais útil separa essas identidades:

{
  "event_id": "EVT-20481",
  "event_type": "proposta_aprovada",
  "event_schema_id": "proposta-aprovada-v3",
  "producer_version": "crm-2026.09.2",
  "policy_version": "comercial-2026-09",
  "occurred_at": "2026-09-29T14:20:00Z",
  "object_id": "PROP-882",
  "data": {}
}

O registry responde pelo schema. O envelope preserva identidade, origem e contexto de evolução.

Escolha compatibilidade pela ordem real de implantação

Compatibilidade só faz sentido quando ligada a produtores, consumidores e mensagens retidas.

Compatibilidade retroativa

O consumidor novo consegue ler eventos produzidos com o schema anterior. Esse modo ajuda quando consumidores são atualizados antes dos produtores e quando precisam reler histórico.

Compatibilidade futura

O consumidor antigo consegue ler eventos produzidos com o schema novo. Esse modo ajuda quando produtores mudam antes de todos os consumidores.

Compatibilidade completa

Versões antigas e novas conseguem conviver nas duas direções previstas pela ferramenta e pelo formato. A flexibilidade cobra disciplina maior sobre campos opcionais, padrões e mudanças permitidas.

Compatibilidade transitiva

A nova versão é comparada com todo o histórico relevante, não apenas com a versão imediatamente anterior. Isso importa quando eventos antigos permanecem retidos, podem ser reprocessados ou sustentam novos consumidores.

A documentação da Confluent distingue verificações retroativas, futuras, completas e transitivas. Ela também liga o modo escolhido à ordem de atualização dos clientes. A Microsoft documenta modos de compatibilidade no Schema Registry do Azure Event Hubs e ressalta que a evolução suportada ali depende do formato e das regras do grupo de schemas.

O nome do modo não autoriza uma mudança sozinho. A equipe precisa conferir as regras do formato e testar mensagens reais de cada versão mantida.

Comece pelo tempo de vida dos eventos

A versão anterior pode continuar circulando muito depois do deploy.

Inventarie:

retenção no tópico ou fila;
mensagens ainda não consumidas;
consumidores pausados;
filas de erro;
arquivos ou streams usados para replay;
tarefas longas que carregam o evento original;
ambientes de contingência;
cópias usadas em auditoria e testes;
prazo em que um produtor antigo ainda pode publicar;
prazo em que um consumidor antigo continuará ativo.

Uma checagem somente contra a última versão pode passar e ainda quebrar um evento de três versões atrás. Quando o histórico continua operacional, a política precisa cobrir esse histórico ou definir uma transformação explícita.

O artigo sobre migração do estado de agentes trata checkpoints e tarefas persistidas. Eventos retidos são outra fronteira: eles podem chegar novamente a vários consumidores, inclusive depois que o produtor original saiu de operação.

Classifique a mudança antes de registrá-la

Adição opcional

Um campo novo pode ser ignorado por leitores antigos e receber valor padrão em leitores novos, conforme as regras do formato. A operação precisa verificar se a ausência continua segura.

Adição obrigatória

Consumidores e mensagens antigas não possuem o valor. A mudança costuma exigir nova versão, preenchimento determinístico ou transição em fases.

Remoção

Retirar um campo pode ser compatível para uma direção e incompatível para outra. Também pode quebrar uma decisão mesmo quando o desserializador aceita a mensagem.

Renomeação

Renomear geralmente equivale a retirar um campo e adicionar outro. Preserve leitura dupla ou use um adaptador durante a convivência.

Mudança de tipo

Trocar texto por número, lista por objeto ou unidade monetária pode invalidar serialização, comparação e regras existentes.

Restrição de enum

Remover um valor aceito deixa eventos antigos sem interpretação válida. Adicionar um valor também exige que consumidores antigos saibam recusá-lo ou encaminhá-lo com segurança.

Mudança semântica

O campo mantém nome e tipo, mas passa a significar outra coisa. O registry pode aceitar. O processo pode quebrar silenciosamente. Mudança de significado pede outro campo, outro evento ou uma versão com documentação e testes próprios.

Use uma sequência de convivência

Uma evolução segura evita a troca coordenada em um único instante.

1. Proponha o contrato

Registre motivo, evento afetado, campos alterados, compatibilidade pretendida, consumidores conhecidos, retenção e data de retirada.

2. Teste no registry

Submeta o schema à regra configurada. Uma rejeição deve interromper a publicação. Uma aprovação estrutural ainda segue para testes operacionais.

3. Atualize leitores

Consumidores passam a entender o formato novo e continuam aceitando as versões antigas necessárias. Valores ausentes e desconhecidos recebem tratamento explícito.

4. Publique o produtor

O produtor começa a emitir a nova versão. A mudança pode ser limitada por ambiente, partição, tipo de evento ou grupo de clientes.

5. Observe a convivência

Meça mensagens por schema, falhas de desserialização, campos ausentes, consumidores atrasados e eventos encaminhados para exceção.

6. Retire a versão antiga

A retirada só avança depois que produtores antigos pararam, backlog e replays foram avaliados e nenhum consumidor aprovado depende do contrato anterior.

Esse fluxo coordena código e dados em movimento. Apenas registrar v2 não organiza a transição.

Valide na publicação e no consumo

A validação no produtor bloqueia mensagens que não obedecem ao schema associado. A documentação do Google Cloud Pub/Sub informa que mensagens incompatíveis com o schema vinculado ao tópico não são publicadas e que o schema pode receber revisões.

Ainda assim, valide também no consumidor.

O consumidor precisa verificar:

identificador de schema conhecido;
tipo de evento esperado;
objeto e conta dentro do escopo;
campos exigidos pela decisão atual;
versão de política aplicável;
validade temporal;
permissões para consultar dados complementares;
tratamento de valor novo ou desconhecido;
rota para versão sem suporte.

Uma mensagem pode ter sido aceita no tópico e continuar inadequada para aquele consumidor. Os dois gates protegem fronteiras diferentes.

Não entregue evento desconhecido ao modelo para ele adivinhar

Quando aparece um campo, enum ou versão sem suporte, o caminho seguro é determinístico:

interromper a ação dependente;
preservar evento e identificadores;
registrar produtor, schema e consumidor;
classificar a incompatibilidade;
encaminhar para adaptador, correção ou fila de exceção;
reprocessar somente depois de teste e autorização.

Pedir ao modelo para inferir o formato pode gerar uma interpretação plausível e impossível de auditar. O modelo pode ajudar a resumir a diferença para uma pessoa. A compatibilidade precisa ser decidida por contrato e código testado.

Trate defaults como decisões

Um valor padrão mantém a desserialização funcionando, mas pode alterar o processo.

Considere a inclusão de requires_human_review. Usar false para eventos antigos evita campo ausente e pode liberar automaticamente casos que nunca foram avaliados por essa regra. Usar true aumenta revisão, porém preserva uma postura conservadora.

Para cada default, registre:

por que o valor representa eventos antigos;
qual consequência ele autoriza ou bloqueia;
em quais versões será aplicado;
como casos ambíguos serão encaminhados;
quando o default deixará de existir;
quem aprovou a decisão.

Compatibilidade sintática sem decisão sobre defaults apenas desloca a quebra para dentro da operação.

Teste com mensagens históricas e futuras

Monte um conjunto pequeno por evento crítico:

mensagem válida de cada versão retida;
campo opcional ausente;
enum antigo;
enum novo desconhecido pelo consumidor anterior;
campo renomeado;
tipo incompatível;
payload válido com semântica antiga;
mensagem duplicada;
mensagem fora de ordem;
evento vencido;
schema desconhecido;
produtor novo com consumidor antigo;
produtor antigo com consumidor novo.

Para cada caso, confirme:

publicação aceita ou bloqueada;
schema resolvido;
desserialização;
normalização interna;
regra empresarial aplicada;
ação externa permitida ou impedida;
evidência gerada;
destino da exceção.

O teste termina no efeito, não no parser.

Exemplo: aprovação comercial em transição

A versão 1 do evento contém:

{
  "proposal_id": "PROP-882",
  "approved": true,
  "total": 48000
}

A versão 2 passa a exigir condição detalhada:

{
  "proposal_id": "PROP-882",
  "decision": "approved",
  "currency": "BRL",
  "payment_terms": {
    "installments": 3,
    "first_due_at": "2026-10-10"
  },
  "approved_version": 7
}

O contrato novo acrescenta informação que o evento antigo não contém. Um adaptador pode copiar proposal_id e mapear approved para decision. Ele não deveria inventar moeda, parcelamento, vencimento ou versão aprovada.

O consumidor novo pode normalizar a versão 1 para um estado dados_comerciais_pendentes, consultar a proposta oficial e pedir revisão quando não houver equivalência segura. O evento continua legível sem ganhar fatos que nunca carregou.

Monitore a adoção por versão

Acompanhe:

eventos publicados por tipo e schema;
produtores por versão;
consumidores por versão;
falhas de registro de schema;
mensagens rejeitadas na publicação;
falhas de desserialização;
versões desconhecidas;
uso de defaults;
eventos encaminhados para exceção;
mensagens antigas ainda presentes no backlog;
reprocessamentos por versão;
consumidores sem tráfego recente;
decisões bloqueadas por incompatibilidade;
efeitos incorretos ligados a mudança de contrato.

Ausência de erro também pode esconder um consumidor parado. Cruze a adoção do schema com consumer lag e idade do backlog, para saber se a versão antiga desapareceu ou apenas deixou de ser processada.

Checklist para operar um schema registry

[ ] Cada evento possui tipo e finalidade claros?
[ ] Schema, produtor, consumidor e política têm versões separadas?
[ ] A retenção e as rotas de replay foram inventariadas?
[ ] O modo de compatibilidade corresponde à ordem de implantação?
[ ] A checagem cobre todas as versões ainda operacionais?
[ ] Mudanças semânticas recebem tratamento além do schema?
[ ] Leitores são atualizados antes da publicação quando necessário?
[ ] Defaults possuem consequência e dono explícitos?
[ ] Publicação e consumo validam suas próprias fronteiras?
[ ] Versão desconhecida bloqueia ação em vez de gerar inferência?
[ ] Testes usam mensagens de versões antigas e novas?
[ ] A retirada depende de backlog e consumidores comprovadamente encerrados?
[ ] Métricas mostram adoção, incompatibilidade e efeito operacional?

Compatibilidade precisa sobreviver ao caminho inteiro

Schema registry cria um gate verificável para formatos que evoluem. Ele impede mudanças incompatíveis conhecidas de chegarem ao fluxo e oferece identidade para produtores e consumidores interpretarem cada mensagem.

A proteção fica completa quando o registry acompanha retenção, ordem de implantação, testes históricos, defaults aprovados e tratamento de versões desconhecidas. Assim, a empresa consegue mudar eventos sem exigir que todo o sistema esqueça imediatamente o formato anterior.

Fontes oficiais verificadas em 29 de setembro de 2026: