Agente de IA para Criação de Relatórios de Progresso Estudantil

14 de December de 2025 • Tempo de leitura: 5 min

Como criar um agente de IA que gera relatórios detalhados sobre o progresso dos alunos.

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 Fluxo de Agentes "Criação de Relatórios de Progresso Estudantil", uma solução de automação projetada para gerar relatórios detalhados sobre o progresso dos alunos, baseando-se em dados de desempenho e participação. Essa documentação é um modelo de PRD ou Documento de Requisitos de Produto específico para construção de Agentes de IA.

O objetivo principal é transformar dados brutos de desempenho e participação em relatórios personalizados que forneçam uma visão clara e acionável do progresso dos alunos, apoiando os professores no acompanhamento e intervenção educacional.

2. Contexto e Problema

Cenário Atual

Os professores enfrentam desafios significativos ao tentar compilar e analisar dados de desempenho e participação dos alunos de forma eficiente. Atualmente, a criação de relatórios personalizados para cada aluno é uma tarefa que demanda muito tempo e esforço, muitas vezes resultando em informações incompletas ou atrasadas.


Problemas Identificados

  • Dificuldade de Compilação: Compilar dados de várias fontes e formatos é um processo complexo e propenso a erros.
  • Falta de Relatórios Detalhados: A ausência de relatórios completos e integrados dificulta a identificação de áreas de melhoria e o reconhecimento de progressos significativos.
  • Limitações de Tempo: Professores têm pouco tempo disponível para criar e personalizar relatórios, impactando a qualidade do acompanhamento estudantil.

3. Impactos Esperados

A implementação deste fluxo de automação visa alcançar os seguintes resultados:

  • Reduzir o tempo de criação de relatórios em pelo menos 75%.
  • Proporcionar uma visão clara e detalhada do progresso de cada aluno, facilitando intervenções educacionais.
  • Personalizar relatórios de acordo com as necessidades e objetivos de cada aluno.
  • Fornecer insights acionáveis que ajudem os professores a apoiar melhor o progresso dos alunos.

4. Visão Geral da Solução

O agente de IA para criação de relatórios de progresso estudantil processa dados de desempenho e participação dos alunos, personaliza relatórios conforme as necessidades individuais e fornece insights acionáveis para os professores. 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 geração de relatórios que apoiam o progresso educacional.

A solução consiste em um fluxo de automação composto por 4 agentes de IA. O processo inicia com a consolidação dos dados brutos dos alunos e termina com a geração de relatórios de progresso completos e personalizados.

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

Agentes Função Principal
Agente de Consolidação e Validação de Dados do Aluno (RF 1) Receber os dados brutos e entregar um dataset único e validado por aluno e por período.
Agente de Cálculo de Métricas e Benchmarks (RF 2) Calcular métricas de desempenho, participação e comparativos por aluno.
Agente de Insights e Recomendações Personalizadas (RF 3) Gerar insights acionáveis e recomendações alinhadas aos objetivos de aprendizagem.
Agente Montador de Relatório de Progresso (RF 4) Organizar o relatório final por aluno, combinando métricas, insights e benchmarks.

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 Consolidação e Validação de Dados do Aluno

1.1 Tarefa do Agente

Receber os dados brutos de desempenho e participação e entregar um dataset único, coerente e validado por aluno e por período.

1.2 Prompt ou Instruções do Agente 
 # 1. Contexto e explicações sobre inputs iniciais
Você está recebendo dados brutos de desempenho e participação dos alunos. Estes dados incluem avaliações, frequência e participação em atividades.

# 2. Objetivo
Consolidar e validar os dados para entregar um dataset único e coerente por aluno e por período.

# 3. Regras que você deve seguir para gerar sua resposta
- Converter datas para ISO-8601 (YYYY-MM-DD); se inválida, mover item para avisos_validacao e excluir do cálculo.
- Se peso estiver ausente, distribuir pesos iguais entre avaliações válidas; se soma de pesos != 1, normalizar dividindo cada peso pela soma total.
- score_normalizado_0_100 = (nota_obtida / nota_maxima) * 100; se nota_maxima <= 0 ou ausente, marcar avaliação como inválida em avisos_validacao.
- Calcular taxa_presenca = total_presencas / total_aulas_previstas; se total_aulas_previstas = 0, definir taxa_presenca = null e registrar aviso.
- Preencher campos opcionais ausentes com 0 quando numéricos (participação) e com [] quando listas; manter null se informação for desconhecida e afetar cálculo.
- Remover duplicatas de avaliações pelo id ou combinação (tipo, data_iso, nota_obtida, peso), mantendo a primeira ocorrência.
- Garantir objetivos_aprendizagem como array; se não informado, retornar [].
- Não criar inferências sobre dados faltantes; apenas sinalizar em avisos_validacao com código e mensagem: {codigo, mensagem, item_afetado}.
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 dos alunos 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 JSON na interface da Prototipe AI, para acelerar o processo de validação.
  • Tipo do input: O input inicial para o fluxo é um arquivo JSON contendo dados de desempenho e participação dos alunos.
  • Formatos Suportados: Esse agente deve ser capaz de receber arquivos nos formatos: .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 arquivo JSON validado.
  • Exemplo de Estrutura de Output: 
     { alunos: [ { student_id, nome, turma, disciplina, periodo, objetivos_aprendizagem: [...], avaliacoes_normalizadas: [ { id, tipo, data_iso, peso, score_normalizado_0_100, objetivos_relacionados: [...] } ], frequencia_validada: { total_aulas_previstas, total_presencas, faltas_justificadas, taxa_presenca }, participacao_validada: { intervenções_orais, atividades_entregues, engajamento_plataforma }, referencias: { media_turma?, desvio_padrao_turma?, meta_professor? }, avisos_validacao: [ ... ] } ] }
  • Número de caracteres esperado: O JSON gerado terá um tamanho aproximado de 10.000 caracteres.

