Agente de IA para Notificação de Aprovações e Reprovações

15 de December de 2025 • Tempo de leitura: 5 min

Como criar um agente de IA que analisa resultados finais e notifica alunos e responsáveis sobre aprovações e reprovações via e-mail ou aplicativo.

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, ferramentas como chamadas a sistemas externos e demais requisitos funcionais para o Fluxo de Agentes "Notificação de Aprovações e Reprovações", uma solução de automação projetada para analisar resultados finais e notificar alunos e responsáveis sobre aprovações e reprovações. 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 é automatizar a análise dos resultados finais dos alunos e enviar notificações padronizadas e personalizadas para alunos e responsáveis via e-mail ou aplicativo móvel, garantindo uma comunicação eficiente e padronizada.

2. Contexto e Problema

Cenário Atual

As instituições de ensino enfrentam desafios significativos na comunicação manual e tardia dos resultados de aprovações e reprovações, o que pode levar à desinformação e insatisfação entre alunos e responsáveis. Atualmente, o processo é caracterizado por:

  • Comunicação manual e tardia de resultados de aprovações e reprovações.
  • Falta de padronização na notificação dos resultados.

Estes problemas resultam em atrasos na informação e inconsistências na forma como os resultados são comunicados, impactando negativamente na experiência dos alunos e responsáveis.

3. Impactos Esperados

A implementação deste fluxo de automação visa alcançar os seguintes resultados:

  • Reduzir o tempo de comunicação de resultados para alunos e responsáveis.
  • Padronizar a qualidade e o formato das notificações enviadas.
  • Aumentar a satisfação dos alunos e responsáveis através de uma comunicação mais clara e eficiente.

4. Visão Geral da Solução

O agente de IA para notificação de aprovações e reprovações automatiza a análise dos resultados finais dos alunos e envia notificações padronizadas e personalizadas para alunos e responsáveis via e-mail ou aplicativo móvel. A seguir são detalhadas todas as regras de negócio e especificações funcionais necessárias para que esse agente atue de forma eficaz e autônoma na comunicação dos resultados de forma padronizada.

A solução consiste em um fluxo de automação composto por 5 agentes de IA. O processo inicia com a consulta ao documento de resultados finais e termina com o registro das notificações enviadas.

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

Agentes Função Principal
Agente de Execução de Consulta a Documento (RF 1) Realizar consulta ao documento "resultados_finais_alunos" para obter dados necessários para análise de aprovação/reprovação.
Agente de Análise de Resultados Finais (RF 2) Automatizar a análise dos resultados finais dos alunos e produzir mensagens padronizadas e personalizadas.
Agente Preparador de Payload de Notificações (RF 3) Transformar as mensagens e destinatários em payloads prontos para envio via e-mail e/ou aplicativo móvel.
Agente de Execução de Chamada à API (RF 4) Realizar chamada à API do sistema de notificação para enviar os payloads de notificação por e-mail ou aplicativo.
Agente de Consolidação de Entregas e Registro (RF 5) Consolidar os resultados de envio por aluno e preparar registro para memória estruturada.

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 os alunos e responsáveis receberão. 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 Execução de Consulta a Documento

1.1 Tarefa do Agente

Realizar consulta ao documento "resultados_finais_alunos" para obter os dados necessários para análise de aprovação/reprovação.

1.2 Prompt ou Instruções do Agente 
Esse agente não precisa de instruções de LLM. Sua única função é executar a consulta ao documento resultados_finais_alunos com os parâmetros recebidos e retornar os registros conforme a estrutura do expected_output.
1.3 Configurações do Agente

1.3.1 Especificação do Input

  • Mecanismo de Acionamento: Este agente deve ser acionado pelo envio dos parâmetros de consulta via API. Na fase de testes, os dados serão enviados manualmente por upload na interface da Prototipe AI, para acelerar o processo de validação.
  • Tipo do input: Parâmetros prontos para efetuar a consulta: {"turma_id" ou "alunos_ids", "periodo_letivo", "campos_desejados"}.
  • 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 até 5.000 caracteres.

1.3.2 Especificação do Output

  • Formato de output: Dados recuperados da consulta com a estrutura: [{"aluno_id":"string","nome":"string","responsaveis":[{"nome":"string","email":"string","id_app":"string|opcional"}],"media_final":number,"frequencia":number,"faltas":number,"status_oficial": "aprovado|reprovado|null","canal_preferencial":"email|app|null"}]
  • Número de caracteres esperado: O output deve ter um tamanho estimado em torno de 10.000 caracteres, dependendo do número de registros retornados.

