TL;DR
Anthropic의 commerce-agents 저장소는 Claude를 기반으로 고객용 shopping agent와 직원용 merchant agent를 같은 prompt, skills, tool contracts로 구현하는 참조 청사진이다. 두 역할은 Messages API, Claude Agent SDK, Managed Agents에서 실행되며, 쇼핑 에이전트는 검색·비교·장바구니 작성까지 처리하고 merchant 에이전트는 분석·재고·가격·캠페인 변경을 승인 대기 상태로 만든다. 안전성은 도구 호출 내부의 fencing, provenance gates, caps, memory validation, merchant approval gate로 유지되고, 체크아웃은 호스트의 경로로 넘겨지며 모델은 URL을 직접 보지 않는다. retail, travel, telecom, entertainment 네 vertical과 Python 3.11+, Node 22 기반 실행 예제가 제공되지만 인증과 운영 배포의 비즈니스 규칙은 각 배포자가 구현해야 한다.
실용적 조언
- 처음부터 모든 업무 흐름을 연결하지 않고 shopping pilot에서는 검색과 상품 상세만 구현한 뒤 나머지 메서드는 unavailable 결과를 반환하도록 구성한다.
- merchant pilot에서는 먼저 여덟 개 읽기 메서드만 연결하고 쓰기 메서드는 거부하게 두면 digest와 metric 흐름을 운영 변경 없이 검증할 수 있다.
- 카트나 주문 추적처럼 배포 시스템에 없는 기능은 enable_* 스위치를 끄고 관련 tools, prompt lines, grounding rule을 함께 제거하며, merchant의 listing edits, inventory, pricing, campaigns도 같은 방식으로 비활성화한다.
- 체크아웃은 백엔드가 호스트의 checkout route 또는 플랫폼 hosted checkout URL을 반환하고 호스트가 화면에 렌더링하게 구성해야 하며, 모델에는 해당 URL을 전달하지 않는다.
- 운영 연결 전에는 ruff, pytest, scripts/check.py, scripts/verify_all.py를 실행하고 travel vertical의 smoke_chat.py로 키가 필요한 실제 대화를 별도 검증한다.
섹션별 상세
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저장소를 복제하고 Python 및 Node 의존성을 설치한 뒤 retail 데모를 실행하는 초기 설정 명령입니다.
claude plugin marketplace add anthropics/commerce-agents
claude plugin install commerce-builder@claude-commerce-agents
claude /scaffold-commerce-agent a shopping assistant for our storeClaude Code plugin을 설치하고 자연어 요청으로 상거래 에이전트 프로젝트 생성을 시작하는 명령입니다.
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 onlyShoppingAgent를 백엔드와 skills 디렉터리에 연결하고 스트리밍 이벤트와 memory extraction을 처리하는 Messages API 실행 예시입니다.
python shopping-agent/runtime-agent-sdk/main.py --once "a two-person tent under $250"
python merchant-agent/runtime-agent-sdk/main.py # approves staged changes with y/NAgent SDK 경로에서 쇼핑 요청을 한 번 실행하고 merchant 에이전트의 staged 변경을 y/N으로 승인하는 명령입니다.
용어 해설
- Agent SDK
- — Agent SDK는 에이전트의 도구 호출과 대화 루프 실행을 애플리케이션 코드에서 처리하도록 제공되는 개발 인터페이스입니다. 이 저장소에서는 Messages API와 동일한 prompt, skills, tool contracts를 사용하되 SDK가 실행 루프를 맡고 호스트는 필요한 grounding 데이터를 미리 읽습니다.
- Managed Agents
- — Managed Agents는 호스팅 환경에서 에이전트를 실행하는 경로입니다. 저장소의 manifest가 역할별 skills와 MCP 서버를 연결하고, 에이전트는 배포된 서버를 통해 기업 시스템에 접근하며 쓰기 작업 앞에는 provenance gates와 승인 절차가 유지됩니다.
- MCP 서버(MCP Server)
- — MCP 서버는 에이전트가 외부 시스템의 기능과 데이터에 접근하도록 도구 인터페이스를 제공하는 서버입니다. 이 구현에서는 쇼핑 에이전트와 merchant 에이전트가 각자의 MCP 서버를 사용하고, Managed Agents에서는 역할별 manifest에 서버가 함께 탑재됩니다.
- Grounding
- — Grounding은 에이전트가 답변이나 작업을 만들 때 백엔드가 읽어온 실제 카탈로그, 재고, 정책 같은 정보를 컨텍스트로 제공하는 방식입니다. 저장소는 호스트가 시스템에서 읽은 결과만 모델에 전달하고, 인증 자격 증명은 호스트가 보관하도록 경계를 둡니다.
- Provenance Gates
- — Provenance gates는 에이전트가 도구 호출로 수행하려는 쓰기 작업의 출처와 허용 조건을 확인하는 안전 장치입니다. 이 구현에서는 safety fencing, 출처 검증, 한도, memory validation이 세 실행 경로 모두의 도구 호출 안에서 작동하고, merchant 변경은 사람의 승인 전까지 staged 상태로 남습니다.
- Staged Change
- — Staged change는 merchant 에이전트가 재고, 상품 목록, 가격, 캠페인에 적용하려는 변경을 즉시 운영 시스템에 쓰지 않고 승인 대기 상태로 저장하는 방식입니다. 호스트의 승인 화면이 변경을 적용하며, 저장소의 예제는 실제 주문, 카드 결제, 운영 중인 목록 변경을 수행하지 않습니다.
언급된 도구
같은 prompt, skills, tool contracts를 사용하면서 호스트 애플리케이션 대신 SDK가 에이전트 실행 루프를 처리하는 실행 경로입니다.
commerce-builder plugin을 설치한 뒤 /scaffold-commerce-agent, /add-commerce-flow, /author-commerce-evals, /review-commerce-agent 명령으로 상거래 에이전트의 생성과 검토를 진행하는 개발 도구입니다.
언급된 리소스
AI 요약 · 북마크 · 개인 피드 설정 — 무료
출처 · 인용 안내
인용 시 "요약 출처: AI Trends (aitrends.kr)"를 표기하고, 사실 확인은 원문 보기 기준으로 진행해 주세요. 자세한 기준은 운영 정책을 참고해 주세요.
