Preparar dados para agente de IA exige 5 camadas de contexto
Preparar dados para agente de IA passa por cinco camadas de contexto escrito: definição de tabela e coluna, modelo semântico de métricas, guias de processo em texto corrido, endosso de fonte confiável e acesso ao repositório de transformação. A lista saiu de um post da LangChain sobre a própria arquitetura. Faltando essas camadas, diz o relato, o agente segue gerando SQL válido e devolvendo resposta em que não dá para confiar.
O erro chega em forma de resposta
O modo de falhar que a LangChain descreve é o agente responder.
Sem contexto, ele escreve consulta que roda. O estrago aparece depois. Ele ignora a definição que a empresa usa para aquele termo, puxa a tabela errada, ou devolve um resultado correto na forma e inútil para a decisão que motivou a pergunta.
Quem recebe o número não consegue distinguir entre os três casos.
As cinco camadas, e o que cada uma resolve
Camada de contexto é o conjunto de informação escrita que o agente lê antes de consultar o banco: definição de tabela e coluna, lógica de métrica, regra de negócio, sinal de fonte confiável e o código que produz o dado. É o que separa SQL válido de resposta confiável.
A LangChain distribui esse contexto em cinco lugares. Cada um informa uma coisa diferente ao agente.
- Definição de tabela e coluna, no dbt. O que o dado representa, quais valores são permitidos, como interpretar, qual filtro se aplica por padrão. No nível da tabela: o grão, as perguntas que ela foi feita para responder, os pontos onde é preciso cuidado.
- Modelo semântico. ARR, pipeline, uso ativo e saúde do cliente, as métricas que voltam toda semana. Definidas uma vez, param de ser reconstruídas a cada pergunta.
- Guias de processo. Fluxo de time, convenção de relatório e regra de negócio em linguagem comum, sem forçar cada detalhe para dentro de uma descrição de coluna. A LangChain compara essa camada a skills do agente.
- Endosso. O carimbo de qual fonte vale, quando existe mais de uma candidata para o mesmo conceito.
- Acesso ao repositório dbt. O agente lê o SQL de ponta a ponta, entende junções e transformações, e rastreia como o campo foi produzido.
A quinta camada muda o tipo de resposta que o agente consegue dar. Com ela ele transita entre o nível do negócio e o nível da implementação, o que serve para validar um número e para achar a origem de um resultado estranho.
Descrição que só repete o nome da coluna não serve
A régua que a LangChain aplica é o leitor humano. A definição precisa fazer uma pessoa entender o que o dado representa, como usar e onde estão os casos de borda.
O padrão que falha é a descrição correta na forma, que não informa nada a quem lê. A frase que não ajuda um analista recém-chegado também não ajuda o agente.
Uma definição completa carrega quatro itens: contexto de negócio, valores permitidos, orientação de interpretação e regra de filtro padrão. Os dois últimos evitam a resposta certa em cima da leitura errada.
Camada semântica não conserta modelagem ruim
Modelo semântico é a camada onde a métrica é definida uma vez só, para que todo consumidor, humano ou agente, use a mesma lógica em vez de reconstruí-la a cada pergunta.
Ela entrega só o que a modelagem embaixo permite. Modelo confuso, duplicado ou mal documentado limita o que a camada de cima consegue fazer, e a LangChain diz isso com todas as letras.
Modelo limpo, grão claro e definição boa elevam a qualidade em cada etapa seguinte. Quem começa o projeto pela camada semântica está construindo pelo telhado.
Endosso perde a função se todo mundo endossa
Endosso é a marcação de que uma tabela ou um painel é a fonte oficial de um conceito. Serve para o caso comum em que várias tabelas, painéis e consultas antigas tocam o mesmo assunto e o agente precisa escolher uma delas.
Com o painel de ARR endossado, o agente responde por ele e pela lógica que está atrás dele.
Duas travas sustentam o mecanismo na LangChain. A marcação é exclusiva do time de dados. E mudança em painel endossado só entra no ar depois de revisão desse time.
O argumento é de escassez. Endosso distribuído a tudo para de carregar informação.
O time corrige o contexto olhando o uso
Nenhuma dessas camadas nasce completa, e a LangChain montou um ciclo de retorno para descobrir o que está faltando.
O time acompanha tema recorrente de conversa, alerta comum e lacuna de contexto, e decide dali onde investir. A ferramenta é o Context Studio, do Hex; para quem construiu o agente em casa, o relato aponta o LangSmith, produto da própria LangChain.
Pergunta que se repete indica painel faltando.
O que a arquitetura produziu na empresa
A LangChain trocou uma stack montada em torno de BI tradicional por outra desenhada para autoatendimento, contexto compartilhado e uso por agente. Antes disso, quase todo pedido de dado passava pelo time, e o time era uma pessoa.
Pelo relato, 100% da empresa hoje usa a nova stack de alguma forma, via Hex. Cerca de 70% ficaram com acesso somente de leitura e cerca de 30% com acesso ao agente, papel que o próprio TI libera a quem pedir.
O time de dados continua no fluxo, recebendo outro tipo de pergunta: as que exigem contexto de negócio mais fundo, modelagem ou alinhamento entre áreas.
O que o relato não informa
Fonte única, e a fonte é a empresa que fez a mudança. Ninguém verificou de fora.
Os três percentuais aparecem sem denominador, e o texto não diz de quantas pessoas se está falando. Não há comparação de antes e depois: nenhuma contagem de pedidos atendidos, nenhuma hora economizada, nenhum custo evitado. O preço da ferramenta fica de fora, assim como eventual relação comercial entre LangChain e Hex.
O dossiê chegou sem data de publicação. O prazo mencionado, um ano de trabalho, é o do relato, sem marco de calendário.
O custo real desse projeto no Brasil
O trabalho de escrever é o que consome orçamento aqui, não a licença da ferramenta.
Dicionário de dados com definição por coluna, métrica com dono único, regra de negócio registrada em texto e alguém com autoridade para dizer qual fonte vale: nenhum fornecedor entrega isso. Sai de gente da casa que conhece o negócio, e é o que ocupa o cronograma.
Quem compra a ferramenta sem essa base leva um gerador de SQL plausível rodando sobre tabelas que ninguém documentou. A resposta continua chegando bem escrita, o que torna o erro mais caro de perceber.
Sobra um detalhe sobre a origem do relato. Numa empresa que vende infraestrutura para agentes, sete em cada dez pessoas ficaram com permissão de leitura.
--- Apurado em 1 veículo de 1 país.