오픈소스 Shopify 지원 에이전트 storekeeper 개발기와 그래프 기반 승인 경계 설계 검토 요청

이 요약은 AI가 원문을 분석해 생성했습니다. 정확한 내용은 원문 기준으로 확인하세요.

TL;DR

작성자는 storekeeper라는 오픈소스 Shopify 고객지원 에이전트를 소개하면서 LLM은 의도 분류와 언어 생성에만 관여시키고 실제 상점 쓰기는 고정 매핑된 파이썬 코드와 인간 승인이 맡도록 설계했다. 워크플로는 LangChain의 structured-output으로 의도를 추출하고 LangGraph의 저수준 노드(Send, interrupt, checkpointer)를 사용해 실행을 중단한 뒤 SQLite 체크포인트로 상태를 보존하고 인간 승인이 있을 때만 GraphQL Admin API를 통해 쓰기를 수행하는 방식이다. 또한 RAG는 로컬 Chroma에서 근거를 가져오고 코드 레이어에서 인용을 검증해 응답의 사실성을 높였으며, 이 설계는 자동화 편의성과 직접적인 위험 통제 사이의 트레이드오프를 명확히 반영한다.

실용적 조언

분류기의 출력 스키마를 가능한 한 좁게 제한하고 실패 케이스를 명시적으로 처리하는 테스트 케이스를 마련하라. 모델이 반환할 수 있는 모든 변형을 예시로 포함한 단위 테스트를 작성해 분류 오류가 매핑 단계로 이어지지 않도록 검증해야 한다. 또한 분류 오류가 발생했을 때 사람이 빠르게 식별하고 재분류할 수 있는 로그와 UI를 준비해야 운영 안정성이 확보된다.
승인 워크플로에는 감사 로그와 재현 가능한 체크포인트를 의무화하라. 각 승인 항목은 SQLite 같은 영속 저장소에 체크포인트와 메타데이터를 기록하고, 재시작 시 동일 인터럽트 ID로 정확히 복원되도록 구현해야 장애 복구가 가능하다. 승인 거부·수정 이력과 실행 전후 상태 스냅샷을 남겨 추후 문제 발생 시 책임 소재를 추적할 수 있어야 한다.
RAG로 근거를 가져오는 경우 근거 문서의 신뢰도와 인용 바이어스를 코드에서 평가하는 절차를 두어야 한다. Chroma에서 유사도 상위 결과를 가져온 뒤 코드 레이어에서 출처와 타임스탬프, 정책 적용 가능 여부를 확인해 인용 여부를 결정하면 모델의 발언이 검증된 사실에 기반함이 보장된다. 인용 불일치나 오래된 문서는 자동으로 제외하는 룰을 병행해 잘못된 근거 사용을 방지해야 한다.

섹션별 상세

01

고객 요청을 LLM으로부터 분리된 태스크 리스트로 변환하는 문제는 잘 정의된 입력·출력 스키마로 해결되며, 작성자는 LangChain의 structured-output 호출을 사용해 모델이 의도만 선택하도록 제한했다. 이 방식은 모델이 자유롭게 행동하거나 임의의 툴 호출을 생성하지 못하게 하며, 이후 실제 Shopify 동작은 고정 매핑된 파이썬 코드가 결정하도록 설계되어 있다. 구현 근거로서 분류-매핑의 분리와 고정 매핑 사용이 명시되어 있다. 이 접근은 모델의 생성적 불확실성이 실제 상점 변경으로 이어지는 위험을 낮추는 실무적 보호를 제공한다.

02

승인 전까지 어떤 쓰기도 실행하지 않는 안전 경계 설계는 인터럽트와 체크포인트 메커니즘으로 실현되며, 중단점과 재개를 관리하기 위해 SQLite에 상태를 저장하는 구조가 도입되었다. 진행 트리의 실행 지점이 interrupt()로 멈추고 인간이 승인할 때만 execute 노드에 진입하므로 자동화 경로가 인간 승인을 우회할 가능성이 제거된다. 게시물에서는 다중 요청 메시지에 대해 Send로 분기해 각 주문별 승인 카드를 생성한 사례와 실제 스크린샷을 근거로 제시했다. 이 설계는 실거래 환경에서의 사고 복구와 승인지연 상황을 모두 다룰 수 있는 영속성 보장을 제공한다.

03

