Contrato de dados para agentes de IA: como criar

A integração pode funcionar e ainda entregar o dado errado

Um agente comercial recebe oportunidades do CRM todas as manhãs. A integração responde sem erro, os campos chegam preenchidos e o processamento termina. Mesmo assim, parte das recomendações usa negócios encerrados como se ainda estivessem ativos.

O problema está no acordo entre os sistemas. Para o CRM, status = ativo significa que o registro continua aberto. Para a equipe comercial, a oportunidade só merece acompanhamento quando também possui responsável, próxima ação e data futura. O agente recebeu um campo válido com um significado insuficiente para a decisão.

Um contrato de dados define o que um produtor entrega, como cada informação deve ser interpretada, quais condições indicam qualidade aceitável e o que acontece quando o acordo deixa de ser cumprido. Ele organiza a fronteira entre sistemas, equipes e agentes antes que um dado ambíguo vire uma decisão operacional.

Esse trabalho cobre entradas, eventos, consultas e objetos compartilhados. As saídas estruturadas para agentes de IA tratam do resultado produzido pelo agente. O contrato de dados governa o material que atravessa toda a cadeia, inclusive antes da primeira chamada ao modelo.

O que é um contrato de dados

Contrato de dados é um acordo verificável entre quem produz uma informação e quem a consome. O acordo descreve estrutura, significado, qualidade, atualização, segurança, compatibilidade e responsabilidade.

Ele pode ser aplicado a:

um evento enviado por webhook;
uma consulta ao CRM;
um lote de documentos;
uma tabela usada para análise;
uma mensagem retirada de uma fila;
um objeto recuperado por API;
um índice usado para montar contexto;
uma saída intermediária entre agentes.

Um schema faz parte do contrato, mas não cobre o acordo inteiro. Saber que valor é um número não explica se ele representa receita bruta, valor líquido, saldo aberto ou previsão. Também não informa moeda, data de referência, origem, atraso esperado ou responsável pela correção.

O contrato torna essas condições explícitas e permite que a arquitetura bloqueie, trate ou encaminhe violações antes de produzir consequência.

Por que agentes ampliam o custo da ambiguidade

Sistemas tradicionais também sofrem com dados ruins. Agentes acrescentam alguns caminhos de propagação.

O modelo interpreta campos dentro de um contexto

Nomes parecidos podem receber o mesmo sentido, mesmo quando representam estados diferentes. Um campo chamado cliente_ativo pode significar contrato vigente para o financeiro e interação recente para o comercial.

O agente combina fontes

CRM, e-mail, documentos e planilhas podem entrar na mesma execução. Sem autoridade e semântica declaradas, a combinação parece completa enquanto mistura versões incompatíveis.

Uma interpretação pode acionar ferramentas

O resultado deixa a tela e atualiza sistemas, cria tarefas, envia mensagens ou escolhe uma rota. A ambiguidade passa a ter efeito externo.

O erro pode reaparecer em escala

Uma regra mal definida afeta cada unidade que recebe o mesmo contrato. O texto varia, mas a causa permanece na interface de dados.

A empresa precisa verificar a qualidade antes da interpretação e confirmar a autoridade antes da ação.

As oito partes de um contrato útil

1. Identidade do conjunto ou evento

Dê ao contrato um nome estável, uma versão e uma finalidade. Declare qual unidade de trabalho ele representa.

Exemplos:

oportunidade disponível para follow-up;
pedido pronto para validação;
chamado aguardando triagem;
documento liberado para análise;
pagamento confirmado;
agenda disponível para marcação.

Termos amplos como dados_do_cliente dificultam acesso, teste e evolução. A identidade deve apontar para um objeto operacional reconhecível.

2. Estrutura

Defina:

campos obrigatórios e opcionais;
tipos e formatos;
identificadores estáveis;
enumerações permitidas;
relacionamentos entre objetos;
limites de tamanho e volume;
representação de ausência;
campos proibidos.

A validação estrutural deve ocorrer antes de enviar o objeto ao agente. Corrigir formato com o modelo costuma aumentar custo e pode esconder uma falha do produtor.

3. Semântica

Cada campo relevante precisa de uma definição que duas áreas consigam aplicar da mesma forma.

