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 de Personalização de Atividades Extracurriculares. 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 é utilizar dados de desempenho e preferências dos alunos para recomendar atividades extracurriculares personalizadas, criando perfis individuais que destacam interesses e habilidades, facilitando a personalização das atividades.
2. Contexto e Problema
Problemas Específicos
O agente deve resolver questões relacionadas à falta de personalização nas atividades oferecidas, que não atendem às necessidades individuais dos alunos, e à dificuldade em identificar interesses e habilidades específicas dos alunos.
- Falta de personalização nas atividades oferecidas, não atendendo às necessidades individuais dos alunos.
- Dificuldade em identificar interesses e habilidades específicas dos alunos.
3. Impactos Esperados
A implementação deste agente visa alcançar os seguintes resultados:
- Melhorar a personalização das atividades extracurriculares oferecidas aos alunos.
- Aumentar o engajamento dos alunos nas atividades extracurriculares.
- Facilitar a identificação de interesses e habilidades específicas dos alunos.
- Otimizar o uso de dados de desempenho e preferências dos alunos para personalização de atividades.
4. Visão Geral da Solução
O agente de IA para personalização de atividades extracurriculares analisa dados de desempenho e preferências dos alunos, criando perfis individuais que destacam interesses e habilidades. 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 recomendação de atividades personalizadas.
A solução consiste em um fluxo de automação composto por dois agentes de IA. O processo inicia com a consolidação do perfil do aluno e termina com a geração de recomendações de atividades extracurriculares.
| Agentes | Função Principal |
|---|---|
Agente de Consolidação de Perfil do Aluno (RF 1)
| Consolidar e atualizar um perfil unificado do aluno a partir de dados de desempenho, respostas de questionários e histórico de atividades. |
Agente Gerador de Recomendações de Atividades Extracurriculares (RF 2)
| Gerar uma lista priorizada de atividades extracurriculares alinhadas ao perfil consolidado do aluno, com justificativas e parâmetros de execuçã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 aluno receberá. Explore os links abaixo para entender melhor a solução em ação.
6. Requisitos Funcionais
RF 1. Agente de Consolidação de Perfil do Aluno
1.1 Tarefa do Agente
Consolidar e atualizar um perfil unificado do aluno a partir de dados de desempenho, respostas de questionários e histórico de atividades, produzindo um perfil pronto para recomendação.
1.2 Prompt ou Instruções do Agente
# 1. Contexto e explicações sobre inputs iniciais Você está recebendo dados de desempenho acadêmico, respostas de questionários e histórico de atividades de um aluno. Este conjunto de dados é utilizado para criar um perfil consolidado do aluno. # 2. Objetivo Consolidar e atualizar um perfil unificado do aluno a partir de dados de desempenho, respostas de questionários e histórico de atividades, produzindo um perfil pronto para recomendação. # 3. Regras que você deve seguir para gerar sua resposta - Normalização de interesses: padronize todos os interesses para minúsculas sem acentuação, mapeando sinônimos para uma taxonomia simples (ex.: "futebol", "esportes coletivos", "programação", "artes visuais", "música", "ciência", "debate", "voluntariado"). - Priorização de habilidades: combine habilidades_desejadas com evidências do histórico (desempenho e feedback). Atribua peso 0–1 por habilidade: 0.6 se declarada pelo aluno, +0.3 se há bom desempenho relacionado, +0.1 se tendência acadêmica positiva na área correlata; limite peso máximo em 1.0. - Preferência de modalidade: se preferencia_atividade for sem_preferencia, defina pela observação do histórico (>=60% das atividades concluídas com desempenho alto em grupo → grupo; caso contrário → individual). Se histórico insuficiente, mantenha sem_preferencia. - Disponibilidade: copie disponibilidade_semanal como número; se ausente, defina como null e registre "disponibilidade_faltante" em gaps_de_dados e qualidade_dados ≤ "media". - Competência por área: derive niveis_competencia_por_area mapeando disciplinas/atividades para áreas correspondentes. Regras: média >=8 ou desempenho alto → avançado; 6–7.9 ou desempenho médio → intermediário; <6 ou desempenho baixo → iniciante. - Objetivos de desenvolvimento: inclua objetivos para cada lacuna acadêmica relevante e cada habilidade_desejada com peso ≥0.6, evitando duplicidade. - Restrições: copie restricoes de metadados e acrescente restrições inferidas do histórico (ex.: indisponibilidade de finais de semana se feedback mencionar). Não invente restrições sem evidência textual ou campo específico. - Fortes e lacunas: fortes = áreas com nível avançado ou tendência positiva; lacunas = áreas com nível iniciante ou tendência negativa. Liste no máximo 5 itens por lista, ordenados por relevância (nota/tendência primeiro, depois histórico). - Prontidão para carga horária: alta se disponibilidade ≥5h/sem e não houver lacunas críticas; média se 2–4h/sem ou lacunas moderadas; baixa se <2h/sem, ou múltiplas lacunas críticas, ou restrições severas. - Qualidade dos dados: alta se houver ao menos: interesse_principal, disponibilidade, e algum histórico ou notas em ≥3 disciplinas; média se faltar um desses; baixa se faltarem dois ou mais. Preencha gaps_de_dados com os campos ausentes específicos. - Consistência temporal: em caso de conflito entre respostas recentes e histórico antigo, priorize as informações mais recentes. Se conflito não resolvido, registre o item em gaps_de_dados com "conflito_[campo]". - Persistência não-PII: não inclua dados sensíveis ou PII além de id_aluno no perfil. Redija campos de texto de forma neutra e objetiva. - Determinismo: mantenha a estrutura e ordenação de chaves do JSON como no expected_output e ordene listas por regra explícita (ver itens 2, 8).
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 dados de desempenho acadêmico, respostas de questionários e histórico de atividades via API. Na fase de testes, os dados serão enviados pelo agente diretamente por upload de um arquivo JSON na interface da Prototipe AI, para acelerar o processo de validação.
- Tipo do input: O input inicial para o fluxo é um arquivo JSON com dados de desempenho acadêmico, respostas de questionários e histórico de atividades.
-
Formatos Suportados: Esse agente deve ser capaz de receber dados nos formatos:
.json. - Número de caracteres esperado: Este agente deve ter capacidade para processar um input de texto com até 30.000 caracteres.
1.3.2 Especificação do Output
- Formato de output: O output deve ser um arquivo no formato JSON contendo o perfil consolidado do aluno. A estrutura deve seguir rigorosamente o modelo especificado no prompt.
-
Exemplo de Estrutura de Output:
{ "perfil": { "id_aluno": "string", "interesses_normalizados": ["string"], "habilidades_priorizadas": [{"habilidade": "string", "peso": number}], "preferencia_modalidade": "individual|grupo|sem_preferencia", "disponibilidade_horas_semana": number, "niveis_competencia_por_area": [{"area": "string", "nivel": "iniciante|intermediario|avancado"}], "objetivos_desenvolvimento": ["string"], "restricoes": ["string"], "contexto_academico": {"fortes": ["string"], "lacunas": ["string"]}, "prontidao_para_carga_horaria": "baixa|media|alta", "qualidade_dados": "baixa|media|alta", "gaps_de_dados": ["string"] } } - Número de caracteres esperado: O JSON gerado deve ter um tamanho estimado em torno de 3.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 Gerador de Recomendações de Atividades Extracurriculares (RF 2).
1.3.6 Regras de Orquestração e Transição
Ao concluir sua execução, esse agente aciona o Agente Gerador de Recomendações de Atividades Extracurriculares (RF 2).
RF 2. Agente Gerador de Recomendações de Atividades Extracurriculares
2.1 Tarefa do Agente
Gerar uma lista priorizada de atividades extracurriculares alinhadas ao perfil consolidado do aluno, com justificativas e parâmetros de execução.
2.2 Prompt ou Instruções do Agente
# 1. Contexto e explicações sobre inputs iniciais Você está recebendo um perfil consolidado do aluno, que contém dados normalizados de interesses, habilidades e preferências. # 2. Objetivo Gerar uma lista priorizada de atividades extracurriculares alinhadas ao perfil consolidado do aluno, com justificativas e parâmetros de execução. # 3. Regras que você deve seguir para gerar sua resposta - Fonte de candidatas: se catalogo_de_atividades for fornecido, use-o integralmente; se não, gere recomendações por categorias padrão (ex.: "esportes coletivos", "programação", "música", "artes visuais", "clube de ciências", "debate", "voluntariado"), definindo atividade_id como null e titulo igual à categoria. - Filtragem básica: descarte atividades incompatíveis com restricoes do perfil ou com tempo_estimado_semana > disponibilidade_horas_semana (tolerância de +1h apenas se prontidao_para_carga_horaria = alta). - Modalidade: priorize atividades que combinem com preferencia_modalidade; se sem_preferencia, não penalize modalidade. - Nível: alinhe nivel_recomendado da atividade ao nível do perfil na área correspondente; se desconhecido, prefira iniciante ou intermediário, evitando avançado quando niveis_competencia_por_area indicar iniciante. - Cálculo do score de aderência (0–100): 40 pontos por alinhamento de interesses (categoria ∈ interesses_normalizados), 25 por aderência de habilidades_priorizadas (soma dos pesos das habilidades relevantes ×25, limitado a 25), 20 por suporte a objetivos_desenvolvimento, 10 por adequação de disponibilidade (0–10 linear, 10 quando tempo_estimado_semana ≤ disponibilidade), 5 por diversidade (bônus se a categoria não repetida nas top recomendações). Arredonde para inteiro. - Ordenação: ordene por aderencia_score desc, depois por menor tempo_estimado_semana, depois por correspondência de modalidade. - Diversidade: garanta no mínimo 2 áreas distintas nas top 3 recomendações quando possível. Se não for possível, marque diversidade_de_areas = false. - Tamanho da lista: retorne de 3 a 5 recomendações; se houver menos candidatas elegíveis, retorne as existentes e inclua perguntas_complementares para ampliar dados. - Justificativas: cada recomendação deve citar explicitamente até 3 fatores do perfil (ex.: interesse X, habilidade Y com peso Z, objetivo Z, disponibilidade de N horas, nível M), sem usar linguagem vaga. - Restrições e requisitos: copie requisitos da atividade; liste restricoes_consideradas a partir do perfil e das restricoes_incompatibilidades filtradas. Nunca recomende atividade que viole restrições. - Dados insuficientes: se perfil.qualidade_dados = "baixa", não bloquear recomendações; inclua perguntas_complementares específicas (ex.: disponibilidade, objetivo principal, experiência prévia) e prefira categorias padrão de nível iniciante. - Proxima ação: defina instrução objetiva (ex.: "Deseja inscrever-se?", ou "Quer ver opções de horário?"), adequada à modalidade e tempo estimado. - Determinismo: mantenha a estrutura de chaves do expected_output; preencha uso_catalogo_padrao conforme origem; compute metricas.total_candidatas antes dos filtros e metricas.total_recomendadas após filtros.
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 arquivo JSON contendo o perfil consolidado do aluno.
-
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é 3.000 caracteres.
2.3.2 Especificação do Output
- Formato de output: O output deve ser um arquivo no formato JSON contendo as recomendações de atividades extracurriculares. A estrutura deve seguir rigorosamente o modelo especificado no prompt.
-
Exemplo de Estrutura de Output:
{ "recomendacoes": [{"atividade_id": "string|null", "categoria": "string", "titulo": "string", "justificativa": "string", "aderencia_score": number, "modalidade": "individual|grupo", "tempo_estimado_semana": number, "nivel": "iniciante|intermediario|avancado", "requisitos": ["string"], "proxima_acao": "string"}], "filtros_aplicados": {"respeitou_disponibilidade": true, "respeitou_restricoes": true, "diversidade_de_areas": true}, "restricoes_consideradas": ["string"], "uso_catalogo_padrao": boolean, "perguntas_complementares": ["string"], "metricas": {"total_candidatas": number, "total_recomendadas": number}} - Número de caracteres esperado: O JSON gerado deve ter um tamanho estimado em torno de 3.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: Não utiliza.
- 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 é o entregável final e não é passada para outros agentes internos.
2.3.6 Regras de Orquestração e Transição
A execução deste agente finaliza o fluxo. As recomendações geradas são o resultado que deve ser disponibilizado ao aluno.