#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

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:

vatio secrets set CLINICA_API https://api.clinica-mantiqueira.example
vatio secrets set CLINICA_API_KEY sk_live_...

tools/buscar_horarios.yml:

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:

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

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:

# 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

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.

#Colocar no ar

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.

Atualizado: 11 de outubro de 2026