Linhagem de dados em agentes de IA: guia prático

Uma resposta errada pode ter começado em uma cópia correta

Um agente de atendimento informa ao cliente uma política que já foi substituída. A base oficial está atualizada. O documento antigo saiu da pasta principal. Mesmo assim, um índice vetorial criado dias antes continua recuperando o trecho anterior.

A equipe vê o texto final e culpa o modelo. A causa está no caminho do dado: documento, extração, divisão em trechos, índice, busca, montagem de contexto, interpretação e resposta. Sem esse caminho registrado, cada investigação começa pela superfície e depende de reconstrução manual.

Linhagem de dados é o registro da origem, das transformações, das cópias e dos usos de uma informação ao longo do processo. Em agentes de IA, ela conecta o dado consultado à decisão proposta e ao efeito confirmado no sistema de destino.

Essa visão permite responder qual fonte alimentou o caso, que versão foi usada, como o conteúdo mudou, quem autorizou o uso e quais execuções precisam de revisão depois de uma correção.

Linhagem, tracing e fonte da verdade têm trabalhos diferentes

Os três mecanismos se encontram, mas não entregam o mesmo artefato.

Fonte da verdade define autoridade

Ela informa qual sistema ou registro governa um campo, estado ou evento. O guia sobre fonte da verdade para agentes de IA ajuda a resolver conflitos entre CRM, ERP, documentos, conversas e memória.

Tracing reconstrói a execução

O tracing de agentes de IA conecta etapas, chamadas, ferramentas, tentativas, aprovações e resultados de uma unidade de trabalho. Ele responde o que aconteceu durante uma execução.

Linhagem segue o dado

A linhagem acompanha uma informação entre fontes, cópias, transformações, contextos, saídas e registros. Ela responde de onde veio, o que mudou, onde foi usada e o que pode ter sido afetado.

Um trace pode mostrar que o agente consultou um índice. A linhagem precisa ligar o trecho recuperado ao documento, à versão, à extração e ao processo que criou o índice.

Quais dados precisam de linhagem

Registrar o caminho completo de tudo pode criar custo e exposição sem utilidade. Comece pelos dados que influenciam decisão, ação ou obrigação.

Priorize:

estados usados para escolher uma rota;
valores financeiros;
identidade de cliente, fornecedor ou colaborador;
políticas e procedimentos;
condições comerciais;
documentos regulados ou contratuais;
dados pessoais ou sensíveis;
classificações que definem prioridade;
evidências usadas em aprovação;
campos escritos em sistemas oficiais;
conteúdo derivado que será reutilizado por outros agentes.

A profundidade deve acompanhar consequência e capacidade de investigação. Um rascunho interno pode exigir referência simples. Uma ação financeira pede origem, versão, transformação, aprovação e confirmação.

O mapa mínimo da linhagem

Uma linhagem útil precisa conectar seis pontos.

1. Origem

Identifique o sistema, documento, evento ou pessoa que produziu o dado. Registre:

tipo de fonte;
identificador do objeto;
versão ou horário;
proprietário;
autoridade sobre o campo;
classificação de sensibilidade;
condição de acesso.

A origem deve permanecer referenciável. Copiar apenas o conteúdo elimina o vínculo necessário para conferir ou corrigir.

2. Captura

Mostre como a informação entrou na arquitetura:

API;
webhook;
consulta ao banco;
upload;
leitura de e-mail;
sincronização;
OCR;
extração multimodal;
entrada manual.

Registre versão do conector, identidade técnica, momento da captura e resultado da validação inicial. Um dado pode estar correto na fonte e ser truncado, convertido ou associado ao objeto errado durante a entrada.

3. Transformação

Toda alteração relevante precisa aparecer no caminho.

Exemplos:

normalização de data ou moeda;
deduplicação;
associação entre entidades;
remoção ou máscara de campos;
OCR;
tradução;
resumo;
classificação;
divisão de documento em trechos;
criação de embedding;
agregação;
cálculo determinístico;
correção humana.

Para cada transformação, registre componente, versão, entrada, saída, regra, horário e responsável. Quando houver perda de informação, deixe a perda explícita.

4. Uso no contexto

O sistema precisa mostrar qual fragmento chegou ao agente e por qual critério.

Inclua:

consulta realizada;
filtros aplicados;
trechos recuperados;
pontuação ou regra de seleção;
ordem e limite de contexto;
exclusões;
versão da fonte;
validade no momento do uso.

