Claude Commerce Agents로 쇼핑 및 판매자 에이전트 구축·실행하기

Claude Commerce Agents가 제공하는 기능

Claude Commerce Agents는 Claude를 기반으로 구축된 두 가지 커머스 중심 AI 에이전트의 참조 구현입니다. 기업은 고객 대면 애플리케이션에 쇼핑 에이전트를 임베드할 수 있으며, 직원은 판매자 에이전트를 사용해 백오피스 워크플로를 운영할 수 있습니다.

각 에이전트는 프롬프트, 스킬, 도구 계약, 안전 게이트를 통해 한 번만 정의됩니다. 동일한 정의를 Messages API, Claude Agent SDK 또는 Managed Agents를 통해 실행할 수 있습니다. 실행 가능한 네 가지 버티컬은 소매, 여행, 통신, 엔터테인먼트 전반에서 이 아키텍처를 보여 줍니다.

저장소에 등장하는 모든 회사, 제품, 브랜드, 인물은 허구입니다. 예제는 주문을 생성하거나 카드를 결제하거나 실제 상품 목록을 업데이트하지 않습니다. 결제는 호스트에 위임되며, 판매자 변경 사항은 담당자가 승인할 때까지 스테이징 상태로 유지됩니다.

두 에이전트 역할 이해하기

쇼핑 에이전트

쇼핑 에이전트는 제품 검색 및 비교, 구매 계획, 장바구니 작성, 주문 및 정책 관련 질문 답변, 고객이 제공한 정보 기억 등 고객 대면 작업을 지원합니다.

다섯 가지 플로는 shopping-agent/skills/ 아래에 있습니다. 실제 시스템에서 에이전트를 사용하려면 관련 카탈로그, 장바구니, 주문, 정책 서비스를 대상으로 StorefrontBackend를 구현해야 합니다.

판매자 에이전트

판매자 에이전트는 직원이 실적을 파악하고, 상품 목록을 관리하며, 재고 및 주문 알림에 대응하고, 가격과 프로모션을 조정하고, 캠페인 초안을 작성하도록 지원합니다. 다섯 가지 플로는 merchant-agent/skills/ 아래에 있습니다.

배포 환경에서는 MerchantBackend를 구현해 분석, 카탈로그, 재고, 가격, 캠페인 시스템에 연결합니다. 모든 변경 사항은 즉시 적용되지 않고 스테이징됩니다. 호스트 애플리케이션은 제안된 변경 사항을 표시하고 승인을 받아야 합니다.

주요 아키텍처 및 기능

• 공유 기반: commerce-common/에는 두 역할이 함께 사용하는 구성, 펜싱, 메모리, 스킬 처리, 그라운딩, 프레젠테이션, 이벤트, 실행기 프레임이 포함되어 있습니다.
• 다중 런타임: 동일한 프롬프트, 스킬, 도구 계약을 Messages API, Agent SDK, Managed Agents에서 사용할 수 있습니다.
• 백엔드 추상화: 에이전트 도구는 백엔드 인터페이스를 호출하므로, 서버에서 자격 증명을 보관하고 비즈니스 시스템에 대한 접근을 중재할 수 있습니다.
• 스테이징되는 판매자 변경 사항: 판매자 변경 사항은 호스트 애플리케이션의 승인 화면을 통한 승인이 필요합니다.
• 구성 가능한 기능: 지원되지 않는 기능을 비활성화하면 해당 기능의 도구, 프롬프트 문장, 그라운딩 규칙이 제거됩니다.
• 확장 가능한 프레젠테이션: PresentationExtension을 통해 도메인별 인터페이스를 추가할 수 있습니다.
• 실행 가능한 예제: 여덟 개의 웹 애플리케이션이 네 가지 버티컬 각각에 대한 스토어프런트와 판매자 포털을 제공합니다.

사전 요구 사항

Python 3.11 이상과 Node.js 22를 설치합니다. 실시간 모델 상호작용을 실행하려면 Anthropic API 키도 필요합니다.