Para proxima_acao_data, por exemplo, declare:

que evento cria ou altera a data;
qual fuso horário é usado;
se o prazo inclui fins de semana;
quando o campo pode ficar vazio;
quem confirma a mudança;
como cancelamento aparece;
qual sistema possui autoridade.

Exemplos positivos, negativos e casos-limite ajudam a reduzir interpretações concorrentes.

4. Qualidade

Transforme qualidade em condições observáveis. O contrato pode exigir:

identificador presente e válido;
relacionamento confirmado com a conta;
campos essenciais completos para o estado atual;
valores dentro de faixas permitidas;
ausência de duplicidade por chave definida;
documento dentro da vigência;
categoria pertencente à taxonomia oficial;
consistência entre campos relacionados.

Defina o tratamento para cada violação. Algumas impedem o processamento. Outras permitem seguir com aviso ou pedem revisão.

5. Atualização e validade

Um dado correto pode chegar depois da janela de decisão. Registre:

frequência de atualização;
atraso esperado;
horário de corte;
data do evento;
data da captura;
prazo de validade;
evento de invalidação;
comportamento durante indisponibilidade.

Um agente que prepara uma reunião pode aceitar dados comerciais atualizados na noite anterior. Um agente que confirma pagamento precisa de outra janela e de confirmação no sistema financeiro.

6. Origem e autoridade

O contrato deve apontar para o produtor e para a fonte autorizada. Cópias, caches e índices precisam aparecer como derivados.

Inclua:

sistema de origem;
objeto e identificador;
proprietário da fonte;
transformação aplicada;
versão do extrator ou conector;
data da última confirmação;
regra para conflitos;
referência para correção.

A fonte da verdade para agentes de IA define qual registro governa cada campo e evento. O contrato leva essa autoridade para a interface consumida pelo agente.

7. Segurança e finalidade

Declare quais dados podem circular, para qual finalidade e sob quais identidades.

O contrato deve registrar:

classificação de sensibilidade;
campos que exigem máscara;
operações permitidas;
ambientes autorizados;
consumidores aprovados;
prazo de retenção;
região ou destino de processamento quando aplicável;
regra de exclusão e correção.

O fato de uma API devolver um campo não autoriza seu uso em qualquer agente. O consumidor deve receber o conjunto mínimo para concluir a responsabilidade.

8. Responsabilidade e suporte

Todo contrato precisa de donos dos dois lados.

O produtor responde pela geração, disponibilidade e correção na origem. O consumidor responde pelo uso dentro da finalidade, pela validação e pelo tratamento de exceções. Quando existe uma plataforma intermediária, ela também precisa de responsabilidade definida.

Registre:

proprietário do produto de dados;
responsável pelo consumidor;
canal para incidentes;
prazo para corrigir classes de erro;
processo de mudança;
evidência de aceite;
data de revisão.

Contrato sem dono vira documentação de uma interface que continua mudando por fora.

Diferencie quebra estrutural de quebra operacional

As duas classes exigem respostas diferentes.

Quebra estrutural

O objeto viola formato, tipo, enumeração ou campo obrigatório. Exemplos:

data inválida;
identificador ausente;
campo renomeado;
lista enviada como texto;
versão desconhecida.

A validação determinística deve bloquear ou encaminhar o objeto. O agente não precisa receber uma entrada que já reprova no contrato.

Quebra operacional

A forma está correta, mas o conteúdo perdeu utilidade ou autoridade. Exemplos:

oportunidade aberta sem responsável;
documento válido no schema e vencido na operação;
status atualizado depois do prazo útil;
cliente ligado à conta errada;
valor confirmado por uma fonte sem autoridade.

Essa classe pede regras de negócio, consulta à fonte oficial e, em certos casos, decisão humana. O monitoramento deve separar as causas para que a equipe corrija o produtor certo.

Versione sem quebrar consumidores silenciosamente

Contratos mudam quando processos, sistemas e decisões mudam. A evolução precisa preservar compatibilidade ou declarar a ruptura.

Mudança compatível

Adicionar um campo opcional, ampliar documentação ou corrigir um exemplo pode manter a versão principal quando os consumidores existentes continuam interpretando o objeto da mesma forma.

Mudança incompatível

