Agente de IA para Planejamento de Grade Curricular

29 de November de 2025 • Tempo de leitura: 5 min

Como criar um agente de IA que ajuda na organização e otimização da grade curricular com base nas preferências dos alunos.

Biblioteca de Prompts e Agentes

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 a criação de um agente de IA para planejamento de grade curricular. Essa documentação é um modelo de PRD ou Documento de Requisitos de Produto específicos para construção de Agentes de IA.

O objetivo é desenvolver um agente que automatize o planejamento de grades curriculares, equilibrando as preferências dos alunos com os requisitos obrigatórios dos cursos, reduzindo o tempo e o esforço manual envolvidos no processo.

2. Contexto e Problema

Instituições de ensino enfrentam dificuldades significativas ao tentar equilibrar as preferências dos alunos com os requisitos curriculares obrigatórios. O processo atual de planejamento de grade é manual e demorado, resultando em ineficiências e insatisfações tanto para alunos quanto para administradores.

Os problemas específicos incluem:

  • Dificuldade em balancear as preferências dos alunos com os requisitos curriculares obrigatórios.
  • Processo demorado e manual de planejamento da grade curricular.

3. Impactos Esperados

Com a implementação deste agente de IA, espera-se alcançar:

  • Otimização da grade curricular, alinhando preferências dos alunos e requisitos obrigatórios de maneira eficiente.
  • Redução do tempo necessário para o planejamento de grades curriculares.
  • Aumento da satisfação dos alunos ao ver suas preferências consideradas no planejamento curricular.

4. Visão Geral da Solução

O agente de IA para planejamento de grade curricular analisa dados de preferências dos alunos e requisitos curriculares, propondo uma grade otimizada e ajustando-a dinamicamente conforme mudanças nas preferências ou requisitos. A seguir são detalhadas todas as regras de negócio e especificações funcionais necessárias para que esse agente atue de forma eficiente e autônoma na organização das grades curriculares.

A solução consiste em um fluxo de automação composto por 4 agentes de IA. O processo inicia com a consolidação dos dados de preferências e requisitos e termina com a geração de uma grade curricular otimizada.

Agentes Função Principal
Agente de Consolidação de Dados para Planejamento de Grade (RF 1) Validar, padronizar e consolidar dados de preferências de alunos, requisitos curriculares e oferta de disciplinas.
Agente de Preparação do Modelo de Otimização da Grade (RF 2) Converter dados consolidados em um modelo de otimização parametrizado.
Agente de Execução de Chamada à API (RF 3) Realizar chamada à API do solver de otimização para obter a solução do modelo.
Agente de Tratamento da Solução e Geração da Grade Final (RF 4) Interpretar a saída do solver, construir a grade final e apontar ajustes possíveis.

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á.

Ver Agente na Prototipe AI

6. Requisitos Funcionais

RF 1. Agente de Consolidação de Dados para Planejamento de Grade

1.1 Tarefa do Agente

Validar, padronizar e consolidar dados de preferências de alunos, requisitos curriculares e oferta de disciplinas, gerando um payload único e consistente para otimização.

1.2 Prompt ou Instruções do Agente 
 # 1. Contexto e explicações sobre inputs iniciais
Você está recebendo dados de preferências dos alunos, requisitos curriculares e oferta de disciplinas em formato JSON. Este conjunto de dados precisa ser validado, padronizado e consolidado para otimização da grade curricular.

# 2. Objetivo
Gerar um payload único e consistente para otimização da grade curricular, garantindo a validade e a integridade dos dados recebidos.

# 3. Regras que você deve seguir para gerar sua resposta
- Verifique a presença e o tipo das chaves raiz: alunos[array], preferencias[array], requisitos_curriculares[array], oferta_disciplinas[array]. Se qualquer uma faltar ou não for array, retorne erro com campo "erro": {"campo": , "mensagem": } e não prossiga às demais regras.
- Converta id_aluno, id_disciplina e turma para UPPERCASE, removendo espaços e acentos. Mantenha cópia do valor original em campos auxiliary_id_original quando houver alteração.
- Em preferencias, se houver múltiplos registros para o mesmo par (id_aluno, id_disciplina), mantenha apenas o de maior prioridade; em empates, mantenha o primeiro por menor índice.
- Para cada (aluno, disciplina) cruze com requisitos do curso do aluno. Se tipo=obrigatoria e a disciplina não estiver em historico_disciplinas_aprovadas, marque obrigatoriedade="obrigatoria".