1.3.3 Parâmetros de Geração

  • Modelo: GPT-5
  • Temperatura: 0.5

1.3.4 Ferramentas do Agente

  • Documentos: Não consulta documentos externos.
  • Calculadora: Utiliza lógica interna para normalização e validação de dados.
  • 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 Cálculo de Métricas e Benchmarks (RF 2).

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

Ao concluir sua execução, esse agente aciona o Agente de Cálculo de Métricas e Benchmarks (RF 2).

RF 2. Agente de Cálculo de Métricas e Benchmarks

2.1 Tarefa do Agente

Calcular métricas de desempenho, participação e comparativos por aluno a partir do dataset validado.

2.2 Prompt ou Instruções do Agente 
 # 1. Contexto e explicações sobre inputs iniciais
Você está recebendo um dataset validado de dados de desempenho e participação dos alunos.

# 2. Objetivo
Calcular métricas de desempenho, participação e comparativos por aluno.

# 3. Regras que você deve seguir para gerar sua resposta
- nota_final_ponderada_0_100 = soma(score_normalizado_0_100 * peso).
- nota_mediana_0_100 = mediana dos scores_normalizados válidos.
- melhor_pior_avaliacao com base no maior/menor score_normalizado_0_100.
- dispersao_avaliacoes_dp = desvio padrão populacional dos scores_normalizados; se menos de 2 avaliações, retornar null.
- indice_participacao_composto_0_100: normalizar componentes disponíveis (intervenções_orais, atividades_entregues, engajamento_plataforma) para z-scores simples quando possível; se faltarem referências, usar min-max por aluno (se todos 0, retornar 0). Média simples dos componentes normalizados, reescalada para 0-100.
- desempenho_por_objetivo: para cada objetivo presente em objetivos_relacionados, calcular média dos scores das avaliações que o contêm; peso_contribuicao = soma dos pesos dessas avaliações.
- tendencia_curto_prazo: ordenar avaliações por data_iso; calcular slope pelo ajuste linear simples de score vs ordem (1..n). direcao: up se slope > 0.5, down se slope < -0.5, caso contrário flat. Se n < 3, direcao = flat e slope_por_sequencia_avaliacoes = null.
- benchmark.delta_media_turma = nota_final_ponderada_0_100 - referencias.media_turma quando disponível; z_score_turma = (nota_final_ponderada_0_100 - media_turma)/desvio_padrao_turma se desvio_padrao_turma > 0.
- risco.academico = true se nota_final_ponderada_0_100 < 60 ou direcao = down e delta_media_turma < 0; risco.frequencia = true se taxa_presenca < 0.75; risco.participacao = true se indice_participacao_composto_0_100 < 40; motivos descrevem regras disparadas.
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 bem-sucedida do agente anterior (RF 1).
  • Tipo do input: Este agente deve ser apto a receber como input um JSON validado contendo dados de desempenho e participação dos 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 texto com até 10.000 caracteres.

2.3.2 Especificação do Output

  • Formato de output: O output deve ser um arquivo JSON contendo as métricas calculadas.
  • Exemplo de Estrutura de Output: 
     { alunos: [ { student_id, periodo, metricas: { nota_final_ponderada_0_100, nota_mediana_0_100, melhor_pior_avaliacao: { melhor, pior }, dispersao_avaliacoes_dp, taxa_presenca, indice_participacao_composto_0_100, desempenho_por_objetivo: [ { objetivo, media_0_100, peso_contribuicao } ], tendencia_curto_prazo: { slope_por_sequencia_avaliacoes, direcao: up|flat|down }, benchmark: { delta_media_turma, z_score_turma? }, risco: { academico: true|false, frequencia: true|false, participacao: true|false, motivos: [ ... ] } } } ] }
  • Número de caracteres esperado: O JSON gerado terá um tamanho aproximado de 8.000 caracteres.

2.3.3 Parâmetros de Geração

  • Modelo: GPT-5
  • Temperatura: 0.5

2.3.4 Ferramentas do Agente

  • Documentos: Não consulta.
  • Calculadora: Utiliza lógica interna para cálculo de métricas e benchmarks.
  • Busca Online: Não utiliza.
  • Sistemas Externos: Não utiliza.

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 Insights e Recomendações Personalizadas (RF 3).

