Agente de IA para banco de dados: consultas em português, sem abrir o banco para ninguém

Um agente de IA conectado ao banco de dados recebe a pergunta em português, escreve o SQL, executa a consulta e devolve a resposta pronta. “Quantos pedidos atrasaram esta semana, por transportadora?” deixa de depender de alguém que saiba SQL e tenha tempo livre.

No CollaborAI, isso virou um conector próprio na versão 1.5: o Banco de Dados, para PostgreSQL, MySQL, SQL Server e Oracle. Este guia mostra como montar o agente, como deixar o acesso seguro e que tipo de pergunta ele responde bem.

O que o agente consegue fazer

Ao ligar o conector a um agente, ele ganha quatro ferramentas:

Ferramenta	Para quê
Listar conexões	Ver quais bancos estão liberados para ele
Listar tabelas	Descobrir as tabelas de um banco ou schema
Descrever tabela	Ler as colunas e os tipos antes de montar a consulta
Consultar	Executar o SQL e receber o resultado

A sequência é a de um analista cuidadoso: o agente olha o que existe, confere a estrutura da tabela e só então escreve a consulta. Você não precisa explicar o esquema a cada pergunta.

Animação: o agente aciona em ordem as ferramentas Listar conexões, Listar tabelas, Descrever tabela e Consultar, cada uma indo ao banco, até devolver a resposta — Primeiro o agente descobre o que existe; só depois escreve a consulta.

Somente leitura por padrão

Toda conexão nasce em modo Somente leitura. Nele, o agente só executa consultas de leitura (SELECT e afins), e qualquer comando que altere dados é recusado antes de chegar ao banco.

Há uma segunda camada que vale em qualquer modo. Comandos como DROP, ALTER, TRUNCATE, CREATE, GRANT e a execução de procedures ficam sempre bloqueados, assim como mais de um comando na mesma consulta.

Se o seu caso exige gravar dados, dá para trocar a conexão para Leitura e escrita. A tela avisa: “o agente poderá executar INSERT/UPDATE/DELETE neste banco. Use um usuário com as permissões mínimas necessárias.” Para responder perguntas, que é o uso mais comum, deixe como está.

Animação: no modo somente leitura, SELECT chega ao banco e UPDATE é barrado; no modo leitura e escrita, UPDATE passa e DROP continua barrado — As duas camadas: o modo da conexão decide se a escrita passa; os comandos destrutivos ficam barrados em qualquer modo.

Passo a passo

1. Crie um usuário só para o agente

Antes de tudo, no próprio banco, crie um usuário dedicado com permissão de leitura apenas nas tabelas ou views que interessam. É a proteção que não depende de nenhuma plataforma: mesmo que algo dê errado, aquele usuário não enxerga o que não deve.

Uma prática que ajuda muito: em vez de liberar as tabelas brutas, crie views com nomes e colunas claros (vw_pedidos_atrasados, vw_vendas_por_regiao). O agente erra menos e você controla exatamente o que sai.

2. Libere o IP de saída no firewall

Em Conectores > Banco de Dados, a tela mostra o IP de saída: todas as consultas dos agentes saem por ele. Libere esse IP no firewall ou no grupo de segurança do banco.

O banco precisa estar acessível pela internet. Endereços de rede interna, como 10.x, 192.168.x ou nomes terminados em .local, são recusados no cadastro.

Tela Banco de Dados com o aviso do IP de saída para liberar no firewall e uma conexão ERP somente leitura com teste OK — O IP de saída fica no topo da tela. Depois de liberar no firewall, use Testar.

3. Cadastre a conexão

Crie uma nova conexão e preencha:

Nome: algo que diga o que é, como “ERP — produção (leitura)”.
Tipo de banco: PostgreSQL, MySQL, SQL Server ou Oracle.
Host, Porta, nome do banco, Usuário e Senha.
Schema padrão (opcional).
Descrição (opcional, mas importante): “Pedidos, clientes e estoque do ERP”. É o que ajuda o agente a escolher a conexão certa quando houver mais de uma.
Conexão segura (SSL/TLS): ligada por padrão, recomendada para qualquer banco acessível pela internet.

A senha é guardada cifrada e nunca mais aparece, nem para você. Depois de salvar, use Testar para confirmar que o firewall deixou a plataforma entrar.

