Claude Commerce Agents: 쇼핑과 백오피스 에이전트를 한 번만 정의해 세 가지 방식으로 실행하는 참조 구현

9bow · 9월 5, 2026, 9:00오전

Claude Commerce Agents 소개

쇼핑몰에 대화형 에이전트를 붙이는 일은 데모 단계까지는 어렵지 않습니다. 상품을 검색해 보여주고 비교해 주는 챗봇은 모델 하나와 검색 API 하나로도 만들어집니다. 문제는 그다음입니다. 에이전트가 장바구니에 무언가를 담아도 되는가, 재고를 고쳐도 되는가, 가격을 내려도 되는가 같은 권한 문제가 남고, 이 판단은 프롬프트에 "함부로 바꾸지 마세요" 라고 적어 두는 것만으로는 지켜지지 않습니다. 실제로 운영에 올리려면 어떤 규칙을 코드가 강제하고 어떤 규칙을 모델의 판단에 맡길지를 줄 단위로 정해야 하는데, 공개된 예제 대부분은 대화 화면까지만 보여주고 이 경계를 다루지 않습니다.

Anthropic이 공개한 Claude Commerce Agents는 그 경계를 코드로 그어 둔 참조 구현(reference implementation)입니다. 이 저장소는 역할이 다른 두 에이전트를 담고 있습니다. 하나는 기업이 자사 앱에 심어 고객에게 노출하는 쇼핑 에이전트이고, 다른 하나는 그 기업의 직원이 백오피스 업무에 쓰는 판매자 에이전트입니다. 두 에이전트는 각각 프롬프트, 스킬, 도구 계약(tool contract), 게이트를 한 번만 정의해 두고, 그 정의를 세 가지 실행 경로 위에서 그대로 돌립니다. 판매자 쪽 쓰기 작업은 전부 사람이 승인해야 반영되는 대기 상태로 쌓이고, 주문을 넣거나 카드를 결제하는 코드는 아예 들어 있지 않습니다.

Claude Commerce Agents를 실행하려면 Python 3.11 이상과 Node.js 22가 필요합니다. 저장소에는 소매, 여행, 통신, 엔터테인먼트 네 개 업종의 실행 가능한 예제가 들어 있고, 각 업종마다 고객용 상점 화면과 직원용 포털 화면이 따로 준비되어 있습니다. 여기에 자신의 시스템에 맞춰 에이전트를 새로 만들어 주거나 이미 만든 에이전트를 검토해 주는 Claude Code 플러그인이 함께 들어 있습니다.

Claude Commerce Agents는 누구에게 맞는가

자사 앱에 상거래 에이전트를 올리려 하는데 권한과 승인 흐름부터 설계해야 하는 팀에게 이 저장소가 가장 잘 맞습니다. 두 에이전트의 스킬과 게이트가 실제로 동작하는 코드로 들어 있고, 무엇이 코드로 강제되고 무엇이 배포자의 몫인지가 docs/safety.md에 규칙 단위로 적혀 있어서, 자신의 설계와 대조하며 읽을 수 있습니다.

반대로 바로 배포할 수 있는 완제품을 찾는 팀에게는 Claude Commerce Agents가 적절한 선택지가 아닙니다. 저장소에 담긴 회사, 브랜드, 상품, 인물은 모두 가상이고, 등장하는 회사도 가상의 ACME 하나뿐입니다. 예제에는 인증이 전혀 없고, 참조용 MCP 서버는 앞단에 인증 게이트웨이가 있다고 환경 변수로 알리지 않는 한 루프백 주소에만 바인딩됩니다. 인증과 권한, 요청량 제한, 사기와 자격 판정 같은 업무 규칙은 저장소가 다루지 않는 영역으로 명시되어 있습니다. 또한 프로젝트는 스스로를 참조 구현으로 규정하면서 유지보수를 하지 않고 기여도 받지 않는다고 밝히고 있어, 장기적으로 갱신되는 프레임워크로 기대하기는 어렵습니다.

Claude Commerce Agents의 두 에이전트

쇼핑 에이전트는 상품을 검색하고 비교하며, 고객의 목표에 맞춰 계획을 세우고, 장바구니를 채우고, 주문과 정책에 관한 질문에 답하고, 고객이 알려 준 정보를 기억합니다. 이 다섯 가지 흐름은 shopping-agent/skills/ 아래에 search-discovery, purchase-research, planning-goals, customer-care, memory-personalization 스킬로 나뉘어 있습니다. 실제 서비스에 붙일 때 개발자가 채우는 부분은 StorefrontBackend 인터페이스로, 자사의 카탈로그, 장바구니, 주문, 정책 시스템을 이 인터페이스 뒤에 연결하면 됩니다.

