A demonstração foi impecável. Perguntaram ao agente qual tinha sido a inadimplência da carteira no trimestre e ele respondeu em três segundos, com gráfico. Semanas depois, em produção, um gerente fez a mesma pergunta e recebeu duas coisas que ninguém tinha previsto: um número diferente do que estava no painel do comitê e um trecho de um parecer de crédito que ele não tinha permissão para ler. Ninguém invadiu nada. O agente fez exatamente o que foi construído para fazer — procurar a resposta no índice vetorial que alguém sincronizou a partir das tabelas, porque era o jeito mais rápido de montar o piloto. O índice é uma cópia. E cópia não herda permissão.

As duas rotas Um agente que responde perguntas sobre dados tem duas rotas possíveis, e elas não competem: elas servem a perguntas diferentes. A rota não estruturada — busca vetorial, o que quase todo mundo chama de RAG — responde “o que este documento diz”. A rota estruturada — geração de consulta, o famoso text-to-SQL — responde “quanto foi”. Escolher entre as duas parece uma decisão de qualidade de resposta, e por isso costuma ser decidida por quem está com pressa. Não é. É uma decisão de governança, porque as duas rotas têm modelos de permissão diferentes, e uma delas não tem o modelo que você imagina que tem.

O que é acessar dado do Lakehouse com um agente?

É transformar uma pergunta em linguagem natural numa operação que o motor de dados sabe executar. Existem exatamente dois jeitos de fazer isso, e a documentação da Databricks os separa em duas páginas irmãs, o que é o melhor endosso possível para quem precisa defender a decisão numa revisão de arquitetura: ferramentas de recuperação estruturada e ferramentas de recuperação não estruturada.

Na rota não estruturada, o texto vira vetor. Documentos são fatiados, transformados em embeddings e gravados num índice — no Databricks, o Databricks AI Search, que até recentemente se chamava Databricks Vector Search. A pergunta também vira vetor e o sistema devolve os trechos mais próximos. O que o agente recebe é texto para ler.

Na rota estruturada, a pergunta vira consulta. O modelo escreve SQL contra tabelas do Unity Catalog e o motor executa. No Databricks isso é o Genie Agent, nome atual do que antes se chamava Genie space. O que o agente recebe é resultado de consulta.

O contraste que interessa não é “qual responde melhor”. É este: na rota estruturada, o dado nunca sai do lugar — a consulta vai até ele e é avaliada no momento da execução. Na rota não estruturada, o dado foi copiado para outro lugar antes de qualquer pergunta existir, e esse outro lugar tem regras próprias.

O problema que resolve

O problema real é que a maioria dos pilotos escolhe a rota errada por um motivo inocente: a rota não estruturada é mais fácil de montar. Você joga tudo num índice — inclusive tabelas — e o agente “funciona”. Ele responde. O que ele não faz é responder certo e responder para quem pode.

Duas falhas nascem dessa escolha, e elas parecem problemas diferentes até você olhar a origem:

1. O número que não bate. Perguntas sobre agregação — soma, média, contagem, participação — não são um problema de recuperação. Você não acha “o faturamento do trimestre” num parágrafo; você calcula. Um índice vetorial devolve os trechos mais parecidos com a pergunta, e “parecido” não é “correto”. O agente então soma o que encontrou e apresenta com a mesma confiança de sempre.
2. O dado que vaza. Aqui está o ponto que fecha o artigo, e ele não é opinião. A documentação do Databricks AI Search, na seção de limitações, diz literalmente: “Row and column level permissions are not supported. However, you can implement your own application level ACLs using the filter API.” Permissão de linha e de coluna não é suportada no índice. O que existe é a possibilidade de você implementar o seu próprio controle, por filtro, na aplicação.

Os três erros que eu mais encontro em campo:

1. Jogar tabela dentro do índice vetorial. Vira busca por similaridade sobre número. É a origem do “quase certo”.
2. Presumir que o índice herda a permissão da tabela de origem. Ele não herda — e a documentação é explícita.
3. Não ter camada de métrica. Sem ela, “receita” é o que o modelo achar que é naquela execução.

Como funciona — passo a passo

