Jul 2, 2026 | 10 minutes

Agent SQL: como construir um agente de IA que consulta seu banco de dados

Artigo histórico da Make (a fonte indica 2 de julho de 2026). Este texto reproduz um guia da Make publicado nessa data. O «nós» e as recomendações, ferramentas, preços e capturas de tela são do autor da Make naquela data; não são uma afirmação deste site nem garantia de que esses apps, recursos ou preços continuem iguais hoje. Para o estado atual das plataformas, consulte as fontes oficiais.

Construa um agente de IA que transforma linguagem natural em consultas SQL no seu banco de dados usando a Make, com passos, testes e variações. Agent SQL é um workflow em que um agente de IA traduz perguntas em inglês simples para consultas SQL seguras, executa essas consultas no seu banco de dados e devolve respostas legíveis. Com mais de 98% dos clientes SQL da Databricks usando AI/BI para dar a cada funcionário acesso direto aos dados, as equipes de negócio precisam de acesso self-service aos dados. Este guia mostra como os agentes de IA da Make transformam perguntas em respostas SQL confiáveis usando um único cenário visual.

O que você precisa antes de construir um workflow de agent SQL

Antes de construir um cenário de agent SQL na Make, reúna os acessos, as credenciais e as proteções de que o workflow depende. A lista abaixo cobre a configuração mínima viável para uma implantação que começa somente com leitura e transforma perguntas em linguagem natural em SQL validado contra seu banco de dados de produção ou réplica.

• Uma conta Make em um plano pago que suporte operations suficientes para o seu volume de consultas e acesso ao Scenario Builder.
• Acesso ao banco de dados por meio de um conector suportado, como a integração MySQL, PostgreSQL ou Microsoft SQL Server, idealmente apontado para uma réplica de leitura com um usuário de privilégios mínimos.
• Credenciais de API do provedor de LLM escolhido (OpenAI, Anthropic ou Azure OpenAI), com uma chave restrita a este cenário.
• Um dicionário de esquema ou catálogo de tabelas armazenado em um data store da Make, documentado na documentação de data stores, para que o agente baseie o SQL em nomes de colunas reais.
• Um canal de revisão no Slack ou por e-mail para aprovações de consultas e registro de auditoria.

O problema: por que o acesso direto ao banco de dados bloqueia os usuários de negócio

O acesso direto ao banco de dados bloqueia os usuários de negócio porque escrever SQL correto exige conhecimento de esquema, lógica de joins e fluência em dialetos que a maioria dos profissionais de marketing, operações e gestão de contas não tem. O resultado é uma lacuna persistente de habilidade em SQL: o líder de receita que precisa de um recorte de churn por segmento, ou o analista financeiro que quer os reembolsos de ontem por região, abre um ticket e espera. Solicitações lentas de dados então se acumulam na fila de analytics, onde uma pergunta de cinco minutos vira uma ida e volta de três dias por Jira, threads de Slack e calls de esclarecimento. O custo disso são decisões tomadas com base em dashboards desatualizados ou no achismo. Analistas queimam horas em consultas repetitivas em vez de trabalho de modelagem, e as equipes de negócio param de fazer perguntas porque a espera não compensa. Conectar uma interface de chat diretamente às tabelas de produção também é arriscado, já que consultas sem restrições podem varrer bilhões de linhas ou expor colunas sensíveis. É aqui que a automação de IA explicada por meio de um cenário controlado muda a economia, dando aos usuários de negócio acesso em linguagem natural enquanto mantém as proteções no próprio banco de dados.

O cenário Make que transforma perguntas em respostas SQL

O cenário Make que transforma perguntas em respostas SQL é um loop agêntico em que uma pergunta em linguagem natural entra na Make, um agente de IA planeja a consulta, um módulo de banco de dados executa o SQL e uma resposta formatada retorna ao solicitante. O padrão usa a plataforma de agentes de IA da Make para orquestrar raciocínio, chamadas de ferramentas e validação dentro de um único canvas visual. Na entrada, um módulo Slack - Watch Messages ou Webhooks - Custom Webhook captura a pergunta do usuário. A pergunta flui para o AI Agents - Run an Agent, que guarda o contexto do esquema, as tabelas permitidas e as definições de ferramentas. O agente decide se deve consultar, esclarecer ou recusar, e então chama um módulo MySQL - Execute a Query (Advanced) ou PostgreSQL - Execute a Query (Advanced) por meio de uma chamada de ferramenta estruturada. Os resultados retornam como bundles, que um Aggregator remodela em um único payload. O agente então redige uma explicação em linguagem simples, e um módulo Slack - Create a Message devolve a resposta ao canal original. Há proteções em cada route: um Filter bloqueia instruções destrutivas, um Router separa caminhos de leitura de caminhos de escalonamento, e um módulo Set Variable registra metadados de auditoria. O Scenario Builder torna cada etapa inspecionável, para que os revisores possam rastrear a pergunta, o SQL gerado e as linhas retornadas em um só lugar.

Como construir o cenário de agent SQL na Make

