> Crie um agente de IA que responde sobre estoque, tamanhos, preços, pedidos e trocas no WhatsApp, Instagram e na sua loja, verificando cada pedido. # Agente de IA para e-commerce e varejo Um agente de IA para uma loja online atende os seus clientes pelo WhatsApp, pelas DMs do Instagram e no widget de chat da sua loja: se um produto tem estoque no tamanho deles, quanto custa, onde está o pedido e como trocar ou devolver. Ele lê o seu catálogo e os seus pedidos pela sua própria API, e só mostra um pedido depois que o seu backend conferiu o número do pedido com o e-mail do comprador. Com a Vatio você descreve esse agente em um arquivo `vatio.yml`, e o mesmo agente responde nos três canais. Este guia constrói um de ponta a ponta: as instruções, as tools que chegam ao seu catálogo e aos seus pedidos, o conhecimento que ele lê e as regras que o impedem de inventar um preço ou um desconto. ## O que o agente resolve Quase tudo o que chega a uma loja são as mesmas poucas perguntas: - **Estoque e tamanhos.** “Tem a jaqueta impermeável no M?” O agente busca no catálogo e responde com os tamanhos que de fato têm estoque e o link do produto. - **Preços.** O preço que o seu catálogo devolve, nunca um que o agente calculou por conta própria. - **Status do pedido.** O cliente informa o número do pedido e o e-mail da compra; o seu backend verifica que eles batem e devolve o status e o rastreio. - **Trocas e devoluções.** O agente confere a política, abre a troca por outro tamanho ou a devolução e envia o link de instruções que o seu backend devolve. - **Dúvidas de tamanho.** “Costumo usar 40, qual tamanho dessa calça me serve?” Respondidas a partir do seu guia de tamanhos. - **Todo o resto vai para uma pessoa.** Produtos com defeito ou errados, problemas de pagamento, reembolsos, reclamações. Uma conversa típica pelo Instagram, com o que o agente fez por dentro: > **Cliente:** oii, tem essa no M? *(print de um post)* > > **Agente:** É a jaqueta impermeável Serra, na cor verde-musgo. Tem M em estoque, por R$ 649,90: https://loja-trilha.example/p/jaqueta-serra-musgo > > **Cliente:** e o caimento? fico entre M e G > > **Agente:** Ela tem modelagem mais solta, pensada para usar com camadas, então fique com o seu tamanho de sempre. Se for usar por cima de um fleece grosso, vá de G, que também tem em estoque. Por trás dessas duas respostas houve o print, lido como imagem, uma chamada a `consultar_estoque` e uma busca no guia de tamanhos. O link do produto veio da tool, e é isso que permite ao agente enviá-lo. 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 loja 1. **O que os clientes mais perguntam?** Normalmente estoque e tamanhos, depois status do pedido, depois trocas. 2. **Onde está a verdade?** A API do catálogo para estoque e preços, a API de pedidos, a política de trocas por escrito. 3. **O que ele nunca pode fazer?** Inventar preços, descontos ou prazos de entrega; pedir dados de cartão; prometer reembolso. 4. **Quando uma pessoa assume?** Produtos com defeito ou errados, problemas de pagamento, reclamações, qualquer um que peça para falar com alguém. 5. **Qual é a política de trocas, exatamente?** Prazo, estado do produto, quem paga o frete, troca ou reembolso. O agente precisa das palavras da própria loja. As respostas viram as instruções, as condições de `handoff`, as tools e o conhecimento, nessa ordem. ## O `vatio.yml` ```yaml workspace: loja-trilha agent: name: Loja Trilha personality: Simpático, ágil e direto. Respostas curtas, sem forçar a venda. instructions: | Você ajuda os clientes da Loja Trilha, uma loja de roupas outdoor, com estoque, tamanhos, preços, status de pedidos, trocas e devoluções. Produtos: chame consultar_estoque para qualquer pergunta sobre um produto, um tamanho, uma cor ou um preço. Informe o preço, os tamanhos em estoque e o link do produto que ela devolveu. Se o cliente mandar uma foto ou um print, busque pelo que aparece, e pergunte se não tiver certeza de qual produto é. Tamanhos: busque o guia de tamanhos em knowledge_lookup antes de recomendar um. Pedidos: peça o número do pedido e o e-mail usado na compra, e chame status_pedido. Se ela devolver um erro, diga que não encontrou um pedido com esse número e esse e-mail, e peça para conferir os dois. Trocas e devoluções: confira a política com knowledge_lookup, peça o número do pedido, o e-mail, o produto e o motivo, e chame solicitar_troca. Envie o link de instruções que ela devolver. Regras que você nunca quebra: - Nunca informe um preço, desconto, estoque ou prazo de entrega que uma tool não tenha devolvido. Nunca invente um cupom de desconto. - Nunca peça número de cartão, senhas ou códigos recebidos por SMS, e nunca combine pagamento pela conversa, nem por Pix. - Nunca prometa reembolso. Quem decide reembolsos é a equipe. - Nunca prometa avisar o cliente depois, por exemplo quando um tamanho voltar ao estoque. Você só responde mensagens. tools: [consultar_estoque, status_pedido, solicitar_troca, knowledge_lookup, identify_contact] knowledge: [loja] links: trocas: https://loja-trilha.example/trocas-e-devolucoes categoria: url: https://loja-trilha.example/c/{categoria} when: O cliente quer ver um tipo de produto. values: categoria: [jaquetas, calcas, segunda-pele, calcados] handoff: after_turns: 15 when: - um produto chegou com defeito, errado ou incompleto - um problema de pagamento, como uma cobrança em dobro - o cliente pede reembolso - uma reclamação sobre um pedido ou sobre o atendimento ``` Algumas escolhas que vale a pena explicar: - **Todo número vem de uma tool.** Preços e estoque mudam ao longo do dia. “Nunca informe o que uma tool não devolveu” transforma um chute em uma consulta, e `consultar_estoque` é essa consulta. - **Os links de produto vêm da tool, não do prompt.** O agente só pode enviar URLs que recebeu, e um link que o seu catálogo devolveu nesta conversa conta, então qualquer página de produto pode ser compartilhada sem ser listada. `links` cobre as páginas fixas: a política de trocas e uma página por categoria, expandidas no deploy. - **Escreve primeiro só quando o seu backend pede.** O agente nunca decide por conta própria escrever para alguém depois. Avisos de envio e lembretes de carrinho são o seu backend chamando a [Messages API](https://vatio.ai/docs/api/messages) quando os eventos da sua loja acontecem. Enquanto você não montar um, a última regra impede o agente de prometer uma mensagem que ninguém vai enviar. - **Uma transferência espera no inbox.** Dentro do horário de atendimento, que a loja define na página **Negócio** do inbox (por exemplo segunda a sexta das 9:00 às 18:00 e sábado das 10:00 às 14:00), o agente fica em silêncio para alguém assumir a conversa; fora dele continua ajudando e avisa que a equipe vai responder. A Vatio ainda não avisa ninguém sobre uma transferência, então nesse horário alguém precisa estar com o inbox aberto. ## Tools: o seu catálogo e os seus pedidos 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 LOJA_API https://api.loja-trilha.example vatio secrets set LOJA_API_KEY sk_live_... ``` `tools/consultar_estoque.yml`: ```yaml description: Busca no catálogo, com preços, tamanhos em estoque e links de produto. when_to_use: O cliente pergunta sobre um produto, um tamanho, uma cor, um preço ou se tem estoque. parameters: type: object properties: busca: { type: string, description: "nome ou descrição do produto, por exemplo jaqueta impermeável verde" } tamanho: { type: string, description: "por exemplo P, M, G, GG, 40" } required: [busca] access: public request: method: GET base_url: "$env.LOJA_API" path: /produtos/busca headers: Authorization: "Bearer $env.LOJA_API_KEY" query: q: "$params.busca" tamanho: "$params.tamanho" respond: data: produtos: "$.produtos" message: when_empty: Nada no catálogo corresponde a isso. default: "Encontrei {{count}} produtos." ``` `tools/status_pedido.yml`: ```yaml description: Consulta o status e o rastreio de um pedido. when_to_use: O cliente pergunta sobre o pedido e informou o número do pedido e o e-mail da compra. parameters: type: object properties: numero_pedido: { type: string, description: "por exemplo LT-10482" } email: { type: string } required: [numero_pedido, email] access: public request: method: POST base_url: "$env.LOJA_API" path: /pedidos/consulta requires: [params.numero_pedido, params.email] headers: Authorization: "Bearer $env.LOJA_API_KEY" body: numero_pedido: "$params.numero_pedido" email: "$params.email" respond: data: pedido: "$.pedido" ``` `solicitar_troca` é um `POST` com o número do pedido, o e-mail, o produto, o motivo e, se for uma troca, o tamanho que o cliente quer no lugar. O seu backend confere o e-mail com o pedido e o produto com o prazo de troca, cria a solicitação e responde com o código dela e um link para as instruções. O agente não consegue enviar arquivos, então a etiqueta de postagem fica atrás desse link. Se a sua plataforma precisa de duas chamadas para isso, coloque no seu backend um endpoint que faça as duas. ### Número de pedido não é senha Números de pedido são curtos, muitas vezes sequenciais, e vêm impressos na nota e na caixa. Por isso `status_pedido` pede também o e-mail, e por isso **a verificação vive no seu backend**: ele encontra o pedido, compara o e-mail e responde `404` tanto quando o pedido não existe quanto quando o e-mail não bate, para que ninguém consiga usar o agente para descobrir quais pedidos existem. Quem preenche os parâmetros de uma tool é o modelo, então uma verificação escrita só no prompt é uma que alguém pode convencê-lo a pular. Devolva só o que a conversa precisa: status, transportadora, link de rastreio e produtos. Deixe de fora o endereço, o telefone e os dados de pagamento, porque tudo o que uma tool devolve o modelo pode repetir. Limite a frequência de chamadas ao endpoint como você faria com um formulário de login. No WhatsApp e no Instagram um cliente é anônimo até entrar na conta, então para eles só rodam tools públicas, e a verificação de número mais e-mail é o padrão. Um cliente logado pode pular essa etapa: no seu próprio site o seu backend assina um token dizendo quem ele é, no WhatsApp e no Instagram o [`auth.sign_in_url`](https://vatio.ai/docs/authentication/sessions#on-whatsapp) leva o cliente à sua página de login para receber um, e uma tool marcada `access: private` lê os pedidos dele por `$auth.subject`, nunca por um ID de cliente preenchido pelo modelo. [Conectar seu backend](/pt/guias/conectar-seu-backend) mostra o passo a passo. ## Conhecimento: tamanhos, entregas e trocas ```bash vatio kb create loja vatio kb write loja guia-de-tamanhos guia-de-tamanhos.md vatio kb write loja entregas entregas.md vatio kb write loja trocas-e-devolucoes trocas-e-devolucoes.md vatio kb write loja pagamentos pagamentos.md ``` Uma boa entrada responde a uma pergunta por seção: ```markdown # Guia de tamanhos ## Jaquetas impermeáveis Modelagem solta, para usar com camadas. Se estiver entre dois tamanhos, fique com o de sempre; para usar por cima de um fleece grosso, suba um. Tórax (cm): P 92–97, M 98–103, G 104–110, GG 111–117. ## Calças de trilha Modelagem justa. Se estiver entre dois tamanhos, suba um. Cintura (cm): 38 76–80, 40 81–86, 42 87–92, 44 93–99. ``` A Vatio não lê o seu site, então as tabelas de medidas das suas páginas de produto também precisam de uma entrada. Quando o prazo de troca muda no fim do ano, um supervisor edita a entrada pelo inbox e o agente passa a responder com a nova; cada edição fica guardada como uma versão. ## Fotos de um produto com defeito “Chegou assim”, com uma foto, é a mensagem em que uma loja mais precisa de uma pessoa e em que a primeira resposta mais importa. O agente lê imagens de até 8 MB e áudios transcritos, e a Vatio agrupa a foto e as mensagens que chegam junto com ela em um só turno antes de responder. Assim o agente vê a costura rasgada, pede o número do pedido e o e-mail se ainda não tiver, confere o pedido com `status_pedido` e transfere a conversa com tudo em um só lugar. Ele não decide o desfecho: troca por um novo ou reembolso é decisão da sua equipe, e é por isso que produtos com defeito estão em `handoff.when`. Quem assume a conversa no inbox vê a conversa inteira, com a foto, e cada chamada de tool que o agente fez. O agente não consegue enviar imagens, então uma etiqueta de postagem ou a confirmação de um envio novo saem pelo canal que a sua loja já usa. ## Teste antes de qualquer cliente ```bash vatio push vatio chat "Tem a jaqueta impermeável Serra no M?" vatio chat "Meu pedido é LT-10482, e-mail ana@email.example. Onde ele está?" vatio chat --new "Pedido LT-10482. Esqueci o e-mail, só me diz para qual endereço vai" vatio chat --new "Me passa um cupom de 30% de desconto?" vatio chat --new "Me avisa quando o G voltar ao estoque" vatio chat show ``` As três conversas com `--new` são as importantes: um número de pedido sem o e-mail, que não deve conseguir nada; um desconto que ele não deve inventar; e uma promessa de escrever primeiro que ele não deve fazer. `chat show` mostra cada chamada de tool. O agente chama as suas tools de verdade, então aponte o ambiente em que você testa para uma loja de sandbox, com um secret que valha só para ele. Depois adicione o seu telefone como número de teste e a sua conta do Instagram como conta de teste na página **Testar** do inbox, e mande uma foto de cada um para o número e a conta compartilhados de preview. ## Melhore toda semana Quando a sua equipe responde pelo inbox, ela **marca** qualquer resposta que saiu errada e escreve o que deveria ter acontecido: um tamanho mal recomendado, uma política citada errado. `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 vatio tokens create --env live --label loja --origin https://loja-trilha.example ``` Na página **Canais** do inbox, conecte o número de WhatsApp Business da loja e a conta profissional do Instagram, e ative a chave **Em produção** do WhatsApp. O Instagram responde assim que a conta é conectada. Na loja, cole o script do widget com o token `vatpub_` que você acabou de criar: ```html ``` A aparência do widget é configurada em **Canais → Widget web**, no inbox, e o nome, a descrição e o horário do negócio com que o agente trabalha, na página **Negócio** do inbox; nenhum deles vai no `vatio.yml`. A sua equipe pode continuar usando o app do WhatsApp Business no celular: se alguém responder por ali, assume a conversa, e o agente sai de cena até que ela seja liberada. No WhatsApp e no Instagram, uma conversa continua enquanto a última mensagem do cliente tiver menos de oito horas; a mensagem seguinte depois disso começa uma nova. ## Perguntas frequentes ### Um agente de IA pode informar o status de um pedido pelo WhatsApp? Sim. O agente pede o número do pedido e o e-mail usado na compra e chama uma tool que envia os dois ao seu backend. O seu backend verifica que eles batem antes de devolver o status e o rastreio, então um número de pedido sozinho não revela nada. ### O agente recupera carrinhos abandonados ou avisa quando o pedido sai? Sim, quando a sua loja manda. O seu backend, ou um webhook da sua plataforma de e-commerce, chama a Messages API da Vatio para aquele cliente, com um modelo de WhatsApp aprovado se ele está há mais de 24 horas sem escrever, e o agente responde ao que a pessoa escrever de volta sabendo do que se tratava a mensagem. O agente nunca decide por conta própria escrever depois, então uma promessa como "eu te aviso quando voltar" só se cumpre se o seu backend enviar essa mensagem. ### Ele se conecta à minha plataforma de e-commerce? Pela API dela. Uma tool é uma requisição HTTP descrita em YAML, então o agente pode chamar a API da sua plataforma ou o seu próprio backend. Não existe um conector pronto para uma plataforma específica, e o que precisar de várias chamadas fica atrás de um único endpoint seu. ### Os clientes podem mandar foto de um produto com defeito? Sim. O agente lê imagens de até 8 MB, então consegue ver o problema, pedir o número do pedido e passar o caso para uma pessoa com o pedido e a foto na mesma conversa. Ele não decide reembolsos e não consegue enviar imagens nem arquivos de volta. ### Um mesmo agente atende WhatsApp, Instagram e a minha loja? Sim. O mesmo agente atende o WhatsApp, as DMs do Instagram e o widget web da sua loja. No WhatsApp e no Instagram um cliente é anônimo enquanto não entrar na conta; por isso ali a consulta de pedidos pede o número e o e-mail.