PrototipeAI | Agente de IA para Agendamento de Atividades Recreativas

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 para Agendamento de Atividades Recreativas. 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 é coordenar eficazmente os horários e recursos disponíveis para atividades recreativas nas escolas, evitando conflitos de agendamento e maximizando o uso dos recursos disponíveis.

2. Contexto e Problema

Cenário Atual

As escolas enfrentam desafios significativos na coordenação de atividades recreativas devido à disponibilidade limitada de recursos e à necessidade de evitar conflitos de agendamento. Os problemas específicos incluem:

Coordenação ineficaz de horários e recursos para atividades recreativas.
Conflitos de agendamento que resultam em uso ineficiente de recursos.
Falta de um sistema automatizado para atualizar dinamicamente os agendamentos com base em mudanças e feedback.

Problemas Identificados

Consumo de tempo: O processo manual de coordenação de atividades consome tempo valioso dos coordenadores e professores, que poderia ser utilizado em outras atividades educacionais.
Conflitos de agendamento: A falta de um sistema eficiente leva a conflitos frequentes de agendamento, prejudicando a experiência dos alunos.
Uso ineficiente de recursos: Recursos disponíveis não são utilizados de forma otimizada, levando a desperdício e subutilização.

3. Impactos Esperados

A implementação deste agente de IA visa alcançar os seguintes resultados:

Reduzir o tempo de coordenação de atividades em pelo menos 70%.
Otimizar o uso de recursos disponíveis nas escolas.
Eliminar conflitos de agendamento através de uma coordenação eficaz e automatizada.
Melhorar a experiência dos alunos ao oferecer um cronograma de atividades recreativas bem organizado.

4. Visão Geral da Solução

O agente de IA para agendamento de atividades recreativas coordena horários e recursos disponíveis nas escolas, evitando conflitos de agendamento e maximizando o uso dos recursos. 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 organização de atividades recreativas nas escolas.

A solução consiste em um fluxo de automação composto por 4 agentes de IA. O processo inicia com a preparação dos dados de agenda e termina com a execução de chamadas à API para persistir o cronograma aprovado.

A execução dos agentes é sequencial e linear, seguindo a ordem definida na tabela abaixo.

Agentes	Função Principal
`Agente de Preparação de Dados de Agenda e Recursos` (RF 1)	Validar, consolidar e padronizar os dados de recursos e disponibilidades para geração de cronogramas.
`Agente de Geração de Cronograma Otimizado` (RF 2)	Sugerir um cronograma sem conflitos que maximize o uso dos recursos e atenda às preferências e políticas definidas.
`Agente de Validação de Conflitos e Ajustes Finais` (RF 3)	Revisar o cronograma sugerido, detectar conflitos residuais e aplicar ajustes simples.
`Agente de Execução de Chamada à API` (RF 4)	Realizar chamada à API do sistema de agendamento para persistir o cronograma aprovado.

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 a escola receberá. Explore os links abaixo para entender melhor a solução em ação.

Ver Agente na Prototipe AI

6. Requisitos Funcionais

RF 1. Agente de Preparação de Dados de Agenda e Recursos

1.1 Tarefa do Agente

Validar, consolidar e padronizar os dados de recursos e disponibilidades para que possam ser usados na geração de cronogramas.

1.2 Prompt ou Instruções do Agente

 # 1. Contexto e explicações sobre inputs iniciais
Você está recebendo dados brutos de recursos, disponibilidades e pedidos de atividades recreativas das escolas.

# 2. Objetivo
Validar, consolidar e padronizar esses dados para que possam ser usados na geração de cronogramas otimizados e sem conflitos.

