🚚 HackaThon25 - AI 배달 상담 챗봇 시스템

LangGraph와 Streamlit을 활용한 프로덕션 수준의 멀티 에이전트 배달 상담 시스템입니다.

📋 목차

프로젝트 개요
아키텍처
에이전트 소개
설치 및 실행
사용법
파일 구조
기여하기

🎯 프로젝트 개요

실제 배달 회사의 고객센터 수준에 가까운 AI 상담 챗봇 시스템입니다. 6개의 전문 에이전트가 협력하여 고객의 다양한 요청을 처리합니다.

주요 기능

🔍 주문 조회 및 상태 확인
❌ 주문 취소 및 환불 처리
🚚 실시간 배달 추적
😞 고객 불만 처리 및 보상
💳 결제 문제 해결
ℹ️ 일반 서비스 안내

🏗️ 아키텍처

시스템 구조

┌─────────────────┐
│   Supervisor    │  ← 요청 분석 및 적절한 에이전트 라우팅
│     Agent       │
└─────────┬───────┘
          │
    ┌─────┴─────┐
    │ LangGraph │  ← 워크플로우 관리
    │ Workflow  │
    └─────┬─────┘
          │
┌─────────┴─────────┐
│   6개 전문 에이전트   │
└───────────────────┘

에이전트 워크플로우

graph TD
    A[사용자 입력] --> B[Supervisor Agent]
    B --> C{요청 분석}
    C -->|주문 조회| D[Query Agent]
    C -->|주문 취소| E[Cancel Agent]
    C -->|배달 추적| F[Delivery Tracking Agent]
    C -->|불만 처리| G[Complaint Agent]
    C -->|결제 문제| H[Payment Agent]
    C -->|일반 문의| I[General Agent]
    D --> J[응답 생성]
    E --> J
    F --> J
    G --> J
    H --> J
    I --> J
    J --> K[사용자에게 응답]

🤖 에이전트 소개

1. Supervisor Agent 🧠

역할: 사용자 요청을 분석하여 적절한 전문 에이전트로 라우팅
기술: GPT-4o-mini + Structured Output
특징: 6개 에이전트 중 최적의 선택

2. Query Agent 📋

역할: 주문 조회 및 상태 확인
처리: 주문번호 추출, 고객별 주문 데이터 조회
응답: 주문 상태, 음식점 정보, 예상 시간 등

3. Cancel Agent ❌

역할: 주문 취소 및 환불 처리
특징: 2단계 확인 프로세스 (요청 → 확인 → 처리)
정책: 조리 단계별 차등 환불

4. Delivery Tracking Agent 🚚

역할: 실시간 배달 추적 서비스
정보: 배달원 정보, 현재 위치, 진행률, 연락처
특징: GPS 기반 실시간 위치 제공

5. Complaint Agent 😞

역할: 고객 불만 처리 및 보상
프로세스: 감정 공감 → 문제 파악 → 해결책 제시 → 보상 처리
보상: 재주문, 환불, 쿠폰 지급 등

6. Payment Agent 💳

역할: 결제 문제 해결 및 환불 처리
기능: 재결제 안내, 포인트 관리, 영수증 재발송
지원: 카드, 현금, 포인트 결제

7. General Agent (Fallback) ℹ️

역할: 전문 에이전트 범위 밖의 일반적인 질문 처리
처리: 서비스 정보, 이용 방법, 정책 안내
정보: 배달 지역, 영업시간, 요금 정보 등

🚀 설치 및 실행

사전 요구사항

Python 3.11+
OpenAI API Key
LangSmith API Key (선택사항)

1. uv 설치 (권장)

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

2. 프로젝트 클론 및 설정

# 프로젝트 클론
git clone https://github.com/sungchan-jupyter/HackaThon25.git
cd HackaThon25

# uv로 의존성 설치 (pyproject.toml 기반)
uv sync

# 또는 기존 방식 (requirements.txt)
uv venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
uv pip install -r requirements.txt

3. 환경 변수 설정

# .env 파일 생성
cp .env.example .env

# .env 파일 편집 (API 키 입력)
OPENAI_API_KEY=your_openai_api_key_here
LANGCHAIN_API_KEY=your_langsmith_api_key_here  # 선택사항
LANGCHAIN_TRACING_V2=true  # 선택사항

4. 애플리케이션 실행

# 최신 버전 (6개 에이전트) - 추천!
uv run streamlit run src/04-chatbot-add-agent.py

# 3개 에이전트 버전
uv run streamlit run src/03-chatbot-기능추가.py

# 기본 버전
uv run streamlit run src/02-chatbot-baseline.py