1. Classifique a pergunta antes de escolher a ferramenta. “O que o contrato diz sobre rescisão?” é recuperação. “Quantos contratos foram rescindidos no trimestre?” é consulta. Perguntas que misturam as duas precisam das duas ferramentas, não de uma no meio do caminho.
2. Mande número para SQL, sempre. Se a resposta envolve agregação, comparação ou período, a rota é estruturada. Não existe recuperação vetorial que substitua um GROUP BY.
3. Defina a métrica antes de expor o agente. Uma metric view no Unity Catalog declara a medida uma vez, em YAML, e a consulta a invoca com a função MEASURE(). Sem isso, você está pedindo ao modelo que decida o que é receita.
4. Aponte o Genie Agent para tabelas curadas. O limite documentado é de 30 tabelas ou views por agente — o que é menos uma restrição do que um convite a curar.
5. Ensine o domínio com trusted assets. Consultas SQL de exemplo e funções SQL registradas dão respostas verificadas para as perguntas que você já sabe que virão.
6. Para a rota não estruturada, escolha o tipo de índice. Delta Sync Index acompanha uma tabela Delta e se atualiza sozinho; Direct Vector Access Index deixa a escrita por sua conta.
7. Implemente o filtro de segurança na consulta ao índice. É a única forma de recorte por linha nessa rota, e ela é sua responsabilidade, não do catálogo.
8. Meça com benchmark, não com impressão. Cada Genie Agent aceita até 500 perguntas de benchmark para avaliar a acurácia das respostas.
9. Decida a retenção da conversa antes de abrir o agente. O trecho recuperado fica gravado na thread — no Foundry, no banco enterprise_memory. Retenção definida depois do primeiro incidente já chega tarde.

A rota não estruturada: o índice é uma cópia com permissão própria

Quando você cria um índice no Databricks AI Search, ele é registrado no Unity Catalog — mas como um objeto próprio, e não como uma extensão da tabela que o alimentou. A consequência aparece no requisito de acesso: quem consulta o índice sem ser o dono precisa de USE CATALOG no catálogo, USE SCHEMA no schema e SELECT no índice. Não SELECT na tabela de origem. No índice.

Junte isso à linha das limitações — “Row and column level permissions are not supported” — e o desenho fica claro: quem tem acesso ao índice tem acesso ao conteúdo do índice, inteiro. O row filter que você configurou com tanto cuidado na tabela Delta não atravessa a fronteira da cópia. Ele nem sabe que a cópia existe.

O caminho oficial para recortar é o filter API: você grava metadados junto de cada trecho — unidade, região, classificação — e filtra por eles na consulta. Funciona, e é o que se deve fazer. Mas repare no que aconteceu com a responsabilidade: a regra de acesso saiu do catálogo, onde é declarativa e auditável, e foi parar no código da aplicação, onde depende de alguém não esquecer de aplicá-la. Isso precisa ser uma decisão consciente — não um efeito colateral de ter escolhido a rota mais fácil.

Uma armadilha de leitura merece aviso, porque um leitor atento vai tropeçar nela: a documentação do MCP server do AI Search diz que os resultados são governados por permissões do Unity Catalog. Isso não contradiz o parágrafo acima. É permissão no índice — o SELECT que citei. Não é row filter da tabela de origem. As duas frases convivem, e confundir uma com a outra é exatamente o erro que produz o vazamento.

Sobre o resto da rota, o que vale saber:

A busca híbrida merece uma linha própria, porque resolve um problema real: vetor sozinho erra em código de produto, número de contrato e nome próprio — justamente os termos que o usuário digita quando sabe o que quer. A parte lexical usa Okapi BM25 e entra pelo parâmetro query_type="hybrid".

A rota estruturada: o SQL executa dentro do motor

Row filters e column masks do Unity Catalog são funções SQL associadas à tabela com ALTER TABLE ... SET ROW FILTER, avaliadas em query time: cada linha passa pela função, e as que retornam FALSE ficam fora do resultado. Como a regra pertence à tabela e é aplicada na execução, ela vale para qualquer consulta que chegue àquela tabela — inclusive a que um modelo acabou de escrever. Não é o agente que respeita a permissão; é o motor que não devolve a linha. Essa é a diferença estrutural entre as duas rotas.

