A cada poucas semanas, alguém da área de negócios perguntava a mesma coisa: “Posso simplesmente digitar minha pergunta e obter os dados?” Depois de ouvir isso vezes suficientes, construímos um agente Text-to-SQL no Databricks e acabamos comparando dois caminhos muito diferentes: Genie Spaces e o Mosaic AI Agent Framework.

O conceito parece simples. Um usuário digita uma pergunta em inglês simples. O agente descobre o que ele quer dizer, escreve o SQL, executa-o no Databricks e retorna uma resposta. Numa demonstração, parece quase mágico. Num ambiente governado real com dados de negócios reais, a história é diferente.

A primeira coisa que aprendemos é que a geração de SQL é a parte fácil. A questão mais difícil é se o agente consegue entender seu modelo de dados, operar dentro das suas regras de segurança e retornar respostas que realmente se sustentem quando alguém agir com base nelas.

Isso nos levou a uma decisão real: usar uma experiência gerenciada do Databricks ou construir o agente nós mesmos?

De um lado, o Genie Spaces, a experiência de análise conversacional gerenciada do Databricks, parecia o caminho mais rápido. Do outro lado, o Mosaic AI Agent Framework, o framework proprietário do Databricks para construir aplicações agenticas personalizadas em Python, oferecia controle sobre cada camada. Mais poderoso, mas também significativamente mais trabalhoso.

Testamos ambos com o mesmo conjunto de dados e as mesmas perguntas de negócios, não apenas para ver qual produzia um SQL melhor, mas para entender o que cada abordagem realmente exigia.

O que é um Agente Text-to-SQL? Genie Spaces e Mosaic AI Explicados

Antes de entrarmos no que construímos, ajuda definir as três partes principais.

Um agente Text-to-SQL é um sistema de IA que pega uma pergunta em linguagem natural e a transforma em SQL executável. Numa demonstração, parece simples: um usuário digita “Qual é o saldo atual da conta 1001?” e o agente produz SELECT balance FROM accounts WHERE account_id = 1001. Num ambiente governado real, a mesma pergunta também exige que o agente saiba a qual tabela “accounts” se refere, se o usuário atual tem permissão para ver aquela linha e o que “balance” significa no seu esquema.

Genie Spaces são a opção gerenciada do Databricks para esta experiência. Você configura um Espaço sobre tabelas, visualizações e metadados do Unity Catalog selecionados, adiciona instruções e exemplos, conecta um SQL Warehouse e obtém uma interface conversacional funcional sem precisar construir a camada de aplicação por conta própria. Pronto para uso: geração de SQL, execução de consultas, apresentação de respostas, permissões do Unity Catalog e uma forma de adicionar contexto de negócios. A desvantagem é o controle: você pode guiar o Genie, mas não possui o fluxo de raciocínio, a orquestração de ferramentas, a memória ou a lógica de validação.

Mosaic AI Agent Framework é o framework proprietário do Databricks para construir aplicações agenticas personalizadas. Não é uma biblioteca genérica de código aberto. É uma parte nativa da plataforma Databricks, projetado para que as equipes possam definir o modelo, ferramentas, prompts, lógica de orquestração, avaliação e implantação dentro do mesmo ambiente governado onde seus dados residem.

A primeira constatação: a geração de SQL não era suficiente

Isso era óbvio em retrospectiva, mas foram necessárias algumas consultas quebradas para realmente entender.

Um agente Text-to-SQL não é útil apenas porque consegue gerar SQL. Uma consulta pode ser sintaticamente perfeita e ainda assim estar errada:

• Pode fazer um join através de um relacionamento obsoleto.
• Pode interpretar mal o que “conta ativa” significa no seu contexto.
• Pode puxar um campo que deveria ser mascarado.
• Pode retornar dados que um determinado usuário não deveria ver.

Assim, o verdadeiro trabalho não era construir o agente. Era construir o contexto que o agente precisava para raciocinar corretamente: o que cada tabela representa, o que cada coluna significa em termos de negócio, como as entidades se relacionam, quais filtros são aprovados, quem pode acessar o quê, e quais funções do Unity Catalog devem ser chamadas como ferramentas controladas.

Antes de comparar as ferramentas, precisávamos de uma base comum

Antes de comparar Genie e Mosaic, tivemos que garantir que ambos estivessem trabalhando a partir da mesma base. Caso contrário, não estaríamos comparando as ferramentas, mas sim duas versões diferentes do problema.

Isso significou documentar tabelas e colunas, codificar regras de negócio que antes existiam apenas na cabeça das pessoas, validar permissões, configurar mascaramento e segurança em nível de linha, e empacotar lógica reutilizável em funções do Unity Catalog. Demorou mais do que o esperado. Mas também tornou tudo o que veio depois muito mais honesto.

