Como ancorar agentes Genie em dados estruturados e documentos sem perder a governança

Criar um agente para automatizar tarefas de negócios simples pode ser fácil. Mas criar um que realmente entenda sua empresa e respeite sua governança de dados existente é muito mais difícil.

Por muito tempo, as equipes precisaram usar sistemas separados para analisar dados estruturados e não estruturados, muitas vezes passando semanas apenas para conectar os dois. Ao permitir a análise diretamente de tabelas e arquivos não estruturados, os Genie Agents simplificam essa arquitetura, permitindo que você embase um único agente com dados estruturados e não estruturados.

À medida que você consolida esses dados, surge uma pergunta crítica: se um agente tem acesso a tudo, o que o impede de dizer a coisa errada para a pessoa errada?

A boa notícia é que, com a Databricks, a resposta está na base de governança de dados que você já possui. Os mesmos mecanismos do Unity Catalog nos quais você confia hoje (sincronização de identidade, privilégios de objeto, ABAC, filtros de linha e máscaras de coluna) governam automaticamente os Genie Agents sem nenhuma configuração adicional. Essa herança contínua depende de uma estratégia de governança bem estruturada, que exploraremos em detalhes.

Para dar vida a esses conceitos, passaremos por esses cenários usando exemplos da Brickstore, uma varejista global fictícia de tijolos, como ponto de referência.

O contrato de governança: os Genie Agents são executados com as credenciais do usuário final

O princípio arquitetônico central é simples: os Genie Agents são executados com as credenciais do usuário final. O Unity Catalog impõe a governança por padrão, garantindo que o acesso a tabelas e volumes esteja vinculado diretamente à identidade e às permissões existentes do usuário final.

Isso é crítico, porque muitos sistemas desenvolvidos internamente concedem amplo acesso aos agentes e dependem de engenharia de prompt para filtrar os resultados na camada do modelo. Isso efetivamente torna o LLM seu perímetro de segurança — uma aposta perigosa, dado que os modelos podem ser manipulados ou burlados. Dizer a um auditor que "adicionei instruções que diziam para não mostrar dados restritos" não é um controle de governança defensável.

Com a estrutura de governança descrita neste artigo, o Unity Catalog, e não o modelo, continua sendo seu perímetro de segurança, assim como ocorre no restante da Databricks. Embora o Genie determine como consultar os dados, ele é incapaz de retornar um registro que o usuário final não tenha autorização para ver, pois cada resposta é filtrada na camada de dados antes mesmo de sair do Lakehouse.

Etapa 0: Tudo começa com a identidade: Automatic Identity Management (AIM) e provisionamento Just-in-Time (JIT)

A base arquitetônica começa garantindo que suas identidades corporativas sejam precisas e atualizadas.

Os controles de acesso são, fundamentalmente, tão confiáveis quanto as identidades que eles avaliam. Uma política que diz "membros de brickstore_apac só podem ver pedidos da APAC" não tem sentido se as suas associações de grupo na Databricks forem uma cópia desatualizada e mantida manualmente do que está no seu provedor de identidade.

Automatic Identity Management para Microsoft Entra ID e Okta elimina essa lacuna. Quando ativado, usuários, grupos, associações de grupo e principais de serviço são sincronizados desses provedores de identidade para a Databricks automaticamente, sem a necessidade de um aplicativo SCIM. O provisionamento Just-in-Time está sempre ativo, de modo que um usuário que nunca fez login na Databricks é provisionado no primeiro login e já chega com suas associações de grupo existentes.

Aqui está o fluxo passo a passo:

1. O IdP é a fonte da verdade. Alguém entra na organização de vendas da APAC; seu provedor de identidade o coloca no grupo brickstore_apac.
2. O AIM sincroniza isso na Databricks — incluindo a associação ao grupo. O JIT provisiona o usuário na Databricks na primeira vez que ele abre o Genie One.
3. As políticas do Unity Catalog baseiam-se nesses grupos — privilégios de objeto, políticas ABAC, filtros de linha e máscaras de coluna avaliam a associação ao grupo no momento da consulta.
4. O usuário faz uma pergunta a um Genie Agent, e a resposta é moldada exatamente pelo que a permissão do grupo dele permite. Nem mais, nem menos.

O resultado é que a governança é contínua, não uma configuração pontual. Quando um funcionário é transferido da APAC para a AMER, o IdP o move entre os grupos, a sincronização propaga a alteração e a próxima pergunta que ele fizer ao Genie retornará a visualização da AMER — sem que ninguém precise abrir um chamado ou fazer alterações no Genie Agent. Quando o funcionário sai da empresa, ele é desativado no IdP e seu acesso a todos os Genie Agents é removido imediatamente.

Etapa 1: Embasamento de dados estruturados e controle de quatro camadas de acesso

Uma vez que as identidades estejam devidamente estabelecidas, podemos focar no que elas têm permissão para ver. Para dados estruturados, um Genie Agent pode acessar qualquer ativo de dados do Unity Catalog — tabelas, views, views materializadas, views de métricas, tabelas de streaming e até tabelas estrangeiras federadas de sistemas externos.