📖 사용법

기본 사용 흐름

고객 선택: 사이드바에서 상담할 고객 선택
요청 입력: 채팅창에 자연어로 요청 입력
자동 라우팅: Supervisor가 적절한 에이전트 선택
전문 응답: 선택된 에이전트가 전문적인 답변 제공

테스트 시나리오

🔍 주문 조회

"주문 12345 조회해주세요"
→ Query Agent가 주문 상태, 음식점 정보, 예상 시간 제공

🚚 배달 추적

"주문 12345 배달 어디까지 왔나요?"
→ Delivery Tracking Agent가 실시간 위치, 배달원 정보 제공

❌ 주문 취소

"주문 12346 취소하고 싶어요"
→ Cancel Agent가 2단계 확인 후 취소 처리

😞 불만 처리

"음식이 차갑게 왔어요"
→ Complaint Agent가 공감, 해결책, 보상 제시

💳 결제 문제

"결제가 안되요"
→ Payment Agent가 재결제 방법, 포인트 사용 안내

ℹ️ 일반 문의

"배달 가능 지역이 어디인가요?"
→ General Agent가 서비스 정보 제공

고객 데이터

테스트용 고객 3명과 주문 데이터가 준비되어 있습니다:

김철수 (VIP): 주문 2건, 포인트 15,000점
이영희 (일반): 주문 1건, 포인트 3,000점
박민수 (골드): 주문 1건, 포인트 8,500점

📁 파일 구조

HackaThon25/
├── .gitignore                        # Git 제외 파일 설정
├── .env.example                      # 환경변수 템플릿
├── README.md                         # 프로젝트 설명서
├── requirements.txt                  # Python 의존성 (기존 방식)
├── pyproject.toml                   # 현대적 Python 프로젝트 설정
├── src/                             # 메인 애플리케이션
│   ├── 02-chatbot-baseline.py       # 기본 챗봇
│   ├── 03-chatbot-기능추가.py        # 3개 에이전트 버전
│   └── 04-chatbot-add-agent.py      # 6개 에이전트 버전 (최신)
└── notebooks/                       # 학습 자료 및 튜토리얼
    ├── 01-chatot-beginner.ipynb     # 기초 튜토리얼
    ├── 01-LangGraph-Introduction.ipynb
    ├── 02-LangGraph-ChatBot.ipynb
    ├── 03-LangGraph-Agent.ipynb
    ├── 04-LangGraph-Agent-With-Memory.ipynb
    ├── 05-LangGraph-Streaming-Outputs.ipynb
    ├── 06-LangGraph-Human-In-the-Loop.ipynb
    └── LangGraph-개요.pdf

🛠️ 기술 스택

Frontend: Streamlit
AI Framework: LangChain + LangGraph
LLM: OpenAI GPT-4o-mini
State Management: LangGraph StateGraph
Memory: LangGraph MemorySaver
Package Manager: uv (권장) 또는 pip

🔧 개발 환경 설정

uv 사용 (권장)

# 새 의존성 추가
uv add package-name

# 개발 의존성 추가
uv add --dev pytest black

# 의존성 업데이트
uv lock --upgrade

# 애플리케이션 실행
uv run streamlit run src/04-chatbot-add-agent.py

전통적인 방식

# 가상환경 생성 및 활성화
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 의존성 설치
pip install -r requirements.txt

# 애플리케이션 실행
streamlit run src/04-chatbot-add-agent.py

🤝 기여하기

Fork the Project
Create your Feature Branch (git checkout -b feature/AmazingFeature)
Commit your Changes (git commit -m 'Add some AmazingFeature')
Push to the Branch (git push origin feature/AmazingFeature)
Open a Pull Request

개발 가이드라인

새로운 에이전트 추가 시 기존 아키텍처 패턴 유지
모든 에이전트는 AgentState 타입 사용
LLM 호출 함수는 call_*_llm 네이밍 컨벤션 따르기
에러 처리 및 폴백 로직 필수 포함

📄 라이선스

이 프로젝트는 MIT 라이선스 하에 배포됩니다. 자세한 내용은 LICENSE 파일을 참조하세요.

🙋‍♂️ 문의

프로젝트에 대한 질문이나 제안사항이 있으시면 언제든 연락주세요!

GitHub Issues: 이슈 생성
Email: [email protected]

⭐ 이 프로젝트가 도움이 되셨다면 스타를 눌러주세요!

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
notebooks		notebooks
src		src
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
uv.lock		uv.lock

sungchan-jupyter/HackaThon25

Folders and files

Latest commit

History

Repository files navigation