Agente de IA para Análise de Desempenho de Alunos

Validar, normalizar e padronizar os dados de avaliações para uso analítico consistente em todo o fluxo.

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 arquivo CSV ou JSON contendo registros 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 arquivo na interface da Prototipe AI, para acelerar o processo de validação.
• Tipo do input: O input inicial para o fluxo é um arquivo CSV ou JSON contendo registros de avaliações dos alunos.
• Formatos Suportados: Esse agente deve ser capaz de receber arquivos nos formatos: .csv, .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 JSON com dois objetos: dataset_normalizado (lista de registros padronizados) e quality_report (sumário de qualidade).
• Exemplo de Estrutura de Output:

   {
    "dataset_normalizado": [
      {"id_aluno": "12345", "nome_aluno": "João Silva", "disciplina": "Matemática", "data_avaliacao_iso": "2025-08-01", "nota_normalizada_0a10": 8.5, "nota_original": 85, "escala_original_max": 100, "peso_normalizado_1": 1.0, "bimestre": 3, "semestre": 2, "turma": "A", "professor": "Maria Oliveira", "modalidade": "prova", "avaliacao_id": "mat2025-01" }
    ],
    "quality_report": {
      "registros_totais": 100,
      "registros_validos": 95,
      "campos_ausentes_por_coluna": {"nome_aluno": 2, "disciplina": 1},
      "linhas_descartadas": 5,
      "linhas_deduplicadas": 3,
      "outliers_detectados": 2,
      "escalas_convertidas": 2,
      "periodos_detectados": 4,
      "observacoes": ["3 linhas removidas por data inválida", "escalas convertidas de 100 para 10 em 2 disciplinas"]
    }
  } 

