모범 사례사용 사례

커머스 에이전트

Copy page



Messages API, Claude Agent SDK, Claude Managed Agents에서 작동하는 구현을 제공하는 오픈 소스 블루프린트인 Claude for commerce를 사용하여 Claude에서 쇼핑 에이전트와 판매자 에이전트를 구축하세요.

이 가이드는 Claude에서 "commerce agent"(커머스 에이전트)를 구축하는 방법을 설명합니다. 커머스 에이전트에는 고객이 앱 안에서 사용하는 "shopping agent"(쇼핑 에이전트)와, 매장을 운영하는 사람들을 위한 "merchant agent"(판매자 에이전트)가 있습니다. 매장을 운영하는 사람은 비즈니스 자체의 운영 직원일 수도 있고 플랫폼의 판매자일 수도 있습니다. 이 가이드는 오픈 소스 "blueprint"(블루프린트)인 Claude for commerce를 바탕으로 합니다. Claude for commerce는 Messages API, Claude Agent SDK, Claude Managed Agents 각각에서 두 에이전트를 실제로 작동하도록 구현한 코드를 제공합니다. 또한 소매, 여행, 통신, 엔터테인먼트 분야의 실행 가능한 예제와, 같은 설계를 여러분의 시스템에 맞춰 스캐폴딩하는 Claude Code 플러그인도 포함합니다.

코드, 설정 지침, 안전 문서는 GitHub의 Claude for commerce 저장소에 있습니다. 에이전트의 구축 방식과 그 이유는 엔지니어링 게시물 효과적인 커머스 에이전트의 구조에 대한 가이드를 읽어 보세요. 이 게시물은 스킬을 갖춘 단일 에이전트 설계, 도구로서의 UI 컴포넌트, 하네스에서 강제하는 안전성, 프롬프트 캐싱, 메모리, eval을 다룹니다.

쇼핑 에이전트

쇼핑 에이전트는 앱 안에서 동작하며, 단일 백엔드 인터페이스를 통해 여러분의 시스템에 접근합니다. 이 인터페이스는 카탈로그, 장바구니, 선호도, 주문, 정책, 주문 처리 서비스 위에 여러분이 직접 구현합니다. 이 인터페이스에는 주문을 넣거나 결제를 처리하는 메서드가 없습니다. 대화에서 에이전트는 다음을 수행할 수 있습니다.

• 카탈로그를 검색하고, 최종 후보를 비교하고, 고객이 설명한 요구 사항을 후보 목록과 추천으로 정리합니다.
• 여행, 이벤트, 방 꾸미기 같은 목표에 맞춰 서로 어울리는 품목 세트를 계획하고 예산에 맞춥니다.
• 제품, 비교, 계획, 주문 상태, 장바구니를 대화 안에 렌더링되는 UI 컴포넌트로 보여줍니다.
• 장바구니를 채운 뒤 여러분의 결제 절차로 넘깁니다.
• 여러분의 주문 및 정책 시스템을 바탕으로 주문, 배송, 반품, 정책 관련 질문에 답변합니다.
• 고객이 기억해 달라고 요청한 내용을 기억하고 이후 세션에 적용합니다.

다섯 가지 "skill"(스킬)이 필요할 때 로드되며, 검색 및 탐색, 구매 조사, 목표 기반 계획, 고객 지원, 메모리 및 개인화를 담당합니다. 근거 제시, 장바구니 및 결제 의미 체계, 표시 방식처럼 에이전트가 대부분의 턴에서 필요로 하는 규칙은 스킬 대신 시스템 프롬프트에 둡니다.

에이전트는 대화 안의 도구 결과에 근거해서만 제품, 가격, 재고 여부, 매장 약관을 언급합니다. 장바구니 쓰기 작업은 해당 세션에서 카탈로그 또는 주문 도구가 반환한 제품 ID만 받습니다. 결제 단계에서는 요약을 준비하고, 고객이 앱에서 이를 확인합니다. 호스팅 결제를 사용하는 경우 백엔드가 결제 URL을 반환하고, 호스트는 이 URL을 모델에 전달하지 않고 바로 렌더링합니다.

판매자 에이전트

판매자 에이전트는 매장을 운영하는 사람들을 지원합니다. 별도의 백엔드 인터페이스를 통해 분석, 카탈로그, 재고, 가격 책정, 캠페인 시스템에 접근하며, 다음을 수행할 수 있습니다.