모델에게 계획·도구 선택 권한을 주지 않겠다는 설계 결정은 Deep Agent 스타일의 자동 루프와 도구 선택을 의도적으로 배제하는 쪽으로 수렴했으며, 그 대신 분류기가 생성하는 검증된 태스크 리스트를 시스템의 계획으로 사용했다. 작성자는 LangGraph의 저수준 제어 요소들(Send, interrupt, checkpointer)이 이 요구에 더 적합했다고 밝히며, 모델이 자체 루프를 설계하거나 임의 작업을 선택하는 것을 차단하는 것이 핵심 목표였다고 명시했다. 이 선택은 자동화 편의성과 직접적인 위험 통제 사이의 트레이드오프를 명확히 드러낸다.

04

근거 제공과 정책 검증은 RAG 기반 검색과 코드 내 검증 절차로 구현되어 응답에 첨부되는 인용이나 정책 판단이 모델의 혼합 오류로 이어지지 않게 구성되었다. 로컬 Chroma에서 추출한 문서를 근거로 사용하되, 인용은 코드에서 검증한 후에만 답변 초안에 포함되므로 모델이 임의로 근거를 발명할 여지가 줄어든다. 게시물은 이 워크플로가 실제 Shopify 개발 스토어와 GraphQL Admin API를 통해 동작한다고 밝혀 실전 연동 상태를 근거로 제시했다. 이 방식은 고객 응대의 설명 책임성과 규정 준수를 동시에 강화하는 방향으로 기능한다.

이미지 분석

Screenshot
이 이미지는 단일 고객 메시지에서 다중 주문을 분기해 별도의 승인 카드로 생성하는 흐름을 시각적으로 확인시킨다. 카드에는 모델이 매칭한 주문 ID와 정책 검증 결과가 텍스트로 표기되어 있어 자동화가 어떤 근거로 중단되고 인간 승인이 필요한지 명확히 드러난다. UI에 표시된 금액과 'Gate passed' 상태는 설계한 정책 검증이 실제로 적용되어 있음을 보여준다.
승인 대기 카드 UI 스크린샷으로 각 주문별 매칭 결과, 정책 게이트 통과 상태, 금액, 승인·거부 버튼이 표시되어 있다.

Screenshot
이 스크린샷은 시스템이 여러 티켓을 동시에 관리하며 히스토리와 상태를 보존하는 운영 측면을 보여준다. 좌측의 히스토리 열과 중앙의 승인 카드 배열은 체크포인팅과 재시작 후 복원 가능성, 다중 동시 승인 항목 처리 사례가 실제로 동작하고 있음을 시사한다. 이미지의 구성은 설계한 안전 경계가 사용자 인터페이스 수준에서도 반영되어 있음을 확인시킨다.
전체 인터페이스 캡처로 보류 중인 티켓 목록과 각 티켓의 히스토리, 현재 승인 대기 카드들이 함께 보인다.

용어 해설

검색 증강 생성(RAG): — 외부 문서나 데이터베이스에서 관련 정보를 검색해 LLM의 응답 컨텍스트로 주입하는 방식이며, 검색 결과를 임베딩·유사도 기반으로 선택하고 응답 생성 전에 인용문이나 근거를 함께 결합해 사실성 보강을 목적으로 사용된다.
구조화된 출력(Structured Output): — 모델이 자유문 대신 JSON 같은 엄격한 스키마로 의도·필드·작업 목록을 반환하도록 유도하는 방식으로, 후속 비즈니스 로직이 예측 가능한 입력을 받아 안전하게 결정적 행동을 수행하게 하는 데 중요하다.
체크포인팅(Checkpointing): — 시스템 상태(예: 승인 대기 항목, 인터럽트 ID)를 영속 스토리지에 저장해 프로세스 재시작 시 이어서 처리할 수 있게 하는 메커니즘으로, 오류 복구와 승인 보존을 위해 사용된다.
벡터 데이터베이스(Vector DB): — 임베딩을 벡터로 저장하고 유사도 검색을 수행하는 저장소로, RAG 워크플로에서 관련 문서를 빠르게 찾아 모델 입력으로 결합하는 역할을 수행한다.

언급된 도구

LangChain추천

LLM 응답을 structured-output으로 유도해 의도 분류를 수행하는 도구

LangGraph추천

그래프 실행 모델에서 Send, interrupt, checkpointer 같은 저수준 제어를 제공하는 도구

LangSmith중립

런 트리와 실행 관리를 시각화하고 interrupt 지점에서 실행을 중단시키는 모니터링 도구

Chroma추천

로컬 임베딩 저장·유사도 검색을 통해 RAG 근거를 제공하는 벡터 데이터베이스

SQLite추천

승인 대기 항목의 체크포인트와 상태 보존을 위한 영속 스토리지

Shopify GraphQL Admin API중립

실제 상점 주문 상태를 조회하고 취소 같은 쓰기 작업을 수행하기 위한 백엔드 API

언급된 리소스

GitHubstore-keeper repository (MIT)