Formulário de nova conexão com nome, tipo PostgreSQL, host, banco, usuário, senha, descrição, conexão segura e Somente leitura ligados — O formulário de conexão. Somente leitura vem ligado.

4. Ligue o banco ao agente

Na seleção de ferramentas do agente, marque as ferramentas de Banco de dados. Logo abaixo aparece o bloco Conexões liberadas para este agente, com duas opções:

Todas as conexões, inclusive as que você cadastrar depois.
Somente as selecionadas, para escolher banco a banco.

Prefira a segunda. Se você tem o banco de produção e o de homologação cadastrados, o agente de vendas não precisa ver os dois. A restrição vale na execução, não só na tela: uma conexão fora da lista é recusada mesmo que o modelo tente usá-la.

Bloco Conexões liberadas para este agente com a opção Somente as selecionadas e a conexão ERP marcada — Cada agente enxerga só os bancos que você liberar.

5. Ensine o vocabulário da empresa

Nas instruções do agente, inclua um glossário curto. O modelo sabe SQL, mas não sabe que “pedido faturado” é status = 'F' ou que o ano fiscal da sua empresa começa em abril.

Use a view vw_pedidos para perguntas sobre pedidos. “Faturado” é status = ‘F’. “Atrasado” é data_entrega_prevista menor que hoje e status diferente de ‘E’. Valores estão em reais, com duas casas. Quando a pergunta for ambígua, pergunte o período antes de consultar.

Perguntas que funcionam bem

“Quais os 10 clientes que mais compraram em outubro, com o total de cada um?”
“Quantos pedidos atrasaram esta semana, por transportadora?”
“Qual produto teve a maior queda de vendas comparando setembro e outubro?”
“Liste os pedidos acima de R$ 5 mil ainda sem nota fiscal.”
“Quantos clientes novos entraram por mês neste ano?”

O que essas perguntas têm em comum: pedem números agregados ou listas curtas. O agente devolve até 100 linhas por consulta por padrão, com teto de 500. Para análises que precisam varrer milhares de linhas, peça o resultado já agrupado (“total por mês”, “top 20”) em vez da lista crua.

Onde o agente pode trabalhar

O mesmo agente responde no Chat do painel, onde você conversa com ele, e pode rodar sozinho com um gatilho de agendamento: toda segunda às 8h, ele consulta o banco e manda por e-mail o resumo de vendas da semana anterior.

Um cuidado: pense duas vezes antes de colocar um agente com acesso ao banco interno em um canal aberto ao público, como o WhatsApp ou o webchat do site. Se for necessário, por exemplo para o cliente consultar o status do próprio pedido, use um usuário de banco que enxergue só uma view com o mínimo de colunas.

Quanto custa

O conector não tem cobrança própria. Cada conversa ou rotina conta como uma execução do agente:

Plano	Execuções de agente por mês
Pro	200
Enterprise	2.000

Acima da cota, as execuções seguintes consomem créditos. Cada usuário pode cadastrar até 20 conexões de banco.

Perguntas frequentes

Preciso saber SQL para usar?

Não. O agente escreve o SQL. Saber SQL ajuda a conferir uma resposta suspeita: no Chat do painel, o bloco Bastidores mostra as ferramentas que o agente acionou em cada resposta.

O agente pode apagar dados?

No modo Somente leitura, não: comandos de escrita são recusados. Comandos destrutivos como DROP e TRUNCATE são recusados em qualquer modo. E o usuário de banco com permissão só de leitura garante o resto.

Funciona com banco na rede interna, sem acesso pela internet?

Não. O banco precisa aceitar conexões vindas da internet, com o IP de saída da plataforma liberado no firewall. Bancos acessíveis apenas na rede interna da empresa não são alcançados.

Posso cadastrar produção e homologação ao mesmo tempo?

Pode, até 20 conexões por usuário. Dê a cada uma um nome e uma descrição que deixem claro qual é qual, e use Conexões liberadas para este agente para que cada agente veja só o banco que deve. Antes de ligar qualquer banco com dados de clientes, vale passar pelas perguntas do post sobre como usar IA na empresa sem vazar dados.

Comece pelo caso mais simples: uma view, um usuário só de leitura e três perguntas que o seu time faz toda semana. Se o agente acertar as três, o resto é questão de ampliar o glossário.