Agente de IA para Avaliação de Impacto de Métodos de Ensino

Validar a integridade, coerção de tipos e consistência do dataset de desempenho, padronizar nomes/valores de colunas e gerar um dataset normalizado e pronto para análise, com relatório estruturado de qualidade.

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 .xlsx contendo os dados brutos 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 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 de dados estruturados (.csv ou .xlsx) contendo as informações brutas dos alunos.
• Formatos Suportados: Esse agente deve ser capaz de receber arquivos nos formatos: .csv, .xlsx.
• 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 contendo o caminho para o arquivo normalizado, uma amostra preview, o schema resultante e um relatório de qualidade.
• Exemplo de Estrutura de Output:

   {
    "dataset_normalizado_path": "string (caminho para arquivo .csv normalizado)",
    "amostra_preview": [{"coluna": "valor_exemplo"}],
    "schema_resultante": {"colunas": {"id": "id_aluno", "tratamento": "metodo_ensino", "tempo": "tempo", "nota_pre": "number", "nota_pos": "number", "aprovado": "0|1", "assiduidade": "number", "sexo": "string", "idade": "number", "socioeconomico": "string|number", "turma": "string", "professor": "string", "disciplina": "string", "ganho_pre_pos": "number"}},
    "qualidade": {
      "missing_por_coluna": {"coluna": 0.0},
      "duplicados_por_id": 0,
      "min_tamanho_grupo_ok": true,
      "grupos": [{"metodo": "metodo_A", "n": 120}, {"metodo": "metodo_B", "n": 98}],
      "faixas_invalidas": [{"coluna": "nota_pos", "contagem": 0}],
      "percent_missing_outcome": 1.2
    },
    "normalizacoes_aplicadas": ["trim_e_lowercase_para_metodo_ensino", "mapeamento_booleans_aprovado_para_0_1", "construcao_ganho_pre_pos", "padronizacao_por_disciplina: false|true"],
    "alertas": [{"codigo": "MISSING_OUTCOME_ALTO", "severidade": "alta", "mensagem": ">20% de missing em outcome"}],
    "dataset_validado": true
  } 

• Número de caracteres esperado: O JSON gerado deve ter um tamanho aproximado de 4.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: 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 Preparação de Script de Análise (RF 2).

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

Ao concluir sua execução, esse agente aciona o Agente de Preparação de Script de Análise (RF 2).

Ler o dataset normalizado e preparar, de forma determinística, o script de análise estatística (ANCOVA, pré–pós, diferença-em-diferenças ou análise observacional com escore de propensão) para estimar o impacto dos métodos de ensino e comparar práticas pedagógicas.

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 contendo o caminho para o dataset normalizado e parâmetros analíticos.
• Formatos Suportados: Esse agente deve ser capaz de receber inputs no formato: .json (JSON).
• Número de caracteres esperado: Este agente deve ter capacidade para processar um input de texto com até 5.000 caracteres.

2.3.2 Especificação do Output

• Formato de output: O output deve ser um JSON contendo o script Python gerado, parâmetros analíticos, checagens planejadas e definições de métricas.
• Exemplo de Estrutura de Output:

   {
    "script": "string com código Python (pandas/statsmodels) pronto para execução, determinístico e com semente fixa",
    "params": {"desenho_analitico": "did|ab|pre_pos|observacional", "metrica_principal": "...", "covariaveis": ["..."], "clusters": ["..."], "comparacoes": {"referencia": "...", "alternativas": ["..."]}},
    "checagens_planejadas": ["balanceamento_covariaveis", "tendencias_paralelas", "overlap_propensity", "outliers"],
    "definicoes_metricas": {"ganho_pre_pos": "nota_pos - nota_pre", "aprovacao": "aprovado em {0,1}"},
    "colunas_normalizadas": {"id": "id_aluno", "tratamento": "metodo_ensino", "tempo": "tempo"},
    "avisos_planejamento": [{"codigo": "AMOSTRA_INSUFICIENTE", "mensagem": "..."}]
  } 

• Número de caracteres esperado: O JSON gerado terá um tamanho aproximado de 3.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.
• Calculadora: Não utiliza.
• 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 do script) deve ser visível para o Agente de Execução de Análise Python (RF 3).

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

Ao concluir sua execução, esse agente aciona o Agente de Execução de Análise Python (RF 3).

Executar o script Python gerado para calcular os efeitos dos métodos de ensino, diagnósticos e métricas definidas.

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 o script Python e os arquivos de dados necessários.
• Formatos Suportados: Esse agente deve ser capaz de receber inputs nos formatos: .json (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 contendo os resultados da execução do script, incluindo efeitos, diagnósticos, sensibilidade, subgrupos, figuras e metadados do modelo.
• Exemplo de Estrutura de Output:

   {
    "efeitos": [{"comparacao": "metodo_B vs metodo_A", "estimativa": -0.23, "ic95": [-0.35, -0.11], "p_valor": 0.001, "p_ajustado": 0.003, "tamanho_efeito": {"cohens_d": -0.28}}],
    "diagnosticos": {"balanceamento": {...}, "tendencias_paralelas": {"p_valor": 0.42}, "overlap_propensity": {"min": 0.05, "max": 0.95}, "vif": {"nota_pre": 2.1}},
    "sensibilidade": {"winsorizado": {...}, "cluster_robusto": {...}},
    "subgrupos": {"genero": {...}, "socioeconomico": {...}},
    "figuras": [{"tipo": "forest", "path": "./figs/efeitos.png"}],
    "metadados": {"seed": 12345, "versao_script": "v1"}
  } 

• 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: Não se aplica
• Temperatura: Não se aplica

3.3.4 Ferramentas do Agente

• Documentos: Não consulta.
• Calculadora: Não utiliza.
• Busca Online: Não utiliza.
• Sistemas Externos: O agente deverá executar o script Python utilizando uma API externa de execução de código.

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 de Interpretação e Relatório de Impacto Pedagógico (RF 4).

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

Ao concluir sua execução, esse agente aciona o Agente de Interpretação e Relatório de Impacto Pedagógico (RF 4).

Interpretar os resultados estatísticos, comparar métodos, destacar a prática mais eficaz e produzir relatório executivo e técnico com recomendações acionáveis e resumo estruturado.

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 os resultados da análise e os parâmetros originalmente usados.
• Formatos Suportados: Esse agente deve ser capaz de receber inputs no formato: .json (JSON).
• Número de caracteres esperado: Este agente deve ter capacidade para processar um input de texto com até 8.000 caracteres.

4.3.2 Especificação do Output

• Formato de output: O output deve ser um JSON contendo o relatório em formato Markdown e um resumo estruturado dos achados.
• Exemplo de Estrutura de Output:

   {
    "relatorio_markdown": "# Relatório de Impacto de Métodos de Ensino...",
    "resumo_estruturado": {
      "metodo_mais_eficaz": "string",
      "comparacoes_significativas": [{"comparacao": "B vs A", "efeito": -0.23, "ic95": [-0.35, -0.11], "p_ajustado": 0.003}],
      "tamanho_de_efeito": {"medida": "cohens_d|OR|RR", "valor": 0.28},
      "confiabilidade": {"nivel": "alta|moderada|baixa", "justificativa": "string"},
      "implicacoes_pedagogicas": ["string"],
      "equidade": {"disparidades": true, "detalhes": "string"},
      "recomendacoes": ["string"],
      "limitacoes": ["string"]
    }
  } 

• Número de caracteres esperado: O JSON final será extenso, com um tamanho mínimo esperado de 6.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.
• 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 e resumo) é 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 usuário.