Relatório semanal automático com IA: do banco de dados ao seu e-mail toda segunda
Como montar um agente que consulta o seu banco de dados em modo somente leitura, calcula os números da semana e entrega o relatório por e-mail toda segunda às 7h, sem ninguém abrir planilha.
Um relatório semanal automático com IA tem três peças: uma conexão somente leitura com o banco onde os números moram, um agente que sabe quais perguntas fazer a esse banco e um gatilho que acorda o agente toda segunda e manda o resultado por e-mail. No CollaborAI as três peças se montam sem código, e este guia mostra cada uma.
O exemplo ao longo do texto é o relatório comercial de uma distribuidora: pedidos, faturamento e ticket médio da semana anterior, comparados com a semana de antes, por região.
Antes de começar: o que pedir ao seu TI
O agente vai consultar o banco pela internet. Duas providências do lado de quem administra o banco evitam 90% dos problemas:
- Um usuário só de leitura. Crie um usuário próprio para o CollaborAI com permissão de
SELECTapenas nas tabelas ou views que o relatório usa. Nada de usuário administrador. - Liberar o IP de saída. As consultas do CollaborAI saem sempre pelo mesmo endereço IP, que aparece na tela de cadastro da conexão, no campo IP de saída. Libere esse IP no firewall do banco.
Uma view pronta ajuda mais do que parece. Se o TI criar uma view vw_pedidos_semana com as colunas
já com nomes claros, o agente erra menos e as consultas ficam mais rápidas.
Peça 1: a conexão com o banco
No menu lateral, abra Conectores e clique em Banco de Dados. O CollaborAI conecta com PostgreSQL, MySQL, SQL Server e Oracle.
Preencha:
- Nome, algo que diga o que é e o nível de acesso, como “ERP — produção (leitura)”.
- Tipo de banco, host (só o endereço, sem
http://), porta, banco, usuário e senha. - Somente leitura, que já vem ligado. Deixe assim: o agente só consegue executar consultas
SELECT. - Conexão segura (SSL/TLS), recomendada para qualquer banco acessível pela internet.
- Schema padrão e Descrição, opcionais. A descrição ajuda o agente a escolher a conexão certa quando houver mais de uma, então escreva o que tem lá: “Pedidos, clientes e estoque do ERP”.
Salve e teste. A senha fica guardada cifrada e nunca aparece de volta na tela. Cada conta pode ter até 20 conexões.
O detalhamento do que o agente pode e não pode fazer no banco está no guia de agente de IA para banco de dados.
Peça 2: o agente que faz as perguntas
Crie um agente novo (se for o primeiro, o guia Especialistas ou Agentes explica a diferença) e, nas Habilidades, ative o grupo Banco de Dados:
| Habilidade | O que faz |
|---|---|
| Listar conexões de banco | Mostra quais conexões o agente pode usar |
| Listar tabelas | Lista tabelas e views de uma conexão |
| Descrever tabela | Mostra colunas, tipos e chaves antes de consultar |
| Executar consulta SQL | Roda a consulta. Em conexão somente leitura, só SELECT |
Logo abaixo aparece o bloco Conexões liberadas para este agente. Marque Somente as selecionadas e escolha a conexão do relatório. Se a sua conta tiver também a conexão de homologação ou a do financeiro, o agente do comercial não enxerga nenhuma das duas.
As instruções do agente
É aqui que o relatório fica bom ou fica genérico. Diga o que cada número significa no seu negócio:
Você gera o relatório comercial semanal. Use apenas a view vw_pedidos_semana da conexão “ERP — produção (leitura)”. “Semana” vai de segunda a domingo. Faturamento é a soma de valor_liquido de pedidos com status FATURADO; ignore cancelados. Ticket médio é faturamento dividido pelo número de pedidos faturados. Faça as somas e as médias no próprio SQL, com GROUP BY por região. Compare com a semana anterior em valor e em %. Responda em até 15 linhas: primeiro os três números principais, depois a tabela por região, depois uma frase sobre a maior variação. Se a consulta falhar ou não houver dados, diga isso claramente e não invente números.
Duas frases desse bloco fazem diferença técnica:
- “Faça as somas no próprio SQL.” Cada consulta devolve até 100 linhas por padrão (no máximo 500). Para um relatório, isso é mais que suficiente desde que o banco entregue os totais agregados, e não as milhares de linhas de pedido.
- “Não invente números.” Se o banco estiver fora do ar, você quer um e-mail dizendo isso, e não um relatório plausível e errado.
Mais sobre como escrever esse bloco no guia de instruções de agente que funcionam.
Antes de agendar, converse com o agente e peça o relatório da semana passada. Confira dois ou três números contra o sistema. Só depois automatize.
Peça 3: o gatilho de segunda-feira
Na página do agente, abra Gatilhos e crie um agendamento:
- Nome do gatilho: “Relatório comercial de segunda”.
- Prompt que será executado: “Gere o relatório comercial da semana anterior.”
- Frequência: Semanal, com segunda em Dias da semana.
- Horário (Brasília): 7h, para o relatório chegar antes da reunião.
- Me enviar email com o resultado, se você também quiser receber.
O funcionamento dos gatilhos, incluindo o de webhook, está no guia de gatilhos.
Para onde vai o relatório
Para mandar o relatório ao time, e não só para você, use o botão Quando terminar, envie para,
na página do agente, e escolha Email. Informe o destinatário (uma lista do time funciona bem), o
assunto e, se quiser, um corpo com marcadores como {agent.name} e {run.output}, que é o texto do
relatório. Em Disparar quando run vier de, marque Agendado, para a saída não disparar a cada
teste que você fizer na conversa.
Há ainda a opção Exigir minha aprovação antes de executar. Com ela ligada, cada envio fica pendente até você aprovar. Vale para relatórios que saem para fora da empresa ou que têm número sensível, como margem por cliente.
Se o relatório precisa sair do seu endereço de e-mail, e não de um remetente da plataforma, conecte o Gmail ou o Outlook e ative a habilidade de envio no agente. O guia de conectores de Gmail, Agenda e Microsoft 365 mostra como liberar só o envio, sem leitura da caixa.
Quanto custa
Cada execução do agente consome um run da cota mensal da conta. O relatório semanal usa de quatro a cinco por mês.
| Pro | Enterprise | |
|---|---|---|
| Execuções de agente por mês | 200 | 2.000 |
| Agendamentos | 3 | 10 |
Quando a cota do mês acaba, os agendamentos são pausados e voltam no dia 1º. O plano Free não inclui execuções de agente nem gatilhos.
Cinco erros comuns
Usuário com permissão demais. Mesmo com a conexão em somente leitura, o usuário do banco deve ter só o necessário. São duas travas independentes, e as duas devem estar fechadas.
Pedir as linhas, e não os totais. “Liste os pedidos da semana” esbarra no limite de linhas e gera um relatório que ninguém lê. Peça os números agregados.
Definição vaga de métrica. Se “faturamento” significa coisas diferentes para o comercial e para o financeiro, escreva a definição nas instruções. O agente segue o que está escrito.
Agendar antes de testar. Rode na conversa, confira contra o sistema, ajuste as instruções. A primeira versão quase nunca é a final.
Liberar todas as conexões. Com mais de uma conexão cadastrada, a opção Todas as conexões deixa o agente consultar qualquer uma, inclusive as cadastradas depois. Prefira liberar só as necessárias.
Perguntas frequentes
O agente consegue alterar dados no banco?
Não, com a conexão em Somente leitura. Nesse modo, a consulta só aceita SELECT, e comandos como
DROP, ALTER ou TRUNCATE são recusados em qualquer modo.
E se o banco estiver numa rede interna, sem acesso pela internet?
O CollaborAI não alcança endereços de rede privada. O banco precisa aceitar conexão pela internet, de preferência só a partir do IP de saída mostrado na tela.
Dá para gerar gráfico no relatório?
O agente entrega texto e tabela. Para gráficos sobre uma planilha exportada, use a análise de dados no Chat, que gera o gráfico como imagem.
Comece com três números, não com trinta. Um relatório curto que chega toda segunda às 7h vale mais que um painel completo que alguém precisa lembrar de abrir.
