Tabelas gold e context documents
Sumário, definições e protocolo de resposta
Resposta com número, recorte e data da carga
Slack, WhatsApp ou chat do CRM
O que resolve
- A mesma pergunta recebe o mesmo número, para qualquer pessoa e em qualquer canal.
- O agente diz qual métrica usou, de que período e quando o dado foi atualizado.
- Quem não tem acesso a um dado não recebe esse dado, e o agente diz onde procurar.
Perguntas de negócio que responde
Faça estas perguntas ao seu agente quando o caso estiver pronto.
O que você precisa
- As métricas principais em tabelas gold, com regra fechada
- Context documents com definições, roteamento por assunto e protocolo de resposta
- O canal (Slack, WhatsApp, chat do CRM) ligado a um agente com o MCP da Nekt
O que você recebe
- Tabelas semânticas por finalidade, com colunas anotadas para a IA
- Um sumário de entrada que diz qual documento ler para cada assunto
- Tokens com escopo por público: diretoria, gerente, time
- Um log de perguntas e respostas e um conjunto de teste para medir o agente
Onde ativar
O time pergunta no canal que já usa e recebe o número com o recorte e a data da carga.
Perguntas executivas curtas, com token restrito às tabelas da diretoria.
Perguntas e respostas do canal viram tabela para medir acerto e tempo e corrigir documentos.
As tabelas gold costumam existir. O esforço está em escrever definições, protocolo e perguntas de teste, e em revisar as respostas nas primeiras semanas. O detalhado traz as regras de negócio, as armadilhas e o teste de aceitação. Ou mande tudo direto para o seu agente com o MCP da Nekt.
O agente recebe acesso a todas as tabelas e escolhe sozinho. Ele lê uma tabela de teste com nome parecido com a oficial, tira média de uma coluna que já é média, trata como zero o dia que ainda não carregou e explica a queda com uma causa que não está em lugar nenhum. Duas pessoas fazem a mesma pergunta e recebem números diferentes, e ninguém consegue auditar de onde veio cada um.
Como costuma ser feito, e a regra
Cada linha é um erro que já aconteceu na prática.
Crie tabelas de consumo por finalidade (venda diária por unidade, funil por mês, receita por cliente), com o grão escrito numa frase na descrição. Quando a regra é complexa, a tabela já traz o resultado numa coluna (por exemplo, um booleano que diz se a linha entra na métrica) e o documento manda usar essa coluna em vez de reescrever a fórmula. Tabelas de rascunho (prefixos debug_, test_, tmp_, sufixos _log, _dryrun, nomes com data) não são fonte de número.
Comece a descrição da coluna com a marcação: @pk (chave do grão), @fk (chave estrangeira), @measure additive (somável em qualquer dimensão), @measure non_additive (ticket médio, percentual, taxa), @grain. Depois diga a origem, a regra e a armadilha. Toda medida monetária declara se é bruta ou líquida. Documente a tabela, não só a transformação: quem procura o dado acha a tabela.
Um documento raiz lista cada documento com uma linha de quando lê-lo. O agente lê todos os que combinam com o pedido; métricas encadeadas se leem juntas (NRR lê também MRR e churn). Se nenhum documento cobre o pedido, o agente avisa em vez de improvisar. Na busca semântica, pergunte pelo conceito e pela métrica: um nome próprio cercado de palavras fracas faz a busca devolver zero documentos. O nome serve para filtrar no SQL.
Ordem fixa: buscar o contexto com a pergunta original, ler os documentos, conferir a última carga, gerar e rodar a consulta, conferir a ordem de grandeza contra um número de referência do documento. O agente nunca responde número sem executar a consulta e nunca recusa por falta de dado antes de ler a estrutura da tabela. Nulo é ausência, não zero. Métrica marcada como 'a validar' não é inferida.
A resposta nomeia a métrica (líquida ou bruta), o período com data inicial e final e a data e hora da última carga. O dia corrente é parcial: compare só dias fechados. Mês aberto não entra como realizado; use o marcador de mês fechado da tabela quando existir.
Campos de data do ERP gravados como meia-noite UTC já são o dia comercial. O agente calcula hoje e ontem no fuso local e compara direto, sem converter o campo. A regra fica escrita na descrição da coluna e no protocolo.
O agente decompõe a variação (volume contra ticket, qual unidade explica a diferença em reais), mas não explica por que caiu nem recomenda ação sem dado que sustente. Base de comparação zero ou muito pequena vira 'base baixa', com a variação em reais. Taxa varia em pontos percentuais. Percentuais e médias não se somam entre linhas: recalcule a razão a partir dos totais.
Cada público tem o seu token MCP com escopo por tabela: a diretoria lê a rede inteira, o gerente lê a view da própria unidade. Pasta no catálogo é organização, não segurança. Dado que identifica pessoa (operador, contato, aluno) fica fora das views amplas. Erro de acesso é o escopo funcionando: o agente diz onde a resposta está, sem pedir permissão nova.
Regras são estáveis; contagens (clientes ativos, número de tabelas, totais) são retrato de uma data e envelhecem em dias. Se o documento divergir da consulta, vale a consulta. Cada documento traz dono, status (validado ou não) e data da última revisão. Ao usar uma regra não validada, o agente avisa.
Mantenha um conjunto de perguntas reais com a resposta esperada e rode a cada mudança de documento. Grave o histórico do canal pareando cada pergunta com a resposta final. Mensagens intermediárias ('estou analisando sua pergunta') não contam como resposta nem como tempo de resposta.
Os documentos que o agente lê
Cada um com um papel. Em conflito, o de domínio vence no cálculo e o protocolo vence na forma.
Definições
Armadilhas que já aconteceram
O agente respondeu a venda bruta de uma loja como líquida e errou em seis dígitos num único dia.
Declare bruto ou líquido em toda coluna monetária e defina o padrão no protocolo.
O agente converteu o fuso de um campo que já era o dia comercial e respondeu zero venda num dia de venda alta.
Escreva na descrição da coluna que a data não leva fuso.
O agente explicou uma queda pela produtividade da equipe e recomendou ação, numa base que só tinha venda, cancelamento e cadastro.
Protocolo: fato, não causa; feche com o que a base não responde.
Sem índice, o agente agregou uma tabela de investigação com nome parecido com a oficial.
Liste as tabelas de consumo no sumário e marque os prefixos de rascunho como proibidos.
As views por unidade foram criadas com gatilho manual e ficaram mais de uma semana sem atualizar, com a fonte em dia.
Gatilho por evento e data da carga em toda resposta.
Perguntas formadas por um nome próprio e palavras fracas voltavam sem nenhum documento, e o agente respondia sem regra.
Busque pelo conceito e pela métrica; use o nome só para filtrar no SQL.
Teste de aceitação
O caso está pronto quando todos os itens passam.
- Num conjunto de pelo menos 30 perguntas reais com resposta esperada, o agente acerta o número em todas as de métrica oficial e responde que o dado não existe nas que a base não cobre.
- A mesma pergunta feita por duas pessoas, em dois canais, devolve o mesmo número e a mesma data de carga.
- Com o token de um gerente, consultar a view de outra unidade devolve erro de acesso.
- Toda resposta numérica do log traz métrica, período e data da última carga.
- A venda líquida de um dia fechado respondida pelo agente bate com o relatório oficial do ERP para o mesmo dia.
Pacote para o agente
Cole no Claude, ChatGPT ou outro cliente com o MCP da Nekt conectado.
Protocolo do agente de dados - Antes de qualquer SQL, busque o contexto com a pergunta original e leia os documentos indicados no sumário <nome do sumário>. - Use só as tabelas de consumo listadas: <lista>. Nunca use tabelas com prefixo debug_, test_, tmp_ ou sufixo _log, _dryrun. - Não responda número sem executar a consulta. Não recuse por falta de dado antes de ler a estrutura da tabela. - Toda resposta numérica traz a métrica, o período com data inicial e final e a data e hora da última carga. - 'Quanto vendeu' = <métrica padrão, ex.: venda líquida>. Bruta só quando pedida. - Datas comerciais não levam conversão de fuso. Hoje e ontem em America/Sao_Paulo. - O dia corrente é parcial: compare só dias fechados. Use como realizado só meses com <marcador de mês fechado> verdadeiro. - Percentuais, médias e ticket não se somam entre linhas: recalcule a partir das somas. - Base de comparação zero, negativa ou menor que um quarto do atual: escreva 'base baixa' e mostre a variação em reais. - Aponte o fato, nunca a causa. Não recomende ação. Feche com o que a base não responde. - Nulo é ausência, não zero. Métrica marcada 'a validar' não é inferida. - Liste pessoas só quando pedido, até 50 linhas, sem telefone, e-mail ou documento. - Erro de acesso: diga que está fora do seu escopo e onde a resposta está. - Se um número escrito num documento divergir da consulta, vale a consulta. Exceções por cliente: - <cliente>: 'lead' sem qualificador = <definição>. - <cliente>: gerentes leem só <view da unidade>; diretoria lê <view da rede>. - <cliente>: número de conferência de <mês fechado>: <métrica> = <valor>.
Construa no meu workspace Nekt o caso "Agente de dados no Slack ou WhatsApp" seguindo as regras em https://academy.nekt.com/casos/agente-slack.md. 1) Encontre as tabelas de origem e confirme as colunas usadas pelas regras. 2) Crie uma transformação no grão indicado aplicando todas as regras. 3) Rode o teste de aceitação e me mostre o resultado de cada item. 4) Crie o context document do caso no workspace, com as exceções dos meus clientes em aberto para eu preencher.
Variações
Em agências e consultorias, um documento de roteamento por cliente e a ordem de precedência entre regra global e exceção.
O mesmo protocolo, disparado por agenda: lê o placar e só fala quando algo sai da faixa.
Com as ferramentas ao vivo do MCP, o agente também executa ações nas ferramentas, como baixar uma parcela no ERP ou ajustar uma campanha, sempre com confirmação.