Shopify의 Anthropic commerce-agents blueprint 기반 상점 에이전트 예제

참고

Claude를 사용하여 Shopify에서 맞춤형 스토어프런트 에이전트를 구축하는 데 관심이 있다면, 다음 예제가 시작하는 데 도움이 될 것입니다. 또는 Shopify Inbox를 사용하여 관리되는 스토어프런트 에이전트를 설정할 수도 있습니다. 이 경우 코딩이 필요하지 않으며 온라인 스토어에서 고객 질문에 답변할 수 있습니다.

Anthropic의 commerce-agents blueprint 기반 Shopify 구현:
storefront/
은 해당 blueprint의 쇼핑 에이전트를 실제 Shopify 스토어에 적용하며,
merchant/
은 동일한 스토어의 Admin API를 통해 머천트 에이전트를 실행합니다. 각 예제는 자체적으로 독립적입니다(자체 API 호스트, 웹 앱, fixtures 및 테스트 보유) — 그리고 vendor/와 blueprint의 패키지만 공유하며, 이 패키지들은 requirements.txt에 고정된 커밋에서 Anthropic의 저장소로부터 설치됩니다.

Anthropic의 commerce-agents blueprint와 Shopify의 UCP 엔드포인트를 기반으로 구축된 실제 Shopify 스토어용 스토어프런트 쇼핑 에이전트입니다. SHOP_DOMAIN을 스토어로 지정하면 에이전트는 라이브 카탈로그를 검색하고, 실제 장바구니를 구성하며, 정책 및 FAQ에서 답변하고, 고객을 스토어 자체의 결제 페이지로 연결합니다. 웹 앱은 이름, 로고, 색상, 베스트셀러 등으로부터 스토어를 브랜드화하므로, 동일한 코드가 모든 상점에 대한 브랜딩된 스토어프런트가 됩니다. 여기서 주문을 하거나 결제를 처리하는 것은 아무것도 없습니다: 결제(checkout), 배송(shipping), 및 지불(payment)은 모두 Shopify 자체 페이지에서 이루어집니다.

blueprint의 패키지들(쇼핑 에이전트, 그 게이트와 스킬, 그리고 공유되는 commerce 타입)은 requirements.txt에 고정된 커밋에서 Anthropic의 저장소로부터 설치됩니다; 이 저장소는 변경 없이 위에 Shopify 스토어프런트를 추가합니다. vendor/는 blueprint의 예제 스캐폴딩을 담고 있습니다 — NOTICE를 참조하십시오.

Python 3.11+ 및 Node 22.

python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env # ANTHROPIC_API_KEY 추가
...

npm install && npm run dev -w storefront/web # 별도의 터미널 · http://localhost:3005

SHOP_DOMAIN은 /.well-known/ucp를 서비스하는 모든 도메인입니다 (기본값 demostore.mock.shop)

변수들을 나열합니다. 장바구니를 추가하려면 스토어가 이미 가지고 있는 것을 열고 ?cart=<장바구니 ID>로 프론트스토어를 열거나 POST /api/cart/attach를 사용하세요.

; 먼저 장바구니를 다시 읽어오므로, 다른 곳에서 수행된 작업은 덮어쓰여지지 않습니다.

• 50달러 이하의 선물 찾고 있어요. 뭘 추천해 주시겠어요?
• 첫 번째 것을 제 장바구니에 추가해 주세요.
• 반품 정책이 어떻게 되나요?

웹 앱의 그리드, 장바구니 드로어, 결제 버튼은 대화와 동기화되며; 결제 버튼을 누르면 스토어의 호스팅된 결제 페이지가 열립니다.

Shop app 자격 증명(credentials)을 사용하면 구매자가 로그인할 수 있고 search_catalog는 개인화된 결과를 반환합니다. SHOPIFY_UCP_CLIENT_ID / SHOPIFY_UCP_CLIENT_SECRET(Shopify Dev Dashboard에서 발급됨)를 설정해야 합니다. 이것들이 없으면 로그인 경로가 503 에러를 반환하고 모든 세션이 게스트(guest)로 처리됩니다. 게스트 경로는 자격 증명 없이 실행하는 것과 동일합니다.

로그인 과정은 Shop에 대한 서버 측의 권한 부여 코드(authorization-code) 방식입니다. 구매자 토큰은 세션별로 키가 지정되며 모델, 브라우저 또는 로그에 절대 도달하지 않습니다. 각 카탈로그 호출은 카탈로그에서 요구하는 대로 토큰을 구매자의 IP와 쌍으로 묶습니다. 만료된 토큰은 한 번 재발급(re-mints)되고; 재발급 실패 시에는 게스트로 폴백합니다.

결제는 인계(handoff) 과정입니다. 비어있지 않은 장바구니는 UCP 결제(create_checkout, 장바구니 쓰기 후 재동기화됨)로 지연 배치(lazily staged)되며, 고객은 스토어 자체의 continue_url을 통해 마무리를 합니다. complete_checkout은 절대 호출되지 않습니다. 이 함수는 주문을 생성하고 결제를 처리하는데, 이 리포지토리에서는 이를 수행하지 않습니다.

