Agente de IA para Avaliação de Desempenho Escolar

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

Como criar um agente de IA que analisa dados de desempenho dos alunos e gera relatórios que ajudam a identificar áreas de melhoria e talento.

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 "Avaliação de Desempenho Escolar", uma solução de automação projetada para analisar dados de desempenho dos alunos e gerar relatórios que ajudam a identificar áreas de melhoria e talento. 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 é transformar dados de desempenho em relatórios visuais e detalhados, destacando pontos fortes e fracos dos alunos, e sugerindo intervenções pedagógicas com base nos dados analisados.

2. Contexto e Problema

Cenário Atual

As escolas enfrentam desafios significativos na análise manual e demorada dos dados de desempenho dos alunos. Atualmente, há uma falta de identificação precisa de áreas de talento e necessidade de melhoria, o que dificulta a tomada de decisões informadas por parte de professores e gestores.

  • Análise manual e demorada dos dados de desempenho dos alunos.
  • Falta de identificação precisa de áreas de talento e necessidade de melhoria.
  • Necessidade de relatórios claros que ajudem professores e gestores a tomar decisões informadas.

Problemas Identificados

  • Consumo de tempo: O processo manual de análise consome um tempo valioso que poderia ser dedicado a atividades pedagógicas mais estratégicas.
  • Inconsistência de Dados: A análise manual está sujeita a diferentes interpretações, resultando em relatórios com níveis variados de qualidade e detalhe.
  • Falta de Intervenções Eficazes: Sem uma análise precisa, é difícil propor intervenções pedagógicas eficazes.
  • Risco de Erros: A análise manual de dados está propensa a erros, que podem levar a decisões pedagógicas equivocadas.

3. Impactos Esperados

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

  • Reduzir o tempo de análise de dados em pelo menos 70%.
  • Padronizar a qualidade e o formato de todos os relatórios de desempenho escolar.
  • Aumentar a precisão na identificação de áreas de talento e necessidade de melhoria.
  • Apoiar intervenções pedagógicas mais eficazes, permitindo que professores e gestores tomem decisões mais informadas.

4. Visão Geral da Solução

O agente de IA para avaliação de desempenho escolar processa dados de desempenho dos alunos, aplica regras de acordo com o contexto escolar e prepara relatórios detalhados para auxiliar professores e gestores. 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 desempenho escolar.

A solução consiste em um fluxo de automação composto por 5 agentes de IA. O processo inicia com a coleta e análise de dados de desempenho e termina com a geração de relatórios e recomendações pedagógicas.

A execução dos agentes é sequencial e linear, seguindo a ordem definida na tabela abaixo. O fluxo inclui etapas condicionais que são executadas apenas se critérios específicos forem atendidos, conforme detalhado após a tabela.

Agentes Função Principal
Agente de Preparação e Validação da Coleta de Dados (RF 1) Validar, consolidar e transformar as instruções de coleta em um plano de recuperação padronizado e seguro.
Agente de Execução de Chamada à API (RF 2) Realizar chamadas às APIs dos sistemas escolares para obter dados conforme plano de recuperação.
Agente de Integração e Padronização de Dados (RF 3) Unificar datasets de múltiplas fontes, padronizar campos e gerar a matriz de características por aluno/disciplina/período.
Agente de Análise Diagnóstica e Identificação de Talentos (RF 4) Diagnosticar pontos fortes e fracos, riscos de queda de desempenho e identificar talentos por aluno e por disciplina.
Agente de Geração de Relatórios e Recomendações Pedagógicas (RF 5) Produzir relatórios claros, visuais e acionáveis para professores e gestores, com recomendações pedagógicas alinhadas aos diagnósticos.

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 e Validação da Coleta de Dados

1.1 Tarefa do Agente

Validar, consolidar e transformar as instruções de coleta (fontes, campos e período de análise) em um plano de recuperação padronizado e seguro.

1.2 Prompt ou Instruções do Agente 
 # 1. Contexto e explicações sobre inputs iniciais
