Agente de IA para Relatórios de Desempenho Financeiro

Ler arquivos de desempenho financeiro histórico de clientes, perfilar a estrutura, validar qualidade dos dados e produzir um mapeamento padronizado para consolidação temporal e por dimensões.

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 arquivos de dados financeiros via API. Na fase de testes, os dados serão enviados diretamente por upload na interface da Prototipe AI, para acelerar o processo de validação.
• Tipo do input: Arquivos contendo dados históricos financeiros de clientes.
• Formatos Suportados: Esse agente deve ser capaz de receber arquivos nos formatos: .xlsx, .xls, .csv, .json.
• Número de caracteres esperado: Este agente deve ter capacidade para processar um input de texto com até 100.000 caracteres.

1.3.2 Especificação do Output

• Formato de output: O output deve ser um objeto JSON estruturado que descreve o esquema padronizado, regras de transformação e diagnóstico de qualidade dos dados.
• Exemplo de Estrutura de Output:

   {"schema_padronizado": {"periodo_col": "data", "formato_periodo": "AAAA-MM|AAAA-Tn|AAAA", "granularidade": "mensal|trimestral|anual", "chaves_dimensoes": ["cliente", "produto", "regiao", "moeda"], "metricas_valor": ["receita", "custo", "lucro", "despesa_operacional"], "moeda_base": "BRL", "taxa_cambio_aplicada": false}, "regras_transformacao": ["normalizar nomes de colunas para snake_case", "converter datas para AAAA-MM-DD"], "diagnostico_qualidade": {"linhas_totais": 0, "intervalo_temporal": {"inicio": "", "fim": ""}, "perc_nulos_por_coluna": {"col": 0.0}, "lacunas_temporais": [{"inicio": "", "fim": ""}], "duplicidades": {"chave": ["periodo", "cliente", "produto", "regiao", "moeda"], "qtd_registros_afetados": 0}, "outliers_suspeitos": [{"coluna": "receita", "regra": "> P99.5", "qtd": 0}], "moedas_detectadas": ["BRL"]}, "padronizacao_realizada": "sim", "justificativa_padronizacao": "Padronização realizada conforme especificações."}

• Número de caracteres esperado: O JSON gerado deve ter um tamanho estimado em torno de 2.000 caracteres.

1.3.3 Parâmetros de Geração

• Modelo: GPT-5
• Temperatura: 0.6

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 Preparador de Script de Consolidação e Cálculo Financeiro (RF 2).

1.3.6 Regras de Orquestração e Transição

Ao concluir sua execução, esse agente aciona o Agente Preparador de Script de Consolidação e Cálculo Financeiro (RF 2).

Gerar o script determinístico (Python/pandas) que consolida os dados conforme o schema padronizado e calcula KPIs e variações temporais necessárias à análise de tendências.

2.3.1 Especificação do Input

• Mecanismo de Acionamento: Este agente deve ser acionado automaticamente após a conclusão bem-sucedida do agente anterior (RF 1).
• Tipo do input: Objeto JSON contendo schema_padronizado, regras_transformacao, diagnostico_qualidade.
• Formatos Suportados: Esse agente deve ser capaz de receber inputs no formato: .json.
• Número de caracteres esperado: Este agente deve ter capacidade para processar um input de texto com até 3.000 caracteres.

2.3.2 Especificação do Output

• Formato de output: O output deve ser um objeto JSON contendo o script Python gerado para consolidação e cálculo financeiro.
• Exemplo de Estrutura de Output:

   {"script": "# código Python pandas para ler arquivos, aplicar mapeamentos, agregar por período e dimensões, e calcular KPIs (receita, custo, lucro, margem_bruta, margem_operacional, var_MoM, var_YoY, CAGR)", "parametros_execucao": {"engine": "python3.11+pandas", "arquivos": ["path_ou_id_1", "path_ou_id_2"], "saida_formato": "json"}}

• Número de caracteres esperado: O JSON gerado deve ter um tamanho estimado em torno de 2.500 caracteres.

2.3.3 Parâmetros de Geração

• Modelo: GPT-5
• Temperatura: 0.6

2.3.4 Ferramentas do Agente