Mas é preciso ser exato sobre como o Genie Agent se autentica, porque a versão simplificada (“ele executa como o usuário”) está errada pela metade. A documentação descreve duas credenciais separadas:

• Compute: a consulta gerada roda no SQL warehouse com a credencial embutida pelo autor do agente. O usuário final não precisa de permissão no warehouse.
• Acesso a dado: o Unity Catalog avalia o acesso com a identidade do usuário final, não a do autor. Cada um vê apenas o que pode ver, e cada consulta é atribuída ao usuário final no histórico.

Ou seja: o motor é do autor, o dado é do usuário. Isso é bom para adoção, mas tem duas consequências operacionais que precisam entrar no seu desenho:

• Se o autor que configurou o warehouse sair da empresa, as credenciais embutidas deixam de valer e as consultas falham para todo mundo que usa aquele agente. É um ponto único de falha com nome e sobrenome.
• Os valores representativos usados para casar o texto da pergunta com o conteúdo das colunas são gerados com as permissões de dado do autor, e passam a fazer parte do contexto compartilhado do agente. É um detalhe fino, mas é um caminho por onde amostra de dado restrito alcança quem não deveria vê-la.

E há um mal-entendido comum que vale desfazer: o Genie não fica preso às tabelas adicionadas ao agente. A documentação diz que ele pode consultar tabelas além dessas, e que o controle é do Unity Catalog, não do agente. Ou seja, o agente não é um perímetro — o catálogo é. Quem pensa em “limitar o agente às tabelas certas” como controle de segurança está protegendo a porta errada.

Do lado de baixo, o que sustenta auditoria: a linhagem do Unity Catalog é capturada automaticamente em nível de coluna para consultas executadas no Databricks, e a atividade do Genie fica registrada na tabela de sistema system.access.audit, sob o service_name aibiGenie.

A terceira camada: da ontologia à métrica governada

Existe um degrau entre “o agente escreve SQL” e “o agente responde certo”, e ele não é modelo maior: é definição.

É aqui que a ontologia deixa de ser diagrama e passa a executar. Ontologia, no sentido prático, é o acordo sobre o que cada conceito do negócio significa e como ele se relaciona com os outros: o que é cliente, o que conta como contrato ativo, qual carteira pertence a qual segmento. Enquanto esse acordo mora num documento de arquitetura, o agente não tem acesso a ele — o que chega ao modelo é nome de coluna. A camada semântica é onde a ontologia vira artefato que o motor lê, e é por isso que ela pertence a esta discussão: o mesmo lugar que define o significado é o lugar onde a permissão continua sendo avaliada. Quando a definição é copiada para um índice, as duas coisas se perdem juntas — o sentido e a regra de acesso.

Metric views são a implementação da semântica do Unity Catalog: separam a definição da medida dos campos pelos quais ela é analisada. Você declara a métrica uma vez, em YAML, com source, filter, dimensions e measures, e a consulta a invoca com MEASURE(). Uma view comum congela agregação e agrupamento na criação; a metric view deixa o agrupamento livre em tempo de consulta.

O ganho no contexto de agente é direto: sem essa camada, “inadimplência” é o que o modelo deduzir a partir dos nomes das colunas, e duas formulações da mesma pergunta produzem dois números — ambos defensáveis, nenhum oficial. Com ela, a definição tem dono, versão e um único lugar onde muda. E o Genie Agent consulta metric views, o que fecha o circuito entre a métrica declarada e a pergunta em linguagem natural.

Vale a nota de rótulo: as metric views entraram em Public Preview, as páginas atuais não trazem mais o aviso e não localizei anúncio formal de disponibilidade geral. Confirme o status antes de escrever no seu documento de arquitetura.

No mundo Microsoft, o papel equivalente é do modelo semântico do Power BI, que carrega lógica de negócio, medidas calculadas e métricas curadas — com um alerta que quase ninguém lê: RLS só restringe usuários com permissão de Viewer. Não se aplica a Admin, Member ou Contributor do workspace. Se o seu agente rodar sob uma identidade com papel de Contributor, ele enxerga tudo, e a frase “o SQL herda as permissões” deixa de ser verdadeira — não por falha do mecanismo, mas por escolha de identidade.