1.3.3 Parâmetros de Geração

  • Modelo: Não se aplica.
  • Temperatura: Não se aplica.

1.3.4 Ferramentas do Agente

  • Documentos: Consulta ao documento "resultados_finais_alunos".
  • 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 Análise de Resultados Finais (RF 2).

RF 2. Agente de Análise de Resultados Finais

2.1 Tarefa do Agente

Automatizar a análise dos resultados finais dos alunos e produzir mensagens padronizadas e personalizadas.

2.2 Prompt ou Instruções do Agente 
1) Determinação do status: quando media_corte e frequencia_minima forem fornecidos, considerar "aprovado" se media_final >= media_corte E frequencia >= frequencia_minima; caso contrário, "reprovado". 2) Ausência de parâmetros: se não receber media_corte/frequencia_minima, usar status_oficial quando presente. Se status_oficial ausente, adotar padrões institucionais usuais: media_corte=6.0 e frequencia_minima=75.0. 3) Motivo da reprovação: definir motivo="media" se media_final < media_corte e frequencia >= frequencia_minima; motivo="frequencia" se frequencia < frequencia_minima e media_final >= media_corte; motivo="ambos" se ambos abaixo; motivo="status_oficial" quando apenas replicar status_oficial. 4) Personalização padronizada: incluir nome do aluno em ambas as mensagens. Conteúdo base: a) aprovado: saudação breve, parabenização, informação objetiva do resultado, próximos passos (ex.: calendário de matrícula/renovação), e assinatura institucional. b) reprovado: tom empático e claro, informar resultado, indicar critérios não atendidos (mencionar média e/ou frequência), orientar sobre recursos/recuperações quando aplicável e canais de atendimento. 5) Campos numéricos: arredondar media_final para 1 casa decimal e frequencia para 1 casa decimal em %. 6) Idioma: português do Brasil, tom profissional e claro. 7) Destinatários: sempre gerar mensagem para aluno; gerar mensagem para responsável quando existir e-mail ou id_app do responsável. 8) Canal preferencial: se canal_preferencial vier no dado, preservar; se ausente, sugerir "app" quando existir id_app válido; caso contrário, sugerir "email" quando houver e-mail. 9) Segurança de conteúdo: proibir divulgação de notas de outros alunos, dados sensíveis não presentes no input e links externos não fornecidos. 10) Saída consolidada: popular ha_mensagens_validas=true quando existir ao menos uma mensagem com algum contato disponível (email ou id_app) para envio; caso contrário, false.
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: Array de registros de alunos recuperados pela consulta ao documento, e, opcionalmente, parâmetros de regra: {"media_corte": number, "frequencia_minima": number}.
  • 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 até 10.000 caracteres.

2.3.2 Especificação do Output

  • Formato de output: { "mensagens": [ {"aluno_id":"string","status":"aprovado|reprovado","motivo":"media|frequencia|ambos|status_oficial","media_final":number,"frequencia":number,"mensagem_aluno":"string","mensagem_responsavel":"string","contatos":{"email_aluno":"string|opcional","email_responsavel":"string|opcional","id_app_aluno":"string|opcional","id_app_responsavel":"string|opcional"},"canal_preferencial":"email|app|null"} ], "ha_mensagens_validas": boolean }
  • Número de caracteres esperado: O output deve ter um tamanho estimado em torno de 15.000 caracteres, dependendo do número de mensagens geradas.

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 gerada por este agente deve ser visível para o Agente Preparador de Payload de Notificações (RF 3).

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

Ao concluir sua execução, esse agente aciona o Agente Preparador de Payload de Notificações (RF 3).

RF 3. Agente Preparador de Payload de Notificações

3.1 Tarefa do Agente

Transformar as mensagens e destinatários em payloads prontos para envio via e-mail e/ou aplicativo móvel.

