Agente de IA para Identificação de Necessidades Psicopedagógicas

30 de November de 2025 • Tempo de leitura: 5 min

Como criar um agente de IA que analisa dados comportamentais e acadêmicos para identificar alunos que possam precisar de apoio psicopedagógico adicional.

Biblioteca de Prompts e Agentes

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 para Identificação de Necessidades Psicopedagógicas, uma solução projetada para analisar dados comportamentais e acadêmicos de alunos. 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 é identificar precocemente alunos que necessitam de suporte psicopedagógico, integrando análises preditivas para sugerir intervenções adequadas e colaborar com educadores na implementação de estratégias de apoio personalizadas.

2. Contexto e Problema

Cenário Atual

As instituições de ensino enfrentam dificuldades em identificar alunos que necessitam de suporte psicopedagógico de forma precoce. A falta de integração entre dados comportamentais e acadêmicos impede uma análise completa das necessidades dos alunos, resultando em intervenções tardias ou inadequadas.


Problemas Identificados

  • Dificuldade de Identificação: A identificação precoce de alunos que necessitam de suporte psicopedagógico é um desafio constante.
  • Falta de Integração: Dados comportamentais e acadêmicos não são integrados de forma eficiente, prejudicando a análise completa das necessidades dos alunos.

3. Impactos Esperados

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

  • Identificação Precoce: Detectar alunos que necessitam de suporte psicopedagógico de forma precoce.
  • Análise Completa: Integrar dados comportamentais e acadêmicos para uma análise abrangente das necessidades dos alunos.
  • Intervenções Personalizadas: Sugerir intervenções adequadas e colaborar com educadores para implementar estratégias personalizadas de apoio.

4. Visão Geral da Solução

O agente de IA para identificação de necessidades psicopedagógicas analisa dados comportamentais e acadêmicos para identificar alunos que possam precisar de apoio adicional. 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 identificação e recomendação de intervenções psicopedagógicas.

A solução consiste em um fluxo de automação composto por 4 agentes de IA. O processo inicia com a preparação de dados e termina com a geração de relatórios executivos para educadores e coordenação.

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

Agentes Função Principal
Agente de Preparação de Script de Consolidação de Dados (Psicopedagógico) (RF 1) Receber planilhas/datasets acadêmicos e comportamentais, padronizar colunas e preparar um script de consolidação.
Agente de Execução de Chamada à API (RF 2) Realizar chamada à API do serviço 'python_runner' para executar o script de consolidação de dados e retornar o dataframe consolidado por aluno.
Agente de Análise de Risco Psicopedagógico e Recomendações (RF 3) Aplicar análise preditiva baseada em regras e tendências sobre o dataset consolidado para identificar alunos em risco e sugerir intervenções psicopedagógicas personalizadas.
Agente de Relatório para Educadores e Coordenação (RF 4) Gerar um relatório executivo em markdown por turma, sumarizando distribuição de risco, principais sinais e plano de ação recomendado para colaboração com educadores.

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.

Ver Agente na Prototipe AI

6. Requisitos Funcionais

RF 1. Agente de Preparação de Script de Consolidação de Dados (Psicopedagógico)

1.1 Tarefa do Agente

Receber planilhas/datasets acadêmicos e comportamentais, padronizar colunas e preparar um script de consolidação (limpeza, junção, criação de métricas e janelas temporais) para execução por serviço externo.

1.2 Prompt ou Instruções do Agente 
 # 1. Contexto e explicações sobre inputs iniciais
Você está recebendo planilhas ou datasets acadêmicos e comportamentais dos alunos. Estes dados incluem informações como notas, faltas, atrasos e ocorrências comportamentais.

# 2. Objetivo
Padronizar e consolidar esses dados para criar um script que será executado por um serviço externo, a fim de calcular métricas relevantes e identificar padrões de comportamento e desempenho.

# 3. Regras que você deve seguir para gerar sua resposta
- Converta todos os nomes de colunas para snake_case e aplique mapeamento de sinônimos.
- Converta 'data' para ISO-8601 (YYYY-MM-DD) e normalize formatos de dados.
- Remova duplicatas e trate valores ausentes de acordo com as regras especificadas.
- Calcule métricas como média de notas, tendência de notas, porcentagem de faltas, entre outras.
- Gere um script em Python que realize todas as transformações e cálculos necessários.