Você está recebendo um JSON de configuração que contém as instruções de coleta de dados de desempenho escolar, incluindo fontes, campos e período de análise.

# 2. Objetivo
Validar, consolidar e transformar as instruções de coleta em um plano de recuperação padronizado e seguro.

# 3. Regras que você deve seguir para gerar sua resposta
- Rejeite a configuração se periodo_referencia.inicio > fim ou período > 365 dias.
- Para cada fonte, verifique: tipo ∈ {api, arquivo}; mapeamento_campos contém ao menos aluno_id, data e um entre nota/participacao/atividade; base_legal informada.
- Aplique minimização de dados removendo campos não essenciais (endereços, contatos, documentos). Liste campos removidos em regras_privacidade.campos_removidos.
- Normalize nomes de disciplinas e métricas em snake_case; converta datas para ISO 8601.
- Defina chaves_primarias conforme disponibilidade: [aluno_id, disciplina, data] quando houver nota/participação; para atividades, inclua atividade_id se existir.
- Defina criterios_qualidade com limites numéricos padrão caso não informados: min_notas_por_disciplina=2; max_dias_sem_registro=14.
- Se alguma fonte requer token, marque no request o placeholder "Bearer ****" sem expor segredos no output.
- Produza consultas_preparadas separadas por escopo_dados (notas, participacao, atividades) quando necessário.
- Sinalize pseudonimizacao=true e exija que qualquer exibição substitua aluno_id por hash_id, mantendo aluno_id apenas para junção interna.

# 4. Exemplo de Output que você deve produzir
Plano de recuperação padronizado: {"consultas_preparadas": [{"fonte_nome": "SIA-Notas", "tipo": "api", "request": {"url": "...", "headers": {"Authorization": "Bearer ****"}, "query": {"inicio": "...", "fim": "...", "turmas": ["8A","8B"]}}, "mapeamento_campos": {...}, "escopo_dados": ["notas"]}], "regras_privacidade": {"pseudonimizacao": true, "campos_removidos": ["endereco","telefone_pais"]}, "chaves_primarias": ["aluno_id","disciplina","data"], "criterios_qualidade": {"min_notas_por_disciplina": 2, "max_dias_sem_registro": 14}}
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 JSON de configuração 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 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 as instruções de coleta de dados de desempenho escolar.
  • 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 JSON contendo o plano de recuperação padronizado e seguro. A estrutura deve incluir consultas preparadas, regras de privacidade, chaves primárias e critérios de qualidade.
  • Exemplo de Estrutura de Output: 
     {"consultas_preparadas": [{"fonte_nome": "SIA-Notas", "tipo": "api", "request": {"url": "...", "headers": {"Authorization": "Bearer ****"}, "query": {"inicio": "...", "fim": "...", "turmas": ["8A","8B"]}}, "mapeamento_campos": {...}, "escopo_dados": ["notas"]}], "regras_privacidade": {"pseudonimizacao": true, "campos_removidos": ["endereco","telefone_pais"]}, "chaves_primarias": ["aluno_id","disciplina","data"], "criterios_qualidade": {"min_notas_por_disciplina": 2, "max_dias_sem_registro": 14}}
  • Número de caracteres esperado: O JSON gerado deve ser claro e direto, com um tamanho estimado em 1.500 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 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 chamadas às APIs dos sistemas escolares para obter dados conforme plano de recuperação.

2.2 Prompt ou Instruções do Agente 
 # 1. Contexto e explicações sobre inputs iniciais
Você está recebendo um payload pronto para execução, contendo consultas preparadas para chamadas às APIs dos sistemas escolares.

# 2. Objetivo
Realizar chamadas às APIs dos sistemas escolares para obter notas, participação e atividades conforme plano de recuperação.

# 3. Regras que você deve seguir para gerar sua resposta
- Executar as requisições conforme especificado; não registrar ou devolver credenciais; respeitar paginação e limites de taxa conforme metadados do plano.
- Assegure-se de que todas as chamadas à API retornem dados válidos e completos;
- Em caso de falha, registre o erro e interrompa o processo para análise manual.

