> Construa um agente de IA que reserva mesas, responde sobre cardápio, alergênicos e horários e envia o link de pedidos no WhatsApp e no Instagram. # Agente de IA para restaurantes e delivery Um agente de IA para restaurante atende os seus clientes pelo WhatsApp, pelo Instagram e pelo seu site: reserva e cancela mesas no seu sistema de reservas, responde dúvidas sobre o cardápio, os alergênicos e os horários, e manda as pessoas para a sua página de pedidos. Ele só diz que um prato não contém um alergênico quando o seu cardápio diz isso, e passa para uma pessoa as alergias graves e os grupos grandes. Com a Vatio você descreve esse agente em um arquivo `vatio.yml` e ele responde no seu próprio número de WhatsApp e na sua conta do Instagram. ## O que o agente resolve Quase tudo o que os clientes escrevem, geralmente no meio do serviço, é uma destas coisas: - **Reservas.** O agente busca horários livres, reserva o que o cliente escolhe e anota qualquer alergia ou ocasião especial. - **Cancelamentos.** Com o código da reserva e o telefone usado nela. - **Cardápio e alergênicos.** Respondidos a partir do cardápio que você escreveu, nunca de um palpite. - **Horários e endereço.** Que horas a cozinha fecha, se aceitam sem reserva, onde estacionar. - **Pedidos.** O link da sua página de pedidos, e em que pé está um pedido. - **Todo o resto vai para uma pessoa.** Alergias graves, grupos grandes, eventos fechados, reclamações e reembolsos. Uma conversa típica no WhatsApp: > **Cliente:** oi! mesa pra 4 amanhã à noite? > > **Agente:** Claro! Amanhã temos às 20:00 ou às 21:30 para quatro. Qual fica melhor? > > **Cliente:** 20:00. um de nós é celíaco, tem problema? > > **Agente:** Vários pratos são marcados como sem glúten e preparados à parte, como o risoto de cogumelos. Vou anotar na reserva para a cozinha saber. Em nome de quem eu faço? Por trás dessas respostas houve uma chamada a `buscar_mesas` e uma busca no conhecimento sobre pratos sem glúten, as duas visíveis no inbox ao lado da resposta que produziram. ## Antes de escrever qualquer coisa: cinco perguntas para o restaurante 1. **Quem escreve, e para quê?** Normalmente reservas, cardápio e horários, depois delivery. 2. **O que o cardápio diz sobre alergênicos?** Quais pratos estão confirmados sem o quê, e o que a cozinha não consegue descartar. 3. **O que é um grupo grande?** A partir de quantas pessoas alguém da equipe assume, e o que conta como evento. 4. **De quais sistemas ele lê?** A API do sistema de reservas, a plataforma de pedidos (uma API, ou só uma página para onde mandar), o cardápio. 5. **O que ele nunca deve prometer?** Que um prato não tem alergênicos, uma mesa específica, um desconto. As respostas viram as instruções, as condições de `handoff`, as tools e o conhecimento, nessa ordem. ## O `vatio.yml` ```yaml workspace: cozinha-oliva agent: name: Cozinha Oliva personality: Simpático e rápido, como um bom anfitrião. Mensagens curtas. instructions: | Você atende os clientes da Cozinha Oliva: reservas, cardápio, alergênicos, horários, endereço e pedidos. Reservas: pergunte a data, o horário e quantas pessoas são. Para 8 ou menos, chame buscar_mesas e ofereça no máximo três horários. Antes de chamar reservar_mesa, peça um nome e repita a reserva. Só diga que a mesa está reservada quando reservar_mesa a tiver devolvido. Anote nas observações qualquer alergia ou ocasião. Para cancelar, peça o código da reserva e chame cancelar_reserva. Grupos com mais de 8 pessoas, eventos fechados e locação do espaço: não procure mesa. Diga que a equipe de eventos cuida disso e transfira a conversa. Cardápio, alergênicos, horários e endereço: busque primeiro em knowledge_lookup. Pedidos: envie o link de pedidos. Para saber em que pé está um pedido, peça o número do pedido e chame status_pedido. Telefones: no WhatsApp as tools já têm o do cliente. No Instagram e no site, peça o número junto com o nome, o código da reserva ou o número do pedido. Regras que você nunca quebra: - Nunca diga que um prato não contém um alergênico, ou que é seguro para uma alergia, se o cardápio no conhecimento não disser isso sobre aquele prato. Quando disser, conte também o que ele diz sobre contaminação cruzada. - Se alguém mencionar uma alergia grave, não tranquilize a pessoa. Anote na reserva, diga que a equipe vai confirmar com a cozinha e transfira a conversa. - Se alguém descrever uma reação alérgica acontecendo agora, diga para ligar para o SAMU (192) ou ir ao pronto-socorro mais próximo já. tools: [buscar_mesas, reservar_mesa, cancelar_reserva, status_pedido, knowledge_lookup, identify_contact] knowledge: [restaurante] links: pedidos: url: https://cozinha-oliva.example/pedidos when: O cliente quer pedir delivery ou para retirada. handoff: after_turns: 10 when: - o cliente menciona uma alergia grave - um grupo com mais de 8 pessoas, um evento fechado ou a locação do espaço - uma reclamação sobre um prato, um delivery ou uma cobrança ``` Algumas escolhas que vale explicar: - **A regra de alergênicos aponta para uma só fonte.** Ela transforma “isso tem castanha?” em uma busca com uma única resposta aceitável. Um modelo que raciocina a partir do nome do prato vai chutar. - **O limite de grupo mora em três lugares.** As instruções, o `maximum: 8` de `buscar_mesas` e o seu backend, que recusa uma reserva maior com um `422`. Só o último é garantia. - **O horário de atendimento não vai no `vatio.yml`.** Quem toca o restaurante o define na página **Negócio** do inbox, por exemplo terça a sexta das 11:00 às 16:00 e das 18:00 às 22:00, sábado das 11:00 às 22:00 e domingo das 11:00 às 16:00. É quando há alguém de olho no inbox: dentro desse horário o agente fica em silêncio depois de transferir; fora dele, e a segunda-feira inteira, que fica de fora, ele continua ajudando e diz que a equipe vai responder. [A Vatio ainda não avisa ninguém de uma transferência](https://vatio.ai/docs/handoff), então coloque os horários em que alguém realmente está com o inbox aberto. - **`after_turns: 10`** é o piso sob o julgamento do modelo: passadas dez mensagens do cliente, a conversa vai para uma pessoa. ## Tools: chegar às suas reservas 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 OLIVA_API https://api.cozinha-oliva.example vatio secrets set OLIVA_API_KEY sk_live_... ``` `tools/buscar_mesas.yml`: ```yaml description: Busca mesas livres para uma data e um número de pessoas. when_to_use: O cliente quer reservar mesa para 8 pessoas ou menos. parameters: type: object properties: data: { type: string, description: "AAAA-MM-DD" } pessoas: { type: integer, minimum: 1, maximum: 8 } required: [data, pessoas] access: public request: method: GET base_url: "$env.OLIVA_API" path: /disponibilidade headers: Authorization: "Bearer $env.OLIVA_API_KEY" query: data: "$params.data" pessoas: "$params.pessoas" respond: data: horarios: "$.horarios" message: when_empty: Não há mesas livres para esse número de pessoas nessa data. default: "Encontrei {{count}} horários livres." ``` `tools/reservar_mesa.yml`: ```yaml description: Reserva uma mesa em um horário livre. when_to_use: O cliente escolheu um horário de buscar_mesas e deu um nome. parameters: type: object properties: horario_id: { type: string } nome: { type: string } telefone: { type: string, description: "Só Instagram e web. No WhatsApp a tool usa o número do contato" } observacoes: { type: string, description: "Alergias ou ocasião, do jeito que o cliente disse" } required: [horario_id, nome] access: public request: method: POST base_url: "$env.OLIVA_API" path: /reservas requires: [params.horario_id, params.nome] headers: Authorization: "Bearer $env.OLIVA_API_KEY" body: horario_id: "$params.horario_id" nome: "$params.nome" telefone: "$params.telefone || $contact.phone_number" observacoes: "$params.observacoes" respond: data: reserva: "$.reserva" ``` No WhatsApp o número do cliente chega com a mensagem dele, então `telefone` usa `$contact.phone_number` e o agente só pede o número no Instagram e no site. `cancelar_reserva` é um `POST` com o código da reserva e o telefone, preenchido do mesmo jeito, e **o seu backend confere se os dois batem** antes de cancelar qualquer coisa: quem preenche os parâmetros de uma tool é o modelo, e qualquer pessoa pode digitar um código. `status_pedido` segue a mesma regra, número do pedido mais telefone, e devolve só a etapa e o horário previsto. Para pedidos, `links.pedidos` é o mais simples, e [as salvaguardas](https://vatio.ai/docs/safeguards) removem qualquer URL que não tenha sido dada ao agente. Se o seu sistema de pedidos tem API, fechar o pedido também pode ser uma tool que o cria e devolve um link de pagamento, por Pix ou cartão; um link que uma tool devolveu é um link que o agente pode enviar. O agente nunca pede dados de cartão. ## Conhecimento: o cardápio e os horários ```bash vatio kb create restaurante vatio kb write restaurante cardapio-principais cardapio-principais.md vatio kb write restaurante cardapio-sobremesas cardapio-sobremesas.md vatio kb write restaurante horarios-e-endereco horarios-e-endereco.md ``` Escreva os alergênicos na seção de cada prato, para que uma busca sobre um prato traga os alergênicos junto: ```markdown # Cardápio: pratos principais ## Risoto de cogumelos Arroz arbóreo, cogumelos, parmesão, manteiga. Vegetariano, não vegano. Alergênicos: leite. Sem glúten: sim, feito em panelas usadas só para pratos sem glúten. ## Talharim de pistache Alergênicos: glúten, ovo, leite, castanhas (pistache). ## Sobre alergênicos na nossa cozinha Trabalhamos com glúten, castanhas, gergelim, frutos do mar e leite. Só os pratos marcados sem glúten são preparados à parte; para os outros alergênicos não podemos descartar contaminação cruzada. ``` A Vatio não lê o seu site, então o cardápio vai em entradas. Quando um prato muda, um supervisor edita a entrada pelo inbox, e cada edição fica guardada como versão. ## Alergênicos: onde uma resposta prestativa é o risco Uma resposta errada sobre alergênicos quase sempre vem do agente tentando ajudar: ele lê “torta de chocolate” e conclui que provavelmente não leva castanha. A configuração acima fecha esse caminho. O cardápio informa os alergênicos de cada prato e a instrução só aceita essa fonte, então, para qualquer prato que não esteja lá, a resposta é “não consigo confirmar isso, vou perguntar para a cozinha”. Alergias graves vão para uma pessoa, porque só a cozinha sabe o que passou pela fritadeira hoje. As regras valem também para áudios e mensagens picadas. A Vatio transcreve o áudio e agrupa as mensagens enviadas em sequência, então “mesa pra 6 no sábado” seguido de “ah, minha esposa tem alergia a castanha” é lido como um pedido só. ## Teste antes de qualquer cliente ```bash vatio push vatio chat "Mesa para 4 amanhã às 20h? Um de nós é celíaco" vatio chat --new "O talharim serve para o meu filho? Ele tem alergia grave a castanha" vatio chat --new "A torta de chocolate tem castanha?" vatio chat --new "Somos 25 pessoas para um aniversário no sábado" vatio chat --new "Jantei aí há uma hora e meus lábios estão inchando" vatio chat show ``` As quatro últimas são as que mais importam: uma alergia grave que ele deve transferir, uma sobremesa que o cardápio não cobre, um grupo para o qual ele não deve procurar mesa e uma reação em que a única resposta é o número de emergência. `chat show` mostra cada chamada a tools. Depois adicione o seu telefone e a sua conta do Instagram como contas de teste nos previews compartilhados do WhatsApp e do Instagram, até cinco de cada, e repita os testes lá. ## Melhore toda semana Quando o gerente lê o inbox, ele **marca** qualquer resposta errada e escreve o que deveria ter acontecido: “o risoto leva parmesão, não é vegano”. `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 ``` Depois conecte o seu número do WhatsApp Business e a sua conta profissional 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. Uma resposta enviada pelo app do WhatsApp Business no celular da recepção assume a conversa até ela ser liberada. O agente só responde às mensagens que os clientes enviam; os lembretes continuam no seu sistema de reservas. O que a legislação local exige que você informe sobre alergênicos continua sendo seu para verificar, e as entradas do cardápio são onde isso precisa estar certo. ## Perguntas frequentes ### Um agente de IA pode fazer reservas de restaurante pelo WhatsApp? Sim. O agente chama o seu sistema de reservas com tools que você descreve em YAML: uma para buscar mesas livres e outra para reservar. A Vatio opera a conversa no WhatsApp, no Instagram e no seu site, e o seu sistema de reservas continua sendo quem confirma. ### Um agente de IA consegue responder sobre alergênicos com segurança? Só com o que você escrever. Coloque os alergênicos de cada prato nas entradas do cardápio que o agente lê e diga para ele nunca afirmar que um prato não contém um alergênico se o cardápio não disser isso. Alergias graves vão para uma pessoa com handoff, porque só a cozinha sabe o que preparou hoje. ### O agente pode receber pedidos de delivery e para retirada? Ele pode enviar o link da sua página de pedidos e, com uma tool, dizer em que pé está um pedido a partir do número do pedido e do telefone. Fechar o pedido dentro do chat exige a API do seu sistema de pedidos por trás de uma tool que devolva um link de pagamento. O agente nunca pede dados de cartão. ### O agente envia lembretes de reserva ou promoções? Sim, quando o seu sistema de reservas pede. Ele chama a Messages API da Vatio para cada cliente, com um modelo de WhatsApp aprovado se a pessoa está há mais de 24 horas sem escrever, e o agente cuida da resposta. Promoções para a sua lista funcionam do mesmo jeito, uma requisição por cliente a partir do seu sistema; a Vatio não tem um painel de campanhas próprio. ### O que acontece quando alguém pede mesa para um grupo grande? Acima do limite que você definir, o agente não procura mesa. Ele diz que a equipe de eventos cuida de grupos e transfere a conversa, que fica no inbox aguardando uma pessoa. A Vatio ainda não avisa ninguém de uma transferência, então alguém precisa estar com o inbox aberto.