3.2 Prompt ou Instruções do Agente 
1) Seleção de canal por mensagem: se canal_preferencial="app" e existir id_app válido do destinatário, preparar payload para app; se "email" e existir e-mail válido, preparar payload de e-mail; quando ambos disponíveis, priorizar canal_preferencial e gerar somente um payload por destinatário. 2) Destinatários: criar payload para o aluno; criar payload para cada responsável com contato válido. 3) Validação de e-mail: considerar válido se contiver '@' e domínio com ponto; remover espaços. 4) Limites e formatação: subject até 78 caracteres; title do push até 60 caracteres; body até 4000 caracteres; remover quebras múltiplas e normalizar espaços. 5) Conteúdo: incluir apenas as mensagens geradas pelo agente anterior, sem alterar seu sentido; acrescentar prefixos padronizados de assunto/título: "Resultado Final - Aprovado" ou "Resultado Final - Reprovado". 6) Metadados obrigatórios em todos os payloads: aluno_id e status. 7) Deduplificação: não criar payloads duplicados para o mesmo canal e destinatário. 8) Definir ha_payloads=true quando houver pelo menos 1 payload gerado; caso contrário, false.
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: Objeto de saída do Agente de Análise de Resultados Finais: { "mensagens": [...], "ha_mensagens_validas": boolean }.
  • 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 até 15.000 caracteres.

3.3.2 Especificação do Output

  • Formato de output: { "payloads": [ {"canal":"email","to":"email@destino","subject":"string","body":"string","metadata":{"aluno_id":"string","status":"aprovado|reprovado"}} | {"canal":"app","to":"id_app_destino","title":"string","body":"string","metadata":{"aluno_id":"string","status":"aprovado|reprovado"}} ], "ha_payloads": boolean }
  • Número de caracteres esperado: O output deve ter um tamanho estimado em torno de 15.000 caracteres, dependendo do número de payloads gerados.

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: Não utiliza.
  • 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 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 de notificação para enviar os payloads de notificação por e-mail ou aplicativo.

4.2 Prompt ou Instruções do Agente 
Esse agente não precisa de instruções de LLM. Sua única função é executar a chamada à API sistema_notificacao com os payloads recebidos e retornar o resultado de cada envio conforme a estrutura do expected_output.
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: Lista de payloads prontos para envio: { "payloads": [ ... ] }
  • 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 até 15.000 caracteres.

4.3.2 Especificação do Output

  • Formato de output: { "entregas": [ {"canal":"email|app","to":"string","status_envio":"enviado|falha","protocolo":"string|opcional","erro":"string|opcional"} ] }
  • Número de caracteres esperado: O output deve ter um tamanho estimado em torno de 10.000 caracteres, dependendo do número de entregas realizadas.

4.3.3 Parâmetros de Geração

  • Modelo: Não se aplica.
  • Temperatura: Não se aplica.

4.3.4 Ferramentas do Agente

  • Documentos: Não consulta.
  • Calculadora: Não utiliza.
  • Busca Online: Não utiliza.
  • Sistemas Externos: O agente deverá enviar os payloads para a API externa configurada manualmente na interface do fluxo.

4.3.5 Memória

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

Ao concluir sua execução, esse agente aciona o Agente de Consolidação de Entregas e Registro (RF 5).

RF 5. Agente de Consolidação de Entregas e Registro

5.1 Tarefa do Agente

Consolidar os resultados de envio por aluno e preparar registro para memória estruturada.

5.2 Prompt ou Instruções do Agente 
1) Agrupar entregas por aluno_id e status. 2) sucesso=true se houver pelo menos um envio com status_envio="enviado" para o aluno; caso contrário, false. 3) canais_enviados: listar canais com envio bem-sucedido. 4) falhas: listar tentativas com status_envio="falha" com respectivo erro. 5) timestamp_iso: gerar em formato ISO 8601 UTC. 6) O output deve ser adequado para gravação na memória estruturada conforme a política do projeto (status e canal utilizado).
5.3 Configurações do Agente

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: Resultado de entregas do agente de API e referência das mensagens geradas: { "entregas": [...], "mensagens": [...] }
  • 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 até 20.000 caracteres.

5.3.2 Especificação do Output

  • Formato de output: { "registro_notificacoes": [ {"aluno_id":"string","status":"aprovado|reprovado","canais_enviados":["email|app"],"sucesso":boolean,"falhas":[{"canal":"string","erro":"string"}],"timestamp_iso":"string"} ] }
  • Número de caracteres esperado: O output deve ter um tamanho estimado em torno de 10.000 caracteres, dependendo do número de registros consolidados.

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: Não utiliza.
  • 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 gerada por este agente é o entregável final e não é passada para outros agentes internos.

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

A execução deste agente finaliza o fluxo. O registro gerado é o resultado que deve ser disponibilizado para memória estruturada.

Posts Relacionados

© 2025 prototipe.ai. Todos os direitos reservados.