판매자 에이전트는 매출 지표를 설명하고, 상품 정보를 정비하고, 재고와 주문 알림에 대응하고, 가격과 프로모션을 조정하고, 캠페인 초안을 씁니다. 다섯 가지 흐름은 merchant-agent/skills/ 아래에 performance-insights, catalog-listings, inventory-operations, pricing-promotions, marketing-campaigns 스킬로 나뉘어 있고, 개발자가 채우는 인터페이스는 MerchantBackend이며 분석, 카탈로그, 재고, 가격, 캠페인 시스템이 연결 대상입니다. 중요한 차이는 판매자 에이전트가 만들어 내는 모든 변경이 즉시 반영되지 않고 대기 중인 변경(staged change) 으로 쌓인다는 점입니다. 호스트 애플리케이션이 그 변경을 승인 표시해야만 반영 요청이 성공합니다.

두 에이전트가 공유하는 부분은 commerce-common 패키지에 모여 있습니다. 설정, 외부 텍스트 격리, 기억, 스킬 로딩, 근거 확보, 화면 구성, 실행기 골격, 이벤트가 여기에 들어갑니다. 저장소를 처음 열었을 때 어느 디렉토리부터 봐야 할지 헷갈린다면 이 패키지가 출발점입니다.

Claude Commerce Agents의 세 가지 실행 경로

같은 에이전트 정의를 Messages API, Claude Agent SDK ( Anthropic이 소개하는 Claude Agent SDK로 에이전트 빌드하기 🤖), Managed Agents 세 가지 방식으로 실행할 수 있고, 각 방식에서 지켜지는 규칙의 범위가 조금씩 다릅니다. 세 경로의 차이는 다음과 같습니다:

실행 경로	무엇인가	근거 확보 규칙의 적용 범위	사람 승인 방식
Messages API	참조가 되는 기본 루프이며 예제 앱들이 이 위에 올라가 있습니다	모든 규칙을 `tool_choice`로 강제	호스트가 승인 표시한 변경만 반영
Claude Agent SDK	같은 프롬프트, 스킬, 도구를 쓰되 루프는 SDK가 돌립니다	미리 읽어 두는 형태가 있는 규칙만 적용	SDK 도구 모음의 `host_approve`
Managed Agents	같은 스킬과 계약 위에서 동작하는 호스팅 에이전트가 사용자의 MCP 서버를 호출합니다	적용되지 않음	플랫폼의 확인 프롬프트가 승인 역할

Messages API 경로의 최소 코드는 다음과 같습니다:

from pathlib import Path

from shopping_agent import ShoppingAgentConfig
from shopping_agent_runtime import ShoppingAgent

agent = ShoppingAgent(backend=your_backend, skills_dir=Path("shopping-agent/skills"),
                      config=ShoppingAgentConfig(brand_name="Your Store"))
async for event in agent.stream_turn(messages, session, state):
    ...   # text_delta, tool_call, ui, cart_update (change_update on the merchant side), turn_complete
await agent.update_memory(messages, session)   # memory extraction; this path only

세 경로 모두 도구 호출을 같은 실행기로 처리하기 때문에, 도구 호출 안에서 강제되는 규칙은 어느 경로를 골라도 그대로 지켜집니다. 반면 근거 확보처럼 대화 한 턴을 관장하는 규칙은 각 실행 환경이 루프를 어떻게 돌리는지에 따라 적용 범위가 갈립니다.

Claude Commerce Agents의 안전장치가 강제되는 위치

Claude Commerce Agents에서 가장 참고할 만한 부분은 안전 규칙을 세 층으로 갈라 둔 방식입니다. 코드가 강제하는 규칙, 프롬프트가 모델에게 요청하는 규칙, 배포자가 직접 채워야 하는 규칙이 문서에서 아예 다른 절로 분리되어 있습니다.

코드가 강제하는 규칙 중 눈여겨볼 만한 것들은 다음과 같습니다:

