Agente de IA para Planejamento de Turmas

Validar, padronizar e enriquecer os dados de matrícula e turmas para uso consistente na alocação.

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 matrícula 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 de um csv na interface da Prototipe AI, para acelerar o processo de validação.
• Tipo do input: O input inicial para o fluxo é um dataset de matrícula em formato CSV.
• Formatos Suportados: Esse agente deve ser capaz de receber dados de matrícula nos formatos: .csv.
• 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 dataset normalizado estruturado em JSON, contendo alunos válidos, turmas válidas, erros e avisos.
• Exemplo de Estrutura de Output:

   {
    "alunos_validos": [{"estudante_id": "123", "nivel_ensino": "medio", "preferencias_ordenadas": ["turma_a"], "prioridade": 0}],
    "turmas_validas": [{"turma_id": "turma_a", "nivel_ensino": "medio", "capacidade": 30, "meta_ocupacao": 0.95}],
    "erros": [{"tipo": "matricula_invalida", "registro_referencia": "estudante_456", "mensagem": "Status de matrícula não é 'ativa'."}],
    "avisos": [{"tipo": "duplicidade_estudante", "registro_referencia": "estudante_789", "mensagem": "Duplicata removida."}]
  } 

• Número de caracteres esperado: O JSON gerado deve ter um tamanho estimado em torno de 5.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 Consolidação de Critérios e Pesos (RF 2).

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

Ao concluir sua execução, esse agente aciona o Agente de Consolidação de Critérios e Pesos (RF 2).

Transformar critérios de negócio em parâmetros explícitos de restrição e escore para a alocação.

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 dataset normalizado em JSON, que corresponde aos dados processados pelo agente anterior.
• 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é 10.000 caracteres.

2.3.2 Especificação do Output

• Formato de output: O output deve ser um arquivo no formato JSON contendo parâmetros de resolução para a alocação de estudantes.
• Exemplo de Estrutura de Output:

   {
    "restricoes": {"nivel_estrito": true, "capacidade_estrita": true},
    "funcao_escore": {"pesos_preferencia": {"1": 1.0, "2": 0.6, "3": 0.3, "demais": 0.0}},
    "objetivos": {"max_satisfacao": true, "min_nao_alocados": true, "balancear_ocupacao": true},
    "criterios_desempate": {"chave": "estudante_id"},
    "meta_ocupacao_turma": {"turma_a": 0.95}
  } 

• Número de caracteres esperado: O JSON gerado deve ter um tamanho estimado em torno de 2.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 com parâmetros de resolução) deve ser visível para o Agente de Alocação Inicial de Estudantes (RF 3).

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

Ao concluir sua execução, esse agente aciona o Agente de Alocação Inicial de Estudantes (RF 3).

Gerar alocação inicial respeitando capacidade e nível de ensino, maximizando atendimento às preferências informadas.

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 dataset normalizado em JSON e parâmetros de resolução, que correspondem aos dados processados pelos agentes anteriores.
• 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é 12.000 caracteres.

3.3.2 Especificação do Output

• Formato de output: O output deve ser um arquivo no formato JSON contendo a alocação inicial de estudantes.
• Exemplo de Estrutura de Output:

   {
    "turmas": [{"turma_id": "turma_a", "nivel_ensino": "medio", "capacidade": 30, "estudantes": ["estudante_123"], "ocupacao": 1}],
    "estudantes_nao_alocados": [{"estudante_id": "estudante_456", "motivo": "sem_vaga_compatível"}],
    "metricas": {"taxa_atendimento_preferencias": 0.9, "total_nao_alocados": 1}
  } 

• Número de caracteres esperado: O JSON gerado deve ter um tamanho estimado em torno de 3.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.
• Calculadora: Utiliza lógica interna para calcular taxa de atendimento de preferências.
• 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 com alocação inicial) deve ser visível para o Agente de Otimização e Balanceamento Fino (RF 4).

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

Ao concluir sua execução, esse agente aciona o Agente de Otimização e Balanceamento Fino (RF 4).

Aprimorar a alocação inicial por meio de trocas locais para reduzir desequilíbrios entre turmas do mesmo nível e aumentar satisfação sem violar restriçõ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 uma alocação inicial de estudantes em JSON e parâmetros de resolução, que correspondem aos dados processados pelos agentes anteriores.
• 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é 15.000 caracteres.

4.3.2 Especificação do Output

• Formato de output: O output deve ser um arquivo no formato JSON contendo a alocação otimizada de estudantes.
• Exemplo de Estrutura de Output:

   {
    "turmas": [{"turma_id": "turma_a", "nivel_ensino": "medio", "capacidade": 30, "estudantes": ["estudante_123"], "ocupacao": 1}],
    "estudantes_nao_alocados": [{"estudante_id": "estudante_456", "motivo": "sem_vaga_compatível"}],
    "metricas": {"taxa_atendimento_preferencias": 0.9, "total_nao_alocados": 1, "desvio_padrao_ocupacao_por_nivel": {"medio": 0.1}, "ganhos_satisfacao": 5, "iteracoes": 100}
  } 