주문은 Order MCP v1 시맨틱스를 따릅니다: 이 에이전트를 통해 배치된 주문만 구매자의 요청(절대 폴링 아님)에서 보이며, 자격 증명에는 read_global_api_orders 스코프가 포함되어야 합니다. 해당 스코프가 없으면 백엔드는 주문 도구를 비활성화하고 에이전트는 고객에게 주문 추적이 불가능하다고 알려주며 대신 확인 이메일을 안내합니다.

같은 상점의 다른 면: Shopify Admin GraphQL API를 활용한 blueprint 기반 머천트 에이전트입니다. 이 에이전트는 상점의 제품(products), 주문(orders), 재고(inventory) 정보를 읽어와 변경 사항을 제안하고, 운영자가 승인하는 변경 사항만 다시 기록합니다.

SHOPIFY_LOCAL_STORE=1 uvicorn merchant.api.main:app --port 8005

이것은 Shopify 계정이 필요 없습니다. SHOPIFY_LOCAL_STORE=1는 백엔드를 다음 위치로 지정합니다:
merchant/api/local_store.py

여기는 merchant/data/seed.json에서 시드된 하나의 상점 Admin API를 위한 인프로세스(in-process) 대체재입니다. 실제 개발 상점을 대상으로 하려면, 대신 merchant/.env 파일에 SHOPIFY_SHOP_DOMAIN과 SHOPIFY_ADMIN_TOKEN을 넣으세요. 이 값들은 merchant/.env.example이 모든 변수를 문서화하며, 각 읽기(read)가 필요한 범위를는 merchant/README.md가 설명합니다. 그런 다음 merchant/scripts/seed_store.py로 시드하고 merchant/scripts/smoke_live.py로 확인하세요.

쓰기(Writes) 작업은 게이트(gated)되어 있으며, 이 부분이 코드를 읽어볼 가치가 있습니다. 에이전트의 stage_* 도구들은 Admin Mutation을 전혀 보내지 않습니다: 스테이지된 변경 사항은 레저(ledger)에 기록되며, 오직 POST /api/merchant/changes/{id}/apply만이 이를 적용합니다. Admin 토큰은 merchant/api/agent_config.py에서 한 번 읽혀져 트랜스포트(transport)로 전달되며, 모델(model), 라우트(route), 또는 로그에 절대 도달하지 않습니다.

이 예제는 호스트(host)만 제공하며 웹 UI를 포함하고 있지 않습니다. /api/merchant는 읽기 작업, 채팅 스트림, 그리고 승인 호출을 처리하며, 운영자용 애플리케이션은 사용자가 직접 구축해야 합니다.

merchant/README.md가 두 상점 중 어느 곳에 대해서도 실행하는 방법을 안내합니다.

storefront/api/: FastAPI 호스트입니다. UCP MCP 클라이언트(ucp_client.py), blueprint의 StorefrontBackend(shopify_backend.py), Shop으로 로그인 기능(identity.py), 브랜드 및 카탈로그 워밍업 라우트, 그리고 에이전트 설정 등을 제공합니다.
storefront/web/: 브랜딩된 상점 전면(Next.js)입니다. 제품 그리드, 장바구니 서랍(cart drawer), blueprint의 공유 웹 컴포넌트를 사용한 어시스턴트 레일을 포함합니다.
storefront/scripts/, storefront/data/: 라이브 스모크 체크, 피처 기록기(fixture recorder), 그리고 테스트가 재생하는 기록된 MCP 응답을 담고 있습니다.
merchant/api/

메르샹트 호스트(merchant host) — Admin GraphQL 전송(admin_client.py), 전송하는 모든 문서(queries.py), 카탈로그 및 주문 캐시, MerchantBackend(shopify_backend.py), 스테이징 레이어(staging.py), 그리고 인-프로세스 로컬 스토어.merchant/scripts/, merchant/data/: 스토어 시더(store seeder), 라이브 스모크 체크(live smoke check), 시드 카탈로그, 및 경고 임계값.vendor/: 블루프린트의 예제 스캐폴딩(demo_common, web-shared)과 그 기술들로, skills/shopping/와 skills/merchant/ 아래에 각각 에이전트당 5개씩 포함되어 있으며 Anthropic의 저장소에서 가져왔습니다 — 작은 로컬 수정 사항은 NOTICE를 참조하십시오.

pytest # 기록된 응답, 네트워크 없음
python storefront/scripts/smoke.py # 라이브 체크, 게스트 경로
python storefront/scripts/smoke_signin.py # 로그인한 경로; SHOP_ACCESS_TOKEN 없이는 무작위 작업만 수행

스토어프런트의 테스트는 storefront/data/recorded_responses.json을 통해 httpx.MockTransport를 재현하며, storefront/scripts/record_fixtures.py는 라이브 스토어에서 다시 기록합니다. 메르샹트는 실제 모듈을 가짜 Admin API 응답(merchant/api/tests/fake_admin.py) 및 로컬 스토어에 대해 실행하고, merchant/scripts/smoke_live.py가 그들의 라이브 대응물입니다. 이 스크립트들 중 어느 것도 Anthropic 키를 필요로 하지 않습니다.

Apache-2.0. 이 저장소는 anthropics/commerce-agents의 코드를 포함합니다 (Copyright Anthropic PBC) — NOTICE를 참조하십시오.