• Número de caracteres esperado: O JSON final deve ter um tamanho estimado em torno de 8.000 caracteres, podendo variar conforme o número de registros 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 Padrões de Desempenho (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 Padrões de Desempenho (RF 2).

Identificar tendências, padrões e riscos de aprendizagem em nível de aluno, disciplina e turma a partir do dataset normalizado.

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 dataset normalizado e o quality_report.
• 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é 50.000 caracteres.

2.3.2 Especificação do Output

• Formato de output: O output deve ser um JSON analytics com insights detalhados sobre desempenho.
• Exemplo de Estrutura de Output:

   {
    "kpis_gerais": {
      "alunos_unicos": 100,
      "disciplinas_unicas": 5,
      "media_geral": 7.2,
      "mediana_geral": 7.0,
      "desvio_padrao_geral": 1.1
    },
    "por_disciplina": [
      {
        "disciplina": "Matemática",
        "media": 6.8,
        "mediana": 7.0,
        "desvio": 1.2,
        "tendência_linear_sazonal": {"coeficiente": -0.3, "direção": "queda", "observacao": "queda no 3º bimestre"},
        "%abaixo_6": 20,
        "%acima_8": 30,
        "consistencia": 0.1
      }
    ],
    "por_aluno": [
      {
        "id_aluno": "12345",
        "nome_aluno": "João Silva",
        "medias_por_disciplina": {"Matemática": 6.8},
        "evolução_temporal": [{"data": "2025-08-01", "nota": 8.5}],
        "tendência_global": "queda",
        "volatilidade": "médio",
        "gaps_disciplinares": ["Matemática"],
        "risco_reprovação": "alto"
      }
    ],
    "por_turma": [
      {
        "turma": "A",
        "media": 7.0,
        "dispersao": 1.0,
        "disciplina_com_maior_gap": "Matemática"
      }
    ],
    "alertas": [
      {
        "tipo": "crítico",
        "alvo": "João Silva",
        "detalhe": "risco alto em Matemática",
        "severidade": "alta"
      }
    ]
  } 

• Número de caracteres esperado: O JSON gerado deve ter um tamanho estimado em torno de 10.000 caracteres, dependendo da complexidade dos dados analisados.

2.3.3 Parâmetros de Geração

• Modelo: GPT-5
• Temperatura: 0.6

2.3.4 Ferramentas do Agente

• Documentos: Não consulta.
• Calculadora: Utiliza lógica interna para calcular KPIs e tendências.
• Busca Online: Não utiliza.
• Sistemas Externos: Não utiliza.

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 (JSON analytics) deve ser visível para o Agente de Recomendações de Intervenções Pedagógicas (RF 3).

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

Ao concluir sua execução, esse agente aciona o Agente de Recomendações de Intervenções Pedagógicas (RF 3).

Converter padrões identificados em planos de intervenção personalizados e acionáveis para alunos e turmas.

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 analytics com insights detalhados sobre o desempenho.
• 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.

3.3.2 Especificação do Output

• Formato de output: O output deve ser um JSON recomendacoes com planos de intervenção personalizados.
• Exemplo de Estrutura de Output:

   {
    "por_aluno": [
      {
        "id_aluno": "12345",
        "nome_aluno": "João Silva",
        "objetivos_aprendizagem": ["Elevar média de Matemática para >=6,5 em 8 semanas"],
        "estrategias": ["Reforço semanal guiado", "Exercícios graduais"],
        "recursos_sugeridos": ["Listas de exercícios por nível", "Tutorias de pares"],
        "carga_semanal_recomendada_h": 3.0,
        "acompanhamento": {"frequencia": "semanal", "indicadores_monitoramento": ["última_nota", "média móvel"]},
        "marco_reavaliacao_dias": 21
      }
    ],
    "por_turma": [
      {
        "turma": "A",
        "foco_disciplinar": "Matemática",
        "estrategias_coletivas": ["Revisão diagnóstica inicial", "Ensino por estações"],
        "semanais_minimas_de_pratica": 2,
        "indicadores_coletivos": ["Elevar média da turma em 0,7 no próximo bimestre"],
        "agenda_formativa": "Quinzenal"
      }
    ],
    "mapeamento_regras_aplicadas": ["Regras de carga semanal", "Regras de acompanhamento"]
  } 

• Número de caracteres esperado: O JSON final deve ter um tamanho estimado em torno de 5.000 caracteres, podendo variar conforme o número de recomendações geradas.

3.3.3 Parâmetros de Geração

• Modelo: GPT-5
• Temperatura: 0.6

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 (JSON recomendacoes) deve ser visível para o Agente de Geração de Relatório para Educadores (RF 4).

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

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

Produzir relatório em Markdown com insights claros e acionáveis, consolidando análises e intervenções.

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 analytics, um JSON recomendacoes e o quality_report inicial.
• Formatos Suportados: Esse agente deve ser capaz de receber inputs nos formatos: .json.
• Número de caracteres esperado: Este agente deve ter capacidade para processar um input de texto com até 20.000 caracteres.

4.3.2 Especificação do Output

• Formato de output: O output deve ser um relatório em Markdown estruturado com insights e recomendações.
• Exemplo de Estrutura de Output:

   # Relatório de Desempenho dos Alunos
  ## Sumário Executivo
  - Identificamos uma tendência de queda em Matemática.
  - Recomenda-se reforço semanal para alunos com média abaixo de 6,5.
  
  ## Panorama Geral
  | Indicador | Valor |
  |-----------|-------|
  | Média Geral | 7.2 |
  | Mediana Geral | 7.0 |
  
  ## Análise por Disciplina
  **Matemática**
  - Média: 6.8
  - % abaixo de 6: **20%**
  - Tendência: ↓
  
  ## Alertas Críticos
  - João Silva: Risco alto em Matemática (média 4,8 e tendência ↓)
  
  ## Recomendações por Aluno
  - **João Silva**
    - Objetivo: Elevar média de Matemática para >=6,5 em 8 semanas
    - Estratégias: Reforço semanal guiado, Exercícios graduais
  
  ## Plano de Acompanhamento
  - Frequência: Semanal
  - Indicadores: Última nota, Média móvel
  
  ## Apêndice Metodológico
  - Limiar de risco: Média < 5 

• Número de caracteres esperado: O relatório gerado deve ter um tamanho estimado em torno de 10.000 caracteres, dependendo da quantidade de dados e recomendações.

4.3.3 Parâmetros de Geração

• Modelo: GPT-5
• Temperatura: 0.6

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 (relatório em Markdown) é 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. O relatório gerado é o resultado que deve ser disponibilizado ao educador.