# 4. Exemplo de Output que você deve produzir
{"matriz_aluno_disciplina": [{"id_aluno": "A001", "id_disciplina": "MAT101", "score_preferencia": 0.85, "obrigatoriedade": "obrigatoria", "periodo_sugerido": 2}], "mapa_horarios": {"MAT101-T1": [{"dia": "seg", "inicio": "08:00", "fim": "10:00"}]}, "capacidade_turma": {"MAT101-T1": 40}, "creditos_disciplina": {"MAT101": 4}, "limites_creditos": {"A001": {"min": 12, "max": 24}}, "prerequisitos": [{"id_disciplina": "CAL202", "requires": ["CAL101"]}], "prerequisitos_satisfeitos": [{"id_aluno": "A001", "id_disciplina": "CAL202", "ok": false, "faltantes": ["CAL101"]}], "alunos_contexto": [{"id_aluno": "A001", "curso": "Engenharia", "disponibilidade": [{"dia": "seg", "inicio": "08:00", "fim": "18:00"}]}], "inconsistencias": [], "versao_dados": {"hash_preferencias": "abc123", "hash_oferta": "def456", "gerado_em": "2025-11-29T07:38:00Z"}}
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 preferências, requisitos e oferta de disciplinas 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 na interface da Prototipe AI, para acelerar o processo de validação.
  • Tipo do input: O input inicial para o fluxo é um arquivo JSON.
  • 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é 100.000 caracteres.

1.3.2 Especificação do Output

  • Formato de output: O output deve ser um arquivo no formato JSON contendo a matriz de aluno-disciplina consolidada e demais dados necessários para otimização.
  • Exemplo de Estrutura de Output: 
     {"matriz_aluno_disciplina": [{"id_aluno": "A001", "id_disciplina": "MAT101", "score_preferencia": 0.85, "obrigatoriedade": "obrigatoria", "periodo_sugerido": 2}], "mapa_horarios": {"MAT101-T1": [{"dia": "seg", "inicio": "08:00", "fim": "10:00"}]}, "capacidade_turma": {"MAT101-T1": 40}, "creditos_disciplina": {"MAT101": 4}, "limites_creditos": {"A001": {"min": 12, "max": 24}}, "prerequisitos": [{"id_disciplina": "CAL202", "requires": ["CAL101"]}], "prerequisitos_satisfeitos": [{"id_aluno": "A001", "id_disciplina": "CAL202", "ok": false, "faltantes": ["CAL101"]}], "alunos_contexto": [{"id_aluno": "A001", "curso": "Engenharia", "disponibilidade": [{"dia": "seg", "inicio": "08:00", "fim": "18:00"}]}], "inconsistencias": [], "versao_dados": {"hash_preferencias": "abc123", "hash_oferta": "def456", "gerado_em": "2025-11-29T07:38:00Z"}}
  • Número de caracteres esperado: O JSON gerado deve ter um tamanho aproximado de 10.000 caracteres, podendo variar conforme a complexidade dos dados.

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

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

Ao concluir sua execução, esse agente aciona o Agente de Preparação do Modelo de Otimização da Grade (RF 2).

RF 2. Agente de Preparação do Modelo de Otimização da Grade

2.1 Tarefa do Agente

Converter dados consolidados em um modelo de otimização (ILP/MILP) parametrizado, pronto para execução por um solver externo.

2.2 Prompt ou Instruções do Agente 
 # 1. Contexto e explicações sobre inputs iniciais
Você está recebendo um objeto JSON com dados consolidados de preferências dos alunos, requisitos curriculares e oferta de disciplinas. Este conjunto de dados precisa ser convertido em um modelo de otimização parametrizado.

# 2. Objetivo
Converter os dados consolidados em um modelo de otimização (ILP/MILP) pronto para execução por um solver externo.

# 3. Regras que você deve seguir para gerar sua resposta
- Crie variáveis binárias x_{aluno}_{disciplina}_{turma} apenas para turmas cujos horários estejam dentro de pelo menos um bloco de disponibilidade do aluno e que não tenham prerequisitos pendentes.
- A utilidade de cada variável é score_preferencia_efetivo = score_preferencia + bonus_obrigatoria, onde bonus_obrigatoria=0.20 se obrigatoriedade="obrigatoria", caso contrário 0.00.
- Para cada turma_global t: Σ_alunos x_{a,*,t} <= capacidade_turma[t].
- Para cada aluno a e cada par de turmas (t1,t2) com sobreposição no mesmo dia, imponha x_{a,*,t1} + x_{a,*,t2} <= 1.
- Para cada aluno a: Σ_(todas variáveis de a) creditos_disciplina[id_disciplina]*x >= limites_creditos[a].min e <= limites_creditos[a].max.

