빠르게 "제 상품은 언제 도착하나요?"라고 물어볼 수 없어서 쇼핑 카트를 포기해 본 경험이 있으신가요? 업계 평균에 따르면 장바구니 포기는 약 70% 수준이며, 느린 응답 속도가 주요 원인입니다. 문의 양식(contact forms), 티켓 포털, 그리고 몇 시간 후에야 답장이 오는 이메일 등이 그 원인입니다.
이러한 문제로 인해 저는 이커머스를 위한 실시간 고객 지원 플랫폼인 Aura Gear를 구축하게 되었습니다. 또한 이는 엔지니어와 AI 에이전트 팀이 사양 정의부터 운영까지 완전한 시스템을 함께 구축하는 방식에 대한 실험이기도 합니다.
⚡ Aura Gear: 실시간 이커머스 고객 지원 플랫폼
CI/CD Pipeline License: MIT Python: 3.10+
현대적인 이커머스 상점(storefronts)을 위해 구축된 비동기적이고 초저지연(ultra-low latency)의 실시간 고객 지원 플랫폼입니다. 즉각적인 주문 추적이 가능한 임베디드형 고객 컨시어지 위젯과 다중 패널 지원 에이전트 명령 센터 기능을 제공합니다.
🌐 실시간 운영 배포 (Live Production Deployment)
Aura Gear
📋 평가 기준 정렬 매트릭스 (Evaluation Rubric Alignment Matrix) (12개 기준 / 24점)
| No | Criterion | Target Score | Evidence / Deliverable File | Summary |
|---|
| 1 | 문제 설명 (Problem Description) | 2 / 2 | README.md, product-spec.md | 문제점, 쇼퍼/에이전트 페르소나, 예상되는 동작을 명확하게 설명함. |
| ... | | | | |
| … | | | | |
View on GitHub
Aura Gear
문제점 (The Problem)
온라인 쇼퍼들은 보통 세 가지 사항에 대해 빠른 답변을 필요로 합니다:
- 소포 추적 및 배송사 일정
- 반품 및 교환 정책
- 사이즈, 사양 및 재고 가용성
Aura Gear는 다음 두 가지 구성 요소를 통해 이를 해결합니다:
- 고객 컨시어지 위젯 (Customer concierge widget): 즉시 주문 추적이 가능한 온라인 스토어용 임베드형 채팅 기능.
- 에이전트 명령 센터 (Agent command center): 지원팀을 위한 다중 패널 대시보드.
| 페르소나 | 필요 사항 |
|---|
| 쇼퍼 (Shopper) | 끊김 없는 즉각적인 답변, 페이지를 벗어나지 않는 주문 조회 기능, 인간 에이전트와 상담할 수 있는 옵션 |
| 지원 에이전트 (Support agent) | 많은 동시 채팅 처리 능력, 고객의 입력 미리 보기(typing previews), 원클릭 매크로, 즉각적인 주문 컨텍스트 |
아키텍처 개요 (Architecture at a Glance)
- 프론트엔드 (Frontend): 빌드 단계가 필요 없는 가벼운 글래스모픽 UI(150KB 미만)
- 백엔드 (Backend): 네이티브 비동기 웹소켓을 사용하는 Python 3.10+와 FastAPI 및 Uvicorn
- 지속성 (Persistence): 대화, 메시지, 에이전트 할당에 대한 스레드 안전한 비동기 채팅 저장소이며 세션 복구 기능 포함
- 배포 (Deployment): Google Cloud Run의 다단계 Docker 이미지
다음 명령어로 로컬에서 실행할 수 있습니다:
python3 app_build/server.py
또는 컨테이너를 사용하여 실행합니다:
docker compose up -d --build
AI 에이전트 팀에 의해 구축됨
프로젝트는 각각 특정 역할을 가진 6개의 에이전트 페르소나에 의해 설계, 구축 및 검증되었습니다:
| Agent | 역할 | 산출물 |
|---|
@pm | Product Manager | product-spec.md, openapi.yaml API 계약 |
| ... | | |
각 에이전트는 .agents/skills/ 아래에 자체 스킬(skill) (지침 파일)을 가지고 있으며, 단일한 startcycle.md 워크플로우가 **인간 승인 게이트(human approval gate)**를 통해 전체 사이클을 오케스트레이션합니다. 최종 결정권은 인간에게 있습니다. | | |
Diagram of the Agent Workflow
컨텍스트 관리: 에이전트를 궤도에 유지하기 (Context Management: Keeping Agents on Track)
AI 에이전트는 컨텍스트가 명확할 때 최고의 성능을 발휘하므로, 이 저장소는 모듈식 문서를 사용합니다:
AGENTS.md: 마스터 거버넌스 파일docs/architecture.md: 아키텍처 및 시퀀스 다이어그램docs/permissions.md: 도구 실행 경계, 파일 시스템 안전성, 자격 증명 격리security/ai-data-policy.md: 원격 측정 정책 (PII 또는 자격 증명 없음)ops/runbook.md: 진단 및 알림 가이드
잘 정리된 문서는 에이전트의 작업 기억(working memory)입니다. 경계가 명확할수록 결과는 더욱 신뢰할 수 있습니다.
테스트 및 CI/CD
모든 테스트를 실행하는 단일 명령어가 있습니다:
python3 -m unittest discover tests
- 단위 테스트(Unit tests): 주문 ID 정규화 (
#ORD-1001, ord-1001, 1001), 주문 카탈로그, 채팅 스토어
- 통합 테스트(Integration tests): 헬스 엔드포인트, 주문 조회, 404 처리, 매크로 엔드포인트
GitHub Actions 파이프라인은 세 단계로 구성되어 있습니다:
Push / Pull Request
|
v
...
운영 환경(Production) 배포는 수동 승인 게이트 뒤에 위치합니다. 개발 환경에서는 자동화가 공격적일 수 있지만, 운영 환경은 신중한 결정이 필요합니다.
screenshot of the manual production deploy
실제 사용자 영향 기반 알림 (Alerting on Real User Impact)
일반적인 CPU 또는 RAM 그래프 대신, 경고는 사용자가 실제로 느끼는 것에 초점을 맞춥니다:
- **웹소켓 드롭률(WebSocket drop rate)**이 3분 이내에 5%를 초과하는 경우 (쇼퍼들이 연결을 끊음)
- **p95 지연 시간(latency)**이 500ms를 초과하는 경우 (채팅이 느리게 느껴짐)
/api/orders에서 **5xx 오류율(error rate)**이 2%를 초과하는 경우 (주문 추적이 실패함)
모든 웹소켓 연결에는 trace_id가 포함되어 있어 로그 간의 상관관계 분석이 용이하며, 원격 측정 데이터(telemetry)에는 개인 데이터, 결제 정보 또는 자격 증명은 절대 포함되지 않습니다.
온콜 에이전트 (The On-Call Agent)
경고가 발생하면, @oncall-responder가 스스로 깨어납니다:
- 알림 웹훅(webhook)을 구문 분석합니다.
trace_id를 통해 오류 로그의 상관관계를 분석합니다 (Correlates error logs).- 고아 세션(orphaned sessions)에서 메모리를 정리합니다.
- 응답하지 않게 된 경우 ASGI 워커(workers)를 재시작합니다.
ops/health-check.sh로 복구를 확인합니다.
이것이 바로 플랫폼 엔지니어링과 AI 엔지니어링이 만나는 지점입니다. 잘 작성된 런북(runbook)은 운영 에이전트의 '두뇌'가 될 수 있습니다.
직접 사용해 보기 (Try It Yourself)
배운 점 (Lessons Learned)
- 사양(Specification)을 먼저, 코드를 나중에. OpenAPI 계약과 수용 기준(acceptance criteria)이 포함된 작업 추적기(task tracker)는 에이전트가 집중하도록 유지합니다.
- 명확한 역할은 에이전트를 더 신뢰할 수 있게 만듭니다. 하나의 에이전트가 하나의 책임(responsibility)을 가지며, 각각 고유의 기술(skill)을 갖게 합니다.
- 인간 개입 루프를 유지합니다 (Keep humans in the loop). 워크플로우와 프로덕션 배포(production deploys)에서의 승인 게이트(approval gates)는 통제권을 보존합니다.
- 인프라 수치뿐만 아니라 사용자 영향도에 대해 경고합니다 (Alert on user impact).
- 런북(Runbook)은 AI 자산입니다. 문서화된 절차는 에이전트에 의해 직접 실행될 수 있습니다.
마무리 생각
Aura Gear는 단순한 채팅 앱 그 이상입니다. 이는 AI 에이전트를 사용하여 완전한 소프트웨어 배포 수명 주기(software delivery lifecycle)를 구축하는 연습입니다. 즉, 사양(specification), 코드, 테스트, 컨테이너, CI/CD, 관측 가능성(observability), 그리고 인시던트 대응(incident response)을 포함합니다.
만약 데이터/플랫폼 엔지니어링과 AI 엔지니어링의 교차점에서 작업하고 있다면, 여러분이 자신의 프로젝트에서 에이전트 역할(agent roles)과 가드레일(guardrails)을 어떻게 구성하는지 듣고 싶습니다. 댓글에 접근 방식을 공유해 주시고, 레포지토리(repo)에 ⭐를 남겨주시면 항상 감사하겠습니다.
