Como Construí um Chatbot RAG em Produção para uma Loja WooCommerce
Uma análise detalhada da arquitetura real de um chatbot RAG no n8n para uma loja WooCommerce regulamentada: integração com Pinecone, orquestração com GPT-4o, o que quebrou e o que funcionou.
Um dos meus clientes vende produtos regulamentados no Canadá. A fila de suporte ao cliente deles estava cheia das mesmas perguntas: como devo dosar isso, posso tomar com minha medicação, onde está meu pedido? Um chatbot parecia óbvio. O que não era óbvio era como construir um que não inventasse (alucinasse) informações de dosagem para alguém perguntando sobre interações medicamentosas.
Essa é uma restrição — a precisão importa mais do que a conveniência — que moldou cada decisão de arquitetura.
Por Que RAG em Vez de um System Prompt Lotado
O primeiro instinto com chatbots de LLM é despejar todo o conhecimento do produto no system prompt e dar o trabalho por encerrado. Para um catálogo pequeno e conteúdo de FAQ estático, funciona. Até que não funciona mais e o chatbot começa a alucinar.
O conteúdo de FAQ aqui incluía orientação médica: quais medicamentos interagem com os produtos do cliente, quem não deve usar esses produtos de forma alguma e cronogramas de dosagem para diferentes condições. Esse conteúdo muda conforme a empresa aprende mais, recebe novas diretrizes de conformidade ou atualiza produtos. Codificar isso rigidamente em um prompt do sistema significa que cada atualização de conteúdo exige uma edição de workflow no n8n e um novo deploy.
Isso também significa que a janela de contexto enche rápido e, em algum momento, o modelo começa a despriorizar o conteúdo enterrado no final de um prompt de 10.000 tokens. O que pode criar respostas erradas.
Uma configuração de RAG adequada inverte isso. A base de conhecimento vive em um banco de dados vetorial. O agente a consulta em tempo de execução. Atualizar a base de conhecimento é apenas um workflow de ingestão.
A abordagem de geração aumentada por recuperação (RAG) também oferece algo que um prompt lotado não consegue: uma trilha de auditoria limpa do que o modelo recuperou antes de responder. Quando um cliente pergunta sobre misturar psilocibina com ISRSs e o bot erra, você pode verificar se o documento correto foi retornado. Com um prompt, você estaria apenas adivinhando.
Dois Índices no Pinecone, e não Apenas Um
O workflow de ingestão cria dois índices separados no Pinecone: products (produtos) e knowledge-base (base-de-conhecimento).
Essa separação é deliberada. O catálogo de produtos e o conteúdo de FAQ têm ritmos de atualização diferentes. Um produto é adicionado ou tem seu preço alterado a cada poucas semanas. O conteúdo do FAQ, especialmente a orientação médica, muda com menos frequência, mas importa mais quando muda. Manter os índices separados significa que você pode re-indexar o catálogo de produtos sem tocar nos embeddings do FAQ, e vice-versa.
Isso também significa que a recuperação permanece limpa. Um cliente perguntando "o que há nas cápsulas do Produto X" deve atingir os dados do produto. Um cliente perguntando "posso tomar isso se tiver transtorno bipolar?" deve atingir o FAQ. Misturar os dois em um único índice corre o risco de o modelo trazer uma descrição de produto em resposta a uma pergunta de segurança.
O modelo de embedding utilizado é o text-embedding-3-large com 3072 dimensões. É mais caro por token do que o padrão text-embedding-3-small. Para informações precisas de dosagem e orientação médica em um contexto regulamentado, a qualidade da recuperação não é o lugar onde se deve cortar custos.
A Camada n8n
O chatbot principal roda como um único workflow do n8n com um agente de IA no centro. Mas a arquitetura real consiste em três workflows: o agente principal, um sub-workflow de consulta de pedidos do WooCommerce e um sub-workflow de tickets de suporte do HelpScout.
Essa separação importa mais do que parece. O agente tem cinco ferramentas disponíveis: a base de conhecimento do Pinecone, o sub-workflow do WooCommerce, o sub-workflow do HelpScout, um registrador no Google Sheets e um utilitário de data/hora. Cada sub-workflow é testável de forma independente, depurável de forma independente e pode ser atualizado sem tocar no agente principal.
Se a API do WooCommerce mudar, eu atualizo um workflow. Se o HelpScout adicionar um novo campo que eu queira capturar, eu atualizo um workflow. O workflow do agente principal não precisa saber de nada disso.
O n8n lida com isso usando o tipo de nó toolWorkflow, que permite ao agente chamar outro workflow como uma ferramenta, passando parâmetros estruturados e recebendo saídas estruturadas. O agente decide quando chamar qual ferramenta — mas o prompt do sistema é explícito sobre a ordem de prioridade.
A Integração com WooCommerce
A consulta de pedidos é uma chamada de API em duas etapas. O agente recebe o e-mail do cliente da conversa e o passa para o sub-workflow do WooCommerce. Esse workflow acessa /wp-json/wc/v3/customers?email=... para resolver o e-mail em um ID de cliente, e então acessa /wp-json/wc/v3/orders?customer=... para recuperar os pedidos.
Duas chamadas, mas limpas. A etapa do ID do cliente também serve como uma verificação natural de autenticação: se nenhum registro de cliente existir para aquele e-mail, o workflow retorna "Nenhum usuário encontrado" e o agente responde de acordo. O agente só exibe informações de pedidos quando o cliente fornece seu próprio e-mail, o que resolve a preocupação com a privacidade sem a necessidade de construir um fluxo de autenticação separado.
Os dados de pedidos retornados são filtrados apenas para os campos que importam para o suporte: ID do pedido, status, data de criação, data de modificação e endereço de entrega. O agente é instruído a resumir os três últimos pedidos concluídos em linguagem simples, em vez de despejar um emaranhado de JSON no cliente.
A Ponte com o HelpScout
Quando o bot não consegue responder a uma pergunta, ele não apenas encerra a conversa: ele oferece a criação de um ticket de suporte. Essa oferta é roteada para o sub-workflow do HelpScout.
O sub-workflow recebe três parâmetros: e-mail, uma flag de função (check_ticket ou create_ticket) e o corpo da mensagem. Se for check_ticket, ele consulta o HelpScout por conversas existentes daquele e-mail e as retorna. Se for create_ticket, ele cria uma nova conversa com status "pendente".
A parte mais importante é: o prompt do sistema instrui o agente a incluir a conversa completa em formato de transcrição, não apenas um resumo. A equipe de suporte recebe um registro completo do que o cliente perguntou, o que o bot disse e onde ele travou.
Esta é a parte com a qual as equipes de suporte realmente se importam. Um ticket que diz "o cliente tinha uma pergunta que o bot não pôde responder" é inútil. Um ticket com uma transcrição completa é acionável em 30 segundos.
A Parte que é Fácil de Esquecer
A maioria dos LLMs modernos são modelos capazes. Eles também são, por padrão, ansiosos por serem úteis. Deixado por conta própria, o modelo responderá a perguntas sobre produtos a partir de seus dados de treinamento, em vez de chamar a ferramenta de base de conhecimento primeiro. Para a maioria dos casos de uso, tudo bem. Para uma loja que vende psicodélicos regulamentados, "dos dados de treinamento" e "preciso" não são sinônimos.
O prompt do sistema passou por várias iterações e testes para resolver isso. A versão atual inclui uma seção rotulada como MANDATORY WORKFLOW (WORKFLOW OBRIGATÓRIO) em letras maiúsculas, uma seção STRICT RULES (REGRAS RÍGIDAS) com instruções explícitas para não responder a perguntas da empresa ou de produtos sem pesquisar na base de conhecimento, e uma declaração de que o agente está "falhando em sua função primária" se responder sem consultar a Base de Conhecimento do Pinecone primeiro.
Isso não é apenas para exibição. É uma afirmação de que o modelo deve responder com confiança a perguntas sobre dosagem ou uso com informações que estão na página do produto ou no FAQ.
A lição: a chamada da ferramenta de base de conhecimento tem que ser tratada como uma restrição, não como uma preferência. Os LLMs tendem a usar seu conhecimento paramétrico porque é rápido e geralmente suficiente. "Geralmente" não é bom o suficiente quando a pergunta é sobre interações medicamentosas.
A configuração de dois modelos ajuda. O agente principal roda no GPT-4o. A ferramenta de recuperação da base de conhecimento roda no GPT-4o-mini, que lida com a consulta ao armazenamento vetorial e formata os blocos retornados. Essa divisão de custos também cria um limite claro: o modelo caro raciocina e orquestra, e o modelo mais barato faz o processamento da recuperação.
O Loop de Feedback
Qualquer pergunta que o bot não consiga responder é registrada em uma planilha do Google, com o texto exato da pergunta, a resposta do bot, o e-mail do cliente (se fornecido), um carimbo de data/hora e uma categoria que o modelo atribui (Envio, Produto, Médico, Devoluções, Geral, Outro).
Esta planilha é a forma como a base de conhecimento melhora ao longo do tempo. A equipe a revisa semanalmente, identifica padrões em perguntas não respondidas e adiciona novas entradas de FAQ. Essas entradas são re-indexadas e adicionadas ao Pinecone. O próximo cliente que fizer a mesma pergunta receberá uma resposta real.
Sem esse loop, a base de conhecimento estagna em seu estado inicial. Você terá um chatbot que lida com as perguntas que você antecipou e falha em todo o resto. Com ele, o bot fica mensuravelmente melhor nas perguntas que seus clientes reais estão fazendo.
A Arquitetura é o Produto
Um chatbot que é preciso sobre questões de saúde sensíveis, consulta pedidos do WooCommerce ao vivo, cria tickets de suporte com transcrições completas e registra suas próprias lacunas de conhecimento não é um simples widget. O valor não está na interface do chat — isso são apenas duas linhas de código de incorporação. O valor está na orquestração: os índices que permanecem atualizados, os sub-workflows que lidam com cada preocupação de forma isolada e o loop de feedback que diz o que construir a seguir.
Se você está construindo algo semelhante: uma loja WooCommerce com um volume de suporte que você não consegue gerenciar manualmente, conhecimento de produto que precisa permanecer preciso, este é o tipo de sistema que eu construo. Entre em contato e vamos construir seu novo sistema de suporte com IA!