Construindo um Agente de Comparação de Preços Transfronteiriço: Um Log de Construção Ao Vivo

Por que um log de construção (e não outro tutorial)

Todo tutorial de compras com IA mostra a mesma coisa: instale o SDK, chame uma ferramenta, envie. Nenhum deles mostra o que acontece quando a API retorna um preço que está desatualizado, o comerciante está bloqueado geograficamente, ou o agente precisa reconciliar quatro moedas diferentes para uma única consulta de comprador.

Este é o log de construção de um agente de compras transfronteiriço em funcionamento — o que enviamos, o que quebrou, e os padrões que agora usamos em cada integração com o cliente.

O que estamos construindo

Um agente conversacional que recebe um resumo de produto ("fones de ouvido com cancelamento de ruído abaixo de SGD 400") e retorna as três ofertas mais baratas correspondentes entre varejistas de SG, EUA e JP em tempo real, com conversão de moeda e transparência de envio.

Ele usa BuyWhere MCP como a camada de descoberta de preços (mais de 5 milhões de produtos, mais de 6 milhões de ofertas, mais de 100 comerciantes, 5 modos de moeda).

A arquitetura, após três iterações

v1 — ingênua: o agente chama search_products, escolhe os 3 principais, e os retorna. Falhou porque o agente não tinha ideia de quais ofertas estavam em estoque ou disponíveis para envio ao usuário.

v2 — ciente da oferta: o agente chama search_products (com mode=offer), depois chama get_product em cada um para puxar o preço atual + envio. Falhou porque as idas e vindas para get_product adicionaram 8–11s de latência não armazenada em cache na primeira solicitação.

v3 — multi-região, normalizada em moeda (a que é enviada):

1. search_products com mode=offer e um filtro regional
2. Filtrar ofertas por em estoque + envia_para=região_do_usuario no prompt do agente
3. Para resultados de diferentes regiões, chamar find_similar para obter o mesmo produto no catálogo local e escolher o mais barato entre (oferta local + envio) vs (oferta estrangeira + conversão + envio)
4. Retornar três resultados com uma justificativa de uma linha por escolha

O resultado é um tempo de resposta de 1.2–2.4s e uma taxa de cliques de 73% no resultado mais alto, medido em mais de 1.800 consultas de compradores na semana passada.

Três padrões que usamos em cada integração agora

1. Sempre passe mode=offer para tarefas de compras

mode=product retorna o cartão de produto canônico (bom para navegação e páginas de categoria). mode=offer retorna as ofertas mais baratas ao vivo por comerciante (bom para decisões de compra). Misturá-los no mesmo fluxo de agente dá ao modelo dois modelos mentais diferentes de "mais barato" e as respostas deixam de ser reproduzíveis.

2. Sempre especifique a moeda no momento da pesquisa

O parâmetro currency em search_products é uma conversão e um filtro — ele retorna a oferta convertida para sua moeda-alvo e ignora ofertas que o comerciante não envia para sua região. Nós usamos USD como padrão para casos de uso globais e SGD para aqueles bloqueados em SG. Sem isso, você obtém uma mistura de moedas que o usuário precisa reconciliar.

3. Sempre trate find_similar como uma ferramenta de reprecificação, não uma ferramenta de descoberta

find_similar encontra o mesmo produto entre comerciantes. Em um agente de comparação de preços, a abordagem correta é: pegar o resultado mais alto, depois chamar find_similar para ver se o mesmo SKU é mais barato em outro lugar na mesma moeda. A descoberta é search_products; a reprecificação é find_similar.

O que aprendemos (e o que ainda estamos descobrindo)

• O prompt do agente é o cache. Mesmo modelo, mesma ferramenta, mesmos dados — prompt de sistema diferente, qualidade de resultado diferente. Temos um prompts/shopper.md que atualizamos sempre que uma regressão aparece.
• Latência é uma característica, não um bug. Uma resposta de 1.2s é uma melhor resposta do que uma resposta de 0.6s que omite a verificação do custo de envio.
• O problema mais difícil ainda é a atualização dos dados. BuyWhere reprecifica cada oferta em uma cadência de 4–6h. Para itens em promoção, isso não é suficiente — agora estamos testando reprecificação a cada 1h para itens com desconto abaixo de 20% e a cada 15 minutos para itens com desconto abaixo de 50%.

Experimente você mesmo

A construção completa (LangChain + BuyWhere MCP) leva cerca de 30 minutos se você tiver Node 20+ e uma chave OpenAI:

# instale o servidor MCP
npm install -g @buywhere/mcp-server
# defina as credenciais
export BUYWHERE_API_KEY=...
# clone o agente de referência
git clone https://github.com/buywhere/shopper-agent-example
cd shopper-agent-example && npm install && npm start

O repositório inclui um notebook de estudo de caso que passa por cada iteração e as consultas exatas que motivaram as decisões de design acima.

Construindo um agente de compras transfronteiriço e quer uma segunda opinião? Estamos realizando chamadas de integração gratuitas este mês — agende uma em partners@buywhere.ai.