Construir o cenário de agent SQL na Make leva sete passos configurados dentro do Scenario Builder, começando com um trigger de entrada e terminando com uma resposta formatada de volta ao usuário. Cada módulo da cadeia tem uma função: receber a pergunta, classificar a intenção, gerar SQL contra um esquema permitido, validar a consulta, executá-la por uma conexão somente de leitura, resumir os resultados com um LLM e entregar a resposta. Siga os passos abaixo em ordem, mantendo o cenário inativo até que os testes do passo 7 passem.

Passo 1: Configure o trigger do agente

Crie um novo cenário e adicione um trigger Webhooks - Custom Webhook como ponto de entrada, já que o app AI Agents da Make não tem um trigger de invocação dedicado. O trigger recebe a pergunta em linguagem natural, o identificador do usuário e um token de sessão usado adiante para logging. Defina uma estrutura de dados explícita para que a saída do bundle seja tipada.

• Aceite os campos JSON: question, user_id, session_id.
• Configure o agendamento como Immediately para que o cenário rode a cada invocação.
• Ative o armazenamento de execuções incompletas para replay durante a depuração.

Passo 2: Carregue o contexto do esquema

Adicione um módulo Data Store - Get a Record que recupera um documento de esquema curado descrevendo apenas as tabelas que o agente tem permissão para consultar. Essa lista de permissões orienta todos os passos seguintes e é a base da proteção contra SQL injection. Armazene nomes de tabelas, nomes de colunas, tipos e descrições curtas de negócio em um registro por banco de dados.

Passo 3: Gere SQL com um LLM

Conecte o OpenAI - Generate a Completion (ou Anthropic Claude - Create a Prompt) e passe o contexto do esquema junto com a pergunta do usuário. Instrua o modelo a retornar JSON com dois campos: sql e rationale. Consulte o guia de integração de LLM da Make para padrões de prompt que produzem saída estruturada parseável.

• Defina a temperatura como 0 para SQL determinístico.
• Force o modo JSON para que o parsing downstream seja confiável.
• Injete as tabelas permitidas literalmente no system prompt.

Passo 4: Valide o SQL antes da execução

Insira um Router seguido de um módulo Tools - Set Variable que faz o parse do SQL gerado e executa três verificações: o tipo de instrução deve ser SELECT, toda tabela referenciada deve constar na lista de permissões e nenhuma palavra-chave proibida (DROP, DELETE, UPDATE, INSERT, ALTER, TRUNCATE, GRANT) pode aparecer. Uma validação malsucedida é roteada para um canal de alerta via Slack - Create a Message e devolve uma recusa educada ao usuário. DICA PRO: Sempre execute o SQL gerado por meio de uma chamada parametrizada de MySQL - Execute a Query (Advanced) ou PostgreSQL - Execute a Query (Advanced) com a conexão autenticada como um usuário de banco de dados somente de leitura. Combine isso com a verificação da lista de permissões do passo 4, e o SQL injection vindo de consultas geradas pelo agente se torna uma superfície fechada: a credencial não consegue alterar dados mesmo que a validação seja contornada.

Passo 5: Execute contra uma conexão somente de leitura

Adicione o módulo de banco de dados correspondente à sua stack: MySQL - Execute a Query (Advanced), PostgreSQL - Execute a Query (Advanced), Microsoft SQL Server - Execute a Query (Advanced) ou BigQuery - Make an API Call. Configure a conexão com um usuário de banco dedicado e somente de leitura, cujos grants permitam apenas SELECT nas tabelas da lista de permissões. Defina um timeout de instrução de 30 segundos no nível do banco de dados para que consultas descontroladas não mantenham operations abertas.

Passo 6: Resuma os resultados para o usuário

Encaminhe o conjunto de resultados para um Iterator se você precisar de tratamento linha a linha, e depois para um Aggregator para consolidar os dados em um único bloco de texto. Passe esse bloco para uma segunda chamada OpenAI - Generate a Completion que transforma as linhas em uma resposta em linguagem simples tendo a pergunta original como contexto. Os padrões de como construir agentes de IA se aplicam diretamente aqui.

Passo 7: Devolva a resposta e registre o log

Envie o resumo de volta por Webhooks - Webhook Response ou Slack - Create a Message, e grave a transação completa (pergunta, SQL, contagem de linhas, latência) em Google Sheets - Add a Row para auditoria. Mova a formatação de resultados de longa duração para um cenário filho usando o recurso de subscenarios para manter o fluxo principal responsivo. DICA PRO: Envolva o passo 5 em um manipulador de erros com um módulo Break configurado para três tentativas em falhas transitórias de conexão, mas roteie erros determinísticos de SQL (sintaxe, permissão negada) para um Tools - Set Variable que realimenta a mensagem de erro no passo 3 para uma única tentativa de correção. Essa configuração módulo a módulo se recupera com elegância sem loops infinitos.

Como testar e solucionar problemas do agente SQL

