Construindo um agente de IA sobre seus dados

A promessa é simples de enunciar e poderosa de viver: uma pessoa de negócio pergunta "qual canal trouxe mais receita esse mês" e recebe a resposta, com número e contexto, sem escrever uma linha de SQL e sem esperar a fila do analista. Isso é um agente sobre seus dados. Não é mágica, é arquitetura: quando as peças certas estão no lugar, o agente lê seus dados, entende a pergunta e responde. Este guia mostra quais são essas peças e como elas se encaixam.

Os quatro ingredientes

Um agente confiável nasce da combinação de quatro coisas. E há uma que pesa mais que as outras: o contexto. Sem contexto o agente adivinha o significado dos dados e erra; com bom contexto ele entende o que cada coluna quer dizer e acerta, mesmo lendo tabelas mais simples. As outras três dão o suporte: dado acessível para ler, MCP para alcançar e um cliente de IA para conversar.

O quarto ingrediente é o cliente de IA (por exemplo o Claude), a interface onde a pessoa faz a pergunta em português. Ele conversa com o MCP, que por sua vez lê seus dados apoiado na Camada Semântica. Repare no papel de cada um: a Camada Semântica é o manual que explica o dado, o MCP é o encanamento e o cliente de IA é a torneira. Uma camada Gold bem modelada ajuda e tende a melhorar o resultado, mas não é pré-requisito. Muita gente monta agentes que consultam direto os dados mais brutos e funciona bem, desde que o contexto esteja lá para explicar o que cada coisa significa.

O caminho da pergunta até a resposta

Cada pergunta em linguagem natural percorre o mesmo trajeto. Veja o fluxo inteiro de uma vez.

Em texto, o trajeto é: pergunta em linguagem natural chega ao agente (via MCP), que lê seus dados apoiado na Camada Semântica para entender quais tabelas usar e o que cada campo significa, monta a consulta, e devolve a resposta. Uma tabela Gold bem modelada deixa esse passo mais fácil, mas o que de fato evita que ele chute é o contexto: em vez de adivinhar que "receita" é a coluna vl, ele lê no context document que receita é valor_liquido somado após aprovação. Sem esse contexto, nem as tabelas tratadas salvam a resposta.

O que faz acertar, o que faz errar

A diferença entre um agente que você confia e um que solta números errados está quase toda no contexto que ele recebe, mais do que na camada onde o dado mora. É o mesmo princípio dos dois lados abaixo.

Esse contraste fica mais fácil de enxergar quando a camada Gold e o contexto são avaliados juntos. O guia de context document ensina a escrever o contexto que faz o agente acertar.

Perguntas que um bom agente responde

Quando os quatro ingredientes estão no lugar, perguntas assim voltam com resposta e número, direto no chat, sem passar pelo analista:

• "Qual canal trouxe mais receita esse mês?" soma a receita por canal na tabela Gold e ordena.
• "Quantos clientes novos fechamos nas últimas 4 semanas?" filtra por data de conversão e conta distintos.
• "Qual produto teve mais devolução no trimestre?" cruza vendas e devoluções já consolidadas na Gold.
• "Como está o ticket médio comparado ao mês passado?" calcula a média e compara os dois períodos.
• "Quais clientes não compram há mais de 60 dias?" lista quem passou do limite de recência.

Repare que todas são perguntas de negócio, não técnicas. A pessoa não precisa saber o nome da tabela nem a coluna certa. Esse conhecimento vive na Camada Semântica, e é o agente quem o usa.