외부 텍스트 격리: 제3자가 쓴 텍스트는 보이지 않는 문자와 제어 문자, 위조된 대화 표식, 대화록과 도구 호출 태그를 걷어낸 뒤 고정된 라벨로 감싸 모델에게 전달됩니다.
출처 검증: 장바구니 쓰기는 이번 세션에서 카탈로그나 주문 도구가 돌려준 상품 식별자만 받아들입니다. 판매자 쪽 대기 변경도 마찬가지로 이번 세션의 도구가 돌려준 상품과 캠페인 식별자만 받습니다.
결제 없음: StorefrontBackend에는 주문을 넣는 메서드 자체가 없습니다. 결제 화면은 장바구니를 그려서 호스트에게 넘기고, 호스팅형 결제 주소는 모델을 거치지 않고 호스트가 직접 받습니다.
사람 승인: require_host_approval이 켜진 기본 설정에서는 호스트가 승인 표시한 식별자에 대해서만 반영이 성공합니다. 미리보기 카드는 아무것도 승인하지 않고, 대화창에 승인한다고 입력해도 아무것도 설정되지 않습니다.
기억 쓰기 제한: 저장되는 사실 하나는 키 64자, 값 200자 이내이며 세 가지 범주 중 하나여야 합니다. 식별자처럼 생긴 값은 기본적으로 거부됩니다.

반면 프롬프트가 모델에게 맡기는 규칙도 문서에 그대로 적혀 있습니다. 격리된 텍스트는 지시가 아니라 보고 대상으로 다룰 것, 약관이나 수치는 이번 대화의 도구 결과에서만 인용할 것, 전문가 상담과 의료, 안전에 관한 질문에는 상품과 함께 전문가 안내를 제시할 것 같은 항목입니다. 프로젝트는 모델이 이 규칙을 어겼을 때 오류가 모델의 문장 안에 갇힌다는 점을 근거로 두 층을 나눕니다. 문장 뒤의 모든 쓰기와 수치, 고지는 이미 코드 쪽 검사를 통과한 것이므로 되돌릴 동작 없이 문장만 정정하면 된다는 설명입니다.

Claude Commerce Agents 설치와 사용

예제를 돌려보는 절차는 저장소를 받아 의존성을 설치하고 업종 하나를 실행하는 순서입니다:

git clone https://github.com/anthropics/commerce-agents.git && cd commerce-agents
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt       # the seven packages and their pinned dependencies
cp .env.example .env                  # add ANTHROPIC_API_KEY
(cd examples && npm ci)               # the eight web apps share one workspace
python scripts/run_demo.py retail     # API :8000 + storefront :3000

--merchant 옵션을 붙이면 상점 화면 대신 직원용 포털이 뜨고, --all을 붙이면 둘 다 뜹니다. 업종별 주소는 소매가 http://localhost:3000(포털 http://localhost:3100), 여행이 http://localhost:3001(포털 http://localhost:3101), 통신이 http://localhost:3002(포털 http://localhost:3102), 엔터테인먼트가 http://localhost:3003(포털 http://localhost:3103)입니다.

자신의 시스템에 맞춘 에이전트를 만들 때는 Claude Code 플러그인을 씁니다. 저장소를 위와 같이 받아 둔 상태에서 플러그인이 그 저장소를 참조 자료로 읽습니다:

claude plugin marketplace add anthropics/commerce-agents
claude plugin install commerce-builder@claude-commerce-agents
claude
/scaffold-commerce-agent a shopping assistant for our store

플러그인은 사용하는 기술 스택을 물어보고 계획을 되읽어 준 뒤 프로젝트를 만듭니다. 이후에는 /add-commerce-flow로 흐름을 추가하고 /author-commerce-evals로 평가를 작성하며, 이미 만들어 둔 에이전트가 있다면 /review-commerce-agent로 시작할 수 있습니다.

한 가지 짚어 둘 점은 결제 자체가 이 저장소의 범위 밖이라는 것입니다. 결제 화면은 사용자가 준비한 결제 경로나 상거래 플랫폼의 호스팅형 결제 주소로 넘기는 데서 끝납니다. 에이전트가 직접 결제를 수행하는 쪽의 논의는 별도의 프로토콜 영역이며, PyTorchKR에도 Universal Commerce Protocol과 Agent Payments Protocol 정리 글이 있습니다.

Claude Commerce Agents의 라이선스

Claude Commerce Agents는 Apache 라이선스 2.0으로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용할 수 있습니다.

Claude for Commerce 소개 페이지 (Anthropic의 커머스 솔루션 안내)

Claude Agent SDK 문서

Claude Commerce Agents 프로젝트 GitHub 저장소

더 읽어보기

이 글은 GPT 모델로 정리한 초안을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 댓글로 알려주시기를 부탁드립니다.

파이토치 한국 사용자 모임이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일로 보내드립니다! 텔레그램(Telegram)이나 Slack/Discord/Teams/Dooray/GoogleChat 등으로도 새 글 알림을 받으실 수 있습니다.

아래쪽에 좋아요를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~