Teste o agente SQL executando um conjunto controlado de perguntas em linguagem natural contra um banco de dados de staging antes de promover o cenário para produção. Comece com consultas somente de leitura com respostas conhecidas, depois avance para prompts ambíguos que estressem o entendimento de esquema do agente. Use o histórico de execuções nativo da Make para inspecionar cada bundle, confirme que o SQL gerado corresponde à intenção e verifique se o Router envia instruções destrutivas para um caminho de rejeição. Combine isso com práticas de transparência de agentes para que os revisores possam rastrear cada decisão. Erros comuns de SQL e padrões de correção de incompatibilidade de esquema para observar:

• Incompatibilidade de esquema: o agente referencia uma coluna que não existe mais. Corrija atualizando o contexto de esquema passado ao OpenAI - Generate a Completion a cada execução.
• Erros de sintaxe: aspas faltando ou divergência de dialeto entre Postgres e MySQL. Adicione um módulo de validação que faz o parse do SQL antes da execução.
• Timeouts: varreduras longas em tabelas sem índice. Limite as linhas da consulta e defina um timeout de instrução na conexão.
• Permissão negada: a conta de serviço não tem SELECT em uma view. Audite os grants na role do banco de dados.

Resultados que você pode esperar de uma implantação de agent SQL

Uma implantação de agent SQL na Make muda o acesso ao banco de dados de uma fila de tickets para uma conversa self-service, produzindo tempo de consulta mais rápido para usuários de negócio e menos tickets de analistas para a equipe de dados. Quando o cenário está no ar, líderes de marketing, parceiros de finanças e gerentes de operações podem fazer perguntas em linguagem simples dentro do Slack ou de um formulário web, e o módulo OpenAI - Generate a Completion combinado com um módulo MySQL - Execute a Query (Advanced) protegido retorna as linhas em segundos. As equipes normalmente veem os backlogs de analistas encolherem à medida que consultas repetitivas, snapshots semanais de receita e contagens de coortes saem da fila. A história do agente da Celonis mostra como cenários de IA semelhantes reduzem o esforço de revisão manual, enquanto a história de eficiência da Perk ilustra como a automação interna libera especialistas para focar em trabalho de modelagem de maior valor em vez de montagem de relatórios.

Variações e próximos passos para o seu agente SQL

O cenário central se adapta a muitos contextos de equipe uma vez que o padrão de validação e execução está no lugar. Troque o trigger de chat por um webhook, roteie os resultados para uma ferramenta de BI ou adicione filtros baseados em papel para que o mesmo agente atenda equipes de finanças, suporte e analytics de produto. Para arquiteturas de referência entre sistemas conectados, o guia de conectividade de API mostra como estender o alcance além dos conectores nativos.

Conclusão

Um workflow de agent SQL na Make transforma perguntas em linguagem simples em respostas de banco de dados governadas, entregando valor direto a analistas e operadores sem expor credenciais brutas ou acesso de escrita arriscado. A recapitulação é concreta: um cenário recebe uma pergunta, um módulo de LLM redige SQL somente de leitura contra um esquema que você publica, um Router de proteção valida a instrução, um módulo de banco de dados a executa, e um módulo final devolve um resumo legível com as linhas subjacentes. Esse padrão escala de um único dashboard de equipe até relatórios self-service para a empresa toda. Mapeie seu esquema, escolha um padrão de pergunta de alto tráfego e comece gratuitamente para lançar seu primeiro cenário de agent SQL ainda esta semana.

Perguntas frequentes

P1: O que é um sistema de agent SQL? Um sistema de agent SQL é um workflow de IA que converte perguntas em linguagem simples em consultas SQL validadas, executa essas consultas contra um banco de dados e retorna respostas formatadas. Na Make, isso roda como um cenário combinando um módulo de LLM com módulos de banco de dados e proteções de segurança. P2: É seguro deixar um agente de IA executar consultas SQL? É seguro quando você impõe proteções de segurança. Use um usuário de banco de dados somente de leitura, restrinja o agente a views aprovadas, valide o SQL gerado com um Router que bloqueia instruções DELETE, DROP, UPDATE e TRUNCATE, e registre cada consulta em log de auditoria antes que o cenário a execute. P3: Quais bancos de dados funcionam com a Make para agent SQL? Os bancos de dados suportados incluem PostgreSQL, MySQL, Microsoft SQL Server e Oracle por meio de conectores de módulo nativos da Make. BigQuery, Snowflake e Airtable também funcionam por meio de seus apps dedicados. Para outros motores, como DuckDB ou ClickHouse, use o módulo HTTP - Make a Request contra a REST API deles. P4: Preciso fazer fine-tuning de um modelo para text-to-SQL? Não é necessário fine-tuning na maioria dos casos. Modelos de fronteira da OpenAI e da Anthropic lidam bem com text-to-SQL quando você passa o esquema, as descrições de colunas e dois ou três exemplos de consulta no system prompt do módulo OpenAI - Generate a Completion. P5: Como a Make lida com consultas de longa duração? A Make lida com consultas de longa duração por meio de configurações de timeout de cenário e padrões assíncronos. Configure o módulo de banco de dados com um timeout de consulta, depois use um Router para enviar consultas pesadas a uma tabela de fila que o agente consulta depois, mantendo o cenário principal responsivo para usuários interativos.