# 3. Regras que você deve seguir para gerar sua resposta
- Converta todas as datas e horas para formato ISO 8601 sem timezone e valide que inicio < fim; se inválido, remova o intervalo e registre em dados_normalizados.alertas.
- Padronize chaves ausentes: se capacidade ausente, defina capacidade=25; se tempo_setup_min ausente, defina 0.
- Deduplicate por id de recurso; em duplicatas, mantenha o último e registre ids_removidos.
- Subtraia blocos de bloqueios das disponibilidades para calcular janelas_livres não sobrepostas por recurso, preservando ordem cronológica.
- Quebre janelas_livres em múltiplos de 5 minutos para facilitar encaixes; não gere fragmentos < 10 minutos.
- Construa matriz_incompatibilidades a partir de restricoes e incompatibilidades declaradas em cada recurso; se não houver, retorne lista vazia.
- Classifique preferências_horario em faixas: manha(08:00-12:00), tarde(12:00-17:00), noite(17:00-21:00) para uso consistente no próximo agente.
- Gere calendario_estruturado.janelas_livres já descontando tempo_setup_min antes e depois de cada atividade hipotética (bloqueie setup apenas na fronteira da janela, sem tornar negativa).

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 brutos de recursos e disponibilidades via API. Na fase de testes, os dados serão enviados pelo 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 conjunto de dados estruturados em JSON que descrevem recursos, disponibilidades, bloqueios e pedidos de atividades.
Formatos Suportados: Esse agente deve ser capaz de receber dados no formato: .json.
Número de caracteres esperado: Este agente deve ter capacidade para processar um input de texto com até 50.000 caracteres.

1.3.2 Especificação do Output

Formato de output: O output deve ser um arquivo no formato JSON contendo dados normalizados, calendário estruturado e matriz de incompatibilidades.

Exemplo de Estrutura de Output:

 {
  "dados_normalizados": {
    "recursos": [...],
    "disponibilidades": [...],
    "bloqueios": [...],
    "pedidos_atividade": [...],
    "politicas": {...}
  },
  "calendario_estruturado": [
    {"recurso_id": "quadra_1", "janelas_livres": [{"inicio": "2025-12-21T10:00", "fim": "2025-12-21T11:00"}, {"inicio": "2025-12-21T11:30", "fim": "2025-12-21T12:00"}]}
  ],
  "matriz_incompatibilidades": [{"recurso_id": "quadra_1", "incompatibilidades": ["aula_educ_fisica_9A"]}],
  "indicadores_base": {"total_recursos": 2, "total_pedidos": 1}
}

Número de caracteres esperado: O JSON gerado terá um tamanho aproximado de 5.000 caracteres.

1.3.3 Parâmetros de Geração

Modelo: GPT-5
Temperatura: 0.7

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 Geração de Cronograma Otimizado (RF 2).

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

Ao concluir sua execução, esse agente aciona o Agente de Geração de Cronograma Otimizado (RF 2).

RF 2. Agente de Geração de Cronograma Otimizado

2.1 Tarefa do Agente

Sugerir um cronograma sem conflitos que maximize o uso dos recursos e atenda às preferências e políticas definidas.

2.2 Prompt ou Instruções do Agente

 # 1. Contexto e explicações sobre inputs iniciais
Você está recebendo dados normalizados, calendário estruturado e matriz de incompatibilidades gerados pelo agente anterior.

# 2. Objetivo
Sugerir um cronograma otimizado que maximize a utilização dos recursos disponíveis e atenda às preferências e políticas definidas.

