PrototipeAI | Agente de IA para Relatórios de Uso de Benefícios

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 um agente de IA voltado para a geração de relatórios sobre o uso de benefícios. 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 é ajudar os beneficiários a rastrear e planejar o uso de seus benefícios de forma eficaz, fornecendo relatórios detalhados e insights financeiros.

2. Contexto e Problema

Os beneficiários enfrentam dificuldade em rastrear o uso de seus benefícios ao longo do tempo, o que impede um planejamento financeiro eficaz. A falta de relatórios detalhados sobre o uso dos benefícios é um obstáculo significativo para uma gestão financeira adequada.

3. Impactos Esperados

A implementação deste agente de IA deve alcançar os seguintes resultados:

Facilitar o rastreamento do uso de benefícios pelos beneficiários.
Fornecer relatórios detalhados que auxiliem no planejamento financeiro.
Oferecer insights e dicas com base nos padrões de uso para melhorar a gestão dos benefícios.

4. Visão Geral da Solução

O agente de IA para relatórios de uso de benefícios gera relatórios detalhados sobre o uso dos benefícios, oferecendo insights e dicas para ajudar na gestão financeira dos beneficiários. A seguir são detalhadas todas as regras de negócio e especificações funcionais necessárias para que este agente atue como um assistente útil e autônomo na gestão e planejamento dos benefícios dos usuários.

A solução consiste em um fluxo de automação composto por dois agentes de IA. O processo inicia com a validação e normalização dos dados de uso de benefícios e culmina na geração de um relatório detalhado e acionável.

A execução dos agentes é sequencial, seguindo a ordem definida na tabela abaixo.

Agentes	Função Principal
`Agente de Validação e Normalização de Dados de Uso de Benefícios` (RF 1)	Padronizar e qualificar os dados de uso de benefícios antes da geração do relatório.
`Agente de Geração de Relatórios e Insights de Uso de Benefícios` (RF 2)	Produzir um relatório claro e acionável do uso de benefícios no período.

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 usuário receberá. Explore os links abaixo para entender melhor a solução em ação.

Ver Agente na Prototipe AI

6. Requisitos Funcionais

RF 1. Agente de Validação e Normalização de Dados de Uso de Benefícios

1.1 Tarefa do Agente

Padronizar e qualificar os dados de uso de benefícios antes da geração do relatório, assegurando consistência temporal, categorização e integridade mínima para análise.

1.2 Prompt ou Instruções do Agente

 # 1. Contexto e explicações sobre inputs iniciais
Você está recebendo um objeto JSON contendo dados de uso de benefícios dos beneficiários.

# 2. Objetivo
Padronizar e qualificar esses dados antes da geração do relatório, assegurando consistência temporal, categorização e integridade mínima para análise.

# 3. Regras que você deve seguir para gerar sua resposta
- Mapear categorias: se a categoria do lançamento não corresponder a uma categoria padrão, aplicar normalização por similaridade semântica.
- Data e período: derivar o mês de cada data; se a data estiver fora do período de referência, marcar inconsistências.
- Valores: converter todos os valores para valor monetário quando a unidade corresponder à moeda informada.
- Duplicidades: considerar duplicado quando existir o mesmo par (data, valor_num, categoria).
- Outliers: marcar outlier quando o valor_num for maior que 3x a mediana mensal da categoria.
- Status de lançamentos: incluir apenas status='aprovado' em agregações.
- Privacidade: não incluir PII além de beneficiario_id e nome_beneficiario já fornecidos.

