#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

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 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:

vatio secrets set LOJA_API https://api.loja-trilha.example
vatio secrets set LOJA_API_KEY sk_live_...

tools/consultar_estoque.yml:

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:

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 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 mostra o passo a passo.

#Conhecimento: tamanhos, entregas e trocas

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:

# 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

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.

#Colocar no ar

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:

<script async src="https://cdn.vatio.ai/v1/widget.js"
        data-workspace="loja-trilha"
        data-token="vatpub_REPLACE_ME"></script>

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.

Atualizado: 11 de outubro de 2026