A engenharia de contexto para agentes de IA organiza a seleção do material necessário. A linhagem preserva a ligação entre esse material e sua origem.

5. Decisão ou saída derivada

Separe o que foi observado do que o modelo inferiu.

Uma saída pode registrar:

fatos extraídos com referência;
transformações determinísticas;
classificação do modelo;
regra aplicada;
evidência usada;
versão do modelo e das instruções;
validação;
aprovação humana;
estado final.

As saídas estruturadas para agentes de IA ajudam a manter fatos, interpretações, validações e decisão em campos diferentes.

6. Consequência

Feche o caminho no destino. Registre:

ação solicitada;
identidade usada;
sistema e objeto afetados;
estado anterior;
alteração proposta;
confirmação devolvida;
identificador da transação;
horário;
responsável por eventual revisão.

Sem confirmação, a linhagem termina em uma intenção. A empresa ainda não sabe se o dado produziu efeito.

Use identificadores que atravessem a cadeia

O vínculo entre camadas depende de chaves estáveis. Alguns identificadores comuns:

source_record_id para o registro de origem;
source_version para a versão ou data válida;
event_id para o evento de entrada;
work_item_id para a unidade operacional;
transform_id para a transformação;
artifact_id para o documento ou saída;
run_id para a execução do agente;
decision_id para a decisão registrada;
transaction_id para o efeito no destino.

Esses campos podem viver em metadados, tabelas de catálogo, logs protegidos e referências de artefatos. Evite usar CPF, telefone ou e-mail como chave técnica distribuída.

Quando sistemas não compartilham identificadores, crie uma tabela de correspondência governada. Correspondência por nome ou texto livre precisa de evidência, score calibrado e caminho de revisão.

Preserve a diferença entre cópia e origem

Agentes usam caches, resumos, índices, bancos vetoriais e memórias para ganhar velocidade. Esses recursos são derivados.

Cada cópia deve declarar:

fonte que a originou;
campos ou trechos incluídos;
transformação aplicada;
momento da criação;
regra de atualização;
evento de invalidação;
prazo de retenção;
consumidores;
uso permitido quando estiver desatualizada.

Um resumo pode orientar leitura. Uma decisão sensível pode exigir confirmação na fonte oficial. Um índice pode localizar uma política. A versão aprovada do documento deve confirmar vigência e conteúdo.

Cópias sem linhagem ganham aparência de fonte própria. Depois de algumas sincronizações, ninguém sabe se a informação representa o sistema oficial, uma interpretação antiga ou uma mistura dos dois.

Modele correções sem apagar a história

Quando um dado muda, a arquitetura precisa distinguir correção, atualização e nova interpretação.

Correção de origem

O registro estava errado e foi corrigido. Preserve o valor anterior, a causa, a identidade autorizada e o horário da correção conforme a política aplicável.

Atualização operacional

O estado mudou porque um novo evento ocorreu. Uma oportunidade avançou, um pagamento foi confirmado ou um contrato expirou. A nova versão não torna a anterior necessariamente incorreta.

Reprocessamento derivado

Depois da mudança, índices, resumos, classificações ou relatórios podem precisar ser gerados novamente.

Revisão de consequências

Decisões e ações produzidas com o dado anterior podem exigir análise. A linhagem deve permitir localizar as unidades afetadas por fonte, versão e janela.

Apagar o registro antigo dificulta explicar decisões tomadas antes da correção. Manter todas as versões sem validade e autoridade cria outra confusão. O desenho precisa preservar histórico e tornar o estado vigente inequívoco.

Faça análise de impacto antes de reprocessar tudo

Quando uma política muda, a reação fácil consiste em reconstruir toda a base e revisar todas as execuções. Isso pode ser caro e desnecessário.

Use a linhagem para responder:

qual fonte e versão mudou;
quais transformações consumiram essa versão;
quais índices, caches e artefatos foram derivados;
quais agentes receberam o conteúdo;
quais decisões dependeram dele;
quais ações tiveram consequência externa;
quais casos ainda estão abertos;
qual classe de risco exige revisão.

A empresa pode reprocessar somente o conjunto afetado, priorizar ações irreversíveis e encerrar casos em que a mudança não altera o resultado.

Esse recorte reduz custo e evita transformar toda atualização em incidente geral.

Exemplo: política de reembolso usada no atendimento

Considere uma política publicada no repositório oficial.

Origem

Documento politica_reembolso, versão aprovada em determinada data, com proprietário e vigência.