저장소 설치

프로젝트를 복제하고, Python 가상 환경을 생성하고, 고정된 Python 종속 항목을 설치하고, 환경 파일을 생성한 다음, 공유 JavaScript 워크스페이스를 설치합니다.

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
cp .env.example .env
(cd examples && npm ci)

.env를 열고 ANTHROPIC_API_KEY를 추가합니다. Python 스크립트를 실행하는 동안에는 가상 환경을 활성화된 상태로 유지합니다.

첫 번째 데모 실행

다음 명령으로 소매 스토어프런트와 API를 시작합니다.

python scripts/run_demo.py retail

소매 API는 포트 8000에서 실행되고, 스토어프런트는 포트 3000에서 실행됩니다. 스토어프런트 대신 판매자 포털을 시작하려면 --merchant를 추가합니다.

python scripts/run_demo.py retail --merchant

두 화면을 모두 시작하려면 --all을 사용합니다.

python scripts/run_demo.py retail --all

사용 가능한 버티컬과 웹 포트는 다음과 같습니다.

• 소매: 스토어프런트 3000, 판매자 포털 3100.
• 여행: 스토어프런트 3001, 판매자 포털 3101.
• 통신: 스토어프런트 3002, 판매자 포털 3102.
• 엔터테인먼트: 스토어프런트 3003, 판매자 포털 3103.

각 예제 디렉터리에는 권장 프롬프트와 좋은 응답에 포함되어야 할 내용을 설명하는 README가 있습니다.

예제 버티컬 살펴보기

소매

ACME 소매 예제는 제품 검색, 비교, 계획, 장바구니, 결제 위임, 메모리 기능을 보여 줍니다. 판매자 포털에는 실적 요약, 스테이징된 재입고, 상품 목록 수정, SQL 뷰를 기반으로 한 분석 위임 기능이 포함되어 있습니다.

여행

ACME Travel은 날짜에 종속된 재고와 present_itinerary 확장 기능을 추가합니다. 판매자 측에는 점유율 캘린더와 날짜 범위별 요금 변경 기능이 포함되어 있습니다.

통신

ACME Mobile은 계정 컨텍스트, 요금제 매트릭스, 서버에서 작성하는 요금 고지 기능을 보여 줍니다. 판매자 워크플로는 규제 대상 요금을 보호하면서 요금제 구성과 가격 변경을 다룹니다.

엔터테인먼트

ACME Tickets에는 시간 제한 홀드, 대기 목록, 양도, 공연장 지도, 전체 요금 고지 기능이 포함되어 있습니다. 판매자 도구는 이벤트 진행 속도, 수용 인원을 늘리는 홀드 해제, 요금을 보존하는 가격 변경을 다룹니다.

Messages API 런타임 사용

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):
    ...

await agent.update_memory(messages, session)

이벤트 스트림에는 text_delta, tool_call, ui, cart_update, turn_complete가 포함될 수 있습니다. 판매자 측에서는 단계적 쓰기가 change_update 이벤트로 표시됩니다.

update_memory를 통한 메모리 추출은 이 런타임 경로에만 해당합니다. 예제 호스트는 X-Session-Id 요청 헤더를 통해 세션 식별자를 받습니다.

Agent SDK 런타임 사용

Agent SDK는 에이전트 루프를 관리하면서 동일한 프롬프트, 스킬, 도구를 실행합니다. 호스트는 그라운딩 읽기 작업을 미리 가져오며, 턴이 끝난 후에는 어떤 작업도 실행되지 않습니다.

콘솔에서 단일 쇼핑 요청을 실행합니다:

python shopping-agent/runtime-agent-sdk/main.py --once "a two-person tent under $250"

판매자 콘솔을 시작합니다:

python merchant-agent/runtime-agent-sdk/main.py

판매자 콘솔은 단계적 변경 사항을 적용하기 전에 y/N 승인을 요청합니다.

Managed Agents를 통한 배포