# 3. Regras que você deve seguir para gerar sua resposta
- Critérios de viabilidade para alocar uma atividade: (a) janela_livre >= duracao_min, (b) capacidade do recurso >= participantes, (c) recurso.tipo compatível com preferencias_recurso_tipo quando houver, (d) recurso não consta na matriz_incompatibilidades para a atividade.
- Objetivo de seleção para cada atividade: maximize score = (peso_preferencia_horario + peso_tipo_recurso + peso_prioridade_politica) - penalidades, onde: peso_preferencia_horario=2 se horário aderente à faixa preferida, 1 se adjacente, 0 se fora; peso_tipo_recurso=2 se tipo está na preferência, 1 se compatível porém não preferido, 0 se não preferido; peso_prioridade_politica é soma dos pesos aplicáveis do campo politicas.prioridades.
- Penalidades determinísticas: -2 se criar ociosidade < 10 min na janela, -1 se alocar fora da faixa escolar, -3 se colidir com bloqueios (proibido, então nem considerar), -1 por cada 10 minutos adicionais sobre a duração mínima devido a arredondamentos.
- Quebra de empates: (1) menor perda_preferencia, (2) maior taxa_utilizacao_recursos resultante, (3) menor distância de horário à preferência declarada (em minutos), (4) id do recurso em ordem alfanumérica.
- Respeite intervalo mínimo entre atividades no mesmo recurso (politicas.intervalo_min_entre_atividades_min) ao encadear múltiplas alocações.
- Garanta distribuição justa: não alocar mais que 60% das janelas de um mesmo recurso a atividades do mesmo responsável quando houver alternativas viáveis.
- Marque conflitos_existentes=true apenas se houver atividades não alocadas ou sobrepostas após aplicar todas as alternativas; liste em sugestoes_alternativas até 3 opções por atividade não alocada, ordenadas pelo score decrescente.

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 conjunto de dados normalizados, incluindo calendário estruturado e matriz de incompatibilidades.
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é 50.000 caracteres.

2.3.2 Especificação do Output

Formato de output: O output deve ser um arquivo no formato JSON contendo o cronograma sugerido, métricas de utilização de recursos e sugestões de alternativas.

Exemplo de Estrutura de Output:

 {
  "cronograma_sugerido": [
    {"atividade_id": "recreacao_001", "recurso_id": "quadra_1", "inicio": "2025-12-21T10:00", "fim": "2025-12-21T11:00", "conflito": false, "justificativa": "melhor aderência a preferências e capacidade"}
  ],
  "metricas": {"taxa_utilizacao_recursos_percent": 75, "atividades_alocadas": 1, "atividades_pendentes": 0},
  "conflitos_existentes": false,
  "sugestoes_alternativas": [
    {"atividade_id": "recreacao_001", "opcoes": [{"recurso_id": "sala_multi_2", "inicio": "2025-12-21T10:00", "fim": "2025-12-21T11:00", "perda_preferencia": 1}]}
  ]
}

Número de caracteres esperado: O JSON gerado terá um tamanho aproximado de 5.000 caracteres.

2.3.3 Parâmetros de Geração

Modelo: GPT-5
Temperatura: 0.7

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 Validação de Conflitos e Ajustes Finais (RF 3).

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

Ao concluir sua execução, esse agente aciona o Agente de Validação de Conflitos e Ajustes Finais (RF 3).

RF 3. Agente de Validação de Conflitos e Ajustes Finais

3.1 Tarefa do Agente

Revisar o cronograma sugerido, detectar conflitos residuais, aplicar ajustes simples e classificar gravidade dos conflitos para eventual acionamento de humano.

3.2 Prompt ou Instruções do Agente

 # 1. Contexto e explicações sobre inputs iniciais
Você está recebendo o cronograma sugerido, métricas de utilização de recursos e sugestões de alternativas gerados pelo agente anterior.

# 2. Objetivo
Revisar o cronograma sugerido para detectar conflitos residuais e aplicar ajustes simples, classificando a gravidade dos conflitos para eventual acionamento de humano.

# 3. Regras que você deve seguir para gerar sua resposta
- Verifique sobreposição por responsável: nenhuma pessoa responsável pode estar em duas atividades simultâneas; em colisão, priorize a atividade com maior score original e repreague a outra usando sugestoes_alternativas.
- Aplique buffers mínimos entre atividades do mesmo responsável (regras_escola.buffers_min_professor) ajustando início/fim quando houver folga suficiente; ao ajustar, não crie janelas < 10 min.
- Classifique conflitos remanescentes: critico (capacidade insuficiente sem alternativa, ausência total de janelas, bloqueio institucional), moderado (não aderência a preferência), leve (distribuição desigual porém viável).
- Se nenhum conflito critico permanecer e todas as atividades solicitadas estiverem alocadas, defina status_para_execucao.pronto_para_agendar=true; caso contrário, mantenha false.
- Defina status_para_execucao.agendamento_aprovado sempre como false, aguardando confirmação humana explícita antes da execução.

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 o cronograma sugerido, métricas de utilização de recursos e sugestões de alternativas.
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.

