> Crie um agente de IA que consulta disponibilidade e tarifas, envia o link de reserva, encontra reservas e atende cada hóspede no WhatsApp no idioma dele. # Agente de IA para hotéis e turismo Um agente de IA para um hotel ou pousada atende os hóspedes no WhatsApp, no Instagram e no seu site, consulta disponibilidade e tarifas no seu motor de reservas, envia o link para reservar o quarto escolhido, encontra uma reserva existente e responde dúvidas sobre check-in, estrutura e destino, no idioma em que o hóspede escreve. Reservas de grupo, reclamações e reembolsos vão para uma pessoa. Com a Vatio você descreve esse agente em um arquivo `vatio.yml` e ele responde pelo seu próprio número de WhatsApp e pela sua conta do Instagram. Este guia monta um de ponta a ponta para uma pousada pequena no litoral: as instruções, as tools que chegam ao seu motor de reservas, o conhecimento que ele lê e as regras que o impedem de inventar uma tarifa. ## O que o agente resolve Quase tudo o que uma central de reservas responde no chat são as mesmas conversas: - **Disponibilidade e tarifas.** O agente pergunta datas e hóspedes, consulta o seu motor de reservas e oferece o que está livre, com a tarifa que ele devolveu. - **Reservar.** Envia o link de reserva do quarto que o hóspede escolheu, com as datas já preenchidas. O pagamento acontece na sua página de reservas. - **Reservas existentes.** Com o código de confirmação e o sobrenome, lê a reserva para o hóspede. - **A estadia.** Horários de check-in e check-out, café da manhã, estacionamento, pets, chegada tarde. - **O destino.** Como chegar do aeroporto, o que tem por perto, o que levar na mala. - **Todo o resto vai para uma pessoa.** Grupos, eventos, reclamações, reembolsos, exceções à política de cancelamento. Uma conversa típica, com o que o agente fez por dentro: > **Hóspede:** oi, tem quarto duplo de 14 a 17 de março? somos 2 > > **Agente:** Tem, sim. Para essas três noites há um Duplo Vista Mar a R$ 690 a diária e um Duplo Jardim a R$ 520, os dois com café da manhã. Qual você prefere? > > **Hóspede:** vista mar. dá pra sair mais tarde? nosso voo é às 18h > > **Agente:** O late check-out até as 14h é gratuito mediante pedido, e a recepção confirma no próprio dia. Depois disso vocês podem deixar as malas na recepção. Aqui está o link para reservar o Duplo Vista Mar de 14 a 17 de março: https://mar-azul.example/reservar?quarto=dvm&in=2027-03-14&out=2027-03-17 Por trás da primeira resposta houve uma chamada a `consultar_disponibilidade`, que devolveu os dois quartos com tarifas e links de reserva; por trás da segunda, uma busca no conhecimento sobre o check-out. O link pôde sair porque a tool o devolveu. A Vatio remove qualquer URL que não tenha sido dada ao agente, então ele não consegue montar uma com as datas erradas. ## Antes de escrever qualquer coisa: cinco perguntas para o hotel 1. **Quem escreve, em quais idiomas e sobre o quê?** Normalmente disponibilidade, tarifas, check-in e como chegar. 2. **O que ele nunca pode dizer?** Uma tarifa ou desconto que não consultou, um upgrade confirmado, um quarto "segurado" sem reserva. 3. **Quando uma pessoa assume a conversa?** Grupos, eventos, reclamações, reembolsos, pedidos que o hotel precisa confirmar. 4. **De quais sistemas ele lê?** A API do motor de reservas ou do PMS, e a página de reservas para onde ele aponta. 5. **Quais são as políticas, nas palavras do próprio hotel?** Cancelamento, crianças, pets, garantia. Elas vão para o conhecimento do jeito que estão escritas. As respostas viram as instruções, as condições de `handoff`, as tools e o conhecimento, nessa ordem. ## O `vatio.yml` ```yaml workspace: pousada-mar-azul agent: name: Pousada Mar Azul personality: Acolhedor, simpático e breve, como uma boa recepção. Nunca um folheto. instructions: | Você ajuda os hóspedes da Pousada Mar Azul, uma pousada de 30 quartos em Paraty, a consultar disponibilidade e tarifas, reservar um quarto, encontrar a reserva e tirar dúvidas sobre a pousada, o check-in e a região. Disponibilidade e reservas: pergunte as datas e quantos adultos e crianças. Chame consultar_disponibilidade e ofereça no máximo três opções, com a tarifa exatamente como a tool devolveu. Para reservar, envie o link_reserva da opção escolhida. O pagamento acontece só na página de reservas. Reservas existentes: peça o código de confirmação e o sobrenome da reserva e chame buscar_reserva. Se não voltar nada, diga que o código e o sobrenome não batem. Alterações e cancelamentos são feitos pelo link gerenciar_reserva ou na recepção. A pousada, o check-in e a região: busque primeiro em knowledge_lookup. As entradas estão em português, então busque em português mesmo que o hóspede escreva em outro idioma. Se não encontrar a resposta, diga isso e ofereça passar a pergunta para a recepção. Regras que você nunca quebra: - Nunca informe uma tarifa, desconto ou disponibilidade que consultar_disponibilidade não tenha devolvido. - Nunca diga que um quarto está reservado ou segurado. Quem confirma é a página de reservas. - Nunca peça nem aceite número de cartão no chat. - Nunca prometa upgrade, early check-in ou late check-out. Eles são pedidos na recepção, que confirma no próprio dia. tools: [consultar_disponibilidade, buscar_reserva, knowledge_lookup, identify_contact] knowledge: [pousada] links: gerenciar_reserva: https://mar-azul.example/minha-reserva handoff: after_turns: 14 when: - uma reserva de cinco quartos ou mais, ou para um evento ou casamento - uma reclamação sobre a estadia ou sobre uma cobrança - o hóspede pede reembolso ou uma exceção à política de cancelamento - um pedido especial que a pousada precisa confirmar, como acessibilidade ``` Algumas decisões que valem explicação: - **A reserva acontece na sua página de reservas.** O seu motor já cobra, aplica as condições de cancelamento e envia a confirmação. O agente leva o hóspede até lá com o quarto e as datas certas, e por isso "nunca diga que está reservado" é uma regra. - **Tarifas são lidas, nunca lembradas.** Elas mudam com a data, a ocupação e a temporada, então só a tool sabe. A regra cita descontos também, porque "faz mais barato?" é a primeira coisa que um hóspede tenta. - **Nenhuma regra diz em que idioma responder.** O agente responde no idioma do hóspede por padrão. A única linha sobre idioma é sobre como buscar, para que achar a resposta não dependa de como o hóspede escreve. - **O horário de atendimento cobre a semana toda.** A equipe de reservas o define na página **Negócio** do inbox, não no `vatio.yml`: todos os dias das 8:00 às 22:00, quando ela acompanha o inbox, não quando a recepção está aberta. Dentro desse horário, uma transferência deixa o agente em silêncio para uma pessoa assumir; fora dele, o agente continua ajudando e avisa que a equipe responde pela manhã. ## Tools: chegar ao seu motor de reservas Uma tool é uma requisição HTTP ao seu backend, descrita em YAML. Guarde o endereço e a chave como secrets: ```bash vatio secrets set POUSADA_API https://api.mar-azul.example vatio secrets set POUSADA_API_KEY sk_live_... ``` `tools/consultar_disponibilidade.yml`: ```yaml description: Consulta disponibilidade e tarifas para uma estadia. when_to_use: O hóspede pergunta se há quarto, ou quanto custa, para certas datas. parameters: type: object properties: entrada: { type: string, description: "AAAA-MM-DD" } saida: { type: string, description: "AAAA-MM-DD" } adultos: { type: integer } criancas: { type: integer } required: [entrada, saida, adultos] access: public request: method: GET base_url: "$env.POUSADA_API" path: /disponibilidade requires: [params.entrada, params.saida, params.adultos] headers: Authorization: "Bearer $env.POUSADA_API_KEY" query: entrada: "$params.entrada" saida: "$params.saida" adultos: "$params.adultos" criancas: "$params.criancas" respond: data: opcoes: "$.opcoes" message: when_empty: Não há quartos livres para essas datas e hóspedes. default: "Encontrei {{count}} opções de quarto." ``` Cada opção traz o quarto, a diária, o total, o que está incluído, as condições de cancelamento e um `link_reserva` com o quarto e as datas já escolhidos. O seu backend monta esse link; o agente só copia. `tools/buscar_reserva.yml`: ```yaml description: Busca a reserva de um hóspede pelo código de confirmação e sobrenome. when_to_use: O hóspede pergunta sobre uma reserva que já fez. parameters: type: object properties: codigo: { type: string } sobrenome: { type: string } required: [codigo, sobrenome] access: public request: method: POST base_url: "$env.POUSADA_API" path: /reservas/buscar requires: [params.codigo, params.sobrenome] headers: Authorization: "Bearer $env.POUSADA_API_KEY" body: codigo: "$params.codigo" sobrenome: "$params.sobrenome" respond: data: reserva: "$.reserva" ``` 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 esta é uma tool pública e **quem confere é o seu backend**. Ele devolve a reserva só quando código e sobrenome batem, e o mesmo `404` tanto se o código não existe quanto se o sobrenome está errado, para ninguém conseguir testar códigos pelo agente. Devolva só o que o hóspede precisa (datas, quarto, o que está incluído), nunca dados de cartão nem nomes de outros hóspedes: o modelo vê cada resultado de tool e pode repeti-lo. Se o seu motor aceita reservas com pagamento na pousada, uma tool `reservar_quarto` pode criar a reserva no chat; a regra passa a ser "só diga que está reservado quando `reservar_quarto` devolveu um código de confirmação". Pontos de fidelidade e estadias anteriores ficam atrás de um login no seu site, com uma tool marcada `access: private`; veja [Conectar seu backend](/pt/guias/conectar-seu-backend). ## Conhecimento: a pousada, as políticas e a região Tudo o que é longo e que o agente deve ler em vez de decorar vai para uma base de conhecimento: uma entrada em Markdown por assunto, com seções que respondam uma pergunta sozinhas. ```bash vatio kb create pousada vatio kb write pousada check-in check-in.md vatio kb write pousada quartos-e-estrutura quartos-e-estrutura.md vatio kb write pousada politicas politicas.md vatio kb write pousada como-chegar como-chegar.md vatio kb write pousada passeios passeios.md ``` Uma boa entrada é específica: ```markdown # Check-in e check-out ## Check-in A partir das 15h. O early check-in é feito mediante pedido e depende de o quarto estar pronto; a recepção confirma no próprio dia. As malas podem ficar na recepção a qualquer hora. ## Check-out Até as 11h. O late check-out até as 14h é gratuito mediante pedido, sujeito à disponibilidade do dia. ``` A Vatio não lê sites, nem o seu nem nenhum outro. Se a resposta está numa página, coloque numa entrada o que o agente precisa; para o que muda todo dia, como a condição de uma estrada, escreva onde o hóspede pode conferir. Supervisores podem editar entradas pelo inbox, e cada edição fica guardada como versão. ## Hóspedes que escrevem em outros idiomas Um hóspede que escreve "Hola, ¿tienen habitación doble del 14 al 17 de marzo?" recebe os quartos e as tarifas em espanhol, da mesma tool e do mesmo conhecimento em português. - **Fixe um idioma só se precisar,** nas instruções ou na personalidade. - **O `data-locale` do widget é para a interface.** Ele define os textos em inglês, espanhol ou português; o idioma em que o agente responde é decidido pela conversa. - **Números não se traduzem.** A tarifa, em qualquer idioma, é a que a tool devolveu. - **Hóspedes mandam áudios, prints e vouchers.** A Vatio transcreve o áudio e passa ao agente imagens e PDFs de até 8 MB, então um print do e-mail de confirmação basta para achar o código. Ela também agrupa várias mensagens seguidas em uma só pergunta antes de responder; veja [Conversas fluidas](/pt/guias/conversas-fluidas). ## Teste antes de qualquer hóspede ```bash vatio push vatio chat "Tem quarto duplo de 14 a 17 de março para dois adultos?" vatio chat "Faz por R$ 450 a diária? Vi mais barato em outro site" vatio chat --new "Hola, ¿a qué hora es el check-in y tienen estacionamiento?" vatio chat --new "Minha reserva é MA-48213, sobrenome Souza. A que horas podemos chegar?" vatio chat --new "Pode reservar você mesmo, meu cartão é 4111 1111 1111 1111" vatio chat show ``` As adversariais são as que importam: um desconto que ele não pode inventar, uma pergunta em espanhol cuja busca você confere no `chat show`, uma reserva com um sobrenome que não bate, então ele não pode revelar nada, e um número de cartão que ele precisa recusar. 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 equipe de reservas usa o inbox, ela **marca** qualquer resposta errada e escreve o que deveria ter acontecido. `vatio flags` transforma essas notas em um documento a partir do qual o seu coding agent corrige, cada flag vira um caso de eval, e a flag é marcada como resolvida quando o live passa no caso dela. Veja [Melhorar seu agente](/pt/guias/melhorar-seu-agente-de-ia). ## Publicar ```bash vatio publish ``` Depois conecte o número de WhatsApp Business e a conta do Instagram da pousada na página **Canais** do inbox (o WhatsApp também precisa da chave **Em produção** ativada), e coloque o widget nas suas páginas de reserva com uma única tag script. Dá para continuar usando o app WhatsApp Business no celular da recepção: uma resposta enviada por ele assume a conversa, e o agente sai de cena até ela ser liberada. O agente nunca decide por conta própria escrever primeiro. As mensagens de pré-chegada saem pelo WhatsApp quando o seu PMS ou o seu backend pedem, pela [Messages API](https://vatio.ai/docs/api/messages), e o agente cuida do que os hóspedes responderem sabendo o que foi enviado. ## Perguntas frequentes ### Um agente de IA pode fazer reservas de hotel pelo WhatsApp? Pode. O agente chama o seu motor de reservas com uma tool que você descreve em YAML, oferece os quartos e tarifas que ela devolveu e envia ao hóspede o link de reserva do quarto escolhido. O pagamento e a confirmação final continuam na sua página de reservas, como hoje. ### O agente responde os hóspedes no idioma deles? Responde. Por padrão o agente responde no idioma em que o hóspede escreve, então você escreve as instruções e o conhecimento uma vez só. Se o seu hotel precisa de um idioma fixo, diga isso nas instruções. ### O hóspede consegue consultar uma reserva que já fez? Consegue, com o código de confirmação e o sobrenome da reserva. Uma tool envia os dois para o seu backend, que confere se batem antes de devolver qualquer coisa. Alterações e cancelamentos vão para a sua página de gerenciamento de reservas ou para a recepção. ### O agente envia mensagens antes da chegada ou lembretes de check-in? Sim, quando o seu sistema pede. O seu backend sabe a data de chegada pelo seu PMS ou motor de reservas, então chama a Messages API da Vatio para cada hóspede e a conversa se abre no WhatsApp: o seu próprio texto, uma mensagem que o agente escreve a partir de um brief, ou um modelo aprovado quando já se passaram 24 horas desde a última mensagem do hóspede. O agente cuida da resposta sabendo por que escreveu. ### Meu motor de reservas não tem API. Ainda dá para fazer? Em parte. Sem um endpoint o agente não consegue consultar disponibilidade, mas consegue responder pelo conhecimento e mandar o hóspede para a sua página de reservas com um link que você declara. Disponibilidade e consulta de reservas precisam de um endpoint pequeno no seu backend que as leia.