Em um ambiente de produção, um agente não pode depender de um prompt inteligente para compensar a falta de contexto. Ele precisa de uma base de dados que foi realmente preparada para ele. Essa preparação é onde reside a maior parte do trabalho real, independentemente da ferramenta que você escolher.

O desafio comum: fazer com que as funções do Unity Catalog funcionem para ambos os agentes

Uma vez estabelecida a base, precisávamos de uma maneira de expor a lógica de negócio reutilizável a ambos os agentes de forma consistente. As funções do Unity Catalog eram o mecanismo natural; em vez de deixar cada agente redescobrir a mesma lógica a cada chamada, poderíamos definir funções controladas para tarefas específicas.

Foi aqui que as coisas ficaram mais nuançadas do que o esperado.

Um desenvolvedor pode ler a documentação, explorar um esquema, perguntar a um colega. Um agente decide se usa uma função com base quase inteiramente em seu nome e descrição. Essa única diferença muda o que significa “bem projetado”.

Para uso do agente, as funções precisam ser:

Nomeadas claramente e autoexplicativas

• Com escopo restrito, para que o agente possa associá-las à tarefa correta
• Documentadas no nível do parâmetro, para que o agente saiba o que passar
• Com saída previsível, para que o agente possa raciocinar sobre o resultado
• Com as permissões corretas
• Não estruturadas como um procedimento armazenado amplo que faz várias coisas ao mesmo tempo
• Este foi um requisito de projeto, não um efeito colateral de querer que as funções funcionassem em duas ferramentas. Funções que pareciam interfaces de produto funcionaram. Funções que pareciam atalhos SQL internos não funcionaram.

Como o Genie Spaces Funciona para Text-to-SQL no Databricks

Começamos com o Genie porque era o caminho mais direto: uma interface conversacional sobre dados governados, sem ter que escrever todo o stack do agente do zero.

A configuração é simples. Crie um Espaço, selecione tabelas ou visualizações, adicione instruções e exemplos, defina relacionamentos, conecte um SQL Warehouse, comece a fazer perguntas. Para um caso de uso de análise de autoatendimento voltado para analistas de negócios, este é um ponto de partida genuinamente forte.

Onde o Genie mostrou seus limites

Os limites apareceram quando fomos além de perguntas simples. Não porque o Genie falhou, mas porque guiar o comportamento através da configuração é diferente de controlá-lo através de código. Você pode adicionar instruções e exemplos, mas não controla o ciclo de raciocínio diretamente.

Testando o Genie através da API

Também testamos a API e o caminho Python para ver se a configuração poderia ser versionada e automatizada. É possível, mas exige muita estrutura inicial. Tabelas, instruções, exemplos, junções e contexto semântico precisam ser explicitamente definidos. Isso o torna adequado para um Espaço que já está estável e precisa ser operacionalizado. É uma experiência difícil se você ainda está descobrindo como o Espaço deve ser.

A forma como pensamos sobre isso: use a interface do usuário enquanto estiver descobrindo a configuração certa, mude para a API assim que o Espaço estiver estável e você quiser automatizá-lo ou versioná-lo.

Mais uma coisa a notar, o Genie pode ser chamado de fora do Databricks através de APIs, mas o próprio Espaço ainda é executado dentro da plataforma Databricks. Um aplicativo externo pode enviar perguntas para um Espaço existente, mas não hospeda nem substitui o tempo de execução.

Construindo um Agente Text-to-SQL Personalizado com o Mosaic AI Agent Framework

Mudar para o Mosaic foi como passar de um produto configurado para um projeto de engenharia propriamente dito.

Em vez de adicionar instruções a um Espaço, estávamos escrevendo Python. Nós controlávamos:

• Seleção de LLM e design de prompt do sistema
• Quais ferramentas expor e como o agente as seleciona
• Tratamento de erros e avaliação de respostas
• Registro de rastreamento e implantação do agente

Esse nível de controle é o ponto principal do Mosaic. Não é uma versão mais flexível do Genie, é uma categoria totalmente diferente, um framework para construir uma aplicação agêntica personalizada. Os casos de uso que fazem sentido aqui são aqueles em que o agente precisa fazer coisas que um Espaço gerenciado não consegue:

• Chamar APIs externas
• Combinar dados do Databricks com documentos
• Acionar fluxos de trabalho
• Seguir lógica de orquestração complexa demais para ser expressa por meio de configuração.

O custo desse controle é a responsabilidade de engenharia. Alguém precisa projetar o agente, manter o código, testar o comportamento da ferramenta, avaliar as saídas e monitorar a produção. Isso não é um motivo para evitar o Mosaic, mas é um fator real para determinar se uma equipe está pronta para ele.

Ao final deste caminho, a comparação deixou de ser sobre funcionalidades. Tornou-se sobre duas formas diferentes de trabalhar.