Managed Agents는 동일한 스킬과 계약을 사용하면서 에이전트를 호스팅합니다. 에이전트는 시스템에 액세스하기 위해 사용자의 MCP 서버를 호출합니다. 다음 명령으로 배포 드라이 런을 실행합니다:

scripts/deploy_managed_agent.sh shopping-agent/managed-agents/shopping-agent

판매자 역할에는 merchant-agent/managed-agents/ 아래의 해당 경로를 사용합니다. 실제 배포를 수행할 때만 --live를 추가합니다.

자체 커머스 에이전트 스캐폴딩

포함된 Claude Code 플러그인은 사용자의 스택에 맞춰 프로젝트를 생성하거나 기존 에이전트를 검토할 수 있습니다. 저장소를 로컬에 복제한 후 플러그인을 등록하고 설치합니다:

claude plugin marketplace add anthropics/commerce-agents
claude plugin install commerce-builder@claude-commerce-agents
claude

Claude Code에서 쇼핑 어시스턴트 스캐폴드를 요청합니다:

/scaffold-commerce-agent a shopping assistant for our store

이 명령은 기술 스택에 대해 질문하고, 계획을 제시한 다음 프로젝트를 빌드합니다. /add-commerce-flow 및 /author-commerce-evals를 사용해 개발을 계속합니다. 이미 존재하는 에이전트에서 시작할 때는 /review-commerce-agent를 사용합니다.

에이전트를 시스템에 연결

이 저장소는 MCP 커넥터를 제공하지 않습니다. 대신 두 에이전트 모두 백엔드 인터페이스를 통해 비즈니스 시스템에 접근합니다. 각 백엔드 메서드는 현재 세션을 위해 호스트가 보유한 자격 증명을 사용해 서버 측에서 사용자의 서비스를 호출해야 합니다. 모델은 메서드 결과만 받습니다.

1. 역할 선택: 고객 쇼핑에는 StorefrontBackend를, 직원 작업에는 MerchantBackend를 구현합니다.
2. 읽기 작업 매핑: 카탈로그, 정책, 분석, 재고, 가격 또는 지원되는 기타 읽기 작업을 기록 원천 시스템에 연결합니다.
3. 순서가 있는 흐름 유지: 워크플로가 고정된 순서를 따라야 한다면 모델에 의존하지 말고 백엔드에서 해당 순서를 강제합니다.
4. 쓰기 제어: 호스트의 승인 화면에서 권한을 부여할 때까지 판매자 변경 사항을 단계적 상태로 유지합니다.
5. 체크아웃 전달: 백엔드에서 체크아웃 URL을 반환하고 호스트가 이를 렌더링하도록 합니다. 모델은 URL을 절대 보지 않아야 합니다.

백엔드는 서버 측에서 커머스 플랫폼 또는 공식 커넥터를 호출할 수 있습니다. 프로젝트에서 언급하는 잠재적 통합 대상에는 분석 웨어하우스, 재무 시스템, 배송 도구가 포함됩니다. MCP 서버를 Managed Agents와 함께 사용하는 경우에도 쓰기 작업 앞에는 출처 검증 게이트를 유지해야 합니다.

기능과 정체성 사용자 지정

유용한 최소 기능부터 시작합니다. 쇼핑 파일럿은 검색 및 상품 세부 정보를 구현하고, 스텁 메서드에서는 사용할 수 없는 결과를 반환할 수 있습니다. 판매자 파일럿은 8개의 읽기 메서드를 구현하고 쓰기를 거부하여, 쓰기 경로를 노출하지 않고도 다이제스트와 지표가 작동하도록 할 수 있습니다.

비즈니스에 특정 기능이 없다면 해당 enable_* 설정을 끕니다. 그러면 모든 런타임 경로에서 연결된 도구, 프롬프트 콘텐츠, 그라운딩 규칙이 제거됩니다. 사용할 수 없는 기능에 의존하는 흐름은 skills/_staged/ 아래에 배치할 수 있습니다.