# 4. Exemplo de Output que você deve produzir
Dados brutos recuperados por fonte: {"datasets": [{"fonte_nome": "SIA-Notas", "tipo": "api", "dados": [{"student_id": "123", "subject": "matematica", "score": 8.7, "date": "2025-03-12"}, ...]}]}
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 payload pronto para execução, contendo consultas preparadas para chamadas às APIs dos sistemas escolares.
  • 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 JSON contendo os dados brutos recuperados por fonte, conforme especificado no plano de recuperação.
  • Exemplo de Estrutura de Output: 
     {"datasets": [{"fonte_nome": "SIA-Notas", "tipo": "api", "dados": [{"student_id": "123", "subject": "matematica", "score": 8.7, "date": "2025-03-12"}, ...]}]}
  • Número de caracteres esperado: O JSON gerado deve ser claro e direto, com um tamanho estimado em 2.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: Não utiliza.
  • Busca Online: Não utiliza.
  • Sistemas Externos: Executar as requisições conforme especificado; não registrar ou devolver credenciais; respeitar paginação e limites de taxa conforme metadados do plano.

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 Integração e Padronização de Dados (RF 3).

RF 3. Agente de Integração e Padronização de Dados

3.1 Tarefa do Agente

Unificar datasets de múltiplas fontes, padronizar campos e gerar a matriz de características por aluno/disciplina/período.

3.2 Prompt ou Instruções do Agente 
 # 1. Contexto e explicações sobre inputs iniciais
Você está recebendo dados brutos de múltiplas fontes, que precisam ser integrados e padronizados para gerar a matriz de características por aluno, disciplina e período.

# 2. Objetivo
Unificar datasets de múltiplas fontes, padronizar campos, tratar qualidade e gerar a matriz de características por aluno/disciplina/período.

# 3. Regras que você deve seguir para gerar sua resposta
- Realize junção por chaves_primarias; se houver conflito de tipos, converta para tipos canônicos: aluno_id string, data ISO, numeradores float.
- Deduplicate com base em chaves_primarias mantendo o registro mais recente por data.
- Trate valores ausentes: para métricas de contagem, imputar 0 quando ausência significa inexistência; para notas, não imputar, apenas sinalizar faltante.
- Calcule por aluno-disciplina no período: nota_media, mediana, desvio_padrao, contagem_avaliacoes; para participação: participacao_taxa=[presenças/(presenças+faltas)], e para atividades: taxa_conclusao=[concluídas/atribuídas] quando disponível.
- Produza percentil_turma por disciplina; compute zscore_nota usando média e desvio da turma no período.
- Remova campos PII não necessários do output público; se pseudonimizacao=true, inclua apenas hash_id, mantendo aluno_id somente em campo interno protegido.
- Gere qualidade.faltantes_por_campo em porcentagem, e liste registros_descartados_por_regra com motivo: {data_invalida, nota_fora_intervalo, duplicado}.

# 4. Exemplo de Output que você deve produzir
Dataset padronizado e relatório de qualidade: {"features": [{"hash_id": "h_abc", "aluno_id": "123" (oculto se exigido), "disciplina": "matematica", "periodo": {"inicio": "...", "fim": "..."}, "nota_media": 8.1, "mediana": 8.0, "participacao_taxa": 0.92, "atividades_concluidas": 12, "faltas": 2, "zscore_nota": 0.7, "percentil_turma": 78}], "qualidade": {"linhas": 1240, "faltantes_por_campo": {"nota": 3.2}, "duplicidades_removidas": 17, "registros_descartados_por_regra": 9}}
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 dados brutos de múltiplas fontes, que precisam ser integrados e padronizados.
  • 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é 20.000 caracteres.