Captura e transformação

O pipeline extrai texto, separa seções, associa metadados e cria entradas no índice. Cada trecho mantém documento, versão, seção e data de processamento.

Uso

Um chamado consulta a base. O sistema recupera os trechos usados, monta o contexto e registra o run_id.

Decisão

O agente classifica elegibilidade, apresenta a regra encontrada e marca casos fora da alçada para revisão. A saída guarda o trecho e a versão da política.

Consequência

Uma pessoa aprova ou a regra autorizada cria a solicitação no sistema financeiro. O destino devolve um identificador.

Se a política for corrigida, a equipe localiza trechos derivados, invalida o índice antigo, identifica decisões ainda abertas e revisa somente consequências que dependeram da regra alterada.

Sem linhagem, a investigação começaria pelas respostas enviadas e tentaria adivinhar qual cópia estava disponível em cada momento.

Linhagem em sistemas com vários agentes

Uma arquitetura multiagente pode transformar o mesmo dado em etapas sucessivas. Um agente extrai fatos, outro classifica risco e um terceiro prepara ação.

Cada handoff precisa preservar:

unidade de trabalho;
origem dos fatos;
transformação anterior;
versão do contrato;
campos derivados;
restrições de uso;
evidência;
decisão pendente;
identidade do produtor e do consumidor.

O contrato de dados para agentes de IA define o acordo entre essas etapas. A linhagem mostra como cada unidade real atravessou os contratos.

Não passe a conversa inteira como se fosse um objeto neutro. Conversas misturam instruções, fatos, hipóteses e correções. Estruture o handoff e mantenha referências para o material de origem.

Proteja dados sensíveis na própria evidência

Linhagem não exige copiar todo o conteúdo para logs. A trilha pode usar identificadores, referências protegidas, hashes, classes e metadados.

Defina:

quais campos ficam no catálogo;
onde o conteúdo completo permanece;
quem acessa cada nível;
como dados pessoais são mascarados;
prazos de retenção;
finalidade da evidência;
exclusão ou anonimização;
tratamento de incidentes.

Um registro chamado fonte_consultada = contrato_cliente.pdf ainda pode expor informação. Nomes de arquivos, consultas, trechos e argumentos merecem classificação.

A política de retenção de dados em agentes de IA deve incluir metadados de linhagem e referências aos artefatos.

Métricas para operar a linhagem

Acompanhe:

decisões relevantes com fonte identificada;
transformações sem versão;
cópias derivadas fora da validade;
saídas sem vínculo com evidência;
ações sem confirmação no destino;
tempo para localizar unidades afetadas;
volume reprocessado depois de correção;
divergências entre origem e cópia;
falhas de identidade entre sistemas;
correções humanas sem retorno à fonte;
dados sensíveis presentes em logs fora da política;
componentes que consomem versões retiradas.

A cobertura deve ser lida por classe de risco. Uma média alta pode esconder justamente o processo financeiro ou regulado que continua sem trilha suficiente.

Checklist de linhagem para agentes de IA

[ ] Os dados críticos estão priorizados por consequência?
[ ] Origem, versão, proprietário e autoridade ficam identificáveis?
[ ] Captura registra conector, identidade e horário?
[ ] Transformações relevantes possuem entrada, saída e versão?
[ ] Cópias e índices apontam para a origem?
[ ] O contexto mostra quais trechos e filtros foram usados?
[ ] Fatos e interpretações aparecem separados?
[ ] Decisões carregam evidência e versão do agente?
[ ] Ações externas possuem confirmação do destino?
[ ] Identificadores atravessam sistemas e agentes?
[ ] Correções preservam histórico e estado vigente?
[ ] A análise de impacto localiza unidades afetadas?
[ ] Dados sensíveis permanecem fora de logs amplos?
[ ] Retenção e acesso seguem finalidade definida?
[ ] Métricas mostram lacunas por classe de risco?

A linhagem reduz o custo de descobrir a causa

Agentes trabalham com dados que passam por cópias, índices, transformações e interpretações antes de chegar a uma ação. Avaliar somente a resposta final deixa a maior parte desse percurso invisível.

A linhagem conecta fonte, versão, transformação, contexto, decisão e consequência. Quando um dado muda ou uma execução falha, a equipe localiza o ponto afetado, corrige a origem e revisa o conjunto necessário. Essa capacidade melhora auditoria, manutenção e controle sem exigir que cada incidente vire uma escavação manual entre sistemas.