3.3.2 Especificação do Output

Formato de output: O output deve ser um arquivo no formato JSON contendo o cronograma ajustado, conflitos pendentes e status para execução.

Exemplo de Estrutura de Output:

 {
  "cronograma_ajustado": [...],
  "conflitos_pendentes": [
    {"atividade_id": "recreacao_009", "tipo": "capacidade_insuficiente", "gravidade": "critico", "alternativas": [...]}
  ],
  "status_para_execucao": {"pronto_para_agendar": true, "agendamento_aprovado": false}
}

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: GPT-5
Temperatura: 0.7

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 deve ser visível para o Agente de Execução de Chamada à API (RF 4).

3.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 4).

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

4.1 Tarefa do Agente

Realizar chamada à API do sistema agendamento_atividades para persistir o cronograma aprovado.

4.2 Prompt ou Instruções do Agente

 # 1. Contexto e explicações sobre inputs iniciais
Você está recebendo o cronograma ajustado e status para execução gerados pelo agente anterior.

# 2. Objetivo
Realizar a chamada à API do sistema de agendamento para persistir o cronograma aprovado.

# 3. Regras que você deve seguir para gerar sua resposta
- Este agente apenas executa a chamada conforme payload recebido e retorna a resposta sem modificações.
- A chamada deve ser feita ao endpoint especificado utilizando o método POST e incluindo as credenciais necessárias no cabeçalho.
- Em caso de erro na chamada, registre o erro para análise posterior.

# 4. Exemplo de Output que você deve produzir
{
  "resposta_api": {"status_http": 201, "ids_agendamentos": ["ag_1001", "ag_1002"], "mensagens": []}
}

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 o cronograma ajustado e status para execução.
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.

4.3.2 Especificação do Output

Formato de output: O output deve ser um arquivo no formato JSON contendo a resposta da API com status HTTP e IDs dos agendamentos.

Exemplo de Estrutura de Output:

 {
  "resposta_api": {"status_http": 201, "ids_agendamentos": ["ag_1001", "ag_1002"], "mensagens": []}
}

Número de caracteres esperado: O JSON gerado terá um tamanho aproximado de 500 caracteres.

4.3.3 Parâmetros de Geração

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

4.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 cronograma ajustado para a API externa e retornar a resposta recebida como resposta.

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 (resposta da API) é 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. A resposta da API é o resultado que deve ser disponibilizado ao usuário.

Agente de IA para Agendamento de Atividades Recreativas

1. Propósito e Escopo

2. Contexto e Problema

Cenário Atual

Problemas Identificados

3. Impactos Esperados

4. Visão Geral da Solução

5. Protótipos

6. Requisitos Funcionais

RF 1. Agente de Preparação de Dados de Agenda e Recursos

1.3.1 Especificação do Input

1.3.2 Especificação do Output

1.3.3 Parâmetros de Geração

1.3.4 Ferramentas do Agente

1.3.5 Memória

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

RF 2. Agente de Geração de Cronograma Otimizado

2.3.1 Especificação do Input

2.3.2 Especificação do Output

2.3.3 Parâmetros de Geração

2.3.4 Ferramentas do Agente

2.3.5 Memória

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

RF 3. Agente de Validação de Conflitos e Ajustes Finais

3.3.1 Especificação do Input

3.3.2 Especificação do Output

3.3.3 Parâmetros de Geração

3.3.4 Ferramentas do Agente

3.3.5 Memória

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

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

4.3.1 Especificação do Input

4.3.2 Especificação do Output

4.3.3 Parâmetros de Geração

4.3.4 Ferramentas do Agente

4.3.5 Memória

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

Posts Relacionados