# 4. Exemplo de Output que você deve produzir
{
  "periodo_normalizado": {"inicio": "2025-01", "fim": "2025-12", "meses_cobertos":["2025-01", "2025-02"]},
  "moeda": "BRL",
  "categorias_mapeadas":[{"categoria_padrao": "Saúde", "aliases":["Consulta médica"] }],
  "usos_normalizados":[{"data": "2025-01-15", "mes": "2025-01", "categoria_padrao": "Saúde", "valor_monetario": 100.0, "unidade": "R$", "status": "aprovado"}],
  "qualidade_dados":{"completude_mensal_por_categoria":[{"mes": "2025-01", "categoria": "Saúde", "possui_dados":true}]}
}

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 dos dados de uso de benefícios via API. Na fase de testes, os dados serão enviados manualmente por upload de um arquivo JSON na interface da Prototipe AI, para acelerar o processo de validação.
Tipo do input: O input inicial para o fluxo é um objeto JSON com dados de uso de benefícios.
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é 50.000 caracteres.

1.3.2 Especificação do Output

Formato de output: O output deve ser um objeto JSON normalizado que contém o período normalizado, moeda, categorias mapeadas, usos normalizados e qualidade dos dados.

Exemplo de Estrutura de Output:

 {
  "periodo_normalizado": {"inicio": "2025-01", "fim": "2025-12", "meses_cobertos":["2025-01", "2025-02"]},
  "moeda": "BRL",
  "categorias_mapeadas":[{"categoria_padrao": "Saúde", "aliases":["Consulta médica"] }],
  "usos_normalizados":[{"data": "2025-01-15", "mes": "2025-01", "categoria_padrao": "Saúde", "valor_monetario": 100.0, "unidade": "R$", "status": "aprovado"}],
  "qualidade_dados":{"completude_mensal_por_categoria":[{"mes": "2025-01", "categoria": "Saúde", "possui_dados":true}]}
}

Número de caracteres esperado: O JSON gerado será conciso e informativo, com um tamanho estimado em torno de 5.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 de Geração de Relatórios e Insights de Uso de Benefícios (RF 2).

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

Ao concluir sua execução, esse agente aciona o Agente de Geração de Relatórios e Insights de Uso de Benefícios (RF 2).

RF 2. Agente de Geração de Relatórios e Insights de Uso de Benefícios

2.1 Tarefa do Agente

Produzir um relatório claro e acionável do uso de benefícios no período, com KPIs, tendências, alertas de extrapolação/subutilização e recomendações práticas para planejamento.

2.2 Prompt ou Instruções do Agente

 # 1. Contexto e explicações sobre inputs iniciais
Você está recebendo um objeto JSON normalizado com dados de uso de benefícios.

# 2. Objetivo
Produzir um relatório claro e acionável do uso de benefícios no período, com KPIs, tendências, alertas de extrapolação/subutilização e recomendações práticas para planejamento.

# 3. Regras que você deve seguir para gerar sua resposta
- Cálculos de referência: utilizar somente lançamentos aprovados para cálculos.
- KPIs globais: calcular o gasto total do período e saldo estimado anual por categoria.
- Tendências: calcular a variação mês a mês e média móvel de 3 meses.
- Projeção: estimar o gasto anual se houver dados suficientes.
- Alertas: identificar riscos de estouro mensal e subutilização.
- Recomendações práticas: sugerir ações baseadas nos padrões de uso.
- Acessibilidade do texto: usar linguagem simples e valores monetários formatados.

# 4. Exemplo de Output que você deve produzir
**Resumo Executivo:**
- Período: Janeiro a Dezembro de 2025
- Moeda: BRL
- Gasto Total: R$ 12.345,67

**KPIs por Categoria:**
- Saúde: 75% de utilização
- Educação: 20% de utilização

**Tendências:**
- Variação Mês a Mês: +10%

**Alertas:**
- Risco de estouro mensal em Saúde

**Recomendações:**
- Considere ajustar o plano de Saúde se a tendência continuar.

**Anexos:**
- Metodologia
- Dados com pendências
- Outliers e Inconsistências

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: Este agente deve ser apto a receber como input um objeto JSON normalizado com dados de uso de benefícios.
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é 10.000 caracteres.

2.3.2 Especificação do Output

Formato de output: O output deve ser um relatório em texto estruturado (Markdown ou texto simples) com seções detalhadas sobre o uso de benefícios.