Do prompt ao carrinho: arquitetura de um agente que compara ofertas entre Amazon, Mercado Livre e Magalu

Você já viu a demo. Alguém digita "iPhone 15 Pro 256GB" no chat, o agente sai correndo, abre Amazon, Mercado Livre e Magalu, e cospe a tabela bonita com preços lado a lado.

Funciona uma vez. Na frente da câmera.

Em produção, esse agente quebra em três pontos que ninguém mostra na demo: ele compara produto que não é o mesmo, ignora frete e cupom, e chama uma API que vai morrer em abril. Esse post é sobre essas camadas que decidem se o agente vira feature de verdade ou vira piada.

TL;DR

• O que é: arquitetura de um agente multi-marketplace que compara ofertas reais entre Amazon, Mercado Livre e Magalu, considerando produto equivalente, frete e cupom.
• Stack/Modelos: orquestrador agêntico (LangGraph, Claude Agent SDK ou Prism no PHP), LLM com tool use, embeddings para matching, fila e cache.
• Custo/Acesso: APIs públicas e de parceiro. Atenção: a Amazon PA-API será descontinuada em 30/04/2026. Quem está construindo hoje precisa saber.
• Foco: decisões arquiteturais. Não é tutorial de código. É o que separa demo de produto.

Por que comparar preço é um problema sujo

Comparar preço parece um if-else. É marketing.

Na prática, são quatro problemas técnicos empilhados:

1. Identidade de produto. "iPhone 15 Pro 256GB Titânio Natural" no Mercado Livre e "Apple iPhone 15 Pro 256 GB Titânio Natural" na Amazon são o mesmo SKU? Provavelmente. E o "iPhone 15 Pro 256GB" sem cor, importado, com 6 meses de garantia? Não.
2. Custo total. O preço da página é só a primeira fatia. Frete pode chegar a 40% do valor da compra. Cupom muda o ranking. Cashback de carteira distorce ainda mais.
3. Acesso à oferta. Cada marketplace tem uma API com regra própria, rate limit próprio, política de afiliado própria. E mudam.
4. Tempo de resposta do agente. O usuário não espera 30 segundos. Você tem entre 3 e 8.

Resolver os quatro ao mesmo tempo é o que torna o projeto interessante. Errar um deles é o que torna a feature inútil.

Visão geral da arquitetura

O pipeline tem cinco camadas, todas com responsabilidade única:

[Usuário]
    │  prompt em linguagem natural
    ▼
[Orquestrador agêntico]
    │  intenção + filtros (CEP, preço-teto, prazo)
    ▼
[Camada de coleta]  ──►  Amazon │ Mercado Livre │ Magalu
    │  ofertas brutas, uma por marketplace
    ▼
[Normalização]
    │  produto canônico (marca, modelo, variante, GTIN)
    ▼
[Matching de equivalentes]
    │  grupos de oferta para o mesmo SKU
    ▼
[Cálculo de custo total]
    │  ranking por custo final
    ▼
[Resposta + link de carrinho]

Por que separar assim? Porque cada camada falha de um jeito diferente e precisa de monitoramento próprio. Coleta falha por rate limit. Matching falha por embedding ruim. Cálculo de frete falha porque o CEP não chegou. Misturar tudo em um prompt gigante é o jeito mais rápido de não saber por que o agente errou.

Camada 1 — Coleta: três marketplaces, três interfaces

Aqui começa a parte que ninguém mostra na demo.

Amazon

A entrada oficial é a Product Advertising API 5.0. Você começa com 1 TPS e 8.640 requisições por dia, e o limite cresce conforme sua receita de afiliado.

Detalhe que muda tudo: a Amazon vai descontinuar a PA-API em 30 de abril de 2026 e migrar para a Creators API. Se seu agente nasceu este ano, ele já nasce em prazo de validade. Planeje a abstração desde o dia zero.

Mercado Livre

A API pública é generosa. O endpoint /sites/MLB/search?q=... retorna lista de itens ativos sem OAuth. Veja a documentação oficial de itens e buscas.

Cuidado com o calendário: a partir de 18 de março de 2026, requisições que só atualizam preço passam a ser rejeitadas com 400. Não afeta busca, mas se seu agente também publica ou atualiza preço, o contrato mudou.

Magalu

A API da Magalu é mais voltada a seller: catálogo, pedido, etiqueta. Para comparação pública você costuma ir por API de afiliado ou por scraping responsável da página de produto, não pelo endpoint de seller. Os endpoints base são id.magalu.com/oauth/token e api.magalu.com/, e há webhooks para eventos de SKU.

O padrão por trás

Três interfaces totalmente diferentes. Uma vai morrer. Outra muda contrato. A terceira é orientada a vendedor.

A consequência arquitetural é direta: uma camada de adapters, um por marketplace, retornando um DTO comum. Tudo o que o agente vê é o DTO. Quando a Amazon migrar para a Creators API, você troca um adapter, não o agente.