Onde a comparação se tornou real

A parte mais difícil não foi construir cada agente. Foi torná-los genuinamente comparáveis.

Para compará-los de forma justa, ambos precisavam trabalhar a partir da mesma base: as mesmas tabelas do Unity Catalog, as mesmas definições de negócio, as mesmas regras de segurança, a mesma lógica de mascaramento e acesso em nível de linha, e as mesmas funções do Unity Catalog.

Chegar lá exigiu mais iterações do que o esperado. Algumas funções tiveram que ser simplificadas. Alguns comentários de coluna tiveram que ser reescritos para serem inequívocos. Alguns parâmetros precisavam de melhor documentação. Alguns formatos de retorno tiveram que ser tornados mais consistentes.

Cada vez que a base compartilhada melhorava, ambos os agentes melhoravam, não apenas um deles. A qualidade do agente é amplamente determinada pela qualidade do contexto governado por trás dele, e não pelo modelo ou interface que está por cima.

Custo e responsabilidade: o que mudou entre os dois caminhos

O auto-stop é uma configuração do SQL Warehouse que desliga o warehouse automaticamente após um período definido de inatividade, evitando custos durante as horas de menor movimento. Para uma equipe pequena ou média que usa o Space durante o horário comercial, os custos podem ser razoavelmente previsíveis com o tamanho de warehouse e a configuração de auto-stop corretos.

A decisão não é realmente sobre qual opção custa menos. É sobre o tipo de equipe que você tem e o que você está preparado para gerenciar ao longo do tempo. No nosso caso, queremos apenas comparar como cada agente funciona para um caso simples.

6 Lições da Construção de um Agente Text-to-SQL no Databricks

Seis coisas que diríamos a nós mesmos se estivéssemos começando isso de novo.

1. Comece com o contexto dos dados, não com o modelo. O LLM pode gerar SQL. O contexto do Unity Catalog é o que torna a resposta correta. Se os metadados estiverem ausentes ou incorretos, mesmo um modelo robusto produzirá consultas com aparência plausível que, na verdade, não funcionam.
2. Projete as funções do Unity Catalog como interfaces de produto, não como atalhos SQL. O agente descobre ferramentas lendo seus nomes e descrições. Nomenclatura clara, escopo restrito, parâmetros documentados e saídas previsíveis importam mais do que uma lógica interna elegante.
3. A API Genie é melhor para repetibilidade do que para exploração. É a ferramenta certa quando um Space está estável e você deseja versioná-lo ou automatizá-lo. É uma experiência difícil se você ainda está descobrindo como o Space deve ser.
4. O Mosaic oferece mais controle, mas a responsabilidade é real. Fluxos de trabalho personalizados, integrações externas e controle total de orquestração são vantagens genuínas, mas vêm com um compromisso da equipe que não deve ser subestimado.
5. Teste a segurança como parte do agente, não depois dele. Permissões, mascaramento e segurança em nível de linha não são uma etapa final de QA. Eles afetam quais consultas são geradas e quais dados retornam. Eles fazem parte da implementação desde o primeiro dia.
6. A base importa mais do que a interface. Melhoramos o contexto do Unity Catalog na metade do experimento, e ambos os agentes melhoraram significativamente. Antes de escolher uma ferramenta, pergunte se seus dados estão realmente prontos para serem processados por um agente.

Conclusão

Ambas as ferramentas funcionaram. Nenhuma delas fez a parte difícil por nós.

O Genie agilizou a disponibilização de uma interface funcional para os usuários, mas era menos configurável em seus detalhes. O Mosaic possibilitou a construção de algo que se comportava exatamente como precisávamos, embora tenha complicado cada etapa do processo. Mas, em ambos os casos, a qualidade do resultado dependeu da qualidade dos metadados, da clareza das regras de negócio e do design das funções do Unity Catalog. A ferramenta foi quase secundária.

Comece com o Genie quando o objetivo for análise de autoatendimento governada e a base de dados estiver razoavelmente limpa. Mude para o Mosaic quando o caso de uso exigir orquestração personalizada, integrações externas ou um comportamento que a configuração simplesmente não consegue expressar.

Mas antes de fazer essa escolha, dedique tempo aos dados. A pergunta não é “qual ferramenta de agente devemos usar?” É “nossos dados estão realmente prontos para um agente raciocinar sobre eles?” Acertando isso, o resto se torna muito mais gerenciável.

Se já temos bons dados, podemos pensar no que estamos procurando: acessibilidade sem liberdade ou liberdade sem acessibilidade.

Continue lendo

Se isso foi útil, escrevemos regularmente sobre IA aplicada, engenharia de dados e construção de sistemas reais em plataformas de dados modernas.

Explore mais artigos em Blogs da Marvik