Anthropic 커머스 에이전트 소스 레벨 아키텍처 분석

앤트로픽 커머스 에이전트란

본 글은 공개된 깃의 코드 내용을 정리한 것입니다. anthropics/commerce-agents는 기업이 자체 커머스 스택 위에 Claude 기반 쇼핑 및 머천트 에이전트를 안전하게 구축할 수 있도록 지원하는 Apache 2.0 라이선스의 레퍼런스 아키텍처(Blueprint)입니다. 

블루프린트에서는 주문 결제나 카드 청구 로직은 의도적으로 제외되어 있으며, 비즈니스 실체는 가상 기업인 “ACME”로 추상화되어 있습니다. 이 레퍼런스의 핵심 가치는 “자율 에이전트의 결정권과 백엔드 시스템의 트랜잭션을 엄격하게 분리하고 안전을 어떻게 강제(Enforce)할 것인가”에 대한 표준 형식을 제시한다는 점에 있습니다.

계층형 아키텍처 (3-Tier Layering)

공식 저장소(https://github.com/anthropics/commerce-agents)에서는 공통 인프라 계층과 역할별 특화 계층으로 분리되어 있음을 알 수 있습니다.

Shopping Agent: 고객 접점 및 인터페이스 설계

StorefrontBackend 핵심 인터페이스 해설

쇼핑 에이전트가 고객과 대화하며 상품을 찾고 장바구니에 담기 위해 호출하는 모든 통신은 StorefrontBackend 클래스에 정의되어 있습니다. 기업은 자사의 기존 커머스 API(상품 DB, 검색 엔진, 장바구니 세션 등)를 이 메서드들에 1:1로 연결하면 됩니다.

• search_products (원하는 조건의 상품 찾아보기)
  • 역할: 고객의 자연어 요청(예: “5만 원대 방수 블루투스 스피커”)을 키워드, 카테고리, 가격 필터로 변환하여 매칭되는 상품 목록을 검색합니다.
  • 안전 메커니즘: 이 도구가 반환한 모든 product_id는 세션 내 화이트리스트(Provenance)에 자동 등록됩니다. 여기서 반환하는 것은 LLM이 아니라 파이썬 코드가 실제 DB에서 가져온 결과입니다. 이후 에이전트가 상품을 카트에 담거나 추천 카드로 띄울 때, 이 화이트리스트에 없는 ID는 즉시 차단되어 할루시네이션을 방지합니다.
• get_product_details (상품 상세 스펙 및 옵션 확인)
  • 역할: 특정 상품의 상세 설명, 기술 스펙, 가격, 실시간 재고, 그리고 선택 가능한 옵션(사이즈, 색상 등)을 가져옵니다.
  • 동작 원리: 에이전트는 이 상세 데이터를 먼저 확인한 뒤 고객에게 필수 옵션을 고르도록 자연스럽게 유도합니다. 옵션 선택이 끝나기 전까지는 장바구니 추가가 보류됩니다.
• 카트 조작: cart_* (장바구니 담기·수정·삭제·조회)
  • 역할: cart_add, cart_update, cart_remove, cart_view 등으로 구성된 세션 기반 장바구니 관리 기능입니다.
  • 안전 메커니즘: 모델이 임의로 호출하더라도 코드 레벨의 Provenance Gate가 개입합니다. 이번 대화 세션에서 실제로 검색·조회된 적 없는 ID는 차단되고, 필수 SKU(옵션)가 누락되었거나 최대 허용 수량을 초과하면 거부됩니다. 또한 세션별 동시성 뮤텍스 락(Mutex Lock)을 적용해 한 사용자의 장바구니 작업들을 1열 종대로 직렬화하여 데이터 꼬임을 방지합니다.
• get_preferences (고객의 취향·제약 기억 읽기)
  • 역할: 고객 프로필에 저장된 선호 성향(예: “평소 L 사이즈 착용”, “달지 않은 디저트 선호”, “캠핑 초보자”)을 불러옵니다.
  • 동작 원리: 기업 회원 DB의 기본 설정과 에이전트가 대화에서 실시간으로 정제한 ‘고객의 상황 및 니즈 태그’를 백엔드 메모리 저장소에서 읽어옵니다. 상품의 잡다한 메타데이터가 아닌 정제된 성향 정보만 주입되므로 대화가 길어져도 개인화된 추천이 유지됩니다.
• get_orders (내 주문 및 배송 내역 조회)
  • 역할: 고객의 과거 및 현재 진행 중인 주문 내역, 배송 현황, 결제 금액 등을 조회합니다. CS 문의(customer-care)에 주로 활용됩니다.
  • 안전 원칙: 철저한 읽기 전용(Read-Only) 인터페이스입니다. 에이전트에게 주문 취소나 환불 권한이 원천적으로 부여되지 않으며, 상태 확인 후 공식 고객센터 지원 플로우로 연결(핸드오프)하는 근거 데이터로만 쓰입니다.
• search_policies (반품/배송/교환 매장 정책 검색)
  • 역할: “무료 반품 기한이 언제까지야?”, “해외 배송도 가능해?” 같은 매장 정책 질문에 대해 최신 규정을 검색합니다.
  • 동작 원리: 모델이 정책 규정을 지어내어 답변하는 문제를 막기 위해, 정책 관련 사용자 발화가 감지되면 Grounding Enforcer가 이 도구 호출을 최우선으로 강제합니다. 발화에 정책 키워드가 감지되면 Claude API의 tool_choice 파라미터에 강제로 도구 이름을 지정해 모델이 도구 호출 외의 일반 텍스트 답변을 생성하지 못하도록 물리적으로 차단합니다.

5개 스킬 체계 상세 분석 (shopping-agent/skills/)

에이전트의 지능과 행동 양식은 방대한 단일 프롬프트에 쑤셔 넣지 않고, 각 도메인 목적별로 분리된 SKILL.md 파일로 모듈화되어 있습니다. 각 파일은 YAML Frontmatter(호출 조건 라우팅용 description)와 구체적인 절차적 행동 규칙(Do’s & Don’ts)을 포함합니다.

1. search-discovery/SKILL.md (상품 탐색 및 추천 발굴)

• 목적: 고객의 막연하거나 구체적인 탐색 요청을 해석하여 최적의 상품군을 압축 노출합니다.
• 핵심 행동 규칙:
  • 선택지 압축 (3~6개 룰): 검색 결과가 20개 나오더라도 화면에 쏟아내지 않고, 사용자의 의도에 가장 부합하는 3~6개의 대표 상품만 엄선하여 제시합니다. 인지 과부하를 방지하기 위함입니다.
  • 재고 소진 시 대체재 명시 (Out-of-Stock Rule): 찾던 상품의 재고가 없을 경우 단순히 “없습니다”로 끝내지 않고, 반드시 대안 상품을 함께 제시하되 “이 상품은 고객님이 찾으시던 X의 대체 상품입니다”라는 점을 문장으로 분명히 밝혀야 합니다.
  • 성급한 단정 금지 (Attribute Clarification): 검색어가 모호할 경우(예: “노트북 가방”) 제멋대로 특정 브랜드를 찍어주지 않고, 크기(인치), 용도(출퇴근/여행), 방수 여부 등 핵심 속성 1~2가지를 되물어 탐색 범위를 좁힙니다.
  • UI 컴포넌트 호출: 텍스트 나열 대신 반드시 present_products 도구를 호출해 규격화된 카드 UI로 상품을 전달합니다.

2. purchase-research/SKILL.md (구매 전 비교 및 사양 분석)

• 목적: 고객이 2개 이상의 상품을 저울질하거나 특정 기술 스펙을 고민할 때 객관적인 비교 기준을 제공합니다.
• 핵심 행동 규칙:
  • 판단 기준(Criteria) 선제 제시: 상품의 차이점을 나열하기에 앞서, 해당 카테고리를 고를 때 무엇을 봐야 하는지 기준 축(Trade-off)을 먼저 설명합니다. (예: “텐트를 고르실 때는 내수압, 무게, 설치 편의성 세 가지가 핵심 기준입니다.”)
  • 객관적 트레이드오프 설명 (No Hard Upsell): 비싼 상품을 일방적으로 칭찬하거나 유도 판매하지 않습니다. “A는 가볍지만 가격이 비싸고, B는 묵직하지만 가성비와 내구성이 좋습니다”처럼 각 선택지의 장단점을 대등하게 서술합니다.
  • 비교 매트릭스 도구 사용: 단순 줄글 비교를 지양하고 present_comparison 도구를 트리거하여 사양, 가격, 특장점이 1:1로 매핑된 시각적 비교 카드를 제공합니다.

3. planning-goals/SKILL.md (복합 목적 및 예산 설계 쇼핑)

• 목적: 캠핑, 해외여행, 신혼집 인테리어 등 하나의 목표 아래 여러 상품이 동시에 필요한 복합 쇼핑 플로우를 전담합니다.
• 핵심 행동 규칙:
  • 실제 예산 산술 계산 (Arithmetic Budget Rule): 사용자가 예산(예: “30만 원 안으로 캠핑 준비”)을 지정했을 때, 추천 상품들의 합산 가격을 모델이 직접 계산하여 구체적인 숫자로 언급해야 합니다. (예: “텐트 15만 원 + 매트 6만 원 + 침낭 8만 원 = 총 29만 원으로 예산 내에 맞췄습니다.”)
  • 예산 초과 시 즉각 경고: 합계가 예산을 단 1원이라도 초과하면 이를 얼버무리지 않고, “합산 32만 원으로 설정하신 30만 원 예산을 2만 원 초과합니다. 매트를 가성비 모델로 변경하시겠습니까?”라고 선택권을 줍니다.
  • 누락 품목 단계적 체크리스트 (Dependencies): 특정 품목에 종속된 필수 아이템(예: 텐트 구매 시 방수포/펙, 전자기기 구매 시 충전기/케이블)의 누락 여부를 체크리스트 형태로 짚어줍니다.

4. customer-care/SKILL.md (주문 추적 및 사후 지원)

• 목적: 배송 현황, 반품 규정, 교환 절차 등 구매 후 발생하는 고객 지원(CS)을 처리합니다.
• 핵심 행동 규칙:
  • 엄격한 쓰기 금지 (Read-Only Enforcement): 에이전트는 주문 상태 조회(get_orders, get_order)만 수행할 수 있습니다. 주문 취소, 배송지 수정, 환불 접수 등의 쓰기 작업은 절대로 직접 실행할 수 없습니다.
  • 공식 지원 플로우 핸드오프 (Support Handoff): 고객이 “주문 취소해줘”, “반품하고 싶어”라고 요구할 경우, 현재 주문 상태를 확인해 준 뒤 “주문 취소는 공식 고객센터 티켓 접수 페이지나 앱 내 [주문 취소 플로우]에서 진행해 주셔야 합니다”라며 호스트 앱의 해당 기능 URL/경로로 넘깁니다.
  • 공감과 사실의 분리: 배송 지연 등에 대해 정중하고 공감하는 어조를 유지하되, 확인되지 않은 배송 예정 시점을 임의로 약속하거나 지어내지 않습니다.

5. memory-personalization/SKILL.md (고객 선호 성향 기억 및 반영)

• 목적: 고객과의 대화 속에서 지속적으로 활용할 가치가 있는 선호도와 제약 조건을 추출하여 기억합니다.
• 핵심 행동 규칙:
  • 상품 데이터 저장 금지 (No Metadata Storage): “고객이 49,000원짜리 파란색 쿨맥스 티셔츠를 봤음”처럼 특정 상품의 스펙, 가격, ID 등 원시 메타데이터는 메모리에 저장하지 않습니다. 이는 토큰 낭비와 추천 편향을 유발합니다.
  • 잠재적 니즈/제약 조건만 추상화 (Needs Extraction): 고객의 발화에서 드러난 본질적인 조건만 추출하여 저장합니다.
    • 허용 예: 신체 사이즈: 상의 L, 선호 스타일: 미니멀, 제약: 갑각류 알레르기, 경험 수준: 캠핑 초보, 선호 예산대: 중저가 가성비
  • 자연스러운 맥락 주입: 기억한 내용을 기계적으로 “당신은 L 사이즈를 입으시니…”라고 매번 강조하지 않고, 검색 필터를 걸 때 보이지 않게 L 사이즈 재고를 우선 필터링하는 방식으로 은은하게 적용합니다.

4대 안전장치

본 아키텍처의 가장 큰 특징은 모델의 프롬프트 준수 능력(Instruction Following)에만 의존하지 않고, 파이썬 코드 레벨에서 안전성을 강제한다는 점입니다.

Provenance Gate (gates.py)

• 환각 방지: 카트에 추가할 수 있는 product_id는 해당 세션 내에서 catalog 또는 order 조회 도구가 반환했던 ID 화이트리스트에 존재하는 것만 허용됩니다. 모델이 임의로 생성한 가상 ID는 차단됩니다.
• 옵션 강제(Variant Hold): 사이즈, 색상 등 옵션 선택이 필요한 상품은 최하위 SKU(Variant)가 선택될 때까지 카트 담기가 보류됩니다.
• 상태 무결성: Mutex Lock을 통한 동시성 제어가 적용됩니다.

Prompt Fencing (fencing.py)

서드파티 텍스트(카탈로그 설명, 리뷰, 정책 문서 등 비신뢰 데이터 – 입점 브랜드 판매자가 등록한 상세 설명이나 일반 유저의 리뷰)가 모델 컨텍스트로 유입될 때 발생할 수 있는 간접 프롬프트 인젝션(Indirect Prompt Injection)을 원천 차단합니다.

• 제로폭 문자(Zero-width characters), 유니코드 양방향 제어문자(Bidi override) 제거
• 가짜 턴 마커(예: \n\nAssistant:, Human:, system:) 및 위조 도구 호출 태그 정규식 제거
• 비신뢰 데이터는 고정된 시스템 XML 라벨(예: <storefront>…</storefront>)로 엄격히 펜싱

Presentation Rehydration (presentation.py)

모델이 렌더링하는 UI 카드(present_products, present_comparison 등)의 신뢰성을 보장합니다.

• 모델이 전달한 UI 파라미터는 스키마 검증 후 폐기되며, 실제 화면에 노출되는 상품명, 가격, 통화 정보는 서버 데이터베이스 레코드에서 다시 조회한 값으로 재주입(Rehydration)됩니다.
• 출처(Provenance)가 확인되지 않은 상품 카드는 자동으로 렌더링에서 드롭되며 로깅됩니다.

Grounding Enforcer (grounding.py)

정책 질의, 구매 후 클레임, 세션 내 미조회 상품 ID 언급 등 사실 검증이 필수적인 발화에 대해 다음 턴의 첫 액션을 특정 읽기 도구(tool_choice)로 강제합니다. SDK 모드에서는 선행 데이터 페치(Prefetch) 파이프라인으로 전환되어 환각을 방지합니다.

Merchant Agent: 휴먼 인 더 루프 거버넌스

머천트 에이전트는 운영 직원이 사용하는 백오피스 에이전트로 성과 분석, 카탈로그 유지보수, 재고 알림, 가격 책정, 프로모션 캠페인 기획의 5개 영역을 지원합니다. 실제 쇼핑몰 운영에 영향을 미치는 데이터 변경 작업(쓰기 작업)들입니다. merchant-agent 소스 코드에 정의된 stage_* 도구들을 보면 구체적으로 다음 4가지를 제안합니다:

1. 가격 및 프로모션 제안 (stage_price_change, stage_promotion)

• 상황: “여름 샌들 재고 소진을 위해 할인율 적용해 줘.”
• 에이전트의 제안 내용:
  • 대상 상품 ID: sandal_cross_01
  • 기존 가격 $\rightarrow$ 제안 가격: 59,000원 $\rightarrow$ 41,300원 (30% 할인)
  • 프로모션 기간: 이번 주말 한정

2. 재고 추가 발주 및 수량 조정 제안 (stage_inventory_adjustment, stage_reorder)

• 상황: “안전 재고 기준(10개) 아래로 떨어진 캠핑 매트 재발주 넣어줘.”
• 에이전트의 제안 내용:
  • 대상 상품: tent_mat_foam
  • 현재 재고: 3개 (위험)
  • 제안 발주 수량: +50개 추가 입고 요청

3. 상품 카탈로그/콘텐츠 수정 제안 (stage_catalog_change)

• 상황: “A 텐트 설명에 방수 등급 누락됐는데 추가해 줘.”
• 에이전트의 제안 내용:
  • 대상 상품 ID: camp_tent_pro
  • 수정할 필드: description
  • 변경 전 텍스트 vs 변경 후 텍스트(Diff) 초안

4. 마케팅 캠페인 및 예산 기획안 (stage_campaign)

• 상황: “신학기 맞이 백팩 기획전 초안 짜줘.”
• 에이전트의 제안 내용:
  • 기획전 명칭, 노출 배너 문구 초안
  • 묶음 할인 대상 상품군 5종
  • 집행할 마케팅 예산 상한선: 300만 원

2단계 스테이징 트랜잭션: 모든 쓰기 작업은 즉시 커밋되지 않고 반드시 stage_* 도구를 통해 가상 영역에 머무릅니다.

인간 승인 강제 (require_host_approval=True):

• 채팅창에 텍스트로 “승인해줘”라고 입력하는 방식은 시스템 차원에서 무시됩니다.
• 포털 웹앱의 /approve 엔드포인트 또는 SDK 콘솔의 host_approve API를 통한 명시적 Cryptographic/Session 서명이 있어야만 apply_change가 실행됩니다.

이중 가드레일 평가 (Double-check Guardrails): 가격 변동폭 제한, 최대 할인율, 재고 조정 단위, 캠페인 예산 한도는 stage_* 시점과 apply_change 직전 시점 양쪽에서 모두 검증됩니다.

격리된 서브에이전트: 데이터 분석 쿼리는 단일 SELECT 문만 허용되는 읽기 전용 샌드박스 델리게이트에서 실행되며, 타임아웃, 리턴 행 수, 문자 수에 하드 캡이 걸려 있습니다.

MCP 커넥터 연동 (MCP Connectors)

저장소 자체에는 사전에 번들된 기본 MCP 커넥터는 포함되어 있지 않습니다. 두 에이전트 모두 백엔드 인터페이스(StorefrontBackend, MerchantBackend)를 통해서만 기업 시스템에 접근합니다.

• 공식 커넥터: 공식 커넥터가 외부 서비스인 경우, 백엔드 메서드 내부에서 해당 서비스를 호출하는 형태로 통합합니다.
  • 분석 데이터 웨어하우스: Snowflake, BigQuery, Databricks, Amplitude
  • 금융 및 결제: Stripe, Square, PayPal, QuickBooks
  • 협업 및 딜리버리: Slack, Google Drive, Gmail
• 커머스 플랫폼 자체 MCP 서버 연동:
  • 카탈로그, 장바구니, 체크아웃을 담당하는 기업 자체 MCP 서버가 있다면, 백엔드 메서드가 서버 사이드에서 이를 호출합니다.
  • Managed Agents 경로에서는 매니페스트(Manifest)를 통해 해당 MCP 서버를 역할별 서버 옆에 나란히 마운트할 수 있습니다.
  • 불변 원칙: 어떠한 방식으로 MCP 서버를 연결하더라도, 모든 쓰기 작업 앞단에는 출처 검증 게이트(Provenance Gate)가 반드시 위치하여 모델의 임의 쓰기 행위를 차단합니다.

점진적 파일럿 도입 전략 (Start Small)

전체 커머스 스택을 한 번에 AI로 전환할 필요 없이 단계적으로 검증할 수 있습니다.

• 쇼핑 에이전트 파일럿:
  • 1단계로 search_products와 get_product_details 2개 메서드만 실제 구현합니다.
  • 나머지 메서드는 스텁(Stub, 임시 대체체)으로 처리합니다. 스텁 메서드는 “현재 제공되지 않음(Unavailable)” 신호만 반환하며, 프롬프트 텍스트의 바이트를 단 하나도 바꾸지 않고 유지시킵니다.
• 머천트 에이전트 파일럿:
  • 1단계로 8개의 읽기(Read) 전용 메서드만 구현하고, 모든 쓰기(Write) 메서드는 호출을 거절하도록 설정합니다.
  • 이 상태만으로도 쓰기 경로의 리스크가 전혀 없는 안전한 상태에서 운영 요약 브리핑(Digests)과 성과 지표 분석(Metrics) 기능을 즉시 운영에 도입할 수 있습니다.