• Número de caracteres esperado: O JSON gerado deve ter um tamanho estimado em torno de 4.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: Utiliza lógica interna para calcular desvio padrão e ganhos de satisfação.
• 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 (JSON com alocação otimizada) deve ser visível para o Agente de Verificação Final e Geração de Saída (RF 5).

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

Ao concluir sua execução, esse agente aciona o Agente de Verificação Final e Geração de Saída (RF 5).

Validar restrições finais e produzir o JSON consolidado de turmas e estudantes, com métricas de qualidade.

5.3.1 Especificação do Input

• Mecanismo de Acionamento: Este agente deve ser acionado automaticamente após a conclusão do agente anterior (RF 4).
• Tipo do input: Este agente deve ser apto a receber como input uma alocação otimizada de estudantes em JSON, que corresponde aos dados processados pelos agentes anteriores.
• 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é 15.000 caracteres.

5.3.2 Especificação do Output

• Formato de output: O output deve ser um arquivo no formato JSON consolidado de turmas e estudantes, com métricas de qualidade.
• Exemplo de Estrutura de Output:

   {
    "turmas": [{"turma_id": "turma_a", "nivel_ensino": "medio", "estudantes": ["estudante_123"], "capacidade": 30, "taxa_ocupacao": 0.9, "atendimento_preferencias": {"n1": 10, "n2": 5, "n3": 2, "outros": 1}}],
    "estudantes_nao_alocados": [{"estudante_id": "estudante_456", "motivo": "excesso_capacidade"}],
    "metricas_gerais": {"taxa_atendimento_global": 0.85, "total_alunos": 100, "total_turmas": 10}
  } 

• Número de caracteres esperado: O JSON gerado deve ter um tamanho estimado em torno de 5.000 caracteres.

5.3.3 Parâmetros de Geração

• Modelo: GPT-5
• Temperatura: 0.6

5.3.4 Ferramentas do Agente

• Documentos: Não consulta.
• Calculadora: Utiliza lógica interna para calcular taxas de ocupação e atendimento global.
• Busca Online: Não utiliza.
• Sistemas Externos: Não utiliza.

5.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 consolidado) deve ser visível para o Agente de Atualização Incremental de Turmas (RF 6).

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

Ao concluir sua execução, esse agente aciona o Agente de Atualização Incremental de Turmas (RF 6).

Aplicar alterações de matrícula de forma incremental, minimizando impacto nas alocações existentes.

6.3.1 Especificação do Input

• Mecanismo de Acionamento: Este agente deve ser acionado automaticamente após a conclusão do agente anterior (RF 5).
• Tipo do input: Este agente deve ser apto a receber como input uma saída final consolidada de turmas e estudantes em JSON e um conjunto de alterações de matrícula.
• 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é 20.000 caracteres.

6.3.2 Especificação do Output

• Formato de output: O output deve ser um arquivo no formato JSON com a saída final atualizada e o diff das movimentações.
• Exemplo de Estrutura de Output:

   {
    "saida_final_atualizada": {
      "turmas": [{"turma_id": "turma_a", "nivel_ensino": "medio", "estudantes": ["estudante_123"], "capacidade": 30, "taxa_ocupacao": 0.9, "atendimento_preferencias": {"n1": 10, "n2": 5, "n3": 2, "outros": 1}}],
      "estudantes_nao_alocados": [{"estudante_id": "estudante_456", "motivo": "excesso_capacidade"}],
      "metricas_gerais": {"taxa_atendimento_global": 0.85, "total_alunos": 100, "total_turmas": 10}
    },
    "diff": {
      "movimentacoes": [{"estudante_id": "estudante_789", "de_turma_id": null, "para_turma_id": "turma_b", "motivo": "nova_matricula"}],
      "resumo": {"adicionados": 1, "removidos": 0, "realocados": 0}
    }
  } 

• Número de caracteres esperado: O JSON gerado deve ter um tamanho estimado em torno de 6.000 caracteres.

6.3.3 Parâmetros de Geração

• Modelo: GPT-5
• Temperatura: 0.6

6.3.4 Ferramentas do Agente

• Documentos: Não consulta.
• Calculadora: Utiliza lógica interna para recalcular métricas de turmas.
• Busca Online: Não utiliza.
• Sistemas Externos: Não utiliza.

6.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 atualizado) é o entregável final e não é passada para outros agentes internos.

6.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 usuário.