> Crie um agente de IA que agenda, remarca e cancela consultas e responde sobre convênios no WhatsApp, com regras que o impedem de diagnosticar. # Agente de IA para clínicas e saúde Um agente de IA para uma clínica atende os pacientes pelo WhatsApp e no seu site, encontra um horário livre, agenda, remarca ou cancela a consulta no seu sistema de agenda, e responde dúvidas sobre especialidades, convênios e preparo de exames. Ele nunca diagnostica, e tudo o que é clínico passa para uma pessoa. Com a Vatio você descreve esse agente em um arquivo `vatio.yml` e ele responde no seu próprio número de WhatsApp. Este guia constrói um de ponta a ponta: as instruções, as tools que chegam à sua agenda, o conhecimento que ele lê e as regras que o mantêm seguro. ## O que o agente resolve Quase tudo o que chega pelo WhatsApp à recepção de uma clínica são as mesmas conversas: - **Agendar.** “Tem algum horário com dermatologista esta semana?” O agente pergunta o necessário, busca horários livres e agenda o que o paciente escolher. - **Remarcar e cancelar.** O paciente informa o código do agendamento, e o agente oferece outros horários ou cancela. - **Convênios e preços.** Quais convênios e planos de saúde a clínica atende, quanto custa uma consulta particular, se um procedimento precisa de autorização prévia do plano. - **Preparo.** Jejum antes do exame de sangue, o que levar, com quanta antecedência chegar. - **Unidades e horários.** Onde fica, estacionamento, horário de funcionamento. - **Todo o resto vai para uma pessoa.** Sintomas, resultados, reclamações, cobranças. Uma conversa típica, com o que o agente fez por dentro: > **Paciente:** oi, tem alguma coisa com dermatologia esta semana? > > **Agente:** Tem, sim. A Dra. Lima atende na quinta às 10:30 e na sexta às 16:00. Qual fica melhor para você? > > **Paciente:** quinta. é para o meu filho, ele tem 8 anos > > **Agente:** A Dra. Lima atende crianças a partir dos 5 anos, então tudo certo. Para agendar, preciso do nome completo e do CPF dele. Por trás da segunda resposta houve uma chamada a `buscar_horarios` e uma busca no conhecimento sobre a faixa etária que a dermatologista atende. Cada chamada de tool fica visível no inbox, ao lado da resposta que ela produziu. ## Antes de escrever qualquer coisa: cinco perguntas para a clínica O agente é tão bom quanto o que a clínica contar para você. Pergunte antes de escrever uma linha: 1. **Quem escreve, e para quê?** Normalmente agendamento, convênios e preparo, nessa ordem. 2. **O que ele nunca pode dizer?** Diagnósticos, opiniões sobre resultados, medicamentos, promessas de cobertura que ele não consegue verificar. 3. **Quando uma pessoa assume?** Sintomas, reclamações, cobranças, qualquer um que peça para falar com alguém. 4. **De quais sistemas ele lê?** A API do sistema de agenda, a tabela de preços, a lista de convênios. 5. **O que conta como emergência?** O agente precisa das palavras da própria clínica e do número para onde encaminhar. As respostas viram as instruções, as condições de `handoff`, as tools e o conhecimento, nessa ordem. ## O `vatio.yml` ```yaml workspace: clinica-mantiqueira agent: name: Clínica Mantiqueira personality: Acolhedor, calmo e breve. Palavras simples, sem jargão médico. instructions: | Você ajuda os pacientes da Clínica Mantiqueira a agendar, remarcar e cancelar consultas, e responde dúvidas sobre especialidades, convênios, preços e preparo de exames. Agendar: pergunte a especialidade ou o profissional e um dia de preferência. Chame buscar_horarios e ofereça no máximo três opções. Antes de chamar agendar_consulta, peça o nome completo e o CPF do paciente e repita o agendamento para ele. Só diga que a consulta está agendada quando agendar_consulta a tiver devolvido. Remarcar ou cancelar: peça o código do agendamento e o CPF, e chame cancelar_consulta. Para remarcar, cancele só depois de agendar o novo horário. Convênios, preços e preparo: busque primeiro em knowledge_lookup. Se não encontrar a resposta, diga isso e ofereça passar a pergunta para a equipe. Regras que você nunca quebra: - Nunca diagnostique, interprete sintomas, resultados ou imagens, nem recomende medicamentos ou doses. - Se alguém descrever dor no peito, falta de ar, sangramento intenso ou perda de consciência, diga para ligar agora para o SAMU, no 192, ou ir ao pronto-socorro mais próximo. Não agende nada. - Nunca prometa que um convênio ou plano de saúde vai cobrir algo. tools: [buscar_horarios, agendar_consulta, cancelar_consulta, knowledge_lookup, identify_contact] knowledge: [clinica] links: portal: https://clinica-mantiqueira.example/pacientes handoff: after_turns: 12 when: - o paciente descreve sintomas e pergunta o que significam - o paciente pergunta sobre um resultado de exame - uma reclamação sobre o atendimento ou sobre uma cobrança - o paciente pede reembolso ``` Algumas escolhas que vale a pena explicar: - **As regras estão escritas como regras.** “Nunca diagnostique” em um item próprio é muito mais confiável do que uma frase escondida em um parágrafo sobre o tom. - **“Só diga que está agendada quando a tool a devolveu.”** Essa linha elimina a falha mais cara de um agente de agendamento: confirmar uma consulta que não existe. - **O horário de atendimento não é o horário do agente.** O agente responde a qualquer hora. O horário que a recepção define na página **Negócio** do inbox, por exemplo segunda a sexta das 8:00 às 20:00 e sábado das 8:00 às 12:00, decide o que acontece depois de uma transferência: dentro dele o agente fica em silêncio para que uma pessoa assuma; fora dele continua ajudando e avisa o paciente que a equipe responde pela manhã. - **`after_turns: 12`** é o piso abaixo do critério do modelo. Passadas doze mensagens do paciente, a conversa vai para uma pessoa, tenha o agente pedido ou não. ## Tools: chegar à sua agenda Uma tool é uma requisição HTTP ao seu backend, descrita em YAML. Guarde o endereço e a chave como secrets para que nunca fiquem no repositório: ```bash vatio secrets set CLINICA_API https://api.clinica-mantiqueira.example vatio secrets set CLINICA_API_KEY sk_live_... ``` `tools/buscar_horarios.yml`: ```yaml description: Busca horários livres para consulta. when_to_use: O paciente quer agendar ou remarcar uma consulta. parameters: type: object properties: especialidade: { type: string, description: "por exemplo dermatologia, pediatria" } a_partir_de: { type: string, description: "AAAA-MM-DD" } required: [especialidade] access: public request: method: GET base_url: "$env.CLINICA_API" path: /horarios headers: Authorization: "Bearer $env.CLINICA_API_KEY" query: especialidade: "$params.especialidade" a_partir_de: "$params.a_partir_de" respond: data: horarios: "$.horarios" message: when_empty: Não há horários livres para essa especialidade nas próximas duas semanas. default: "Encontrei {{count}} horários livres." ``` `tools/agendar_consulta.yml`: ```yaml description: Agenda um horário livre para um paciente. when_to_use: O paciente escolheu um horário de buscar_horarios e confirmou o nome e o CPF. parameters: type: object properties: horario_id: { type: string } nome: { type: string } cpf: { type: string } required: [horario_id, nome, cpf] access: public request: method: POST base_url: "$env.CLINICA_API" path: /agendamentos requires: [params.horario_id, params.nome, params.cpf] headers: Authorization: "Bearer $env.CLINICA_API_KEY" body: horario_id: "$params.horario_id" nome: "$params.nome" cpf: "$params.cpf" respond: data: agendamento: "$.agendamento" ``` `cancelar_consulta` tem o mesmo formato: um `POST` com o código do agendamento e o CPF. **O seu backend verifica que os dois batem** antes de cancelar qualquer coisa. Quem preenche os parâmetros de uma tool é o modelo, então a verificação de que um agendamento pertence a quem está pedindo tem de viver no código, não no prompt. Devolva um status HTTP real quando algo falhar, como um `409` quando alguém acabou de ocupar o horário. A Vatio transforma qualquer resposta que não seja 2xx em um erro que o agente consegue explicar, então uma corrida perdida vira “esse horário acabou de ser ocupado, sexta às 16:00 continua livre” em vez de uma confirmação falsa. ### O que fica atrás de um login No WhatsApp e no Instagram um contato é anônimo até entrar na conta, e para um contato anônimo só rodam tools públicas. **Resultados, diagnósticos e histórico médico ficam atrás de um login**, em uma tool marcada `access: private` que lê só os dados do paciente que o seu backend assinou. No seu site ou app, esse é o token que você coloca na página; no WhatsApp e no Instagram, adicione `sign_in_url` em `auth:` e a tool envia antes ao paciente um botão **Entrar** que abre o seu site, e a Vatio pede para ele confirmar o número ou a conta que está sendo conectada antes de a conversa seguir ([veja a documentação](https://vatio.ai/docs/authentication/sessions#on-whatsapp)). Sem isso, o agente pode enviar o link do seu portal do paciente; é para isso que serve `links.portal` lá em cima. [Conectar seu backend](/pt/guias/conectar-seu-backend) mostra como montar o lado do login. ## Conhecimento: convênios, preços e preparo Tudo o que é longo e que o agente deve ler em vez de memorizar vai em uma base de conhecimento: uma entrada em Markdown por tema, com seções que respondem sozinhas a uma pergunta. ```bash vatio kb create clinica vatio kb write clinica convenios convenios.md vatio kb write clinica preparo-exames preparo-exames.md vatio kb write clinica especialidades especialidades.md vatio kb write clinica unidades unidades.md ``` Uma boa entrada é específica: ```markdown # Preparo de exames ## Exames de sangue Jejum de 8 horas. Pode beber água. Traga um documento com foto, a carteirinha do convênio e o pedido médico. A coleta é de segunda a sábado, das 7:00 às 10:30, sem agendamento. ## Ultrassom de abdome total Jejum de 6 horas e não fume. Chegue 15 minutos antes. ``` A Vatio não lê o seu site. Se a resposta está em uma página, coloque em uma entrada o que o agente precisa. Os supervisores podem editar entradas pelo inbox quando os preços mudam, e cada edição fica guardada como uma versão. ## Áudios e fotos Os pacientes mandam áudios e fotos de pedidos médicos. A Vatio transcreve o áudio e passa ao agente as imagens e os PDFs compatíveis, então um “segue meu pedido” com uma foto vira o agendamento do exame certo. Ela também agrupa as três mensagens que alguém manda seguidas em uma só pergunta antes de responder. O agente lê o pedido para saber o que agendar; não o interpreta, e é exatamente isso que as regras acima deixam explícito. ## Teste antes de qualquer paciente ```bash vatio push vatio chat "Oi, tem horário com dermatologia na quinta?" vatio chat "Estou com dor no peito e não consigo respirar direito" vatio chat --new "O que significa um colesterol de 260?" vatio chat show ``` As três últimas são as importantes: uma emergência que ele não deve tentar agendar, um resultado que ele não deve interpretar, e `chat show` para ler cada chamada de tool que ele fez. Depois adicione o seu telefone como número de teste na página **Testar** do inbox e converse com o agente no número compartilhado de preview do WhatsApp. Para isso você não precisa de conta na Meta. ## Melhore toda semana Quando a recepção usa o inbox, ela **marca** qualquer resposta que saiu errada e escreve o que deveria ter acontecido. `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 live passa nesse caso. Veja [Melhorar seu agente](/pt/guias/melhorar-seu-agente-de-ia). ## Colocar no ar ```bash vatio publish ``` Depois conecte o número de WhatsApp Business da clínica em **Canais** no inbox e ative-o. Dá para continuar usando o app do WhatsApp Business no celular: se alguém da recepção responder por ali, assume a conversa, e o agente sai de cena até que ela seja liberada. As conversas com pacientes são dados de saúde. Mantenha-as longe de onde não devem estar: a Vatio nunca coloca o conteúdo de uma conversa no email diário, e o seu backend deveria aplicar a mesma regra aos próprios logs. Todo workspace da Vatio é tratado como se guardasse dados sensíveis: as conversas ficam criptografadas, só vão para modelos de IA sem retenção de dados e a equipe da Vatio não pode lê-las a menos que você conceda acesso de suporte. Em **Segurança**, no inbox, exija a verificação em duas etapas de toda a sua equipe; assim as sessões também são encerradas após 12 horas sem uso. Verificar o que a legislação local exige da comunicação de uma clínica com os pacientes continua sendo tarefa sua. ## Perguntas frequentes ### Um agente de IA pode agendar consultas médicas pelo WhatsApp? Sim. O agente chama o seu sistema de agenda com tools que você descreve em YAML: uma para buscar horários livres e outra para agendar. A Vatio opera a conversa no WhatsApp; o seu sistema continua sendo quem confirma o agendamento. ### O agente vai dar conselhos médicos? Só se você deixar, e você não deveria. Escreva a regra de forma explícita nas instruções (nunca diagnosticar, interpretar sintomas ou resultados, nem recomendar medicamentos) e coloque as perguntas sobre sintomas em handoff.when para que uma pessoa assuma. ### Os pacientes podem ver resultados de exames pelo agente? Só depois de entrar na conta. Ler os dados de um paciente exige uma tool privada e um visitante autenticado: no seu site ou app, o seu backend assina um token dizendo quem ele é, e no WhatsApp ou no Instagram, com um sign_in_url no vatio.yml, o agente envia antes ao paciente um botão Entrar que abre o seu site. Um paciente que não entrou na conta só tem tools públicas. ### O agente envia lembretes de consulta? Sim, quando o seu sistema de agenda pede. Ele sabe da consulta, então chama a Messages API da Vatio para cada paciente e a conversa se abre no WhatsApp: o seu próprio texto, um brief a partir do qual o agente escreve, ou um modelo aprovado quando já passaram 24 horas desde a última mensagem do paciente. O agente atende a resposta sabendo por que escreveu, e o seu sistema continua decidindo quem recebe um lembrete e quando. ### Meu sistema de agenda não tem API. Ainda dá para fazer? Uma tool é uma requisição HTTP, então o agente precisa de um endpoint para chamar. Se o seu sistema não oferece um, o trabalho está em um serviço pequeno no seu backend que leia e escreva a agenda. O agente nunca entra em uma tela.