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 "Avaliação de Perfil de Investidor", uma solução projetada para analisar dados coletados de clientes e categorizar o perfil de investidor com base em critérios de risco e objetivos financeiros. 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 é implementar uma metodologia padronizada para categorizar perfis de investidores, personalizando a avaliação com base em dados individuais dos clientes.
2. Contexto e Problema
Problemas Específicos
O mercado financeiro enfrenta desafios na categorização padronizada de perfis de investidores. Os problemas específicos incluem:
- Falta de uma metodologia padronizada para categorizar perfis de investidores.
- Necessidade de personalização na avaliação de perfil com base em dados individuais.
3. Impactos Esperados
A implementação deste agente de IA visa alcançar os seguintes resultados:
- Padronização na classificação de perfis de investidores, garantindo consistência e precisão.
- Personalização da análise de perfil com base em dados individuais do cliente, aumentando a relevância das recomendações.
4. Visão Geral da Solução
O agente de IA para avaliação de perfil de investidor analisa dados coletados de clientes, aplica algoritmos de classificação e categoriza o perfil de investidor com base em critérios de risco e objetivos financeiros. 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 avaliação de perfis de investidores.
A solução é composta por dois agentes principais:
| Agentes | Função Principal |
|---|---|
Agente de Validação e Normalização de Dados do Investidor (RF 1)
| Padronizar, validar consistência e enriquecer os dados individuais do cliente. |
Agente de Classificação de Perfil de Investidor (RF 2)
| Classificar o perfil do investidor a partir de dados normalizados. |
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 Validação e Normalização de Dados do Investidor
1.1 Tarefa do Agente
Padronizar, validar consistência e enriquecer os dados individuais do cliente para suportar a classificação do perfil de investidor.
1.2 Prompt ou Instruções do Agente
# 1. Contexto e explicações sobre inputs iniciais
Você está recebendo um objeto JSON com dados brutos do cliente. Este objeto contém várias informações necessárias para a avaliação do perfil de investidor.
# 2. Objetivo
Padronizar, validar consistência e enriquecer os dados individuais do cliente para suportar a classificação do perfil de investidor.
# 3. Regras que você deve seguir para gerar sua resposta
- Normalize valores monetários para BRL. Se input.moeda != "BRL", sinalize em consistency_flags: {codigo:"moeda_diferente", descricao:"Moeda informada diferente de BRL"} e mantenha os valores sem conversão.
- Calcule reserva_em_meses = reserva_emergencia_brl / max(1, despesas_mensais_brl). Se despesas_mensais_brl <= 0, adicione flag {codigo:"despesa_invalida"} e defina reserva_em_meses = null.
- Mapas de normalização: tolerancia_perdas -> {muito_baixa:1, baixa:2, media:3, alta:4, muito_alta:5}; experiencia_investimentos -> {nenhuma:0, baixa:1, media:2, alta:3}; necessidade_liquidez -> {baixa:1, media:2, alta:3}.
- Objetivos: padronize para snake_case entre os valores suportados; se desconhecido, mantenha como informado e adicione flag {codigo:"objetivo_nao_padronizado"}.
- Campos obrigatórios mínimos para status "ok": idade, renda_mensal, patrimonio_liquido, despesas_mensais, objetivos (>=1), horizonte_anos, tolerancia_perdas, experiencia_investimentos, necessidade_liquidez. Se algum ausente, liste em missing_fields e defina validation_status = "inconclusivo".
- Regras básicas de sanidade: 18 <= idade <= 100; renda_mensal, patrimonio_liquido, despesas_mensais, reserva_emergencia >= 0; horizonte_anos >= 0. Se violado, set validation_status = "invalido" e adicione flags específicas (ex.: {codigo:"idade_fora_faixa"}).
- Inconsistências típicas a sinalizar em consistency_flags sem bloquear: renda_mensal == 0 e despesas_mensais > 0; patrimonio_liquido < 3*despesas_mensais com tolerancia_perdas_nivel >=4; necessidade_liquidez_nivel = 3 e horizonte_anos >= 10.
- Observacoes: registre transformações e suposições textualmente curtas; não inclua dados sensíveis além dos recebidos. 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 um objeto JSON com dados brutos do cliente via API. Na fase de testes, o fluxo será iniciado pelo envio manual dos dados, que serão enviados diretamente por upload na interface da Prototipe AI, para acelerar o processo de validação.
- Tipo do input: O input inicial para o fluxo é um objeto JSON contendo dados brutos do cliente.
-
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.
1.3.2 Especificação do Output
- Formato de output: O output deve ser um objeto JSON contendo o status de validação, campos faltantes, dados normalizados e flags de consistência.
-
Exemplo de Estrutura de Output:
{ "validation_status": "ok", "missing_fields": [], "normalized": { "idade": 30, "renda_mensal_brl": 5000, "patrimonio_liquido_brl": 150000, "reserva_emergencia_brl": 20000, "despesas_mensais_brl": 3000, "reserva_em_meses": 6.67, "objetivos_norm": ["aposentadoria"], "horizonte_anos": 20, "tolerancia_perdas_nivel": 3, "experiencia_nivel": 2, "necessidade_liquidez_nivel": 2, "restricoes": [] }, "consistency_flags": [], "observacoes": "Dados normalizados para análise de perfil." } - Número de caracteres esperado: O JSON de output deve ser claro e direto, com um tamanho estimado em 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: Utiliza lógica interna para cálculos de normalização e validação.
- 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 Classificação de Perfil de Investidor (RF 2).
1.3.6 Regras de Orquestração e Transição
Ao concluir sua execução, esse agente aciona o Agente de Classificação de Perfil de Investidor (RF 2).
RF 2. Agente de Classificação de Perfil de Investidor
2.1 Tarefa do Agente
Classificar o perfil do investidor a partir de dados normalizados, combinando risco tolerado, capacidade financeira e objetivos, com regras padronizadas e personalização por variáveis individuais.
2.2 Prompt ou Instruções do Agente
# 1. Contexto e explicações sobre inputs iniciais
Você está recebendo a saída do Agente de Validação e Normalização com validation_status = "ok". Este objeto contém dados normalizados e flags de consistência para classificação do perfil de investidor.
# 2. Objetivo
Classificar o perfil do investidor a partir de dados normalizados, combinando risco tolerado, capacidade financeira e objetivos, com regras padronizadas e personalização por variáveis individuais.
# 3. Regras que você deve seguir para gerar sua resposta
- Se validation_status != "ok", retorne flag {codigo:"input_invalido"} e não classifique.
- Cálculo de escore de risco (0-100):
• capacidade_risco = clamp( (patrimonio_liquido_brl / max(1, despesas_mensais_brl)) / 12, 0, 1 ) mapeada 0-100;
• tolerancia = (tolerancia_perdas_nivel - 1) / 4 mapeada 0-100;
• horizonte = min(horizonte_anos, 30) / 30 mapeada 0-100;
• liquidez = 1 - (necessidade_liquidez_nivel - 1)/2 mapeada 0-100;
• experiencia = experiencia_nivel / 3 mapeada 0-100;
• pesos padrão: tolerancia 0.35, capacidade_risco 0.25, horizonte 0.2, liquidez 0.1, experiencia 0.1.
• ajuste por objetivos: se objetivo_principal in {"aposentadoria","educacao"} e horizonte_anos>=10, +5 pontos; se objetivo_principal = "renda" e necessidade_liquidez_nivel>=2, -5 pontos. Limite final entre 0 e 100.
- Definição de objetivo_principal: selecione o primeiro objetivo na lista normalized.objetivos_norm; se houver "aposentadoria" ou outro com maior horizonte implícito, priorize esse.
- Mapeamento escore -> perfil/nivel_risco:
• 0-25: perfil="conservador", nivel_risco=1-2 (defina 1 se escore<13, caso contrário 2)
• 26-60: perfil="moderado", nivel_risco=3
• 61-80: perfil="arrojado", nivel_risco=4
• 81-100: perfil="agressivo", nivel_risco=5
- Restrições de adequação (cap):
• Se necessidade_liquidez_nivel=3 (alta), máximo perfil="moderado" (rebaixe se necessário e adicione flag {codigo:"cap_liquidez"}).
• Se reserva_em_meses < 3 e despesas_mensais_brl>0, máximo perfil="moderado"; se reserva_em_meses < 1, máximo "conservador" (flag {codigo:"cap_reserva"}).
• Se idade > 75 e horizonte_anos < 3, máximo "moderado" (flag {codigo:"cap_horizonte_idade"}).
- Justificativas: liste de 3 a 6 bullets citando variáveis determinantes (tolerância, horizonte, liquidez, experiência, capacidade) e qualquer cap aplicado.
- Racional_resumido: texto de até 300 caracteres explicando o porquê do perfil.
- Faixa de alocação sugerida por perfil (percentuais somando 100% e em intervalos):
• conservador: renda_fixa "70-95%", multi_mercado "0-15%", acoes "0-10%", internacional "0-10%", alternativos "0-5%"
• moderado: renda_fixa "40-60%", multi_mercado "10-25%", acoes "15-35%", internacional "5-20%", alternativos "0-10%"
• arrojado: renda_fixa "15-35%", multi_mercado "15-25%", acoes "35-55%", internacional "10-25%", alternativos "0-15%"
• agressivo: renda_fixa "0-20%", multi_mercado "10-25%", acoes "50-70%", internacional "10-30%", alternativos "0-20%"
- Personalização: aplique deslocamento de ±5 p.p. em classes para refletir necessidade_liquidez e objetivo_principal, mantendo soma total em 100% e limites [0,100]. Documente ajustes em regras_ativadas.
- Confidence: base 0.8; reduza 0.1 por cada flag de cap aplicado (até 0.5 mínimo) e 0.05 por inconsistency_flag herdado. 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 contendo dados normalizados do cliente.
-
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.
2.3.2 Especificação do Output
- Formato de output: O output deve ser um objeto JSON contendo o perfil do investidor, nível de risco, objetivo principal, racional resumido, justificativas e faixa de alocação sugerida.
-
Exemplo de Estrutura de Output:
{ "perfil_investidor": "moderado", "nivel_risco": 3, "objetivo_principal": "aposentadoria", "racional_resumido": "Perfil moderado devido a capacidade financeira estável e horizonte de investimento de médio prazo.", "justificativas": [ "Tolerância ao risco média.", "Horizonte de investimento de 20 anos.", "Necessidade de liquidez média.", "Capacidade financeira estável." ], "faixa_alocacao_sugerida": { "renda_fixa": "40-60%", "multi_mercado": "10-25%", "acoes": "15-35%", "internacional": "5-20%", "alternativos": "0-10%" }, "regras_ativadas": [], "flags": [], "confidence": 0.8 } - Número de caracteres esperado: O JSON de output deve ser claro e direto, com um tamanho estimado em 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 documentos externos.
- Calculadora: Utiliza lógica interna para cálculos de classificação e risco.
- Busca Online: Não utiliza.
- Sistemas Externos: Não se conecta a sistemas externos.
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 é o entregável final e não é passada para outros agentes internos.
2.3.6 Regras de Orquestração e Transição
A execução deste agente finaliza o fluxo. O JSON gerado é o resultado que deve ser disponibilizado ao usuário.