Do lado da Microsoft: Fabric data agent e Microsoft Foundry

Quem está no Fabric tem o mesmo desenho com outra embalagem. O Fabric data agent é um recurso de disponibilidade geral para construir sistemas de perguntas e respostas sobre os seus dados, e ele traduz linguagem natural em três linguagens diferentes conforme a fonte: NL2SQL para lakehouse e warehouse, NL2DAX para modelos semânticos e NL2KQL para bases KQL.

Dois pontos merecem destaque para quem vem da discussão anterior: ele usa as credenciais de quem pergunta para aplicar o menor privilégio, e a documentação afirma que honra todas as permissões do usuário sobre o dado, incluindo RLS e CLS — a regra está no dado, não na aplicação. E são até cinco fontes por agente, em qualquer combinação de lakehouse, warehouse, base KQL, modelo semântico, ontologia e Microsoft Graph.

Repare no que não está nessa lista: arquivo. No lakehouse você seleciona tabelas, não arquivos — CSV ou JSON precisa ser ingerido numa tabela antes que o agente enxergue. É a postura oposta à da busca em arquivos do Foundry, que cria o índice a partir do upload. No Fabric o dado entra pelo catálogo, ou não entra.

Uma correção honesta ao argumento que fiz acima: o Azure AI Search já tem ingestão de ACL e RBAC, rótulos do Purview e ACLs do SharePoint — mas em preview, e com defasagem documentada entre a mudança da permissão na origem e o reconhecimento dela pelo índice. Isso reforça a tese em vez de desmontá-la: a permissão continua sendo uma segunda cópia da regra, que precisa ser sincronizada e pode estar velha no momento da consulta.

Onde o agente da Microsoft guarda o que leu

Fora do Fabric, o agente da Microsoft roda no Microsoft Foundry — nome atual do que era Azure AI Foundry, e o redirecionamento da própria documentação confirma a troca. No setup padrão do Foundry Agent Service, o estado do agente fica em três recursos seus, ligados ao projeto por um capability host: Storage, Cosmos DB e Azure AI Search.

Isso reforça o argumento em vez de mudá-lo. O índice de conhecimento é um recurso da sua assinatura, com RBAC próprio — a permissão que vale ali é a do serviço de busca, não a da tabela de onde o dado saiu. E há um detalhe que quase ninguém pesa: threads e mensagens ficam no banco enterprise_memory, no Cosmos DB. O trecho que o agente recuperou e mostrou ao usuário fica gravado na conversa. Corrigir o filtro do índice depois não desfaz a resposta já dada — ela virou histórico, e histórico é dado.

pergunta do usuário
        │
        ├─ "o que o documento diz?" → rota não estruturada
        │      ├─ Databricks AI Search  · o índice é securable próprio
        │      ├─ Azure AI Search       · ACL ingerida em preview, com atraso
        │      ├─ Foundry · file search · o índice nasce do arquivo enviado
        │      │      └─ recorte por metadado na consulta (filter API)
        │      │             └─ a ACL é sua responsabilidade
        │      └─ Fabric data agent     · não lê arquivo: exige tabela
        │             └─ o dado entra pelo catálogo, ou não entra
        │
        ├─ "quanto foi?"            → rota estruturada
        │      ├─ métrica definida? → metric view · MEASURE()
        │      ├─ consulta livre    → Genie Agent · SQL em query time
        │      │      └─ row filter + column mask do Unity Catalog
        │      └─ fonte no Fabric   → Fabric data agent · NL2SQL/NL2DAX/NL2KQL
        │             └─ RLS e CLS do usuário que pergunta
        │                    └─ a ACL é do dado
        │
        └─ depois da resposta       → o estado do agente
               └─ thread no enterprise_memory · Cosmos DB (Foundry)
                      └─ o histórico também é dado

Como as duas rotas viram um agente só

Na prática você não escolhe uma e descarta a outra: você expõe as duas como ferramentas e deixa o orquestrador decidir. Nas três plataformas o desenho é o mesmo — o que muda é o nome e, sobretudo, quem assina a consulta:

Leia a coluna da direita de cima a baixo e o argumento inteiro do artigo cabe ali. As três primeiras linhas perguntam quem é você antes de responder. As duas últimas perguntam apenas se você alcança o índice.

