커머스 에이전트
커머스 에이전트 (Commerce agent)
이 가이드는 클로드에서 커머스 에이전트를 만드는 방법을 보여줘요. 앱 안에서 고객이 사용하는 쇼핑 에이전트와, 가게를 운영하는 사람들(비즈니스 운영 직원이든 플랫폼의 판매자든)을 위한 머천트 에이전트가 그 대상이에요. 이를 위해 클로드 포 커머스(Claude for commerce)라는 오픈소스 블루프린트를 사용하는데, Messages API, Claude Agent SDK, Claude Managed Agents 각각에 대해 두 에이전트의 작동 구현이 있고, 리테일·여행·통신·엔터테인먼트용 실행 가능 예제와, 당신의 시스템에 맞춰 같은 설계를 스캐폴딩해 주는 Claude Code 플러그인도 포함돼 있어요.
출처: 문서
본문
코드, 설정 지침, 안전 문서는 GitHub의 Claude for commerce 리포지토리에 있어요. 에이전트가 어떻게 만들어지고 왜 그렇게 만들어졌는지(스킬을 갖춘 단일 에이전트 설계, UI 컴포넌트를 도구로 사용, 하네스 강제 안전, 프롬프트 캐싱, 메모리, evals)는 엔지니어링 포스트 효과적인 커머스 에이전트 해부 가이드를 읽어 보세요.
쇼핑 에이전트 (The shopping agent)
쇼핑 에이전트는 앱 안에 있으며, 카탈로그, 장바구니, 선호, 주문, 정책, 주문 이행 서비스 위에 구현하는 단일 백엔드 인터페이스를 통해 당신의 시스템에 닿아요. 그 인터페이스의 어떤 메서드도 주문을 하거나 돈을 옮기지 않아요. 대화에서 에이전트는 다음을 할 수 있어요:
- 카탈로그를 검색하고, 최종 후보를 비교하고, 설명된 필요를 짧은 리스트와 추천으로 바꿔요.
- 여행, 이벤트, 방 같은 목표를 향한 조정된 아이템 세트를 계획하고, 예산에 맞춰요.
- 대화에서 렌더링되는 UI 컴포넌트로 제품, 비교, 계획, 주문 상태, 장바구니를 보여줘요.
- 장바구니를 채우고 당신의 체크아웃으로 인계해요.
- 당신의 주문·정책 시스템에서 주문, 배송, 반품, 정책 질문에 답해요.
- 고객이 기억하라고 요청한 것을 기억하고 이후 세션에서 적용해요.
다섯 개의 스킬이 검색·발견, 구매 조사, 목표를 향한 계획, 고객 케어, 메모리·개인화를 다루며 필요할 때 로드돼요. 근거(grounding), 장바구니·체크아웃 의미론, 프레젠테이션처럼 대부분의 턴에서 필요한 규칙은 대신 시스템 프롬프트에 있어요.
에이전트는 대화의 도구 결과에서만 제품, 가격, 가용성, 가게 약관을 진술하며, 장바구니 쓰기는 그 세션에서 카탈로그나 주문 도구가 반환한 제품 ID만 받아들여요. 체크아웃은 고객이 앱에서 확인하는 요약을 준비해요. 호스팅 체크아웃을 사용하면 백엔드가 그 URL을 반환하고, 호스트가 모델을 통과시키지 않고 렌더링해요.
머천트 에이전트 (The merchant agent)
머천트 에이전트는 가게를 운영하는 사람들을 지원해요. 자체 백엔드 인터페이스를 통해 분석, 카탈로그, 재고, 가격, 캠페인 시스템에 닿으며, 다음을 할 수 있어요:
- 비즈니스가 어떻게 돌아가는지 설명해요: 지표가 왜 움직였는지, 어떤 세그먼트가 그것을 주도했는지, 비교 기간 대비 속도. 선택적 분석 델리게이트가 시간·크기 예산 아래에서 읽기 전용 쿼리를 실행해요.
- 주의가 필요한 것(낮은 재고, 느린 판매품, 주문 예외)의 일일 요약을 제시해요.
- 운영자가 제공한 자료로 리스팅 콘텐츠를 개선하고 카탈로그 데이터를 수정해요.
- 가게의 가드레일 안에서 마진 미리보기와 함께 가격 변경과 프로모션을 추천해요.
- 오디언스, 배치, 예산을 포함한 마케팅 캠페인 초안을 작성해요.
다섯 개의 스킬은 실적 인사이트, 재고·운영, 카탈로그·리스팅, 가격·프로모션, 마케팅 캠페인을 다뤄요.
머천트 에이전트가 제안하는 모든 쓰기 작업(리스팅 업데이트, 가격 변경, 재고 조치, 프로모션, 캠페인)은 서버 생성 ID가 있는 단계적 변경(staged change)이며, 운영자가 미리보기 카드로 보게 돼요. 최대 가격 변동, 프로모션 깊이, 재입고 크기, 캠페인 예산, 보호 필드 같은 가드레일은 변경을 준비할 때와 적용할 때 모두 확인돼요. 변경은 대화 밖에서 사람이 승인한 후에만 적용돼요. Messages API 경로의 머천트 포털 버튼, Agent SDK 콘솔의 확인 프롬프트, 또는 Claude Managed Agents의 적용 도구에 대한 항상-묻기 권한 정책으로요. 채팅에 입력한 승인은 아무것도 승인하지 않아요.
업종별 예시 (Vertical examples)
각 예시에는 가상 데이터 위의 고객 매장(storefront)과 머천트 포털이 포함돼요.
| 업종 | 매장 | 머천트 포털 |
|---|---|---|
| 리테일 | 내장 컴포넌트 위의 검색, 비교, 계획, 장바구니, 체크아웃, 메모리 | 일일 요약, 단계적 재입고와 리스팅 수정, SQL 뷰 위의 분석 델리게이트 |
| 여행 | 날짜 제한 재고와 여정 컴포넌트 | 점유율 캘린더와 날짜 창 요율 변동 |
| 통신 | 계정 컨텍스트, 요금제 매트릭스, 서버 작성 수수료 공시 | 요금제 구성, 영향받는 라인을 명시하는 가격 변동, 보호된 규제 수수료 |
| 엔터테인먼트 | 시간 경과 홀드, 대기자 명단, 양도, 공연장 지도, 올인 수수료 공시 | 이벤트 페이싱, 실제 용량을 추가하는 홀드 해제, 수수료를 보존하는 가격 변동 |
실행되는 곳 (Where it runs)
Messages API와 Agent SDK 런타임은 Claude API, Amazon Bedrock, Google Cloud Agent Platform, Microsoft Foundry 또는 당신의 자체 게이트웨이를 통해 실행돼요. Claude Managed Agents 경로는 Claude API에서 실행돼요. 리포지토리의 배포 가이드가 각 경로가 어디서 플랫폼을 선택하는지와 각각이 기대하는 모델 ID 형식을 보여줘요.
Claude Code 플러그인으로 직접 만들기
블루프린트에는 Claude Code 플러그인이 포함되어 있고, 이 플러그인은 복제된 리포지토리를 참조로 읽고 당신의 시스템에 맞춰 에이전트를 만들어요. 네 개의 명령이 처음부터 테스트된 에이전트까지의 경로를 다뤄요:
| 명령 | 하는 일 |
|---|---|
/scaffold-commerce-agent |
스택에 대해 인터뷰하고, 계획을 재생하며, 참조 패키지 위에 쇼핑 에이전트·머천트 에이전트 또는 둘 다를 스캐폴딩해요 |
/add-commerce-flow |
스킬을 복사하고, 호출하는 도구를 연결하며, 첫 eval 사례를 작성해 기존 에이전트에 흐름 하나를 추가해요 |
/author-commerce-evals |
러너, 당신의 카탈로그에 대한 첫 사례, CI용 리플레이 게이트가 있는 eval 스위트를 만드세요 |
/review-commerce-agent |
이미 운영 중인 에이전트를 매핑하고, 참조와 비교하며, 고른 부분을 변환해요 |
플러그인은 또한 아키텍처, 프롬프트 캐싱, 도구로서의 UI, 신뢰와 안전, evals, 머천트 운영에 관한 여섯 개 스킬을 담고 있으며, Claude Code 대화가 그것과 일치할 때마다 로드돼요. 설치 지침은 리포지토리 README에 있어요.
대신 참조를 손으로 적응하려면, 서비스 위에 쇼핑 또는 머천트 백엔드 인터페이스를 구현하고, 없을 시스템은 구성 플래그로 꺼서 그 도구와 프롬프트 줄이 빠지도록 하고, 브랜드명, 어시스턴트명, 음성을 설정하세요. 리포지토리의 백엔드 가이드가 신원과 자격 증명, 주문 흐름, 체크아웃 인계, 옵션이 있는 제품을 안내해요. 파일럿은 검색과 제품 상세를 구현하고 나머지는 스텁(더미)으로 둘 수 있어요.