• 비즈니스 현황을 설명합니다. 지표가 변한 이유, 변화를 이끈 세그먼트, 비교 가능한 기간 대비 진행 속도를 알려줍니다. 선택 사항인 분석 위임 에이전트는 시간 및 크기 예산 안에서 읽기 전용 쿼리를 실행합니다.
• 재고 부족, 판매 부진 상품, 주문 예외 등 주의가 필요한 사항을 일일 요약으로 보여줍니다.
• 운영자가 제공한 자료를 바탕으로 상품 등록 콘텐츠를 개선하고 카탈로그 데이터를 수정합니다.
• 매장의 "guardrail"(가드레일) 범위 안에서 마진 미리보기와 함께 가격 변경과 프로모션을 추천합니다.
• 대상 고객, 게재 위치, 예산을 포함한 마케팅 캠페인 초안을 작성합니다.

다섯 가지 스킬은 성과 인사이트, 재고 및 운영, 카탈로그 및 상품 등록, 가격 책정 및 프로모션, 마케팅 캠페인을 담당합니다.

판매자 에이전트가 제안하는 모든 쓰기 작업은 "staged change"(스테이징된 변경)로 처리됩니다. 상품 등록 업데이트, 가격 변경, 재고 조치, 프로모션, 캠페인 모두 마찬가지입니다. 스테이징된 변경에는 서버에서 생성한 ID가 부여되며, 운영자에게는 미리보기 카드로 표시됩니다. 최대 가격 변동 폭, 프로모션 할인 폭, 재입고 규모, 캠페인 예산, 보호 필드 같은 가드레일은 변경을 스테이징할 때 한 번, 적용할 때 다시 한 번 검사됩니다. 변경은 사람이 대화 밖에서 승인한 후에만 적용됩니다. 승인 방식은 경로마다 다릅니다. Messages API 경로에서는 판매자 포털의 버튼을, Agent SDK 콘솔에서는 확인 프롬프트를, Claude Managed Agents에서는 적용 도구에 설정한 항상 확인 권한 정책을 사용합니다. 채팅에 입력한 승인은 아무것도 승인하지 않습니다.

업종별 예제

각 예제에는 가상 데이터를 사용하는 고객 스토어프런트와 판매자 포털이 포함되어 있습니다.

실행 환경

Messages API 및 Agent SDK 런타임은 Claude API, Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry에서 실행되며, 자체 게이트웨이를 통해서도 실행할 수 있습니다. Claude Managed Agents 경로는 Claude API에서 실행됩니다. 저장소의 배포 가이드에서 각 경로가 플랫폼을 선택하는 위치와 각 경로에 필요한 모델 ID 형식을 확인할 수 있습니다.

Claude Code 플러그인으로 직접 구축하기

블루프린트에는 Claude Code 플러그인이 함께 제공됩니다. 이 플러그인은 복제한 저장소를 참조로 읽고, 여러분의 시스템에 맞는 에이전트를 구축합니다. 네 가지 명령으로 아무것도 없는 상태에서 테스트를 마친 에이전트까지 만들 수 있습니다.

플러그인에는 아키텍처, 프롬프트 캐싱, 도구로서의 UI, 신뢰 및 안전, eval, 판매자 운영에 관한 여섯 가지 스킬도 포함되어 있습니다. 이 스킬들은 Claude Code 대화 내용과 관련이 있을 때마다 로드됩니다. 설치 지침은 저장소 README에 있습니다.

참조 구현을 직접 조정하려면 다음 단계를 따르세요. 먼저 여러분의 서비스 위에 쇼핑 또는 판매자 백엔드 인터페이스를 구현하세요. 그런 다음 구성 플래그로 보유하지 않은 시스템을 비활성화하세요. 그러면 해당 시스템의 도구와 프롬프트 줄이 제외됩니다. 마지막으로 브랜드 이름, 어시스턴트 이름, 어조를 설정하세요. 저장소의 백엔드 가이드는 신원 및 자격 증명, 순서가 있는 플로우, 결제 인계, 옵션이 있는 제품을 단계별로 설명합니다. 파일럿 단계에서는 검색과 제품 상세 정보만 구현하고 나머지는 스텁으로 처리해도 됩니다.

시작하기