왜 빌드 로그인가 (다른 튜토리얼이 아닌)

모든 AI 쇼핑 튜토리얼은 같은 것을 보여줍니다. SDK를 설치하고, 도구를 호출하고, 배포하는 것. 그들 중 어느 것도 API가 오래된(stale) 가격을 반환하거나, 판매자가 _지리적으로 차단(geo-blocked)_되었거나, 에이전트가 단일 쇼핑객 문의에 대해 _네 가지 다른 통화_를 조정해야 하는 상황은 보여주지 않습니다.

여기는 작동하는 국경 간 쇼핑 에이전트의 빌드 로그입니다. 우리가 배포한 것, 무엇이 고장 났는지, 그리고 이제 모든 고객 통합에서 사용하는 패턴들입니다.

우리가 구축하는 것

제품 개요(

1. 쇼핑 작업 시 항상 mode=offer를 전달하세요

mode=product는 표준 제품 카드 (canonical product card)를 반환합니다 (브라우징 및 카테고리 페이지에 적합). mode=offer는 판매자별로 가장 저렴한 실시간 (live) 오퍼를 반환합니다 (쇼핑 결정에 적합). 동일한 에이전트 흐름 내에서 이 둘을 혼합하면 모델에 "가장 저렴한" 것에 대한 두 가지 서로 다른 멘탈 모델 (mental models)을 제공하게 되어 답변의 재현성 (reproducibility)이 떨어집니다.

2. 검색 시점에 항상 통화를 지정하세요

search_products의 currency 파라미터는 변환 (conversion)이자 필터 (filter) 역할을 합니다. 즉, 오퍼를 대상 통화로 변환하여 반환할 뿐만 아니라, 판매자가 해당 지역으로 배송하지 않는 오퍼는 건너뜁니다. 우리는 글로벌 유스케이스 (use cases)에는 USD를, 싱가포르 제한 유스케이스에는 SGD를 기본값으로 사용합니다. 이를 지정하지 않으면 사용자가 직접 조정해야 하는 여러 통화가 섞여서 나옵니다.

3. find_similar를 탐색 도구가 아닌 재가격 책정 (re-pricing) 도구로 취급하세요

find_similar는 여러 판매자에 걸쳐 동일한 제품을 찾습니다. 가격 비교 에이전트에서 올바른 접근 방식은 다음과 같습니다: 최상위 결과를 가져온 다음, find_similar를 호출하여 동일한 통화 내에서 동일한 SKU가 다른 곳에서 더 저렴한지 확인하는 것입니다. 탐색 (Discovery)은 search_products이며, 재가격 책정 (re-pricing)은 find_similar입니다.

우리가 배운 것 (그리고 여전히 파악 중인 것)

• 에이전트 프롬프트 (agent prompt)가 곧 캐시 (cache)입니다. 동일한 모델, 동일한 도구, 동일한 데이터라 하더라도 시스템 프롬프트 (system prompt)가 다르면 결과 품질이 달라집니다. 우리는 성능 저하 (regression)가 발생할 때마다 업데이트하는 prompts/shopper.md를 보유하고 있습니다.
• 지연 시간 (Latency)은 버그가 아니라 기능입니다. 배송비 확인을 누락한 0.6초의 응답보다, 배송비를 포함한 1.2초의 응답이 더 나은 답변입니다.
• 가장 어려운 문제는 여전히 데이터 신선도 (data freshness)입니다. BuyWhere는 4~6시간 주기로 모든 오퍼의 가격을 재책정합니다. 할인 품목의 경우 이것만으로는 부족합니다. 현재 우리는 20% 미만 할인 품목에 대해서는 1시간 주기, 50% 미만 할인 품목에 대해서는 15분 주기의 재가격 책정을 테스트하고 있습니다.

직접 시도해 보세요

Node 20 이상 버전과 OpenAI 키가 있다면 전체 빌드 (LangChain + BuyWhere MCP)에 약 30분이 소요됩니다:

# MCP 서버 설치
npm install -g @buywhere/mcp-server
# 자격 증명 설정
...

이 리포지토리에는 각 반복 과정과 위의 설계 결정(design decisions)을 이끌어낸 정확한 쿼리(queries)를 단계별로 설명하는 사례 연구 노트북 (case-study notebook)이 포함되어 있습니다.

국경 간 쇼핑 에이전트 (cross-border shopping agent)를 구축 중이며 전문가의 검토가 필요하신가요? 이번 달에 무료 통합 상담 (integration calls)을 진행하고 있습니다 — partners@buywhere.ai로 예약하세요.