적절한 skills/ 디렉터리 아래에 SKILL.md를 포함하는 디렉터리를 추가하여 사용자 지정 흐름을 생성합니다. 도메인별 UI에는 PresentationExtension을 사용합니다. brand_name, assistant_name, brand_voice 설정으로 두 에이전트 중 어느 쪽이든 정체성을 사용자 지정할 수 있습니다.

안전 및 배포 책임

이 프로젝트는 세 가지 런타임 경로 모두에서 도구 호출 내부에 펜싱, 출처 검증 게이트, 제한, 메모리 검증, 판매자 승인을 적용합니다. 그라운딩, 분석 예산, 메모리 추출은 런타임 수준의 기능입니다.

이러한 제어 기능이 배포 환경별 보안을 대체하지는 않습니다. 예제에는 인증이 없으며 MCP 서버는 루프백 인터페이스에만 바인딩됩니다. 프로덕션 호스트의 신원 확인, 권한 부여, 비즈니스 규칙, 규정 준수, 자격 증명 처리, 승인 정책은 여전히 사용자의 책임입니다. 실제 시스템을 연결하기 전에 안전 가이드를 검토하세요.

구현 확인

테스트 및 린트 도구가 필요하다면 개발 요구 사항을 설치하세요.

pip install -r requirements-dev.txt

서식 검사, 린트, 테스트 및 저장소 검사를 실행하세요.

ruff check . && ruff format --check . && pytest && python scripts/check.py

배포 드라이 런과 웹 빌드를 포함한 전체 확인 워크플로를 실행하세요.

python scripts/verify_all.py

실시간 대화 하나를 실행하려면 API 키를 제공하고 다음 명령을 실행하세요.

python scripts/smoke_chat.py --vertical travel

고급 팁

• 캐시 동작을 확인하세요: turn_complete 이벤트 또는 런타임 모델 호출 로그에서 cache_read_input_tokens를 확인하세요. 두 번째 턴에서 값이 0이면 프롬프트 접두사가 변경되었다는 뜻입니다.
• 마켓플레이스를 지원하세요: 판매자를 검색 기준으로 취급하고, 세션에서 식별된 운영자에게 판매자 에이전트의 범위를 제한하세요.
• 계정별 가격을 적용하세요: 가격이 계정이나 계약에 따라 달라지는 경우 세션 계정에 적용되는 가격을 반환하세요.
• 체크아웃을 조정하세요: 체크아웃을 직접 운영하지 않는다면 장바구니를 비활성화하거나 견적, 구매 주문서 또는 호스팅된 체크아웃 페이지로 워크플로를 넘기세요.
• 플랫폼별 클라이언트를 사용하세요: 런타임은 client=를 통해 anthropic 클라이언트를 받고, SDK 런타임은 CLI 환경에서 플랫폼 구성을 읽습니다.
• 배포 옵션을 검토하세요: 저장소는 배포 가이드에서 GCP Vertex AI, AWS Bedrock, Microsoft Foundry 및 게이트웨이 배포를 설명합니다.
• 백엔드 매핑을 살펴보세요: 신원, 자격 증명, 체크아웃, 주문 흐름, 제품 옵션 및 사용할 수 없는 수치는 백엔드 가이드에서 다룹니다.

결론

Claude Commerce Agents는 공유 프롬프트, 기술, 계약 및 안전 제어 기능을 바탕으로 고객 대상 쇼핑 도우미와 승인 절차가 적용된 판매자 도구를 구축하기 위한 실용적인 아키텍처를 제공합니다. 실행 가능한 버티컬부터 시작하고, 플랫폼에 맞는 런타임을 선택하며, 적절한 백엔드 인터페이스를 구현하고, 지원되지 않는 기능을 비활성화한 다음, 프로덕션 데이터나 쓰기 작업을 연결하기 전에 전체 시스템을 확인하세요.

이 저장소는 Apache License 2.0에 따라 사용이 허가됩니다. 참조 구현이며 유지 관리되지 않고 기여를 받지 않습니다.