3.3.2 Especificação do Output

  • Formato de output: O output deve ser um JSON contendo o dataset padronizado e um relatório de qualidade dos dados.
  • Exemplo de Estrutura de Output: 
     {"features": [{"hash_id": "h_abc", "aluno_id": "123" (oculto se exigido), "disciplina": "matematica", "periodo": {"inicio": "...", "fim": "..."}, "nota_media": 8.1, "mediana": 8.0, "participacao_taxa": 0.92, "atividades_concluidas": 12, "faltas": 2, "zscore_nota": 0.7, "percentil_turma": 78}], "qualidade": {"linhas": 1240, "faltantes_por_campo": {"nota": 3.2}, "duplicidades_removidas": 17, "registros_descartados_por_regra": 9}}
  • Número de caracteres esperado: O JSON gerado deve ser claro e direto, com um tamanho estimado em 3.000 caracteres.

3.3.3 Parâmetros de Geração

  • Modelo: GPT-5
  • Temperatura: 0.6

3.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.

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 Análise Diagnóstica e Identificação de Talentos (RF 4).

RF 4. Agente de Análise Diagnóstica e Identificação de Talentos

4.1 Tarefa do Agente

Diagnosticar pontos fortes e fracos, riscos de queda de desempenho e identificar talentos por aluno e por disciplina.

4.2 Prompt ou Instruções do Agente 
 # 1. Contexto e explicações sobre inputs iniciais
Você está recebendo um dataset padronizado que precisa ser analisado para diagnosticar pontos fortes e fracos, riscos de queda de desempenho e identificar talentos por aluno e por disciplina.

# 2. Objetivo
Diagnosticar pontos fortes e fracos, riscos de queda de desempenho e identificar talentos por aluno e por disciplina.

# 3. Regras que você deve seguir para gerar sua resposta
- Talento: percentil_turma ≥ talento_percentil_min E zscore_nota ≥ 0.5 E participacao_taxa ≥ 0.85 quando disponível; classifique consistencia como alta se desvio_padrao ≤ 0.8 e contagem_avaliacoes ≥ 3.
- Risco: percentil_turma ≤ risco_percentil_max OU zscore_nota ≤ queda_zscore OU participacao_taxa < participacao_min; priorize risco se condições de talento e risco ocorrerem simultaneamente.
- Áreas de melhoria: identifique o maior gap entre aluno e média da turma por habilidade/tema quando disponível; caso não haja granularidade, reporte por disciplina.
- Estabilidade temporal: se existirem múltiplos períodos, sinalize tendência (subindo/estável/caindo) usando variação de nota_media ≥ ±0.5.
- Inclua somente evidências numéricas verificáveis a partir de features; não infira atributos sensíveis (ex.: renda, etnia).
- Gere sumários agregados por turma e disciplina, com proporções (%).

# 4. Exemplo de Output que você deve produzir
Diagnósticos por aluno e sumário de coorte: {"diagnosticos": [{"hash_id": "h_abc", "disciplina": "matematica", "status": {"talento": true, "risco": false}, "evidencias": {"percentil": 93, "nota_media": 8.7, "consistencia": "alta", "participacao_taxa": 0.95}, "areas_melhoria": [], "pontos_fortes": ["raciocinio_logico"]}], "sumarios": {"talentos_por_disciplina": {"matematica": 8}, "em_risco_por_disciplina": {"portugues": 5}}}
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 um dataset padronizado que precisa ser analisado para diagnosticar pontos fortes e fracos, riscos de queda de desempenho e identificar talentos.
  • 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é 15.000 caracteres.

4.3.2 Especificação do Output

  • Formato de output: O output deve ser um JSON contendo diagnósticos por aluno e sumário de coorte.
  • Exemplo de Estrutura de Output: 
     {"diagnosticos": [{"hash_id": "h_abc", "disciplina": "matematica", "status": {"talento": true, "risco": false}, "evidencias": {"percentil": 93, "nota_media": 8.7, "consistencia": "alta", "participacao_taxa": 0.95}, "areas_melhoria": [], "pontos_fortes": ["raciocinio_logico"]}], "sumarios": {"talentos_por_disciplina": {"matematica": 8}, "em_risco_por_disciplina": {"portugues": 5}}}
  • Número de caracteres esperado: O JSON gerado deve ser claro e direto, com um tamanho estimado em 2.000 caracteres.