Por exemplo, tabelas Delta são os fatos e as dimensões. Na Brickstore, isso corresponde a brickstore.sales.orders (cada pedido, com um region e um customer_email) e brickstore.sales.products (o catálogo de tijolos). Metric Views são a camada semântica governada por cima — elas codificam as definições das suas métricas de negócios (por exemplo, o que significa "receita líquida", como "tijolos vendidos" é calculado, o que conta como um "tijolo mais vendido") uma única vez, em YAML, para que cada consumidor as calcule da mesma forma.

Sobre esses ativos estão quatro camadas de controle de acesso que as pessoas costumam confundir:

Os privilégios de objeto são a primeira camada de acesso: sem SELECT, o Genie não pode consultar a tabela em nome do usuário final. Mas conceder acesso a uma tabela não significa que você precisa conceder todo o acesso. Você aplica filtros de linha e máscaras de coluna sobre essas concessões, de modo que um gerente regional possa consultar a tabela de pedidos vendo apenas as linhas de sua própria região e nunca o e-mail bruto do cliente. Esses controles de linha e coluna baseiam-se nos mesmos grupos que suas concessões já usam — is_account_group_member('brickstore_apac') e afins. O ABAC, a seguir, não substitui nada disso; é apenas uma maneira de vincular os mesmos filtros e máscaras por meio de uma política, em vez de fazer isso tabela por tabela.

ABAC: defina a política uma vez, deixe-a se propagar

A maneira antiga de fazer segurança de linha e coluna era por tabela: escrever um filtro de linha, anexá-lo a orders; escrever uma máscara de coluna, anexá-la a outra tabela; repetir para sempre. Isso ainda funciona para lógicas pontuais, mas em centenas de tabelas é uma configuração propensa a falhas.

Políticas ABAC, que agora estão em GA no Unity Catalog junto com tags governadas e classificação automatizada de dados, invertem isso. Você marca dados confidenciais com tags governadas (pares de chave/valor controlados por acesso em nível de conta como pii:email), e escreve uma política que diz "onde quer que esta tag apareça, aplique esta proteção". Novas tabelas herdam a proteção no momento em que são marcadas, portanto não há trabalho por tabela.

Uma máscara de coluna + Política ABAC que protege todas as colunas de e-mail no catálogo, em uma única instrução:

E um filtro de linha + Política ABAC para que cada gerente veja apenas os pedidos de sua região, com base na associação ao grupo:

O resultado: o gerente da APAC faz uma pergunta sobre pedidos e o Genie Agent retorna apenas as linhas da APAC, com customer_email mascarado. O gerente da AMER consulta a mesma tabela e obtém as linhas da AMER.

Etapa 2: Estendendo a mesma governança para documentos

Historicamente, a estratégia de governança para as equipes tem sido mais desafiadora ao lidar com dados não estruturados. Embora os dados estruturados sejam gerenciados com segurança em um data warehouse ou banco de dados, os documentos geralmente são mantidos em um sistema de armazenamento isolado, governado por ACLs separadas.

A solução é manter os arquivos dentro do mesmo plano de governança que seus dados estruturados. Você pode colocá-los em volumes do Unity Catalog e eles se tornam recursos protegíveis como qualquer outro. Você concede GRANT READ VOLUME para os grupos e usuários que devem visualizá-los, e o Genie raciocina sobre eles sob o mesmo contrato de identidade:

Vale a pena entender um comportamento antes de projetar seu agente: quando você anexa um volume a um Genie Agent, ele se torna uma fonte obrigatória. Isso significa que o agente valida o acesso a cada fonte anexada quando é carregado, de modo que um usuário que não tenha READ VOLUME em um volume anexado não poderá usar esse agente de forma alguma. Em outras palavras, as concessões de volume governam os documentos como um pré-requisito para usar o agente, portanto, certifique-se de delimitar o escopo das fontes de documentos de cada agente para o público que deve usar esse agente. Se dois públicos precisarem de documentos diferentes, talvez seja necessário fornecer a eles Genie Agents diferentes (cada um montando apenas os volumes que o usuário pode ler).

Lembre-se também de que um volume do Unity Catalog é a menor unidade protegível, portanto, as permissões se aplicam a todo o volume, e não a arquivos individuais. Você não pode escolher arquivos específicos para compartilhar; deve conceder acesso a todo o volume ou a nada dele.

Com essas considerações em mente, os volumes podem ser anexados diretamente aos Genie Agents como uma fonte de conhecimento, da mesma forma que você faria para uma tabela ou visualização. Os Genie Agents leem muito além de PDFs — os formatos suportados incluem PDF, arquivos de imagem (JPG, JPEG, PNG, TIFF, TIF) e documentos do Office (DOC, DOCX, PPT, PPTX), além de texto simples e Markdown. Na prática, isso significa que contratos digitalizados, apresentações de slides e folhas de especificações são todos válidos, não apenas PDFs limpos. (Consulte a documentação de volumes dos Genie Agents para obter a lista completa e os limites atuais.)