• Documentos: Não consulta.
• Calculadora: Não utiliza.
• Busca Online: Não utiliza.
• Sistemas Externos: Não utiliza.

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 Execução de Consolidação e Cálculo (RF 3).

2.3.6 Regras de Orquestração e Transição

Ao concluir sua execução, esse agente aciona o Agente de Execução de Consolidação e Cálculo (RF 3).

Executar o script Python/pandas gerado para consolidar os dados e calcular KPIs sobre os arquivos informados, retornando os resultados em JSON.

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: Payload pronto com o script Python e parâmetros de execução.
• Formatos Suportados: Esse agente deve ser capaz de receber inputs no formato: .json.
• Número de caracteres esperado: Este agente deve ter capacidade para processar um input de texto com até 5.000 caracteres.

3.3.2 Especificação do Output

• Formato de output: O output deve ser um JSON com lista de registros agregados contendo as métricas calculadas.
• Exemplo de Estrutura de Output:

   {"periodo": "AAAA-MM", "dimensoes": {"cliente": "...", "produto": "...", "regiao": "...", "moeda": "..."}, "metricas": {"receita_total": 0.0, "custo_total": 0.0, "lucro": 0.0, "margem_bruta_%": 0.0, "margem_operacional_%": 0.0, "var_MoM_%": 0.0, "var_YoY_%": 0.0, "CAGR_%": 0.0}}

• Número de caracteres esperado: O JSON gerado deve ter um tamanho estimado em torno de 3.000 caracteres.

3.3.3 Parâmetros de Geração

• Modelo: GPT-5
• Temperatura: 0.6

3.3.4 Ferramentas do Agente

• Documentos: Não consulta.
• Calculadora: Não utiliza.
• Busca Online: Não utiliza.
• Sistemas Externos: Não utiliza.

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 deve ser visível para o Agente de Geração de Relatório e Insights Financeiros (RF 4).

3.3.6 Regras de Orquestração e Transição

Ao concluir sua execução, esse agente aciona o Agente de Geração de Relatório e Insights Financeiros (RF 4).

Analisar os resultados consolidados e produzir um relatório em markdown com tendências, variações relevantes e insights acionáveis para decisão.

4.3.1 Especificação do Input

• Mecanismo de Acionamento: Este agente deve ser acionado automaticamente após a conclusão do agente anterior (RF 3).
• Tipo do input: JSON contendo série temporal de métricas por período e dimensões.
• Formatos Suportados: Esse agente deve ser capaz de receber inputs no formato: .json.
• Número de caracteres esperado: Este agente deve ter capacidade para processar um input de texto com até 6.000 caracteres.

4.3.2 Especificação do Output

• Formato de output: O output deve ser um relatório em markdown com a estrutura especificada, apresentando insights financeiros.
• Exemplo de Estrutura de Output:

   # Relatório de Desempenho Financeiro
  
  ## Resumo Executivo
  - Principais destaques (3–5 bullets)
  
  ## Contexto e Metodologia
  - Fontes, período analisado, granularidade e notas de qualidade
  
  ## Tendências Temporais
  - Receita, custo, lucro, margens: evolução e variações (MoM/YoY)
  
  ## Análise por Segmentos
  - Quebras por cliente/produto/região/moeda com top movimentos e outliers
  
  ## Insights Acionáveis
  - Recomendações objetivas (verbo no imperativo)
  
  ## Riscos e Limitações
  - Observações sobre lacunas, moedas não convertidas, dados ausentes
  
  ## Apêndice
  - Tabelas resumo e especificações de gráficos

• Número de caracteres esperado: O relatório gerado deve ter um tamanho estimado em torno de 4.500 caracteres.

4.3.3 Parâmetros de Geração

• Modelo: GPT-5
• Temperatura: 0.6

4.3.4 Ferramentas do Agente

• Documentos: Não consulta.
• Calculadora: Não utiliza.
• Busca Online: Não utiliza.
• Sistemas Externos: Não utiliza.

4.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.

4.3.6 Regras de Orquestração e Transição

A execução deste agente finaliza o fluxo. O relatório gerado é o resultado que deve ser disponibilizado ao usuário.