# 4. Exemplo de Output que você deve produzir
{"engine":"python_pandas","script":"# código em Python para:\n# 1) Normalizar esquema e tipos\n# 2) Tratar ausências e outliers leves\n# 3) Calcular janelas móveis 4, 8 e 12 semanas\n# 4) Gerar métricas por aluno e data de corte\n# 5) Emitir dataframe consolidado por aluno_id","inputs":[{"name":"dataset","format":"csv|xlsx|json","content_reference":"input_file_or_json"}],"parameters":{"janela_semanas":[4,8,12],"limiar_atraso_minutos":5,"timezone":"America/Sao_Paulo","campo_data":"data"}}
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 dados acadêmicos e comportamentais 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: O input inicial é um conjunto de dados em formatos CSV, XLSX ou JSON.
  • Formatos Suportados: Esse agente deve ser capaz de receber inputs nos formatos: .csv, .xlsx, .json.
  • Número de caracteres esperado: Este agente deve ter capacidade para processar um input de dados com até 150.000 caracteres.

1.3.2 Especificação do Output

  • Formato de output: O output deve ser um JSON contendo o script de consolidação de dados e as especificações para execução.
  • Exemplo de Estrutura de Output: 
     {"engine":"python_pandas","script":"# código em Python para:\n# 1) Normalizar esquema e tipos\n# 2) Tratar ausências e outliers leves\n# 3) Calcular janelas móveis 4, 8 e 12 semanas\n# 4) Gerar métricas por aluno e data de corte\n# 5) Emitir dataframe consolidado por aluno_id","inputs":[{"name":"dataset","format":"csv|xlsx|json","content_reference":"input_file_or_json"}],"parameters":{"janela_semanas":[4,8,12],"limiar_atraso_minutos":5,"timezone":"America/Sao_Paulo","campo_data":"data"}}
  • Número de caracteres esperado: O JSON gerado deve ter aproximadamente 2.000 caracteres.

