1. Propósito e Escopo
Este documento define todos os prompts, configurações de memória, transição entre estados e demais requisitos funcionais para o Agente de IA Analítico, uma solução projetada para transformar perguntas de negócio em insights acionáveis. Essa documentação é um modelo de PRD ou Documento de Requisitos de Produto específicos para construção de Agentes de IA.
O objetivo principal é converter perguntas em linguagem natural em scripts SQL, executar consultas no banco de dados e apresentar insights em forma de relatórios, gráficos ou resumos.
2. Contexto e Problema
Cenário Atual
Organizações enfrentam desafios ao tentar extrair insights acionáveis de grandes volumes de dados. Perguntas de negócio são frequentemente complexas e requerem a tradução para consultas SQL, além de análise dos resultados para extração de insights.
Problemas Identificados
- Complexidade na Tradução: A tradução de perguntas de negócio para consultas SQL requer conhecimento técnico especializado.
- Tempo de Resposta: A execução de consultas e análise de resultados pode ser demorada, atrasando a tomada de decisão.
- Capacidade de Análise: A análise manual dos dados recuperados pode ser propensa a erros e inconsistências.
3. Impactos Esperados
A implementação deste agente de IA visa alcançar os seguintes resultados:
- Reduzir o tempo de resposta na obtenção de insights a partir de perguntas de negócio.
- Aumentar a precisão na tradução de perguntas para consultas SQL.
- Automatizar a análise e apresentação de dados em formatos acionáveis.
4. Visão Geral da Solução
O agente de IA analítico transforma perguntas de negócio em scripts SQL, executa consultas em bases de dados e gera relatórios, gráficos ou resumos com insights. A seguir são detalhadas todas as regras de negócio e especificações funcionais necessárias para que esse agente atue como um assistente útil e autônomo na transformação de perguntas em insights acionáveis.
A solução é composta por um fluxo de automação com três agentes de IA. O processo inicia com a transformação de perguntas em scripts SQL e termina com a geração de relatórios ou resumos.
| Agentes | Função Principal |
|---|---|
Agente de Transformação de Perguntas em Script SQL (RF 1)
| Converter perguntas de negócio em scripts SQL. |
Agente de Execução de Consultas em Banco de Dados (RF 2)
| Executar o script SQL e recuperar os dados necessários. |
Agente de Análise e Geração de Relatórios (RF 3)
| Analisar dados recuperados e gerar relatórios, gráficos ou resumos. |
5. Protótipos
Para proporcionar uma visão clara e tangível da solução proposta, criamos protótipos interativos que demonstram tanto o fluxo de trabalho dos agentes quanto o resultado final que o cliente receberá. Explore os links abaixo para entender melhor a solução em ação.
6. Requisitos Funcionais
RF 1. Agente de Transformação de Perguntas em Script SQL
1.1 Tarefa do Agente
Converter perguntas de negócio em linguagem natural em scripts SQL para consulta ao banco de dados.
1.2 Prompt ou Instruções do Agente
# 1. Contexto e explicações sobre inputs iniciais Você está recebendo perguntas de negócio em linguagem natural. Seu objetivo é transformar essas perguntas em scripts SQL precisos e seguros. # 2. Objetivo Converter perguntas de negócio em linguagem natural em scripts SQL para consulta ao banco de dados. # 3. Regras que você deve seguir para gerar sua resposta - Identifique as entidades-chave e suas relações na pergunta. - Mapeie estas entidades para tabelas e colunas no banco de dados. - Assegure-se de que o script SQL gerado seja seguro e otimizado, prevenindo SQL injection e respeitando permissões de acesso. # 4. Exemplo de Output que você deve produzir SELECT nome, vendas FROM clientes WHERE cidade = 'São Paulo';
1.3 Configurações do Agente
1.3.1 Especificação do Input
- Mecanismo de Acionamento: Este agente é o ponto de partida do fluxo e deve ser acionado pelo envio de perguntas de negócio em linguagem natural via API. Na fase de testes, o fluxo será iniciado pelo envio manual das perguntas, que serão inseridas diretamente na interface da Prototipe AI para acelerar o processo de validação.
- Tipo do input: Perguntas de negócio em linguagem natural.
- Formatos Suportados: Texto simples (plain text).
- Número de caracteres esperado: Até 500 caracteres por pergunta.
1.3.2 Especificação do Output
- Formato de output: Script SQL pronto para execução.
-
Exemplo de Estrutura de Output:
SELECT nome, vendas FROM clientes WHERE cidade = 'São Paulo';
- Número de caracteres esperado: Scripts SQL podem variar em tamanho, mas devem ser concisos, geralmente entre 100 e 1000 caracteres.
1.3.3 Parâmetros de Geração
- Modelo: GPT-5
- Temperatura: 0.3
1.3.4 Ferramentas do Agente
- Documentos: Não consulta documentos externos.
- Calculadora: Não utiliza.
- Busca Online: Não utiliza.
- Sistemas Externos: Não se conecta a sistemas externos.
1.3.5 Memória
- Visibilidade das Instruções (Prompt): As instruções deste agente não devem ser visíveis para nenhum agente subsequente.
- Visibilidade da Resposta: A resposta gerada por este agente deve ser visível para o Agente de Execução de Consultas em Banco de Dados (RF 2).
1.3.6 Regras de Orquestração e Transição
Ao concluir sua execução, esse agente aciona o Agente de Execução de Consultas em Banco de Dados (RF 2).
RF 2. Agente de Execução de Consultas em Banco de Dados
2.1 Tarefa do Agente
Executar o script SQL no banco de dados e recuperar os dados necessários.
2.2 Prompt ou Instruções do Agente
# 1. Contexto e explicações sobre inputs iniciais
Você está recebendo um script SQL gerado para consulta ao banco de dados. Seu objetivo é executar este script e recuperar os dados necessários.
# 2. Objetivo
Executar o script SQL no banco de dados e recuperar os dados necessários.
# 3. Regras que você deve seguir para gerar sua resposta
- Conecte-se ao banco de dados de forma segura utilizando credenciais apropriadas.
- Execute o script SQL e garanta que a execução ocorra dentro de limites aceitáveis de tempo.
- Capture e trate erros de execução, retornando mensagens de erro claras e informativas.
# 4. Exemplo de Output que você deve produzir
{
"dados": [
{"nome": "João", "vendas": 1000},
{"nome": "Maria", "vendas": 1500}
]
} 2.3 Configurações do Agente
2.3.1 Especificação do Input
- Mecanismo de Acionamento: Este agente deve ser acionado automaticamente após a conclusão do agente anterior (RF 1).
- Tipo do input: Script SQL para execução no banco de dados.
- Formatos Suportados: Texto simples (plain text).
- Número de caracteres esperado: Até 1000 caracteres por script.
2.3.2 Especificação do Output
- Formato de output: Dados recuperados do banco de dados em formato JSON.
-
Exemplo de Estrutura de Output:
{ "dados": [ {"nome": "João", "vendas": 1000}, {"nome": "Maria", "vendas": 1500} ] } - Número de caracteres esperado: Os dados recuperados podem variar amplamente em tamanho, mas devem ser estruturados de forma clara e concisa.
2.3.3 Parâmetros de Geração
- Modelo: GPT-5
- Temperatura: 0.3
2.3.4 Ferramentas do Agente
- Documentos: Não consulta documentos externos.
- Calculadora: Não utiliza.
- Busca Online: Não utiliza.
- Sistemas Externos: Conecta-se ao banco de dados para execução das consultas.
2.3.5 Memória
- Visibilidade das Instruções (Prompt): As instruções deste agente não devem ser visíveis para nenhum agente subsequente.
- Visibilidade da Resposta: A resposta gerada por este agente deve ser visível para o Agente de Análise e Geração de Relatórios (RF 3).
2.3.6 Regras de Orquestração e Transição
Ao concluir sua execução, esse agente aciona o Agente de Análise e Geração de Relatórios (RF 3).
RF 3. Agente de Análise e Geração de Relatórios
3.1 Tarefa do Agente
Analisar os dados recuperados e gerar relatórios, gráficos ou resumos com insights.
3.2 Prompt ou Instruções do Agente
# 1. Contexto e explicações sobre inputs iniciais Você está recebendo dados recuperados do banco de dados. Seu objetivo é analisar esses dados e gerar relatórios, gráficos ou resumos com insights acionáveis. # 2. Objetivo Analisar os dados recuperados e gerar relatórios, gráficos ou resumos com insights. # 3. Regras que você deve seguir para gerar sua resposta - Analise os dados para identificar padrões, tendências e anomalias. - Escolha o formato de apresentação mais adequado (relatório, gráfico, resumo) com base na complexidade dos dados. - Garanta que os insights sejam claros e acionáveis, providenciando contexto para a tomada de decisão. # 4. Exemplo de Output que você deve produzir Relatório: "As vendas totais em São Paulo foram de R$ 2500, com João e Maria sendo os principais vendedores."
3.3 Configurações do Agente
3.3.1 Especificação do Input
- Mecanismo de Acionamento: Este agente deve ser acionado automaticamente após a conclusão do agente anterior (RF 2).
- Tipo do input: Dados recuperados do banco de dados em formato JSON.
- Formatos Suportados: JSON.
- Número de caracteres esperado: Variável, dependendo do volume de dados recuperados.
3.3.2 Especificação do Output
- Formato de output: Relatórios, gráficos ou resumos em formato texto ou imagem.
-
Exemplo de Estrutura de Output:
Relatório: "As vendas totais em São Paulo foram de R$ 2500, com João e Maria sendo os principais vendedores."
- Número de caracteres esperado: O relatório ou resumo deve ser claro e conciso, geralmente entre 100 e 1000 caracteres.
3.3.3 Parâmetros de Geração
- Modelo: GPT-5
- Temperatura: 0.3
3.3.4 Ferramentas do Agente
- Documentos: Não consulta documentos externos.
- Calculadora: Pode utilizar lógica interna para cálculos básicos.
- Busca Online: Não utiliza.
- Sistemas Externos: Não se conecta a sistemas externos.
3.3.5 Memória
- Visibilidade das Instruções (Prompt): As instruções deste agente não devem ser visíveis para nenhum agente subsequente.
- Visibilidade da Resposta: A resposta gerada por este agente é o entregável final e não é passada para outros agentes internos.
3.3.6 Regras de Orquestração e Transição
A execução deste agente finaliza o fluxo. O relatório, gráfico ou resumo gerado é o resultado que deve ser disponibilizado ao usuário.