Para garantir um roteamento preciso e o desempenho ideal, siga estas práticas recomendadas para configurar seus volumes:

• Adicione uma descrição clara: Descreva exatamente qual conteúdo o volume contém, como ele está organizado e como o agente deve usá-lo. Não use marcadores de posição genéricos. Por exemplo, em vez de "arquivos regionais", use "Relatório de mercado da APAC — motivadores de demanda, tendências e itens a serem observados para a região APAC". O Genie depende dessa descrição para selecionar o volume correto.
• Evite conteúdo duplicado: Anexar vários volumes que contêm informações sobrepostas torna mais difícil para o agente recuperar documentos relevantes. O mesmo se aplica a arquivos individuais dentro de um volume.
• Evite arquivos irrelevantes: Inclua apenas arquivos que sejam relevantes para o domínio do agente. Arquivos irrelevantes podem confundir o agente.
• Use nomes de arquivo claros: Use nomes de arquivo descritivos para que o agente possa distinguir entre os arquivos.

Etapa 3: Genie Agents em produção: mesma pergunta, respostas diferentes

Neste ponto, o Genie Agent está totalmente capacitado para agir como um verdadeiro especialista no domínio — com acesso total a dados estruturados e não estruturados. A base de conhecimento subjacente ainda está totalmente protegida por filtros de linha, máscaras de coluna e concessões de volume com base em permissões por usuário.

Avaliamos nossa implementação testando-a com dois usuários diferentes fazendo exatamente a mesma pergunta, o que deve gerar duas respostas exclusivamente corretas.

Considere duas sessões simultâneas do Genie Agent, ambas baseadas nos mesmos ativos — a tabela orders, o catálogo products e o volume market_report. Embora um solicitante pertença a brickstore_apac e o outro a brickstore_amer, ambos enviam exatamente a mesma consulta:

"Qual produto é o nosso mais vendido neste trimestre e o que está impulsionando essa demanda? Além disso, liste os principais clientes por trás dessas vendas e seus e-mails."

Resposta 1 - para o gerente da APAC

Resposta 2 - para o gerente da AMER

Há três coisas que vale a pena destacar:

• Os números são diferentes e ambos estão corretos. A consulta de "tijolos mais vendidos" de ambos os gerentes extrai dados das mesmas tabelas — a diferença está puramente nas linhas às quais cada um tem direito, e não em uma diferença na forma como a métrica foi calculada.
• A diferença exigiu zero engenharia de prompt por usuário. Ninguém escreveu "se o usuário for da APAC, oculte outras regiões". As instruções do agente são idênticas. O Unity Catalog fez a filtragem no momento da consulta — tanto nas linhas quanto na coluna mascarada. Observe que a coluna de e-mail está mascarada para proteger as PII.
• Dados estruturados, enriquecidos por conhecimento não estruturado. Sem os documentos regionais, o Genie poderia ter identificado a pergunta “o quê” facilmente, mas teria tido dificuldades para descobrir quais fatores estão impulsionando a demanda. Com dados não estruturados disponíveis, o Genie tem todo o contexto do negócio.

Padrões para ficar atento

Alguns padrões para ficar atento ao levar os aprendizados deste blog para a produção:

• Tag, depois política. Não mascare tabela por tabela. O instinto é proteger as três tabelas à sua frente. Resista a isso. Defina tags governadas e políticas ABAC para preparar sua governança de dados para o futuro.
• Um público por volume. Como o volume é a menor unidade que pode ser concedida, decida o acesso ao documento no limite do volume. Se dois documentos precisarem de leitores diferentes, eles precisarão de volumes diferentes e de diferentes Agentes Genie — planeje o layout com antecedência.
• Tenha cuidado ao expor o Genie One ou os Agentes Genie externamente via MCP ou API - você deve gerenciar a identidade com cuidado. Ao contrário de executá-lo por meio da UI do Databricks, nem sempre você tem permissão para usar a identidade do usuário final (ex: ao usar um Service Principal para autenticação). Existem padrões específicos a serem adotados, e a Databricks detalha as configurações de U2M, M2M e OBO em Acesse o Genie em qualquer lugar.
• Teste por personificação, não por inspeção. Não valide a governança lendo a política e se convencendo de que ela está certa — faça a mesma pergunta como membro de cada grupo e compare as respostas. Transforme isso em um teste de regressão e execute-o sempre que as políticas ou os agrupamentos mudarem.

Conclusão

Criar um agente pode ser fácil, mas governá-lo exige um trabalho real de design. No Databricks, as identidades corporativas são sincronizadas a partir do IdP, os privilégios de objeto controlam o acesso, o ABAC e as tags governadas aplicam proteção em escala, os filtros de linha e as máscaras de coluna controlam o que retorna, e os documentos são mantidos no mesmo sistema que os dados.

Com essa configuração, os Agentes Genie herdam toda a governança sem qualquer configuração adicional.

Para começar a criar seu primeiro Agente Genie governado, visite a documentação do Genie e a documentação de políticas ABAC.

(Esta publicação no blog foi traduzida utilizando ferramentas baseadas em inteligência artificial) Publicação original