Duas limitações declaradas do servidor do Genie evitam surpresa: ele é somente leitura e não guarda histórico de conversa. Quem precisa de continuidade precisa mantê-la fora dele. O Fabric data agent tem a sua, e ela é a contrapartida honesta do On-Behalf-Of: não aceita service principal. Agente que roda desacompanhado, em pipeline noturno, não passa por essa porta.

Registrar lógica como função do Unity Catalog e expô-la como ferramenta é o padrão mais subestimado da lista: tira a regra de negócio do prompt e a coloca num objeto com dono e permissão. E, quando a função é usada como trusted asset, o Genie não consegue ver nem alterar o SQL de dentro dela — exatamente o que se quer para lógica que não deve ser exposta.

Para orquestrar tudo isso, o nome atual na plataforma é Supervisor Agent, dentro do Agent Bricks, que coordena Genie Agents, endpoints de agente, funções do Unity Catalog, MCP servers e agentes próprios. Do lado Microsoft o equivalente é o Foundry Agent Service.

A armadilha mora na última linha da tabela: é a rota não estruturada no ponto em que ela é mais fácil de acionar sem perceber — basta arrastar um arquivo.

Os erros que aparecem quando a rota está errada

• O número muda conforme a pergunta é formulada. Falta metric view. O modelo está inventando a definição a cada execução.
• O agente cita um documento que o usuário não deveria ver. Índice sem filtro de metadado. Não adianta procurar o furo no Unity Catalog: ele não tem jurisdição ali.
• A resposta ignora o filtro que existe na tabela. Alguém indexou a tabela em vez de consultá-la.
• Tudo falha de uma vez, para todos os usuários. Credencial embutida do autor do Genie Agent perdeu validade.
• O agente responde sobre uma tabela que ninguém adicionou. Comportamento documentado: o controle é do catálogo, não do agente.
• Você corrigiu o filtro e o vazamento continua no histórico. O trecho recuperado ficou na thread. Corrigir a origem não reescreve conversa passada.

Boas práticas para produção

• Escolha a rota pela forma do dado, não pela facilidade de montar. Texto para índice, número para SQL.
• Nunca indexe tabela transacional para responder pergunta de agregação. Se a resposta exige GROUP BY, o caminho é consulta.
• Trate o índice vetorial como cópia governada à parte, com classificação própria e ciclo de vida próprio.
• Escreva o filtro de metadado na consulta ao índice desde o primeiro dia, mesmo no piloto. Retrofit de ACL é o tipo de dívida que só é cobrada em auditoria.
• Declare as métricas antes de abrir o agente para usuário final. Sem definição, não há resposta certa — há resposta plausível.
• Prefira função do Unity Catalog a lógica no prompt. Prompt não tem dono nem permissão.
• Não use identidade privilegiada para o agente. Papel de Contributor no Power BI e conta de serviço ampla no Databricks anulam o recorte por linha.
• Rode benchmark a cada mudança relevante de tabela, instrução ou modelo.
• Documente quem é o autor de cada Genie Agent e tenha plano para a saída dessa pessoa.
• Trate a thread do agente como repositório de dado. No Foundry ela vive no seu Cosmos DB: classifique, defina retenção e inclua no escopo de auditoria.

O que precisa estar de pé

Fundação — a autoridade sobre o dado. As tabelas estão no Unity Catalog com dono definido, row filters e column masks aplicados onde a política exige, e a linhagem em nível de coluna é capturada. O índice vetorial, se existe, está registrado como objeto próprio, com classificação declarada e um responsável nomeado — e ninguém confunde o SELECT do índice com o SELECT da tabela. O armazenamento de thread do agente entra na mesma lista: é repositório, não detalhe de runtime.

Está de pé quando remover o acesso de uma pessoa a uma tabela muda o que ela recebe do agente, nas duas rotas.

Produção com contexto — a semântica virando resposta. As métricas que o negócio usa estão declaradas como metric views, com dono e versão; o Genie Agent aponta para um conjunto curado de tabelas e tem trusted assets para as perguntas conhecidas; o benchmark existe e roda. A pergunta “quanto foi” tem uma resposta só, e ela é a mesma no painel e no agente.