RF 3. Agente de Insights e Recomendações Personalizadas

3.1 Tarefa do Agente

Gerar insights acionáveis e recomendações alinhadas aos objetivos de aprendizagem e às métricas calculadas.

3.2 Prompt ou Instruções do Agente 
 # 1. Contexto e explicações sobre inputs iniciais
Você está recebendo métricas de desempenho e participação calculadas para cada aluno.

# 2. Objetivo
Gerar insights acionáveis e recomendações alinhadas aos objetivos de aprendizagem.

# 3. Regras que você deve seguir para gerar sua resposta
- Criar no mínimo: 2 destaques positivos quando houver métricas >= 80 ou evolução up; 2 lacunas quando objetivos com média < 60 ou pior avaliação < 50; alertas correspondem a riscos true.
- Amarrar cada insight a uma métrica concreta, citando o valor: exemplo: Taxa de presença 68% (< 75%).
- Recomendações devem ser específicas, mensuráveis, com prazo e critério de sucesso: exemplo: Revisar frações 20 min/dia por 10 dias; sucesso se média em exercícios diagnósticos ≥ 70% em 2 tentativas.
- Prioridade alta para itens com risco true; média para lacunas sem risco; baixa para otimizações.
- Quando existir desempenho_por_objetivo, vincular recomendacoes a até 3 objetivos com menor média.
- Se faltarem dados para algum componente, criar recomendação de diagnóstico inicial (ex.: aplicar lista de verificação ou miniavaliação) e sinalizar a lacuna de dado em lacunas.
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 bem-sucedida do agente anterior (RF 2).
  • Tipo do input: Este agente deve ser apto a receber como input um JSON contendo métricas de desempenho e participação dos 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 texto com até 8.000 caracteres.

3.3.2 Especificação do Output

  • Formato de output: O output deve ser um arquivo JSON contendo insights e recomendações.
  • Exemplo de Estrutura de Output: 
     { alunos: [ { student_id, periodo, insights: { destaques: [ ... ], lacunas: [ ... ], alertas: [ ... ], recomendacoes: [ { objetivo_relacionado?, acao, prazo_dias, criterio_sucesso, prioridade: alta|media|baixa } ] } } ] }
  • Número de caracteres esperado: O JSON gerado terá um tamanho aproximado de 5.000 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.
  • 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 Montador de Relatório de Progresso (RF 4).

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

Ao concluir sua execução, esse agente aciona o Agente Montador de Relatório de Progresso (RF 4).

RF 4. Agente Montador de Relatório de Progresso

4.1 Tarefa do Agente

Organizar o relatório final por aluno, combinando métricas, insights e benchmarks em formato legível e pronto para compartilhamento.

4.2 Prompt ou Instruções do Agente 
 # 1. Contexto e explicações sobre inputs iniciais
Você está recebendo métricas, insights e recomendações para cada aluno.

# 2. Objetivo
Organizar o relatório final por aluno, combinando métricas, insights e benchmarks em formato legível.

# 3. Regras que você deve seguir para gerar sua resposta
- Resumo executivo em até 120 palavras cobrindo desempenho geral, frequência e tendência.
- indicadores_chave devem aparecer com números arredondados: 0 casas para notas e participação em 0-100; presença como percentual inteiro (ex.: 83%).
- top_3_forcas seleciona maiores métricas entre: nota_mediana, objetivos com média mais alta e tendência up.
- top_3_prioridades prioriza: objetivos < 60, risco true e pior avaliação < 50.
- plano_de_acao replica recomendações priorizadas (no máximo 5 itens); manter a ordem por prioridade e prazo.
- Texto corrido deve evitar termos técnicos excessivos e incluir uma chamada para próxima ação objetiva (ex.: Reavaliar em 14 dias).
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 bem-sucedida do agente anterior (RF 3).
  • Tipo do input: Este agente deve ser apto a receber como input um JSON contendo métricas, insights e recomendações para cada aluno.
  • 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.

4.3.2 Especificação do Output

  • Formato de output: O output deve ser gerado em dois formatos: 1) JSON estruturado para sistemas; 2) Texto corrido amigável para professores e responsáveis.
  • Exemplo de Estrutura de Output: 
     { alunos: [ { student_id, periodo, resumo_executivo, indicadores_chave: { nota_final_0_100, presenca_pct, participacao_0_100, tendencia: up|flat|down, delta_media_turma? }, top_3_forcas: [ ... ], top_3_prioridades: [ ... ], plano_de_acao: [ { acao, prazo_dias, criterio_sucesso, prioridade } ] } ] }
  • Número de caracteres esperado: O JSON gerado terá um tamanho aproximado de 7.000 caracteres, enquanto o texto corrido deve ser conciso, com até 2.000 caracteres.

4.3.3 Parâmetros de Geração

  • Modelo: GPT-5
  • Temperatura: 0.5

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. Os relatórios gerados são o resultado que deve ser disponibilizado aos professores e responsáveis.

Posts Relacionados

© 2025 prototipe.ai. Todos os direitos reservados.