4.3.3 Parâmetros de Geração

  • Modelo: GPT-5
  • Temperatura: 0.6

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 se conecta a sistemas externos.

4.3.5 Memória

4.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 Recomendações Pedagógicas (RF 5).

RF 5. Agente de Geração de Relatórios e Recomendações Pedagógicas

5.1 Tarefa do Agente

Produzir relatórios claros, visuais e acionáveis para professores e gestores, com recomendações pedagógicas alinhadas aos diagnósticos.

5.2 Prompt ou Instruções do Agente 
 # 1. Contexto e explicações sobre inputs iniciais
Você está recebendo diagnósticos por aluno e sumários de coorte, que precisam ser transformados em relatórios claros e visuais com recomendações pedagógicas.

# 2. Objetivo
Produzir relatórios claros, visuais e acionáveis para professores e gestores, com recomendações pedagógicas alinhadas aos diagnósticos.

# 3. Regras que você deve seguir para gerar sua resposta
- Estrutura do relatório: capa (período, turmas, proprietário), visão geral (sumários e gráficos descritos textualmente), seções por disciplina, destaques de talentos e alunos em risco, recomendações, plano de acompanhamento (KPIs e prazos), anexo de qualidade de dados.
- Recomendações mapeadas por condição:
  • Risco por baixa participação: contato proativo, reforço de rotina, tarefas curtas de engajamento; KPI: participacao_min ≥ 0.85 em 30 dias.
  • Risco por desempenho: reforço de pré-requisitos, prática espaçada, tutorias focadas; KPI: +0.5 na nota_media em 45 dias.
  • Talento: enriquecimento (desafios, projetos), mentoria, trilhas avançadas; KPI: manter percentil ≥ 90 e participação ≥ 0.9.
- Forneça flagrantes de dados (avisos) quando qualidade abaixo do mínimo: exibir banners como "dados insuficientes para conclusão" quando contagem_avaliacoes < 2.
- Privacidade: exibir apenas hash_id em conteúdos distribuídos; não incluir PII. Inserir nota de conformidade: base legal, minimização, direito de acesso/correção.
- Saída dupla obrigatória: um markdown legível e um JSON estruturado com chaves: alunos, sumarios, intervencoes_sugeridas, kpis_seguimento, avisos_qualidade.
- Linguagem objetiva e não determinística; evitar rótulos estigmatizantes; focar em ações concretas e mensuráveis.

# 4. Exemplo de Output que você deve produzir
Relatório em Markdown e JSON: {"markdown": "# Relatório...", "json": {"alunos": [...], "intervencoes_sugeridas": [...], "kpis_seguimento": [{"indicador": "taxa_conclusao_atividades", "meta": 0.9, "prazo_dias": 30}]}}
5.3 Configurações do Agente

5.3.1 Especificação do Input

  • Mecanismo de Acionamento: Este agente deve ser acionado automaticamente após a conclusão do agente anterior (RF 4).
  • Tipo do input: Este agente deve ser apto a receber diagnósticos por aluno e sumários de coorte.
  • 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é 15.000 caracteres.

5.3.2 Especificação do Output

  • Formato de output: O output deve ser um relatório em Markdown e um JSON estruturado com chaves: alunos, sumarios, intervencoes_sugeridas, kpis_seguimento, avisos_qualidade.
  • Exemplo de Estrutura de Output: 
     {"markdown": "# Relatório...", "json": {"alunos": [...], "intervencoes_sugeridas": [...], "kpis_seguimento": [{"indicador": "taxa_conclusao_atividades", "meta": 0.9, "prazo_dias": 30}]}}
  • Número de caracteres esperado: O JSON gerado deve ser claro e direto, com um tamanho estimado em 2.500 caracteres.

5.3.3 Parâmetros de Geração

  • Modelo: GPT-5
  • Temperatura: 0.6

5.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.

5.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 (relatório em Markdown e JSON) é o entregável final e não é passada para outros agentes internos.

5.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 ao usuário.

Posts Relacionados

© 2025 prototipe.ai. Todos os direitos reservados.