{
  "marketplace": "mercadolivre",
  "external_id": "MLB123456789",
  "title": "Apple iPhone 15 Pro 256GB Titânio Natural",
  "brand": "Apple",
  "gtin": "0194253433637",
  "raw_attributes": { "...": "..." },
  "price": 8499.00,
  "currency": "BRL",
  "shipping_options": [{ "type": "standard", "price": 0, "eta_days": 5 }],
  "coupon_hint": "PRIMEIRACOMPRA10",
  "url": "https://..."
}

Sem DTO comum, qualquer mudança de fornecedor vira refactor em cascata.

Camada 2 — Normalização e identidade do produto

Você tem três ofertas com títulos diferentes. Antes de comparar, precisa decidir se elas falam do mesmo produto.

Existe um identificador global pra isso: o GTIN, também chamado de EAN no Brasil. 13 dígitos, único por SKU. Quando o marketplace expõe o GTIN, sua vida fica simples: dois GTINs iguais = mesmo produto. Fim.

O problema é que nem sempre vem. E quando vem, vem sujo.

Pipeline de normalização que costuma resolver:

1. Limpeza textual. Lowercase, strip de pontuação, normalização de unidades (256gb, 256 GB e 256gigas viram a mesma coisa).
2. Extração de marca. Dicionário curado de fabricantes (Apple, Samsung, Xiaomi, LG, Sony) aplicado por regex tolerante.
3. Extração de modelo. Regex específica por categoria. Em smartphones, algo como iPhone\s*\d+(\s*Pro)?(\s*Max)?.
4. Extração de variante. Cor, capacidade, voltagem, geração.
5. Validação de GTIN. Padding com zero à esquerda para 13 dígitos, validação do dígito verificador. E nunca confundir GTIN com MPN: esse é um dos erros mais comuns no Google Shopping.

Saída: um produto canônico estruturado, não um título livre. É esse objeto que vai pro próximo passo.

Camada 3 — Matching: o produto é mesmo o mesmo?

Aqui é onde a maior parte dos comparadores caseiros morre.

Três níveis de matching, em ordem de preferência:

Nível 1: regra dura (GTIN)

Se as duas ofertas têm GTIN e os GTINs batem, são o mesmo produto. Confiança máxima. Custo zero. É o caminho rápido. E o mais raro.

Nível 2: similaridade semântica

Quando GTIN não tem, você cai em embeddings. Geração de vetor para o produto canônico (marca + modelo + variante + atributos-chave), busca por similaridade de cosseno contra os candidatos.

Threshold típico: cosseno acima de 0.92 = forte candidato a match. Abaixo de 0.85 = não é o mesmo produto. A faixa entre os dois é zona cinza. E zona cinza não vira ranking sozinha.

Detalhe importante: pesquisas recentes em deduplicação multimodal mostram ganho real ao combinar embedding de texto com embedding de imagem do produto, comprimidos em vetores de 128 dimensões. Para celular, livro, eletrodoméstico, onde a foto é padronizada, o custo extra paga.

Nível 3: LLM-as-judge

Para a zona cinza, você não chuta. Você manda os dois títulos para um LLM com prompt específico:

Você é um comparador de produtos. Dadas duas ofertas:
A: {titulo_A} | atributos: {attrs_A}
B: {titulo_B} | atributos: {attrs_B}

Responda APENAS um JSON: {"same_product": bool, "reason": str}
Considere marca, modelo, capacidade, cor, geração e versão regional.

Por que isso funciona quando embedding sozinho não funciona? Porque o LLM aplica conhecimento semântico que o vetor não tem. Ele sabe que "iPhone 15 Pro" e "iPhone 15" são produtos diferentes, mesmo com cosseno alto.

A abordagem multi-agente Q2K, publicada em 2025, atinge 95,62% de acurácia em matching de SKU, justamente decompondo a comparação em perguntas verificáveis. Para um agente em produção, você não precisa do framework completo. Precisa da ideia: decompor a decisão de equivalência em perguntas explícitas.

Camada 4 — Custo total: frete e cupom não são detalhe

Preço de vitrine não decide compra. Custo total decide.

A função de ranking precisa olhar pelo menos três fatores:

custo_final = preco_produto
            + frete_para_o_cep
            - cupom_aplicavel
            - cashback_estimado

Frete é o mais difícil. Cada marketplace expõe de um jeito:

• Mercado Livre: endpoint de calculadora de frete por item e CEP.
• Amazon: frete depende de Prime, FBA, do seller terceiro. Difícil prever sem login.
• Magalu: simulador no front, raramente em API pública aberta.

A consequência arquitetural: o frete é um sub-agente, com cache por CEP + SKU + dia, com fallback. Se a calculadora não responder em N milissegundos, você usa um valor estimado por categoria e marca a oferta como "frete aproximado". Nunca esconda do usuário.

Cupom é pior. Cupom é dado sujo, fora da API, divulgado em comunidade. Tratamento honesto:

1. Detectar campo coupon_hint quando o marketplace expõe.
2. Aplicar regra conhecida (ex: "primeira compra App Magalu = 10%").
3. Marcar a oferta como "cupom condicionado" no ranking.
4. Nunca descontar cupom incerto sem mostrar a condição.

Esconder a condição do cupom é o jeito rápido de o usuário chegar no checkout, não conseguir aplicar, e nunca mais voltar.

Camada 5 — Orquestração: por que isso é trabalho de agente

Por que um agente, e não um job em fila?

Porque a decisão é dinâmica. O usuário pergunta: "acha um iPhone 15 Pro com frete grátis pra 01310-100, mas só se chegar em 3 dias". Esse prompt vira:

1. Intent extraction (product=iPhone 15 Pro, cep=01310-100, max_eta=3, free_shipping=true).
2. Coleta paralela em três marketplaces.
3. Normalização + matching.
4. Cálculo de custo total com filtros.
5. Resposta com top-N e link de carrinho.

LangGraph é forte aqui porque entrega paralelismo, checkpointing e gates de aprovação humana de fábrica. No Laravel, você consegue arquitetura equivalente com Prism + filas + uma máquina de estados simples. Não precisa importar Python pra parecer sério.

O ponto não é o framework. O ponto é a separação:

• O LLM decide o que buscar e como filtrar.
• Os adapters fazem a busca.
• O matching e o ranking são determinísticos. Saem do LLM.

Esse é o erro mais caro que vejo em demos: deixar o LLM "decidir o ranking". Ranking de preço com frete é matemática. Não terceirize raciocínio que sua linguagem já sabe fazer.

Limitações e pontos de atenção

Lista do que vai morder você:

• Bloqueio anti-bot. Scraping responsável de página pública existe, mas marketplace grande tem proteção pesada. Em escala, você vai ser bloqueado. Use API quando há, e respeite robots.txt e rate.
• TOS de afiliado. Comparador que não declara afiliado vira processo. Cada marketplace tem regra própria sobre exibição de preço, link e desambiguação.
• Cache estagnado. Preço muda em segundos no Mercado Livre. Cache de 30 minutos pode mostrar oferta que já não existe. Defina TTL por categoria.
• Match falso positivo. Vender "smartphone equivalente" achando que era o mesmo é o tipo de erro que destrói confiança. Quando o agente não tem certeza, diga que não tem certeza no output.
• Custos do LLM. LLM-as-judge para cada par candidato explode rápido. Faça o filtro com embedding antes, e só mande pro LLM o que ficou na zona cinza.
• Privacidade do CEP. CEP é dado pessoal sob a LGPD. Cache com TTL curto e nunca jogue em log.

Sem essas seis decisões, você tem demo. Não tem produto.

CTA

Construir agente de comparação de preço que aguenta produção é exatamente o tipo de feature que separa o dev que "usa IA" do dev que constrói produto com IA.

No Clã Beer & Code a gente discute esse tipo de arquitetura toda semana: tool use real, matching, ranking, agente em produção. Se você quer parar de fazer demo bonita e começar a entregar feature de IA que sobrevive a um boleto, o Clã é o ambiente.

FAQ rápido

Posso usar só o Mercado Livre, que tem API pública, e ignorar Amazon e Magalu? Pode, e é uma escolha legítima de MVP. Mas o valor do agente cresce com o número de fontes. Comece com um, abstraia o adapter, e vá adicionando.

Preciso mesmo de embeddings? Não dá pra comparar título com Levenshtein? Dá, e funciona pra produto simples. Mas Levenshtein não distingue "iPhone 15 Pro" de "iPhone 15 Pro Max" pelo que importa. A palavra "Max" tem peso semântico, não tipográfico. Em produção, embedding paga o custo.

O agente pode adicionar ao carrinho sozinho? Tecnicamente sim, via deep link com parâmetros. Funciona melhor como "abrir carrinho com produto pré-selecionado" do que "comprar autônomo". Compra autônoma sem confirmação humana é um problema de UX e de segurança que você não quer resolver no v1.

E quando a Amazon desligar a PA-API em abril de 2026? Você troca o adapter de Amazon pela Creators API e o resto do agente nem fica sabendo. Esse é o ROI real da camada de adapter: sobreviver à mudança de fornecedor sem reescrever produto.

Conclusão

Agente de comparação de preço não é prompt. É arquitetura.

Coleta com adapter por marketplace. Normalização com produto canônico. Matching em três níveis, com GTIN antes de embedding e LLM-as-judge só na zona cinza. Custo total que olha frete, cupom e tempo de entrega. Orquestração que mantém a decisão determinística onde precisa ser determinística.

O próximo passo dessa categoria de agente é ir além de preço: entrar em estoque, em variação regional, em recomendação personalizada por histórico. Mas só chega lá quem montou a fundação direito.

Já que você ficou até aqui, vale ver também como implementar Agent Builder e Chatkit da OpenAI com Laravel e como construir recomendação semântica com embeddings em Laravel. Mesma família de problema, ângulos complementares.