1. Propósito e Escopo
Este documento define todos os prompts, configurações de memória, transição entre estados, consulta a documentos e demais requisitos funcionais para o Agente de IA para Monitoramento de Bem-Estar Estudantil. 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 é analisar feedbacks de estudantes sobre seu bem-estar emocional e gerar relatórios detalhados para psicólogos escolares, auxiliando na identificação de necessidades emocionais e intervenções adequadas.
2. Contexto e Problema
Problemas Identificados
O bem-estar emocional dos estudantes é um aspecto crítico que precisa ser monitorado para garantir um ambiente escolar saudável. Atualmente, as escolas enfrentam desafios em:
- Monitorar continuamente o bem-estar emocional dos estudantes.
- Gerar relatórios que auxiliem na identificação de necessidades emocionais específicas.
O processo manual de monitoramento é demorado e pode não capturar todas as nuances dos feedbacks dos estudantes. A falta de padronização nos relatórios e a dificuldade em identificar sinais de alerta são problemas recorrentes.
3. Impactos Esperados
A implementação deste agente de IA visa alcançar os seguintes resultados:
- Melhorar a precisão e a regularidade no monitoramento do bem-estar emocional dos estudantes.
- Aumentar a eficiência na geração de relatórios para psicólogos escolares.
- Identificar rapidamente áreas de atenção e possíveis intervenções.
4. Visão Geral da Solução
O agente de IA para monitoramento de bem-estar estudantil processa feedbacks de estudantes, aplica regras de análise emocional e gera relatórios para psicólogos escolares. 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 análise do bem-estar emocional dos estudantes.
A solução consiste em um fluxo de automação composto por 2 agentes de IA. O processo inicia com a preparação e normalização dos feedbacks dos estudantes e termina com a geração de um relatório clínico utilizável por psicólogos escolares.
A execução dos agentes é sequencial e linear, seguindo a ordem definida na tabela abaixo.
| Agentes | Função Principal |
|---|---|
Agente de Preparação e Normalização de Feedbacks (RF 1)
| Padronizar, anonimizar e preparar feedbacks estudantis para análise de bem-estar emocional. |
Agente de Análise de Bem-Estar e Geração de Relatório Clínico (RF 2)
| Analisar feedbacks preparados para identificar estados emocionais, riscos e recomendações, produzindo relatório utilizável por psicólogos escolares. |
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 psicólogo escolar receberá. Explore os links abaixo para entender melhor a solução em ação.
6. Requisitos Funcionais
RF 1. Agente de Preparação e Normalização de Feedbacks
1.1 Tarefa do Agente
Padronizar, anonimizar e preparar feedbacks estudantis para análise de bem-estar emocional.
1.2 Prompt ou Instruções do Agente
# 1. Contexto e explicações sobre inputs iniciais Você está recebendo um array de objetos com feedbacks textuais dos estudantes. Este array contém informações sobre o bem-estar emocional dos estudantes coletadas através de diferentes canais. # 2. Objetivo Padronizar, anonimizar e preparar feedbacks estudantis para análise de bem-estar emocional. # 3. Regras que você deve seguir para gerar sua resposta - Gerar `feedback_id` único e determinístico por item: se existir `id_original`, defina `feedback_id` = hash( id_original + ts_normalizado ); caso contrário, hash( texto + timestamp ). Use hash consistente (ex.: SHA-256 truncado em 16 chars). - Normalizar timestamp: converter timestamp para ISO-8601 (UTC) em `ts_iso`; se ausente, registrar `ts_iso` como '1970-01-01T00:00:00Z' e marcar no campo `motivos_alerta_normalizacao` (interno) = 'sem_timestamp'. - Detectar idioma do texto; definir idioma em código ISO (pt, en, es...). Se idioma não for detectável, definir 'und'. - Higienização textual: remover espaços duplicados, quebras excessivas, HTML, emojis não essenciais e assinaturas; preservar citações relevantes entre aspas. - Anonimização PII: substituir nomes próprios, telefones, e-mails, RG/CPF, endereços e perfis/redes por placeholders [NOME], [TELEFONE], [EMAIL], [DOC], [ENDERECO], [HANDLE]; definir `pii_removida`=true se qualquer substituição ocorrer. - Limitar extensão: se texto > 3000 caracteres, truncar preservando frases completas até o limite e adicionar o sufixo '… [TRUNCADO]'. Registrar caracteres e `tokens_aprox` (estimativa 1 token ≈ 4 chars). - Descartar entradas inválidas: se texto vazio após limpeza ou com menos de 10 caracteres significativos, excluir do output. Não gerar objeto para entradas descartadas. - Canal: padronizar valor para minúsculas sem acentos (ex.: 'app', 'email', 'formulario', 'chat'); se desconhecido, definir null. - `student_ref_hash`: se houver `student_id`, gerar hash determinístico truncado 16 chars; caso contrário, null. - Deduplicação: se houver duplicatas com similaridade semântica muito alta (>=0,85) e mesmo `student_ref_hash` e `ts_iso` ± 24h, manter apenas a primeira ocorrência (ordem por `ts_iso` crescente) e descartar as demais. - Saída estritamente no formato especificado sem comentários fora dos campos e sem markdown.
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 feedbacks estudantis via API. Na fase de testes, o fluxo será iniciado pelo envio manual dos dados, que serão enviados para o agente diretamente por upload de um arquivo na interface da Prototipe AI, para acelerar o processo de validação.
- Tipo do input: O input inicial para o fluxo é um array de objetos com feedbacks textuais dos estudantes.
- 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é 90.000 caracteres.
1.3.2 Especificação do Output
- Formato de output: O output deve ser um array normalizado pronto para análise.
-
Exemplo de Estrutura de Output:
[{ "feedback_id": "abc123", "student_ref_hash": "def456", "ts_iso": "2025-12-03T06:22:00Z", "canal": "email", "idioma": "pt", "texto_limpo": "Texto do feedback limpo e anonimizado.", "pii_removida": true, "caracteres": 200, "tokens_aprox": 50, "id_original": "789" }] - Número de caracteres esperado: O array final deve ser conciso e informativo, com um tamanho estimado em torno de 4.500 caracteres, podendo variar conforme a quantidade de feedbacks processados.
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 Análise de Bem-Estar e Geração de Relatório Clínico (RF 2).
1.3.6 Regras de Orquestração e Transição
Ao concluir sua execução, esse agente aciona o Agente de Análise de Bem-Estar e Geração de Relatório Clínico (RF 2).
RF 2. Agente de Análise de Bem-Estar e Geração de Relatório Clínico
2.1 Tarefa do Agente
Analisar feedbacks preparados para identificar estados emocionais, riscos e recomendações, produzindo relatório utilizável por psicólogos escolares.
2.2 Prompt ou Instruções do Agente
# 1. Contexto e explicações sobre inputs iniciais
Você está recebendo o output do Agente de Preparação e Normalização de Feedbacks (array normalizado) e, opcionalmente, parâmetros de contexto {janela_dias: number (padrão 30), limiares: {risco_critico: number, risco_alto: number, risco_moderado: number}}.
# 2. Objetivo
Analisar feedbacks preparados para identificar estados emocionais, riscos e recomendações, produzindo relatório utilizável por psicólogos escolares.
# 3. Regras que você deve seguir para gerar sua resposta
- Janela temporal: se houver `ts_iso` nos itens, definir `periodo_analisado` do feedback mais antigo ao mais recente recebidos e aplicar `janela_dias` se fornecida; se não, considerar todos.
- Sentimento: classificar cada feedback em negativo, neutro ou positivo; calcular `distribuicao_sentimento` em porcentagem com duas casas decimais.
- Escore de bem-estar: converter sentimento e intensidade para escala 0-100 (negativo=0-40, neutro=41-60, positivo=61-100); `escore_bem_estar_medio` é a média ponderada pelo comprimento do texto (caracteres).
- Taxonomia de emoções: usar conjunto fechado {tristeza, ansiedade, estresse, raiva, culpa, vergonha, alegria, esperança, tédio, solidão}; retornar `top_emocoes` com no máximo 5 itens, cada um com `incidencia_pct`.
- Temas recorrentes: usar taxonomia {provas, notas, carga_horaria, desempenho, bullying, amigos, professores, familia, sono, alimentacao, saude_mental, autoimagem, financas, transporte, seguranca, tecnologia/redes}; no máximo 7 temas.
- Sinais de alerta e severidade: rotular um item como sinal de alerta se houver menções explícitas ou fortes indícios. Severidade:
- critico: menções diretas a ideação suicida ('quero morrer', 'tirar minha vida'), plano, automutilação recente, abuso/violência em curso.
- alto: relatos persistentes de bullying com medo, insônia severa, uso de substâncias com prejuízo, ameaças.
- moderado: tristeza/ansiedade intensa com impacto funcional (faltas, notas caindo) sem menções letais.
- baixo: preocupações pontuais sem impacto claro.
Para cada `sinal_alerta`, incluir `evidencia_textual` literal (trecho curto do `texto_limpo`) e `confianca` (0-1) compatível com a clareza do indício.
- Estudantes em risco: agrupar por `student_ref_hash` quando disponível; `maior_severidade` é o maior nível detectado no período; definir `recomendacao_prioridade`: '24h' para critico, '72h' para alto, 'monitorar' para moderado.
- Recomendações clínicas: gerar ações concretas e proporcionais ao risco. Exemplos de `nivel_escola`: 'ajuste de carga de tarefas', 'mediação de conflito', 'flexibilização de prazos'. `Nivel_psicologo`: 'triagem breve', 'sessão individual focal', 'check-in semanal'. `Encaminhamento_externo`=true somente para severidades 'alto' ou 'critico' com indícios de risco à integridade.
- Indicadores de acompanhamento: propor de 3 a 5 itens mensuráveis (ex.: 'redução de auto-relatos de insônia', 'ausências por motivo emocional'); `prazo_revisao_dias` entre 14 e 30.
- Prontidão para acionar humano: `ativar`=true se houver qualquer severidade 'alto' ou 'critico' ou se `escore_bem_estar_medio` < 45; `motivo` deve citar quantos casos e tipos.
- Resumo e sumário: escrever em português claro e objetivo, sem jargões clínicos excessivos, evitando diagnósticos formais; incluir incertezas quando aplicável.
- Confiabilidade: não inferir fatos fora do texto; não criar dados de identificação; se muitos itens forem 'und' em idioma, mencionar essa limitação no `resumo_geral`.
- Deduplicação adicional: se múltiplos `sinais_alerta` referirem-se ao mesmo `feedback_id`, manter apenas o de maior severidade.
- Saída deve ser estritamente no JSON especificado; além disso, preencher `sumario_para_psicologos` com um parágrafo curto (máx. 800 caracteres) destacando áreas de atenção e próximas ações.
- Não utilizar linguagem de diagnóstico (ex.: 'depressão', 'transtorno'); preferir 'sinais de...', 'relatos de...'. 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 o output do Agente de Preparação e Normalização de Feedbacks (array normalizado) e, opcionalmente, parâmetros de contexto.
- 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é 90.000 caracteres.
2.3.2 Especificação do Output
- Formato de output: O output deve ser um JSON estruturado de relatório clínico e sumário textual curto.
-
Exemplo de Estrutura de Output:
{ "resumo_geral": "O bem-estar emocional dos estudantes foi monitorado durante o período analisado, identificando áreas de risco e propondo intervenções.", "periodo_analisado": { "inicio_iso": "2025-11-01T00:00:00Z", "fim_iso": "2025-12-01T23:59:59Z" }, "volume_feedbacks": 100, "distribuicao_sentimento": { "negativo": 25.00, "neutro": 50.00, "positivo": 25.00 }, "escore_bem_estar_medio": 55.00, "top_emocoes": [ {"emocao": "ansiedade", "incidencia_pct": 30.00}, {"emocao": "alegria", "incidencia_pct": 20.00} ], "temas_recorrentes": [ {"tema": "provas", "incidencia_pct": 40.00}, {"tema": "bullying", "incidencia_pct": 20.00} ], "sinais_alerta": [ {"feedback_id": "abc123", "student_ref_hash": "def456", "severidade": "alto", "tipo": "bullying", "evidencia_textual": "Relato de bullying constante.", "confianca": 0.85} ], "estudantes_em_risco": [ {"student_ref_hash": "def456", "maior_severidade": "alto", "motivos_chave": ["bullying"], "recomendacao_prioridade": "72h"} ], "recomendacoes_clinicas": { "nivel_escola": ["mediação de conflito"], "nivel_psicologo": ["sessão individual focal"], "encaminhamento_externo": false, "observacoes": "Monitorar caso de bullying identificado." }, "indicadores_acompanhamento": { "itens": ["redução de auto-relatos de insônia"], "prazo_revisao_dias": 30 }, "prontidao_para_acionamento_humano": { "ativar": true, "motivo": "1 caso de alta severidade identificado." }, "sumario_para_psicologos": "Recomenda-se atenção ao aumento de relatos de bullying e ansiedade. Ações de mediação e sessões focais são sugeridas." } - Número de caracteres esperado: O JSON final deve ser claro e direto, com um tamanho estimado em 8.000 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 calcular distribuições e escores.
- 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.
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 psicólogo escolar.