Renomear campo, alterar tipo, mudar significado, retirar enumeração ou modificar regra de ausência pode exigir uma nova versão.

Uma transição controlada inclui:

proposta com motivo e impacto;
lista de produtores e consumidores afetados;
exemplos nas duas versões;
testes de contrato;
período de convivência;
telemetria de uso;
data de retirada;
rollback ou adaptador temporário.

O controle de mudanças em agentes de IA deve promover contrato, validadores, conectores, testes e consumidores no mesmo pacote.

Implemente testes em três fronteiras

No produtor

Teste se cada objeto emitido respeita estrutura, semântica e condições de qualidade que podem ser verificadas na origem.

Na integração

Teste serialização, transformação, filtros, paginação, ordenação, fuso horário, duplicidade, atraso e perda de campos. Muitos contratos quebram no conector, não no sistema de origem.

No consumidor

Teste se o agente rejeita versão desconhecida, trata ausência, respeita finalidade e encaminha violações sem inventar valores. Inclua casos estruturalmente válidos com significado errado.

O ambiente de teste para agentes de IA deve reproduzir contratos e falhas sem depender de dados reais sensíveis.

Exemplo: contrato para follow-up comercial

Considere um agente que prepara a próxima ação de oportunidades abertas.

Unidade

Uma oportunidade elegível para revisão comercial.

Campos essenciais

oportunidade_id;
conta_id;
responsavel_id;
estagio_codigo;
ultima_interacao_em;
proxima_acao_em;
consentimento_contato;
restricoes;
versao_contrato.

Condições operacionais

a oportunidade continua aberta no CRM;
conta, contato e responsável possuem vínculo válido;
a última interação está disponível;
restrições de contato foram consultadas;
a data usa o fuso definido;
o registro chegou dentro da janela aceita;
conflitos bloqueiam envio e criam pendência.

Resultado da violação

Campo ausente pode gerar correção automática na origem quando existe regra determinística. Identidade conflitante, consentimento incerto ou estado divergente interrompem a ação e chegam ao responsável com evidência.

O agente só prepara ou executa follow-up depois que o contrato demonstra que a unidade está apta para aquela etapa.

Métricas para operar contratos de dados

Acompanhe por contrato e versão:

objetos recebidos;
aprovação estrutural na primeira passagem;
violações por campo e produtor;
objetos fora da janela de validade;
conflitos de identidade;
versões desconhecidas;
rejeições por finalidade ou permissão;
tempo para corrigir a origem;
exceções encaminhadas;
falhas que chegaram ao agente;
decisões afetadas por dado inválido;
consumidores ainda presos a versões antigas.

Taxa alta de entrega diz pouco quando o dado chega incompleto ou tarde. O indicador útil relaciona conformidade com unidades concluídas corretamente e sem retrabalho escondido.

Checklist do contrato de dados

[ ] A unidade de trabalho está nomeada?
[ ] Produtor e consumidores estão identificados?
[ ] Campos, tipos, enumerações e ausências estão definidos?
[ ] O significado de cada campo crítico é comum entre as áreas?
[ ] Qualidade possui condições mensuráveis?
[ ] Atualização e validade acompanham a janela de decisão?
[ ] Origem, autoridade e transformações aparecem no objeto ou em referência?
[ ] Finalidade, sensibilidade, acesso e retenção estão registrados?
[ ] Violações possuem tratamento por classe?
[ ] Existem donos para corrigir produção e consumo?
[ ] Mudanças compatíveis e incompatíveis seguem ritos diferentes?
[ ] Testes cobrem produtor, integração e consumidor?
[ ] O agente rejeita versão desconhecida e conflito relevante?
[ ] Métricas mostram efeito no processo, além da entrega técnica?

O contrato transforma integração em responsabilidade

Conectar um agente a uma API confirma que os sistemas conseguem trocar mensagens. A operação ainda precisa saber o que cada dado significa, quanto tempo permanece válido, quem responde por sua qualidade e qual decisão ele pode sustentar.

O contrato de dados reúne essas condições em uma interface verificável. Quando um produtor muda ou uma entrada perde qualidade, a arquitetura percebe antes que o agente distribua o erro. A empresa ganha uma base mais segura para combinar sistemas, modelos e pessoas sem depender de interpretações implícitas.