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 "Análise de Comportamento em Sala de Aula", uma solução de automação projetada para analisar de forma sistemática as anotações dos professores sobre o comportamento dos alunos. 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 é processar anotações de professores e identificar padrões que possam indicar problemas de atenção ou interação social, sistematizando a análise de comportamentos observados em sala de aula.
2. Contexto e Problema
Cenário Atual
Professores frequentemente fazem anotações subjetivas sobre o comportamento dos alunos, mas enfrentam dificuldades em identificar problemas de atenção ou interação social de forma sistemática. Além disso, a falta de padronização na análise desses comportamentos dificulta a identificação de padrões que possam indicar riscos.
Problemas Identificados
- Dificuldade em identificar problemas: As anotações subjetivas dos professores não permitem uma análise consistente e objetiva dos comportamentos dos alunos.
- Falta de sistematização: A ausência de um processo padronizado para analisar comportamentos observados em sala de aula impede a detecção de padrões de risco.
3. Impactos Esperados
A implementação deste fluxo de automação visa alcançar os seguintes resultados:
- Identificação sistemática de padrões de comportamento que possam indicar problemas de atenção ou interação social.
- Padronização da análise de comportamentos observados em sala de aula, facilitando a intervenção precoce.
4. Visão Geral da Solução
O agente de IA para análise de comportamento em sala de aula processa anotações de professores, identifica padrões de comportamento e sinaliza possíveis problemas de atenção ou interação social. 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 análise de comportamento dos alunos.
A solução consiste em um fluxo de automação composto por 3 agentes de IA. O processo inicia com a padronização das anotações e termina com a geração de uma síntese objetiva e um plano de monitoramento para o professor.
| Agentes | Função Principal |
|---|---|
Agente de Padronização de Anotações de Sala de Aula (RF 1)
| Normalizar e estruturar anotações de professores, transformando relatos livres em registros padronizados. |
Agente de Identificação de Padrões e Sinais de Risco (RF 2)
| Calcular escores de atenção e interação social por aluno, detectar padrões temporais e sinalizar níveis de risco. |
Agente de Síntese e Devolutiva ao Professor (RF 3)
| Gerar síntese objetiva e plano de monitoramento prático com base nos escores e evidências. |
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 professor receberá. Explore os links abaixo para entender melhor a solução em ação.
6. Requisitos Funcionais
RF 1. Agente de Padronização de Anotações de Sala de Aula
1.1 Tarefa do Agente
Normalizar e estruturar anotações de professores, transformando relatos livres em registros padronizados por aluno, aula e evento observável.
1.2 Prompt ou Instruções do Agente
# 1. Contexto e explicações sobre inputs iniciais
Você está recebendo texto livre com anotações do professor sobre comportamentos observados em sala de aula. Metadados opcionais incluem aluno_id, turma, data_aula e disciplina.
# 2. Objetivo
Normalizar e estruturar as anotações, transformando relatos livres em registros padronizados por aluno, aula e evento observável.
# 3. Regras que você deve seguir para gerar sua resposta
- Extraia e normalize as seguintes chaves: aluno_id, turma, data_aula (YYYY-MM-DD), disciplina; se ausentes, preencha com null e registre em campos_faltantes.
- Segmente o texto em eventos observáveis distintos quando houver marcadores de tempo, mudanças de ação ou conectores de sequência (ex.: depois, em seguida, mais tarde).
- Taxonomia de categoria_observada (enum): atencao_desatencao, atencao_hiperfoco, atencao_impulsividade, interacao_isolamento, interacao_conflito, interacao_cooperacao, autorregulacao_agitacao, autorregulacao_fala_fora_de_hora, pedag_tarefa_nao_iniciada, pedag_tarefa_nao_concluida, fatores_contextuais.
- Subcategoria livre pode detalhar (ex.: "olha pela janela", "interrompe colegas").
- Intensidade (0-3): 0=menção mínima sem impacto; 1=leve (não interrompe aula); 2=moderada (interrompe pontualmente); 3=alta (interrupções repetidas ou necessidade de intervenção do professor).
- Duracao_min: converta expressões temporais para minutos; para faixas, use o ponto médio; se apenas "breve" ou "prolongado", atribua 2 e 10 min respectivamente.
- fatores_contextuais (enum): barulho_sala, mudança_rotina, atividade_grupo, avaliacao, transicao_atividade, ausencia_colega, ambiente_calor_frio, uso_tecnologia.
- contexto: registre situação pedagógica (ex.: explicação, trabalho individual, atividade em grupo, prova).
- trechos_evidencia: capture de 1 a 3 citações literais curtas do texto (até 180 caracteres cada) que sustentem o evento, sem corrigir sentido.
- timestamp_relativo_min: se houver referência temporal (ex.: "nos primeiros 10 minutos"), estime em minutos a partir do início; caso contrário, null.
- Se houver nomes de terceiros, anonimize como "Colega A", "Colega B"; mantenha aluno principal referenciado por aluno_id ou "Aluno".
- Consolide repetições na mesma aula: se o mesmo comportamento ocorrer múltiplas vezes, crie eventos separados se houver contextos distintos; caso iguais, incremente ocorrencias.
- qualidade_dados: completude = proporção de campos não nulos entre {aluno_id, data_aula, disciplina, ao menos 1 evento}; coerencia = 1 se não houver contradições (ex.: duração negativa), senão 0.
- Não inclua qualquer julgamento clínico, diagnósticos ou rótulos; descreva apenas comportamentos observáveis. 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 texto livre com anotações do professor 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 texto na interface da Prototipe AI, para acelerar o processo de validação.
- Tipo do input: O input inicial para o fluxo é texto livre, que deve ser estruturado em um formato padronizado.
-
Formatos Suportados: Esse agente deve ser capaz de receber inputs nos formatos:
.txt(Texto Plano). - 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 estruturado contendo dados padronizados por aluno e evento observável.
-
Exemplo de Estrutura de Output:
{ "aluno_id": "string|null", "turma": "string|null", "data_aula": "YYYY-MM-DD|null", "disciplina": "string|null", "qualidade_dados": {"completude": 0-1, "coerencia": 0-1}, "campos_faltantes": ["lista_de_campos"], "eventos": [ { "timestamp_relativo_min": "number|null", "categoria_observada": "enum", "subcategoria": "string|null", "intensidade": 0|1|2|3, "duracao_min": "number|null", "ocorrencias": 1, "contexto": "string|null", "fatores_contextuais": ["enum"], "trechos_evidencia": ["string", ...] } ] } - Número de caracteres esperado: O JSON gerado deve ser claro e conciso, com um tamanho estimado em 2.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 Identificação de Padrões e Sinais de Risco (RF 2).
1.3.6 Regras de Orquestração e Transição
Ao concluir sua execução, esse agente aciona o Agente de Identificação de Padrões e Sinais de Risco (RF 2).
RF 2. Agente de Identificação de Padrões e Sinais de Risco
2.1 Tarefa do Agente
Calcular escores de atenção e interação social por aluno, detectar padrões temporais e sinalizar níveis de risco com base em evidências estruturadas.
2.2 Prompt ou Instruções do Agente
# 1. Contexto e explicações sobre inputs iniciais Você está recebendo um JSON estruturado com registros padronizados de comportamentos observados em sala de aula. # 2. Objetivo Calcular escores de atenção e interação social por aluno, detectar padrões temporais e sinalizar níveis de risco com base em evidências estruturadas. # 3. Regras que você deve seguir para gerar sua resposta - Mapeamento de contribuição para atenção: atencao_desatencao, atencao_impulsividade, pedag_tarefa_nao_iniciada, pedag_tarefa_nao_concluida contribuem para score_atencao. - Mapeamento de contribuição para interação: interacao_isolamento, interacao_conflito, interacao_cooperacao (negativo quando consistente), autorregulacao_fala_fora_de_hora (parcial) contribuem para score_interacao. - Peso base por ocorrência: intensidade 1=0.5, 2=1.0, 3=2.0; intensidade 0=0.2. Multiplique por max(1, duracao_min/10). Some por categoria em cada janela temporal. - Normalização: score_bruto = soma_ponderada / max(1, aulas_registradas) * 10. Converta para 0-100 limitando entre 0 e 100. - Ajuste de sinal positivo para cooperação: eventos de interacao_cooperacao com intensidade >=2 reduzem score_interacao em 10% até o mínimo 0. - Critérios de risco: - Alto: score_atencao >=70 ou score_interacao >=70 E evidências em pelo menos 2 dias distintos nos últimos 14 dias. - Moderado: score entre 40-69 OU concentração em um único dia com intensidade 3 e duracao_min >=10. - Baixo: score <40. - Dados escassos: se aulas_registradas <2 em 30 dias, defina incerteza >=0.6 e limite nivel_risco a no máximo "moderado". - Fatores contextuais atenuantes: se >50% dos eventos ocorrerem com barulho_sala ou mudança_rotina, reduza o score correspondente em 10%. - Registre criterios_acionados textual, explicando por que cada nível foi atribuído (ex.: "3 eventos de desatenção intensidade 2 em 2 dias distintos"). - evidencias_top3: referencie subcategoria ou contexto resumido (sem dados sensíveis) que sustentem o sinal. - Não produzir qualquer linguagem diagnóstica; focar em padrões de frequência, intensidade e duração. Evitar rótulos pessoais.
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 estruturado contendo registros padronizados de comportamentos observados.
-
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 até 6.000 caracteres.
2.3.2 Especificação do Output
- Formato de output: O output deve ser um JSON contendo escores de atenção e interação social, níveis de risco e evidências estruturadas.
-
Exemplo de Estrutura de Output:
{ "aluno_id": "string|null", "score_atencao": 0-100, "score_interacao": 0-100, "nivel_risco": "baixo|moderado|alto", "incerteza": 0-1, "janelas": {"7d": {"aulas": number, "eventos_chave": [{"categoria": "string", "contagem": number}]}, "30d": {"aulas": number, "eventos_chave": [{"categoria": "string", "contagem": number}] } }, "criterios_acionados": ["string"], "evidencias_top3": ["string", ...], "requisitos_dados_faltantes": ["string"] } - Número de caracteres esperado: O JSON gerado deve ser claro e direto, com um tamanho estimado em 2.500 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: Utiliza lógica interna para calcular escores e níveis de risco.
- Busca Online: Não utiliza.
- Sistemas Externos: Não se conecta a sistemas externos.
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 gerada por este agente deve ser visível para o Agente de Síntese e Devolutiva ao Professor (RF 3).
2.3.6 Regras de Orquestração e Transição
Ao concluir sua execução, esse agente aciona o Agente de Síntese e Devolutiva ao Professor (RF 3).
RF 3. Agente de Síntese e Devolutiva ao Professor
3.1 Tarefa do Agente
Gerar síntese objetiva e plano de monitoramento prático com base nos escores e evidências, em linguagem não clínica e aplicada ao contexto de sala.
3.2 Prompt ou Instruções do Agente
# 1. Contexto e explicações sobre inputs iniciais Você está recebendo um JSON contendo escores de atenção e interação social, níveis de risco e evidências estruturadas. # 2. Objetivo Gerar síntese objetiva e plano de monitoramento prático com base nos escores e evidências, em linguagem não clínica e aplicada ao contexto de sala. # 3. Regras que você deve seguir para gerar sua resposta - Tamanho do briefing_texto: 120 a 180 palavras, tom neutro e colaborativo; evitar jargões clínicos e rótulos. - Estrutura do briefing_texto: (1) resumo dos padrões em bullets curtos; (2) impacto em aula quando houver; (3) fatores contextuais relevantes; (4) nível de risco e incerteza com linguagem prudente. - objetivos_proximos_7_dias: 3 ações SMART, específicas e observáveis (ex.: "Durante explicações, registrar 3 checagens de atenção a cada 10 min"). - indicadores_observaveis: 3-5 métricas simples (ex.: "nº de interrupções intensidade 2+", "minutos focado em tarefa individual"). - checklist_registro: sempre incluir data, duração estimada, contexto pedagógico, fatores contextuais, exemplos textuais curtos. - sinais_acionar_coordenacao: inclua gatilhos práticos (ex.: "2 ou mais aulas na semana com intensidade 3"; "conflitos repetidos com colegas"). - Se incerteza >=0.6, enfatize necessidade de mais dados antes de qualquer encaminhamento e ajuste recomendações para observação estruturada. - Nunca incluir recomendações terapêuticas ou diagnósticas; restringir-se a manejo de sala e observação. - Personalize o tom se preferencias_tom_opcionais.tom estiver presente, mantendo objetividade.
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 escores de atenção e interação social, níveis de risco e evidências estruturadas.
-
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 até 4.000 caracteres.
3.3.2 Especificação do Output
- Formato de output: O output deve ser um JSON contendo uma síntese objetiva e um plano de monitoramento prático.
-
Exemplo de Estrutura de Output:
{ "briefing_texto": "string", "plano_monitoramento": { "objetivos_proximos_7_dias": ["string", ...], "indicadores_observaveis": ["string", ...], "checklist_registro": ["string", ...], "sinais_acionar_coordenacao": ["string", ...] } } - Número de caracteres esperado: O JSON gerado deve ser claro e direto, com um tamanho estimado em 2.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
- 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.
3.3.6 Regras de Orquestração e Transição
A execução deste agente finaliza o fluxo. O JSON gerado é o resultado que deve ser disponibilizado ao professor.