Está de pé quando duas formulações diferentes da mesma pergunta devolvem o mesmo número.

Escala e eficiência — a plataforma como produto. Novas fontes entram por um caminho conhecido: função do Unity Catalog para lógica, metric view para métrica, índice para documento. A orquestração é declarativa, o custo do sincronismo contínuo é uma escolha consciente por caso de uso, e adicionar um domínio novo não exige redesenhar o agente.

Está de pé quando incluir um domínio novo significa registrar objetos no catálogo, e não escrever código de integração.

A ordem é causal, não cronológica. Não adianta declarar métrica sobre dado sem dono, e não adianta escalar um agente que ainda não devolve o mesmo número duas vezes.

Perguntas frequentes (FAQ)

RAG serve para responder pergunta sobre número?

Não. Busca vetorial devolve trechos semelhantes à pergunta, e semelhança não é agregação. Pergunta que envolve soma, média, período ou comparação pertence à rota estruturada.

O índice vetorial herda os row filters da tabela de origem?

Não. A documentação do Databricks AI Search afirma que permissão de linha e de coluna não é suportada, e indica implementar o controle na aplicação usando o filter API. O índice é um objeto separado, com permissão própria.

Então o Genie Agent executa como o usuário que pergunta?

Só em parte, e a distinção importa. A consulta roda no warehouse com a credencial embutida pelo autor do agente; o acesso ao dado é avaliado pelo Unity Catalog com a identidade do usuário final, e é assim que row filters e column masks continuam valendo.

Adicionar só as tabelas certas ao agente é um controle de segurança?

Não. A documentação diz que o Genie pode consultar tabelas além das adicionadas, porque o controle é do Unity Catalog e não do agente. O perímetro é o catálogo.

Preciso de metric view se já tenho modelo semântico no Power BI?

Não necessariamente, mas precisa de uma camada de métrica, e ela precisa ser a mesma para o painel e para o agente. Duas definições da mesma métrica em lugares diferentes reproduzem exatamente o problema que a camada existe para resolver.

E no Microsoft Fabric, o desenho muda?

Não na essência. O Fabric data agent traduz para SQL, DAX ou KQL conforme a fonte, usa as credenciais de quem pergunta e honra RLS e CLS. A rota não estruturada continua sendo uma cópia indexada.

Onde fica o dado quando o agente roda no Microsoft Foundry?

Em recursos da sua assinatura. No setup padrão do Foundry Agent Service, Storage, Cosmos DB e Azure AI Search ficam ligados ao projeto por um capability host, e as threads vão para o banco enterprise_memory. A permissão que vale no índice é o RBAC do serviço de busca, não a da tabela de origem — e a conversa é um segundo lugar onde o conteúdo recuperado passa a existir.

Conclusão

A escolha entre RAG e text-to-SQL não é sobre qual responde melhor: é sobre onde mora a regra de acesso. Na rota estruturada, a regra está na tabela e é avaliada em cada execução — o motor simplesmente não devolve a linha que você não pode ver. Na rota não estruturada, a regra virou uma cópia, e a documentação diz com todas as letras que permissão de linha e de coluna não é suportada no índice. As duas rotas são legítimas e a maioria dos sistemas sérios usa as duas. O que não é legítimo é usar a segunda achando que ela se comporta como a primeira.

O teste de maturidade cabe numa pergunta que você pode fazer hoje ao seu time: se eu remover o acesso de uma pessoa a uma tabela, o que muda no que o agente responde para ela? Se a resposta for “muda nas duas rotas”, o desenho está de pé. Se for “muda no SQL, no índice eu preciso conferir”, pelo menos o risco é conhecido. E se for silêncio, o que existe não é um agente de dados — é uma cópia sem dono respondendo com a confiança de quem tem. Vale fazer a mesma pergunta uma segunda vez, no passado: e o que já foi respondido, onde está?

👉 Se você está levando um agente de dados para produção — especialmente em ambiente regulado, onde a pergunta do auditor não é se o agente acerta, mas por que ele viu aquela linha, este é o ponto de partida.
Quer trocar ideia sobre acesso governado a dados por agentes? Me chama no LinkedIn.