--- id: casos/agente-slack area: IA uso: muito usado esforco: médio grao: Uma tabela semântica por finalidade, com grão declarado; um documento por domínio --- # Agente de dados no Slack ou WhatsApp O time pergunta em linguagem natural no Slack ou no WhatsApp e recebe o número oficial, com a métrica, o período e a data da última carga, ou ouve que aquele dado não existe. ## Resumo executivo **Para quem:** Times que perguntam números todo dia no chat e querem a resposta oficial sem abrir o BI nem depender do time de dados. **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. **Por que importa:** Um agente sem regra escrita responde com confiança o número errado: lê bruto no lugar de líquido, converte fuso de uma data que já é o dia comercial, inventa uma causa para a queda. Na primeira vez que a diretoria pega um erro, o canal perde a confiança. O que separa um agente confiável de um chatbot é a camada semântica e o protocolo de resposta, não o modelo. **Perguntas de negócio que responde** - Quanto vendemos ontem, líquido, e como isso se compara com o mesmo dia da semana passada? - Qual o ticket médio da semana por unidade? - Quantos leads entraram neste mês e de quais canais? - Quais unidades estão abaixo da meta do mês? - O número de ontem já está atualizado? **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 ## Detalhado ### O problema 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. ### Regras de negócio 1. **Uma tabela semântica por pergunta de negócio.** 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. (Evite: Dar ao agente acesso ao lakehouse inteiro.) 2. **Anote cada coluna para a IA.** 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. (Evite: Coluna total_vendas sem dizer se é bruta ou líquida.) 3. **Um sumário de entrada com 'Ler quando'.** 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. (Evite: Dezenas de documentos soltos, sem índice, buscados pelo nome do cliente.) 4. **Contexto antes de SQL, número só da consulta.** 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. (Evite: Responder de memória ou estimar quando a consulta falha.) 5. **Toda resposta declara métrica, recorte e carga.** 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. (Evite: Responder 'vendemos R$ X' sem dizer o quê nem até quando.) 6. **Data comercial não leva fuso.** 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. (Evite: Converter para o fuso local um campo que já é o dia.) 7. **Fato, não causa.** 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. (Evite: Explicar a queda pela produtividade do time numa base que só tem venda.) 8. **Acesso por público, com token e view.** 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. (Evite: Um token de administrador para todos e o filtro de unidade no prompt.) 9. **Documento tem dono e data; a consulta vence.** 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. (Evite: Copiar números para o documento e nunca revisar.) 10. **Meça o agente com perguntas de teste e log.** 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. (Evite: Validar o agente com duas perguntas no dia da entrega.) ### 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. - **Lista os documentos e quando ler cada um** → Sumário de entrada - **Regras de número, recorte, o que não inventar** → Protocolo de resposta - **Como calcular cada métrica, com número de referência** → Domínio - **Qual tabela responde cada tipo de pergunta** → Roteamento - **Estrutura de um entregável recorrente** → Playbook - **Definições e escopos próprios de um cliente ou unidade** → Exceções ### Definições | Métrica | Definição | |---|---| | Resposta numérica válida | número devolvido por consulta executada na conversa, com métrica, período e data da última carga declarados | | Última carga | maior data de negócio ou de atualização (_nekt_sync_at) da tabela consultada, no fuso local | | Dia fechado | qualquer dia anterior ao corrente no fuso local; o dia corrente é sempre parcial | | Base baixa | base de comparação zero, negativa ou menor que um quarto do valor atual; a variação sai em reais, sem percentual | | Acerto do agente | perguntas do conjunto de teste respondidas com o número esperado / perguntas do conjunto, medido a cada mudança de documento | | Tempo de resposta | da pergunta até a resposta final do agente no canal, sem contar mensagens intermediárias | | Escopo do público | tabelas e views liberadas no token MCP daquele público | ### Armadilhas - **Bruta lida como líquida.** O agente respondeu a venda bruta de uma loja como líquida e errou em seis dígitos num único dia. Como evitar: Declare bruto ou líquido em toda coluna monetária e defina o padrão no protocolo. - **Zero venda num dia cheio.** O agente converteu o fuso de um campo que já era o dia comercial e respondeu zero venda num dia de venda alta. Como evitar: Escreva na descrição da coluna que a data não leva fuso. - **Causa inventada.** O agente explicou uma queda pela produtividade da equipe e recomendou ação, numa base que só tinha venda, cancelamento e cadastro. Como evitar: Protocolo: fato, não causa; feche com o que a base não responde. - **Tabela de rascunho como fonte.** Sem índice, o agente agregou uma tabela de investigação com nome parecido com a oficial. Como evitar: Liste as tabelas de consumo no sumário e marque os prefixos de rascunho como proibidos. - **View por unidade parada.** As views por unidade foram criadas com gatilho manual e ficaram mais de uma semana sem atualizar, com a fonte em dia. Como evitar: Gatilho por evento e data da carga em toda resposta. - **Busca sem resultado pelo nome.** Perguntas formadas por um nome próprio e palavras fracas voltavam sem nenhum documento, e o agente respondia sem regra. Como evitar: Busque pelo conceito e pela métrica; use o nome só para filtrar no SQL. ### Teste de aceitação - [ ] 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. ### Context document ```text Protocolo do agente de dados - Antes de qualquer SQL, busque o contexto com a pergunta original e leia os documentos indicados no sumário . - Use só as tabelas de consumo listadas: . 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' = . 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 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: - : 'lead' sem qualificador = . - : gerentes leem só ; diretoria lê . - : número de conferência de : = . ``` ### Variações - **Agente por cliente:** Em agências e consultorias, um documento de roteamento por cliente e a ordem de precedência entre regra global e exceção. - **Agente de alertas:** O mesmo protocolo, disparado por agenda: lê o placar e só fala quando algo sai da faixa. - **Agente que age:** 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.