1.3.3 Parâmetros de Geração

  • Modelo: GPT-5
  • Temperatura: 0.4

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 Chamada à API (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 Chamada à API (RF 2).

RF 2. Agente de Execução de Chamada à API

2.1 Tarefa do Agente

Realizar chamada à API do serviço 'python_runner' para executar o script de consolidação de dados e retornar o dataframe consolidado por aluno.

2.2 Prompt ou Instruções do Agente 
 # 1. Contexto e explicações sobre inputs iniciais
Você está recebendo um JSON contendo o script de consolidação de dados e as especificações para execução. Este script deve ser executado por um serviço externo para consolidar os dados acadêmicos e comportamentais dos alunos.

# 2. Objetivo
Enviar o payload para a API do serviço 'python_runner' e retornar o dataframe consolidado por aluno.

# 3. Regras que você deve seguir para gerar sua resposta
- Realize a chamada à API com o payload JSON recebido.
- O output deve ser um JSON contendo a chave 'consolidado' com a lista de alunos e suas métricas calculadas.

# 4. Exemplo de Output que você deve produzir
{"consolidado":[{"aluno_id":"A123","turma":"6A","media_notas":7.2,"tendencia_notas_8s":-0.15,"pct_faltas_4s":0.12,"taxa_atrasos_4s":0.8,"ocorrencias_graves_8s":2,"taxa_entrega_trabalhos_4s":0.6,"leitura_media_semana":1.2,"variacao_desempenho_ultimas_avaliacoes":1.1,"dispersao_desempenho":0.18,"referencia_tempo":"2025-11-30"}]}
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 JSON contendo o script de consolidação de dados e as especificações para 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 até 2.000 caracteres.

2.3.2 Especificação do Output

  • Formato de output: O output deve ser um JSON contendo a chave 'consolidado' com a lista de alunos e suas métricas calculadas.
  • Exemplo de Estrutura de Output: 
     {"consolidado":[{"aluno_id":"A123","turma":"6A","media_notas":7.2,"tendencia_notas_8s":-0.15,"pct_faltas_4s":0.12,"taxa_atrasos_4s":0.8,"ocorrencias_graves_8s":2,"taxa_entrega_trabalhos_4s":0.6,"leitura_media_semana":1.2,"variacao_desempenho_ultimas_avaliacoes":1.1,"dispersao_desempenho":0.18,"referencia_tempo":"2025-11-30"}]}
  • Número de caracteres esperado: O JSON gerado deve ter aproximadamente 1.500 caracteres.

2.3.3 Parâmetros de Geração

  • Modelo: Não se aplica (uso de ferramenta)
  • Temperatura: Não se aplica

2.3.4 Ferramentas do Agente

  • Documentos: Não consulta documentos externos.
  • Calculadora: Não utiliza.
  • Busca Online: Não utiliza.
  • Sistemas Externos: O agente deverá enviar o JSON recebido para a API externa ('python_runner') e retornar o dataframe consolidado.

2.3.5 Memória

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

Ao concluir sua execução, esse agente aciona o Agente de Análise de Risco Psicopedagógico e Recomendações (RF 3).

RF 3. Agente de Análise de Risco Psicopedagógico e Recomendações

3.1 Tarefa do Agente

Aplicar análise preditiva baseada em regras e tendências sobre o dataset consolidado para identificar alunos em risco e sugerir intervenções psicopedagógicas personalizadas.

3.2 Prompt ou Instruções do Agente 
 # 1. Contexto e explicações sobre inputs iniciais
Você está recebendo um JSON com a lista de alunos e suas métricas calculadas a partir dos dados acadêmicos e comportamentais.

# 2. Objetivo
Aplicar análise preditiva para identificar alunos em risco e sugerir intervenções psicopedagógicas personalizadas.

# 3. Regras que você deve seguir para gerar sua resposta
- Considere simultaneamente desempenho, assiduidade, comportamento e engajamento dos alunos.
- Calcule o risk_score e classifique o nível de risco (alto, moderado, baixo).
- Sugira intervenções personalizadas para cada aluno identificado em risco.

# 4. Exemplo de Output que você deve produzir
{"alunos":[{"aluno_id":"A123","turma":"6A","risk_score":0.82,"risk_level":"alto","confidence_score":0.78,"indicadores_acionados":["queda_continua_notas","faltas_altas","ocorrencias_graves"],"racional":"Notas caíram nas últimas 8 semanas (inclinação -0,15 p/semana), faltas 12% em 4 semanas e 2 ocorrências de gravidade média/alta.","recomendacoes":[{"tipo":"apoio_academico","acao":"reforço em matemática 2x/semana","responsavel":"prof_matematica","inicio_em":"2025-12-02","duracao_semanas":8},{"tipo":"socioemocional","acao":"sessões psicopedagógicas de autorregulação 1x/semana","responsavel":"psicopedagogo","inicio_em":"2025-12-03","duracao_semanas":8}],"plano_monitoramento":{"frequencia":"quinzenal","metricas":["tendencia_notas_8s","pct_faltas_4s","taxa_entrega_trabalhos_4s"],"metas":{"pct_faltas_4s":"<0.05","taxa_entrega_trabalhos_4s":">=0.85"},"criterio_alta":"risk_score < 0.35 por 6 semanas"}}],"metadados":{"referencia_tempo":"2025-11-30","versao_regra":"v2"}}
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: Este agente deve ser apto a receber como input um JSON contendo a lista de alunos e suas métricas calculadas.
  • 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 até 3.000 caracteres.

3.3.2 Especificação do Output

  • Formato de output: O output deve ser um JSON contendo a análise de risco e as recomendações psicopedagógicas para cada aluno.
  • Exemplo de Estrutura de Output: 
     {"alunos":[{"aluno_id":"A123","turma":"6A","risk_score":0.82,"risk_level":"alto","confidence_score":0.78,"indicadores_acionados":["queda_continua_notas","faltas_altas","ocorrencias_graves"],"racional":"Notas caíram nas últimas 8 semanas (inclinação -0,15 p/semana), faltas 12% em 4 semanas e 2 ocorrências de gravidade média/alta.","recomendacoes":[{"tipo":"apoio_academico","acao":"reforço em matemática 2x/semana","responsavel":"prof_matematica","inicio_em":"2025-12-02","duracao_semanas":8},{"tipo":"socioemocional","acao":"sessões psicopedagógicas de autorregulação 1x/semana","responsavel":"psicopedagogo","inicio_em":"2025-12-03","duracao_semanas":8}],"plano_monitoramento":{"frequencia":"quinzenal","metricas":["tendencia_notas_8s","pct_faltas_4s","taxa_entrega_trabalhos_4s"],"metas":{"pct_faltas_4s":"<0.05","taxa_entrega_trabalhos_4s":">=0.85"},"criterio_alta":"risk_score < 0.35 por 6 semanas"}}],"metadados":{"referencia_tempo":"2025-11-30","versao_regra":"v2"}}
  • Número de caracteres esperado: O JSON gerado deve ter aproximadamente 3.500 caracteres.

3.3.3 Parâmetros de Geração

  • Modelo: GPT-5
  • Temperatura: 0.5

3.3.4 Ferramentas do Agente

  • Documentos: Não consulta documentos externos.
  • Calculadora: Utiliza lógica interna para calcular o risk_score e confidence_score.
  • Busca Online: Não utiliza.
  • Sistemas Externos: Não utiliza.

3.3.5 Memória

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

Ao concluir sua execução, esse agente aciona o Agente de Relatório para Educadores e Coordenação (RF 4).

RF 4. Agente de Relatório para Educadores e Coordenação

4.1 Tarefa do Agente

Gerar um relatório executivo em markdown por turma, sumarizando distribuição de risco, principais sinais e plano de ação recomendado para colaboração com educadores.

4.2 Prompt ou Instruções do Agente 
 # 1. Contexto e explicações sobre inputs iniciais
Você está recebendo um JSON com a análise de risco psicopedagógico e recomendações para os alunos.

# 2. Objetivo
Gerar um relatório executivo em markdown que resume a distribuição de risco, principais sinais e plano de ação recomendado para cada turma.

# 3. Regras que você deve seguir para gerar sua resposta
- Separe relatórios por turma e calcule KPIs como contagem e porcentagem por nível de risco.
- Liste os sinais mais frequentes e sugira ações coletivas correspondentes.
- Formate o relatório em markdown simples, pronto para exportação em PDF.

# 4. Exemplo de Output que você deve produzir
### Relatório Executivo - Turma 6A - 30/11/2025

#### Sumário de Risco
- **Alto:** 5 alunos (25%)
- **Moderado:** 10 alunos (50%)
- **Baixo:** 5 alunos (25%)

#### Principais Sinais
- Queda contínua de notas
- Faltas altas
- Ocorrências graves

#### Plano de Ação Recomendado
- Reforço em matemática 2x/semana
- Sessões psicopedagógicas semanais
- Oficina de planejamento de estudos

#### Próximos Passos
- Monitoramento quinzenal
- Próxima revisão: 14/12/2025
4.3 Configurações do Agente

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: Este agente deve ser apto a receber como input um JSON contendo a análise de risco psicopedagógico e recomendações para os alunos.
  • 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 até 3.500 caracteres.

4.3.2 Especificação do Output

  • Formato de output: O output deve ser um documento em markdown, pronto para exportação em PDF, que resume a distribuição de risco, principais sinais e plano de ação recomendado para cada turma.
  • Exemplo de Estrutura de Output: 
     ### Relatório Executivo - Turma 6A - 30/11/2025

#### Sumário de Risco
- **Alto:** 5 alunos (25%)
- **Moderado:** 10 alunos (50%)
- **Baixo:** 5 alunos (25%)

#### Principais Sinais
- Queda contínua de notas
- Faltas altas
- Ocorrências graves

#### Plano de Ação Recomendado
- Reforço em matemática 2x/semana
- Sessões psicopedagógicas semanais
- Oficina de planejamento de estudos

#### Próximos Passos
- Monitoramento quinzenal
- Próxima revisão: 14/12/2025
  • Número de caracteres esperado: O documento em markdown deve ter aproximadamente 2.500 caracteres.

4.3.3 Parâmetros de Geração

  • Modelo: GPT-5
  • Temperatura: 0.4

4.3.4 Ferramentas do Agente

  • Documentos: Não consulta documentos externos.
  • 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 resultado final e deve ser disponibilizada para os educadores e coordenação.

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 aos educadores e coordenação.

Posts Relacionados

© 2025 prototipe.ai. Todos os direitos reservados.