PrototipeAI | Agente de IA para Avaliação de Desempenho Estudantil

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 Avaliação de Desempenho 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 é automatizar a análise do desempenho estudantil, gerando feedbacks personalizados e identificando padrões de desempenho que possam indicar dificuldades específicas.

2. Contexto e Problema

Cenário Atual

A análise do desempenho dos alunos em provas e atividades é um processo manual e demorado. Professores enfrentam dificuldades em fornecer feedbacks personalizados que ajudem no desenvolvimento dos alunos.

Análise manual e demorada do desempenho estudantil em provas e atividades.
Dificuldade em fornecer feedbacks personalizados que ajudem no desenvolvimento dos alunos.

3. Impactos Esperados

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

Reduzir o tempo de análise do desempenho estudantil.
Fornecer feedbacks personalizados para cada aluno.
Identificar padrões de desempenho que possam indicar dificuldades específicas.

4. Visão Geral da Solução

O agente de IA para avaliação de desempenho estudantil analisa automaticamente o desempenho dos alunos em provas e atividades, gera feedbacks personalizados e identifica áreas de melhoria. 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 estudantil.

A solução consiste em um fluxo de automação composto por 7 agentes de IA. O processo inicia com a coleta de dados de avaliações e termina com a geração de feedbacks personalizados e recomendações de intervenção.

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

Agentes	Função Principal
`Agente de Validação e Normalização de Dados`	Validar, padronizar e preparar os dados de avaliações para análise consistente.
`Agente de Cálculo de Desempenho por Critério e Mestria`	Consolidar o desempenho por critério/habilidade e classificar níveis de domínio por aluno.
`Agente de Detecção de Padrões e Lacunas`	Identificar áreas fortes e fracas por aluno e tendências da turma.
`Agente de Geração de Feedback Personalizado`	Redigir feedback claro e motivador para cada aluno.
`Agente de Recomendações de Intervenção`	Propor intervenções práticas e recursos alinhados às lacunas identificadas.
`Agente de Síntese da Turma`	Produzir uma visão executiva agregada para o professor e coordenação.

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

1.1 Tarefa do Agente

Validar, padronizar e preparar os dados de avaliações para análise consistente por aluno e por critério.

1.2 Prompt ou Instruções do Agente

 # 1. Contexto e explicações sobre inputs iniciais
Você está recebendo um JSON com lista de alunos e suas avaliações. Estrutura mínima: alunos[{id_aluno, nome, avaliacoes:[{id_avaliacao, tipo, data, itens:[{id_item, criterio, habilidade, nota_obtida, nota_maxima, peso_item?}], peso_avaliacao?, observacoes_professor?}]}], parametros_opcionais:{escala_padrao (ex: 0-10), limiares_mestria{dominio, proximidade, em_desenvolvimento}, politica_faltas (ex: tratar_nulo_como_zero:true/false)}.

# 2. Objetivo
Validar, padronizar e preparar os dados de avaliações para análise consistente por aluno e por critério.

# 3. Regras que você deve seguir para gerar sua resposta
- Rejeite notas fora do intervalo [0, nota_maxima]; se ocorrer, crie flag_validacao {codigo:'nota_fora_intervalo', severidade:'alta', mensagem} e corrija por clamp ao limite mais próximo.
- Se nota_maxima ausente, crie flag {codigo:'nota_maxima_ausente', severidade:'alta'} e exclua o item da média daquela avaliação.
- Se peso_item ausente, assuma peso uniforme entre itens daquela avaliação (1/N); normalize pesos para somar 1 por avaliação (4 casas decimais).
- Se peso_avaliacao ausente, assuma pesos uniformes entre avaliações do mesmo aluno; normalize pesos para somar 1 por aluno.
- Se nota_obtida nula: aplicar politica_faltas; se tratar_nulo_como_zero=true, defina 0; caso contrário, exclua o item do cômputo e crie flag {codigo:'item_sem_nota'}.
- Calcule score_percentual = (nota_obtida/nota_maxima)*100 com arredondamento para 1 casa decimal.
- Mapeie criterios/habilidades textual e preserve exatamente os rótulos recebidos (não renomeie).

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 com dados de avaliações 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 do JSON na interface da Prototipe AI, para acelerar o processo de validação.
Tipo do input: O input inicial para o fluxo é um JSON estruturado com dados de avaliações.
Formatos Suportados: Esse agente deve ser capaz de receber JSONs estruturados.
Número de caracteres esperado: Este agente deve ter capacidade para processar um input de texto com até 150.000 caracteres.

1.3.2 Especificação do Output

Formato de output: O output deve ser um JSON normalizado com dados dos alunos e avaliações, incluindo flags de validação e metadados de normalização.

Exemplo de Estrutura de Output:

 {
  "alunos_normalizados": [
    {
      "id_aluno": "123",
      "nome": "João Silva",
      "avaliacoes_normalizadas": [
        {
          "id_avaliacao": "456",
          "data": "2025-12-13",
          "itens": [
            {
              "id_item": "789",
              "criterio": "Matemática",
              "habilidade": "Álgebra",
              "score_percentual": 85.0,
              "peso_normalizado": 0.25
            }
          ],
          "peso_avaliacao_normalizado": 0.5,
          "observacoes_professor": "Bom desempenho geral."
        }
      ],
      "flags_validacao": [
        {
          "codigo": "nota_fora_intervalo",
          "severidade": "alta",
          "mensagem": "Nota excedeu o intervalo permitido."
        }
      ]
    }
  ],
  "metadados_normalizacao": {
    "escala_utilizada": "0-10",
    "politica_faltas_aplicada": "tratar_nulo_como_zero",
    "total_flags": 1
  }
}

Número de caracteres esperado: O JSON final deve ser conciso e informativo, com um tamanho estimado em torno de 10.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.
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 Desempenho por Critério e Mestria.

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

Ao concluir sua execução, esse agente aciona o Agente de Cálculo de Desempenho por Critério e Mestria.

Agente de IA para Avaliação de Desempenho Estudantil