> Construa um agente de IA que responde sobre cursos, mensalidades e requisitos, consulta o status da inscrição e agenda visitas, sem prometer aprovação. # Agente de IA para escolas, faculdades e matrículas Um agente de IA para uma escola ou faculdade atende os futuros alunos, e os pais que escrevem por eles, pelo WhatsApp, pelo Instagram e pelo seu site de matrículas: cursos, mensalidades, requisitos de admissão e bolsas, o status de uma inscrição, e uma visita ao campus ou uma ligação com um consultor. Ele nunca promete aprovação nem bolsa. Com a Vatio você descreve esse agente em um arquivo `vatio.yml` e ele responde no seu próprio número de WhatsApp, na sua conta do Instagram e no seu site. ## O que o agente resolve As equipes de captação respondem as mesmas perguntas a cada processo seletivo: - **Cursos.** O que um curso cobre, quanto tempo dura, em qual campus. - **Mensalidades e bolsas.** A mensalidade de um ingresso específico, e o que cada bolsa exige. - **Requisitos e prazos.** Documentos, nota do ENEM, entrevistas, datas de encerramento. - **Status da inscrição.** A etapa e os documentos pendentes. - **Visitas e ligações.** Uma visita guiada ao campus ou uma ligação com um consultor. - **Todo o resto vai para uma pessoa.** Exceções, recursos, atendimento a pessoas com deficiência, parcelamentos. Uma conversa típica: > **Mãe:** oi, estou escrevendo pela minha filha. ela quer fazer enfermagem, o que ela precisa? > > **Agente:** Com prazer. Para Enfermagem ela precisa do certificado do ensino médio, da nota do ENEM e de uma entrevista. As inscrições para o ingresso em 2027.1 fecham em 15 de janeiro. Uma visita ao campus ajudaria? > > **Mãe:** sim, se tiver alguma no sábado > > **Agente:** Tem visitas guiadas neste sábado às 10:00 e no sábado dia 18 às 11:30. Qual fica melhor, e qual é o nome da sua filha? Por trás dessas respostas houve uma busca no conhecimento, uma chamada a `buscar_horarios_visita` e uma nota com `remember` sobre Enfermagem para 2027.1, tudo visível no inbox. ## Antes de escrever qualquer coisa: cinco perguntas para a instituição 1. **Quem escreve, e para quê?** Futuros alunos e pais, sobre cursos, mensalidades e prazos; candidatos, sobre o status. 2. **O que ele nunca deve dizer?** Promessas de aprovação ou de bolsa, chances com base na nota, mensalidades de um ingresso que ainda não tem preço. 3. **Quando uma pessoa assume?** Exceções, recursos, atendimento a pessoas com deficiência, parcelamentos. 4. **De quais sistemas ele lê?** A API do sistema acadêmico, a agenda onde as visitas são marcadas, a tabela de mensalidades, as regras das bolsas. 5. **O que um número de inscrição pode revelar?** Decida o que alguém com ele e o CPF do candidato pode saber. Normalmente a etapa e os documentos pendentes; nunca o resultado. As respostas viram as instruções, as condições de `handoff`, as tools e o conhecimento, nessa ordem. ## O `vatio.yml` ```yaml workspace: faculdade-horizonte agent: name: Matrículas Faculdade Horizonte personality: Claro, paciente e acolhedor. Nunca insistente. instructions: | Você atende os futuros alunos da Faculdade Horizonte, e os pais ou responsáveis que escrevem por eles, sobre cursos, mensalidades, requisitos, bolsas e prazos. Cursos, mensalidades, requisitos, bolsas e datas: responda só com o que knowledge_lookup devolver, e diga sempre a qual ingresso uma mensalidade se refere. Se não encontrar a resposta, diga isso e ofereça passar a pergunta para um consultor. Visitas e ligações com um consultor: pergunte qual curso interessa, chame buscar_horarios_visita e ofereça no máximo três opções. Peça um nome, um e-mail e, exceto no WhatsApp, um telefone, e chame agendar_visita. Só diga que está agendado quando agendar_visita tiver devolvido. Status da inscrição: peça o número de inscrição e o CPF do candidato e chame status_inscricao. Informe a etapa e os documentos pendentes. Se o resultado já saiu, diga que foi enviado por e-mail e está no portal do candidato; nunca comunique o resultado você mesmo. Pais e responsáveis: ajude do mesmo jeito. Salve o nome de quem está escrevendo com identify_contact. Use remember para salvar o curso e o ingresso que a família está avaliando, e recall quando ela voltar. Regras que você nunca quebra: - Nunca prometa nem preveja aprovação, uma vaga ou uma bolsa, e nunca estime as chances de alguém a partir das notas. Quem decide são as comissões de admissão e de bolsas. - Nunca informe uma mensalidade, uma data ou um requisito que o conhecimento não tenha devolvido. - Nunca compartilhe nada de uma inscrição sem o número dela e o CPF do candidato. tools: [knowledge_lookup, buscar_horarios_visita, agendar_visita, status_inscricao, identify_contact, remember, recall] knowledge: [admissao] links: inscricao: https://faculdade-horizonte.example/inscricao portal: https://faculdade-horizonte.example/candidatos curso: url: https://faculdade-horizonte.example/cursos/{curso} when: A pessoa quer a página completa de um curso. values: curso: [enfermagem, administracao, engenharia-de-software, design-grafico] handoff: after_turns: 14 when: - a pessoa pede uma exceção a um requisito ou a um prazo - a pessoa discorda de um resultado de admissão ou de bolsa - dúvidas sobre atendimento a pessoas com deficiência ou uma condição de saúde - a pessoa pergunta sobre parcelamento ou dificuldade financeira ``` Algumas escolhas que vale explicar: - **O agente nunca comunica um resultado.** Um resultado merece as palavras que a sua equipe de admissão escolheu, não um chat no celular compartilhado da família. O endpoint abaixo nem sequer o devolve, então a regra não depende só do prompt. - **Mensalidades só a partir do conhecimento, sempre com o ingresso.** Uma mensalidade informada para o semestre errado é uma promessa que alguém vai cobrar. - **`after_turns: 14`** é mais alto do que num agente de reservas porque conversas de matrícula são longas. Passadas catorze mensagens, a conversa vai para uma pessoa. ## Tools: status da inscrição e visitas Uma tool é uma requisição HTTP para o seu backend, descrita em YAML. Guarde o endereço e a chave como secrets: ```bash vatio secrets set HORIZONTE_API https://api.faculdade-horizonte.example vatio secrets set HORIZONTE_API_KEY sk_live_... ``` `tools/status_inscricao.yml`: ```yaml description: Consulta a etapa de uma inscrição e os documentos pendentes. when_to_use: Alguém pergunta por uma inscrição e informou o número dela e o CPF do candidato. parameters: type: object properties: numero_inscricao: { type: string, description: "por exemplo INS-2027-04812" } cpf: { type: string, description: "O CPF do candidato, não o do responsável" } required: [numero_inscricao, cpf] access: public request: method: POST base_url: "$env.HORIZONTE_API" path: /inscricoes/status requires: [params.numero_inscricao, params.cpf] headers: Authorization: "Bearer $env.HORIZONTE_API_KEY" body: numero_inscricao: "$params.numero_inscricao" cpf: "$params.cpf" respond: data: etapa: "$.etapa" documentos_pendentes: "$.documentos_pendentes" ``` `tools/agendar_visita.yml`: ```yaml description: Agenda uma visita ao campus ou uma ligação com um consultor em um horário livre. when_to_use: A pessoa escolheu um horário de buscar_horarios_visita e deu um nome e uma forma de contato. parameters: type: object properties: horario_id: { type: string } nome_estudante: { type: string } email: { type: string } telefone: { type: string, description: "Só Instagram e web. No WhatsApp a tool usa o número do contato" } curso: { type: string, description: "por exemplo enfermagem, administração" } required: [horario_id, nome_estudante, curso] access: public request: method: POST base_url: "$env.HORIZONTE_API" path: /visitas requires: [params.horario_id, params.nome_estudante] headers: Authorization: "Bearer $env.HORIZONTE_API_KEY" body: horario_id: "$params.horario_id" nome_estudante: "$params.nome_estudante" email: "$params.email || $contact.email" telefone: "$params.telefone || $contact.phone_number" curso: "$params.curso" respond: data: visita: "$.visita" ``` `buscar_horarios_visita` é um `GET` com o tipo de visita, o curso e uma data. `||` usa o que a pessoa digitou ou, se não houver, o que já está no contato dela. No WhatsApp o número já está no contato, então o agente só pede o número no Instagram e no site. Numa ligação com um consultor, é o consultor quem liga no horário marcado; o agente só agenda. A segurança deste agente mora na tool de status. No WhatsApp e no Instagram um contato é anônimo enquanto não [entrar na conta](https://vatio.ai/docs/authentication/sessions#on-whatsapp), então `status_inscricao` é pública, e o número mais o CPF são a única coisa entre um desconhecido e uma inscrição. **O seu backend confere se os dois batem**, responde a um CPF que não bate exatamente como a um número que não existe, e limita as tentativas. É um `POST` para o CPF nunca ficar em uma URL. E o que ela devolver é o que qualquer pessoa com esses dois dados vai saber, então ela devolve só a etapa e os documentos pendentes. A inscrição completa fica atrás do login do seu portal do candidato, onde o mesmo agente pode usar uma [tool privada](https://vatio.ai/docs/authentication/tools) que lê `$auth.subject` em vez de pedir números. ## Conhecimento: cursos, mensalidades e bolsas ```bash vatio kb create admissao vatio kb write admissao cursos cursos.md vatio kb write admissao mensalidades-2027 mensalidades-2027.md vatio kb write admissao requisitos requisitos.md vatio kb write admissao bolsas bolsas.md ``` Uma entrada que diz com clareza quem decide facilita seguir a regra de não prometer: ```markdown # Bolsas ## Bolsa de mérito acadêmico Para calouros com nota de destaque no ENEM. Não há formulário separado: vale a inscrição no processo seletivo. A comissão de bolsas decide quem recebe, e com qual desconto, depois que os resultados são publicados. Ninguém pode confirmar antes disso. ## Prazo As inscrições para bolsas do ingresso em 2027.1 fecham em 15 de dezembro de 2026. ``` A Vatio não lê o seu site, então mensalidades e requisitos vão em entradas. Quando o próximo ingresso tiver preço, escreva `mensalidades-2028` ao lado de `mensalidades-2027`, não por cima. ## Pais, alunos e conversas que duram meses Muitas conversas são começadas por um pai ou uma mãe, e a inscrição é do estudante. As instruções resolvem as duas coisas: - **Quem escreve é o contato.** `identify_contact` salva o nome de quem está escrevendo, então o inbox mostra o responsável, e não um estudante que nunca escreveu. - **Os dados do estudante abrem a inscrição.** Um responsável com o número de inscrição e o CPF do estudante recebe a etapa como qualquer outra pessoa. A regra é a mesma para todos, e é isso que a torna segura. - **A memória continua.** As pessoas pesquisam um curso meses antes de se inscrever. Uma conversa no WhatsApp continua até a última mensagem ter mais de oito horas; a seguinte começa do zero. Com `remember` e `recall`, o que foi salvo em março continua lá em outubro, e os supervisores leem as mesmas notas no contato, no inbox. ## Teste antes de qualquer candidato ```bash vatio push vatio chat "Oi, o que eu preciso para me inscrever em Enfermagem?" vatio chat "Tirei 720 no ENEM. Vou passar? E a bolsa?" vatio chat --new "Sou a mãe dela. Inscrição INS-2027-04812, em que pé está?" vatio chat --new "Quanto custa Administração para o ingresso em 2028.1?" vatio chat show ``` A segunda não pode prometer nem estimar nada. A terceira não traz CPF, então o agente tem que pedir o do estudante e não dizer nada até ter. A quarta pede uma mensalidade que ainda não está no conhecimento. Depois adicione o seu telefone como número de teste no preview compartilhado do WhatsApp e teste como um responsável que manda um áudio. ## Melhore toda semana Quando a equipe de captação lê o inbox, ela **marca** qualquer resposta errada e escreve o que deveria ter acontecido: “o prazo de Design Gráfico mudou para 30 de janeiro”. `vatio flags` transforma essas notas em um documento a partir do qual o seu coding agent consegue corrigir, cada flag vira um caso de eval, e a flag é marcada como resolvida quando o live passa nela. Veja [Melhorar seu agente](/pt/guias/melhorar-seu-agente-de-ia). ## Publicar ```bash vatio publish vatio tokens create --env live --label matriculas --origin https://faculdade-horizonte.example ``` O token vai no script do widget no seu site de matrículas. Depois conecte o seu número do WhatsApp Business e a sua conta do Instagram na página **Canais** do inbox, e ative a chave **Em produção** do WhatsApp. O Instagram responde assim que a conta é conectada. O agente nunca decide por conta própria escrever primeiro; os lembretes de prazo saem pelo WhatsApp quando o seu sistema acadêmico os envia pela [Messages API](https://vatio.ai/docs/api/messages). Inscrições têm dados pessoais, muitas vezes de menores de idade. A Vatio nunca coloca o conteúdo de uma conversa no email diário: ele só se lê no inbox ou com um token da Vatio, e o que a legislação local exige sobre o tratamento dos dados dos candidatos continua sendo seu para verificar. ## Perguntas frequentes ### Um agente de IA pode responder dúvidas de admissão de uma escola ou faculdade? Sim. Cursos, mensalidades, requisitos, bolsas e prazos vão em entradas de conhecimento que você escreve, e o agente responde a partir delas no WhatsApp, no Instagram e no seu site. A Vatio não lê o seu site, então tudo o que o agente precisa saber tem que estar em uma entrada. ### Os candidatos podem consultar o status da inscrição pelo WhatsApp? Sim, com o número de inscrição e o CPF do candidato. Uma tool pública envia os dois para o seu backend, que só responde se eles batem e devolve a etapa e os documentos pendentes. A inscrição completa fica atrás do login do seu portal do candidato. ### O agente vai prometer aprovação ou bolsa? Não, se você escrever a regra. Diga para ele nunca prometer nem prever aprovação ou bolsa e nunca estimar chances a partir de notas, e teste exatamente isso com vatio chat antes de publicar. Os supervisores marcam qualquer resposta que escapar, e cada flag vira um caso de eval. ### Os pais podem falar com o agente em nome dos filhos? Sim. O agente ajuda do mesmo jeito, salva o nome do pai ou da mãe como contato e pede o número de inscrição e o CPF do estudante para ler uma inscrição. Ele pode lembrar qual curso e qual ingresso a família está avaliando para a próxima conversa. ### O agente consegue agendar visitas ao campus e conversas com um consultor? Sim, com tools que chamam a API da agenda ou do sistema acadêmico onde você as marca. O agente reserva o horário; numa ligação com um consultor, é o consultor quem liga para o estudante nesse horário. O agente não faz ligações.