# 4. Exemplo de Output que você deve produzir
{"model": {"variables": [{"name": "x_A001_MAT101_T1", "type": "binary"}], "objective": {"sense": "maximize", "expression": "sum(score_preferencia_efetivo * x_aluno_disciplina_turma) - lambda_choque * sum(choques) - lambda_credito * desvios_creditos"}, "constraints": [{"name": "capacidade_MAT101_T1", "expression": "sum(x_*_MAT101_T1) <= 40"}, {"name": "credito_min_A001", "expression": "sum(creditos* x_A001_*) >= 12"}], "parameters": {"lambda_choque": 10, "lambda_credito": 0.5, "fairness": false}}, "metadata": {"timestamp": "2025-11-29T07:38:00Z", "schema": "ilp_generic_v1"}}
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 do agente anterior (RF 1).
  • Tipo do input: Este agente deve ser apto a receber como input um JSON consolidado de dados de preferências e requisitos.
  • 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.

2.3.2 Especificação do Output

  • Formato de output: O output deve ser um arquivo no formato JSON contendo o modelo de otimização ILP/MILP parametrizado.
  • Exemplo de Estrutura de Output: 
     {"model": {"variables": [{"name": "x_A001_MAT101_T1", "type": "binary"}], "objective": {"sense": "maximize", "expression": "sum(score_preferencia_efetivo * x_aluno_disciplina_turma) - lambda_choque * sum(choques) - lambda_credito * desvios_creditos"}, "constraints": [{"name": "capacidade_MAT101_T1", "expression": "sum(x_*_MAT101_T1) <= 40"}, {"name": "credito_min_A001", "expression": "sum(creditos* x_A001_*) >= 12"}], "parameters": {"lambda_choque": 10, "lambda_credito": 0.5, "fairness": false}}, "metadata": {"timestamp": "2025-11-29T07:38:00Z", "schema": "ilp_generic_v1"}}
  • Número de caracteres esperado: O JSON gerado deve ter um tamanho aproximado de 5.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 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 deve ser visível para o Agente de Execução de Chamada à API (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 Chamada à API (RF 3).

RF 3. Agente de Execução de Chamada à API

3.1 Tarefa do Agente

Realizar chamada à API do sistema curriculum_optimization_solver para obter a solução do modelo ILP/MILP preparado.

3.2 Prompt ou Instruções do Agente 
 # 1. Contexto e explicações sobre inputs iniciais
Você está recebendo um payload JSON pronto contendo o campo "model" no schema ilp_generic_v1 e "parameters" opcionais conforme o solver.

# 2. Objetivo
Executar a chamada à API do sistema curriculum_optimization_solver para obter a solução do modelo de otimização.

# 3. Regras que você deve seguir para gerar sua resposta
- Invoque a API do sistema curriculum_optimization_solver passando o payload JSON recebido.
- A ferramenta retornará a solução do modelo, incluindo status, valor do objetivo e alocações.
- Seu output final deve ser exclusivamente o JSON retornado pela API, sem nenhum texto ou formatação adicional.
- Em caso de falha na chamada da API, o processo deve ser interrompido e o erro registrado para análise manual.

# 4. Exemplo de Output que você deve produzir
{"status": "optimal", "objective_value": 123.45, "assignments": [{"id_aluno": "A001", "id_disciplina": "MAT101", "turma": "T1", "x": 1}], "shadow_prices": [], "solver_logs": "..."}
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 do agente anterior (RF 2).
  • Tipo do input: Este agente deve ser apto a receber como input um payload JSON pronto para execução no solver.
  • 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é 5.000 caracteres.

3.3.2 Especificação do Output

  • Formato de output: O output final e único deste agente deve ser o JSON retornado pela API do solver.
  • Exemplo de Estrutura de Output: 
     {"status": "optimal", "objective_value": 123.45, "assignments": [{"id_aluno": "A001", "id_disciplina": "MAT101", "turma": "T1", "x": 1}], "shadow_prices": [], "solver_logs": "..."}
  • Número de caracteres esperado: O JSON gerado deve ter um tamanho aproximado de 2.000 caracteres.

3.3.3 Parâmetros de Geração

  • Modelo: GPT-5
  • Temperatura: Não se aplica (uso de ferramenta)

3.3.4 Ferramentas do Agente

  • Documentos: Não consulta documentos externos.
  • Calculadora: Não utiliza.
  • Busca Online: Não utiliza.
  • Sistemas Externos: O agente deverá enviar o JSON recebido para a API externa do solver e retornar o JSON de resposta.

3.3.5 Memória

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

Ao concluir sua execução, esse agente aciona o Agente de Tratamento da Solução e Geração da Grade Final (RF 4).

RF 4. Agente de Tratamento da Solução e Geração da Grade Final

4.1 Tarefa do Agente

Interpretar a saída do solver, construir a grade final por aluno e por turma, explicar decisões e apontar ajustes possíveis quando a solução for inviável ou subótima.

4.2 Prompt ou Instruções do Agente 
 # 1. Contexto e explicações sobre inputs iniciais
Você está recebendo um objeto JSON com "solver_result" (status, objective_value, assignments, logs) e "contexto" (cópia do output do Agente de Consolidação para referência de horários, créditos e nomes).

# 2. Objetivo
Interpretar a saída do solver, construir a grade final e gerar um relatório explicativo das decisões e ajustes possíveis.

# 3. Regras que você deve seguir para gerar sua resposta
- Para cada assignment com x=1, recupere horários via mapa_horarios[turma_global] e créditos via creditos_disciplina[id_disciplina].
- Monte grade_json.por_aluno ordenando disciplinas por dia (seg..dom), depois por inicio e, em empates, por id_disciplina.
- Monte grade_json.por_turma listando alunos_alocados ordenados por id_aluno.
- Calcule para cada aluno: creditos_totais = Σ creditos; satisfacao_media = média dos score_preferencia (sem bônus) das disciplinas alocadas.
- Se status ∈ {"infeasible", "unbounded", "error"}, gere campo diagnostico com: restricoes_suspeitas (lista textual com causas prováveis) e propostas_de_relaxacao.

# 4. Exemplo de Output que você deve produzir
{"grade_json": {"por_aluno": [{"id_aluno": "A001", "disciplinas": [{"id_disciplina": "MAT101", "turma": "T1", "horarios": [{"dia": "seg", "inicio": "08:00", "fim": "10:00"}], "creditos": 4}]}], "por_turma": [{"turma": "MAT101-T1", "alunos_alocados": ["A001", "A007"]}]}, "relatorio_markdown": "# Resultado da Otimização\n- Status: optimal\n- Função objetivo: 123.45\n## Satisfação média por aluno\n...\n## Choques evitados\n...\n## Recomendações de ajuste\n..."}
4.3 Configurações do Agente

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 com o resultado do solver e o contexto de horários e créditos.
  • 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.

4.3.2 Especificação do Output

  • Formato de output: O output deve ser um JSON contendo a grade final por aluno e por turma, além de um relatório em Markdown.
  • Exemplo de Estrutura de Output: 
     {"grade_json": {"por_aluno": [{"id_aluno": "A001", "disciplinas": [{"id_disciplina": "MAT101", "turma": "T1", "horarios": [{"dia": "seg", "inicio": "08:00", "fim": "10:00"}], "creditos": 4}]}], "por_turma": [{"turma": "MAT101-T1", "alunos_alocados": ["A001", "A007"]}]}, "relatorio_markdown": "# Resultado da Otimização\n- Status: optimal\n- Função objetivo: 123.45\n## Satisfação média por aluno\n...\n## Choques evitados\n...\n## Recomendações de ajuste\n..."}
  • Número de caracteres esperado: O JSON gerado deve ter um tamanho aproximado de 8.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 documentos externos.
  • Calculadora: Não utiliza.
  • Busca Online: Não utiliza.
  • Sistemas Externos: Não se conecta a sistemas externos.

4.3.5 Memória

  • Visibilidade das Instruções (Prompt): As instruções não são visíveis para agentes subsequentes.
  • Visibilidade da Resposta: A resposta gerada por este agente é o resultado 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. A grade final gerada é o resultado que deve ser disponibilizado ao usuário.

Posts Relacionados

© 2025 prototipe.ai. Todos os direitos reservados.