liangdabiao/langgraph_multi-agent-rag-customer-support

본 프로젝트는 다중 에이전트 (Multi-Agent) 및 검색 증강 생성 (Retrieval-Augmented Generation, RAG) 기술을 기반으로 한 고객 지원 시스템을 구현합니다. Python, LangChain 및 LangGraph를 활용하여 항공권 예약, 렌터카, 호텔 예약, 일정 추천을 포함한 다양한 여행 관련 문의를 처리할 수 있는 대화형 AI를 구축했습니다. 또한 WooCommerce 쇼핑몰과 연동하여 상품 조회, 게시글 조회, 양식 제출, 주문 조회 등 쇼핑몰 기능도 지원합니다. 본 프로젝트는 기초 프레임워크인 https://github.com/ro-anderson/multi-agent-rag-customer-support 를 포크(fork)하여 제작되었습니다.

본 프로젝트는 원본을 바탕으로 대폭적인 기능 확장을 진행하였으며, 보안 가드레일 메커니즘 (탈옥 방지 및 관련성 검사)과 GoHumanLoop 기반의 인적 검토 프로세스를 추가하여 시스템의 보안성과 제어 가능성을 크게 향상시켰습니다.

시스템은 다중 에이전트 아키텍처를 채택하고 있으며, LangGraph를 사용하여 상태 그래프 (State Graph)를 구현합니다. 주요 구성 요소에 대한 설명은 다음과 같습니다:

주 보조자 (Primary Assistant): 사용자 문의의 진입점입니다. 사용자의 요구 사항에 따라 대화를 전문 보조자에게 라우팅합니다. 전문 보조자 (Specialized Assistants): 항공권 예약 보조자: 항공 관련 문의 및 예약을 처리합니다. 렌터카 보조자: 렌터카 요청을 관리합니다. 호텔 예약 보조자: 호텔 예약 문의를 처리합니다. 일정 추천 보조자: 여행 및 활동 추천을 처리합니다. WooCommerce 보조자: 이커머스 제품 및 주문 조회를 처리합니다. 양식 제출 보조자: 사용자 양식 제출을 처리합니다. 블로그 검색 보조자: 블로그 게시글 검색을 처리합니다.

도구 노드 (Tool Nodes): 각 보조자는 도구에 접근할 수 있습니다. 안전 도구는 사용자의 확인 없이 사용할 수 있지만, 민감한 도구는 실행 전 사용자의 확인이 필요합니다.

라우팅 로직 (Routing Logic): 시스템은 현재 상태와 사용자 입력에 따라 보조자와 도구 노드 사이에서 대화를 라우팅하기 위해 조건부 엣지 (Conditional Edges)를 사용합니다.

사용자 확인 (User Confirmation): 민감한 작업의 경우, 시스템은 일시 중단되어 사용자에게 확인을 요청한 후 계속 진행합니다. 메모리 및 상태 관리 (Memory and State Management): 시스템은 대화 상태를 유지하며 메모리 체크포인트 (Memory Checkpoints)를 사용하여 진행 상황을 저장합니다.

보안 및 확인 메커니즘 (Security and Confirmation Mechanisms): 민감한 작업 확인: 사용자는 데이터를 수정할 수 있는 모든 작업에 대해 반드시 확인해야 합니다. 보안 가드레일 (Security Guardrails): 사용자 입력을 처리하기 전, 시스템은 AI 에이전트를 통해 탈옥 방지 및 관련성 검사를 수행합니다. 인적 검토 (GoHumanLoop): 민감한 작업은 사용자의 확인을 거친 후에도 GoHumanLoop 프레임워크를 통해 관리자에게 최종 검토를 요청합니다 (예: Feishu 알림을 통해).

이러한 아키텍처를 통해 다양한 고객 지원 시나리오를 유연하고 모듈화된 방식으로 처리할 수 있는 동시에, 민감한 작업에 대해 다중 보안 조치를 내장할 수 있습니다.

효과적인 모니터링 및 디버깅 능력을 보장하기 위해, 프로젝트는 관측 가능성 (Observability)을 강화하고자 LangSmith를 통합했습니다. LangSmith는 도구 사용, 에이전트 응답, 오류를 포함한 요청의 생명 주기를 추적하는 데 도움을 주어, 개발자가 다중 에이전트 시스템의 성능 변화를 시간에 따라 파악할 수 있게 합니다.

• Python 3.12+

• Poetry

• Docker 및 Docker Compose

• OpenAI API Key

• LangSmith API Key (선택 사항, 추적용)

• 코드 저장소를 클론(clone)하고 프로젝트 디렉토리로 이동합니다.

• .dev.env로부터 .env 파일을 생성합니다:

cp .dev.env .env

• .env 파일을 편집하여 필요한 값을 입력합니다:

OPENAI_API_KEY="your_openai_api_key"
LANGCHAIN_API_KEY="your_langsmith_api_key" # 선택 사항
# GoHumanLoop를 구성하려면 다음을 추가하세요:
...

• 의존성 설치:

poetry install

• Qdrant 벡터 데이터베이스 실행 (선택 사항, 또는 직접 클라우드 Qdrant 사용):

docker compose up qdrant -d

다음 주소를 통해 Qdrant UI에 접속할 수 있습니다: http://localhost:6333/dashboard#

• 벡터 임베딩 생성:

poetry run python vectorizer/app/main.py

• 고객 지원 채팅 시스템 실행:

CLI 버전:

poetry run python ./customer_support_chat/app/main.py

Web 인터페이스 버전:

poetry run uvicorn web_app.app.main:app --reload --host 0.0.0.0 --port 8000

본 프로젝트는 두 가지 주요 서비스를 포함합니다:

Vectorizer: 지식 기반에 벡터 임베딩을 생성합니다. Customer Support Chat: 주 대화형 AI 시스템입니다. faq_documents: 벡터 임베딩 생성을 위한 지식 기반 문서입니다. web_app: 사용자와 상호 작용하는 웹 인터페이스 버전입니다. graphs: 시스템 구조를 시각화하기 위한 시스템 그래프가 포함된 디렉토리입니다. faq_extension: 독립적인 벡터 임베딩 생성을 위한 새로 추가된 지식 기반 문서 디렉토리입니다.

Customer Support Chat 서비스는 Vectorizer가 생성한 벡터 데이터베이스에 의존합니다.

본 프로젝트는 두 가지 주요 데이터 소스를 사용합니다:

• 여행 데이터베이스: LangGraph의 여행 데이터베이스 벤치마크입니다. 이 SQLite 데이터베이스에는 항공편, 예약, 승객 및 기타 여행 관련 데이터가 저장되어 있습니다. - Qdrant: 여행 데이터베이스의 벡터 임베딩을 저장하고 검색하는 데 사용되는 벡터 데이터베이스입니다.

시스템 기능 설명 문서-기술 구현판.md , 시스템 기능 설명 문서.md ,

다중 에이전트 RAG 시스템을 계속 개선하기 위해, 다음과 같은 직접적으로 관련된 강화 방향들이 있습니다:

도구 최적화:
고급 RAG 기술을 활용하여 기존 도구의 잠재력을 개선할 여지가 매우 큽니다:

• 기존 검색 도구 (search_flights, search_hotels, search_car_rentals 등)에 '적응형 RAG(Adaptive RAG)' 방법을 구현하여, 더 정교한 필터링을 통합함으로써 벡터 데이터베이스(VecDB)에서 검색하는 정확도를 높입니다. - VecDB 결과가 불충분할 때, 네트워크 검색 도구에 **'수정적 RAG(Corrective RAG)'**를 적용하여, 폴백 검색이 더욱 관련성 있고 효율적이도록 보장합니다. - **'자가 RAG(Self-RAG)'**를 활용하여 생성된 답변이 검색된 데이터(VecDB 또는 네트워크 검색에서 온)에 기반하는지 평가합니다. 그렇지 않다면, 에이전트는 응답 전에 더 정확하거나 추가적인 정보를 요청할 수 있어 최종 출력의 데이터 무결성을 보장합니다.

그래프 아키텍처 최적화:

그래프 최적화: graph.py에서 다양한 에이전트에 더 상세한 조건 경로를 추가하여 논리를 강화하고, 사용자 질의 및 검색 문서를 기반으로 더 나은 결정을 내리도록 합니다.

메모리 통합:

• 캐시 데이터베이스를 구현하여 사용자 상태와 대화 기록을 저장함으로써, 에이전트가 과거 상호 작용을 참조하여 더욱 개인화되고 상황 인지적인 응답을 제공할 수 있도록 합니다. 현재는 개별 JSON 파일(user_data 폴더 내부)에 개인 사용자 데이터를 직접 저장하고 있습니다.

안녕하세요, 오늘 제가 최근 연구하고 개선한 AI 프로젝트를 공유하고자 합니다: 다중 에이전트(Multi-Agent)와 RAG 기술을 기반으로 한 지능형 고객 서비스 시스템입니다. 이 프로젝트는 원래 여행 관련 문제, 예를 들어 항공편 조회나 호텔 예약 등을 처리하는 데 사용되었습니다. 하지만 저는 이것에 더 큰 잠재력이 있다고 생각하여 시간을 들여 '업그레이드'했고, 더욱 강력하고 안전하게 만들었습니다.

간단히 말해, 이 프로젝트는 여러분과 '대화'할 수 있는 AI 고객 서비스입니다. 질문을 하면 단순히 인터넷에서 텍스트를 검색해서 붙여넣어 주는 것이 아니라, 실제 고객 서비스 전문가처럼 사용자의 요구 사항을 이해하고, 다양한 도구(예: 데이터베이스 조회, 정책 확인, 심지어 예약까지)를 호출한 다음, 정확하고 완전한 답변을 제공합니다.

이것이 해결하는 핵심 문제는 **AI 고객 서비스가 어떻게 더 '똑똑'하고, 더 '전문적'이며, 더 '안전'해질 수 있느냐?**입니다.

• '똑똑함(Smart)': 많은 AI 챗봇은 간단한 질문에는 괜찮지만,

'나쁜 질문'에 대한 필터링 부족: 사용자의 입력이 악의적인 '탈옥(Jailbreak)' 시도(예: AI가 모든 규칙을 무시하도록 유도하거나 시스템 프롬프트(System Prompt)를 탐색하려는 시도)인지, 혹은 완전히 관련 없는 '엉뚱한 질문'(예: "홍샤오로우 만드는 법 알려줘")인지 판단할 능력이 없습니다. 이러한 무효한 입력은 시스템을 방해하고 효율성을 떨어뜨리며, 심지어 위험을 초래할 수도 있습니다. 인적 검토(Human Review) 단계의 부재: 사용자가 민감한 작업을 확인해야 하긴 하지만, 기업용 애플리케이션(Enterprise Application) 관점에서는 사용자의 확인만으로는 충분하지 않습니다. 많은 경우, 특히 가치가 높은 작업이 포함될 때는 만전을 기하기 위해 '관리자'가 최종 검토 및 승인을 수행하는 과정이 필요합니다.

위의 두 가지 '안전' 측면의 부족함을 해결하기 위해, 저는 주로 두 가지 측면에서 개선을 진행했습니다.

'안전 가드레일(Security Guardrails)' 설치: 탈옥 방지 가드레일 (Jailbreak Guardrail): 사용자의 질문 후, 메인 어시스턴트(Main Assistant)가 처리하기 전에 전담 AI '안전 검사관'을 추가했습니다. 이 '검사관'은 사용자의 최신 문장을 빠르게 분석하여 탈옥이나 공격 의도가 있는지 판단합니다. 만약 의도가 있다면 시스템은 즉시 차단하고, 사용자에게 "이 질문에는 답변할 수 없습니다"라고 정중하게 알립니다. 관련성 검사 가드레일 (Relevance Guardrail): 이 '검사관'은 또한 사용자의 질문이 우리 고객 서비스 시스템의 '업무 범위'와 관련이 있는지도 판단합니다. 예를 들어, 항공편이나 호텔에 대해 묻는 것은 관련이 있지만, "요리법"을 묻는 것은 관련이 없습니다. 관련 없는 질문에 대해서는 시스템이 이를 기록하거나(또는 안내를 제공하거나) 하되, 정상적인 고객 서비스 흐름을 방해하지 않도록 합니다.

'인적 검토(GoHumanLoop)' 도입: - 모든 '민감한' 작업(예: 항공권 취소, 주문 수정)에 대해, 사용자가 '확인'을 클릭한 후 시스템이 즉시 실행하지 않습니다. 대신 GoHumanLoop라는 프레임워크를 통해 해당 작업 요청을 백엔드 관리자에게 자동으로 전송합니다(예: Feishu를 통해). - 관리자는 사용자가 어떤 작업을 수행하려 하는지 명시된 명확한 알림을 받게 됩니다. 관리자는 이 작업이 합리적인지 판단한 후 '승인' 또는 '거절'을 클릭해야 합니다. 관리자가 승인한 후에만 작업이 실제로 실행됩니다. 이는 '사용자 확인 + 관리자 승인'이라는 이중 보안 장치를 형성하여 시스템의 안전성을 크게 향상시킵니다.

• 모든 '민감한' 작업(예: 항공권 취소, 주문 수정)에 대해, 사용자가 '확인'을 클릭한 후 시스템이 즉시 실행하지 않습니다. 대신 이 작업 요청을 GoHumanLoop라는 프레임워크를 통해 백엔드 관리자에게 자동으로 전송합니다.

이 두 가지 메커니즘을 통해 시스템은 마치 '지능형 문지기'(안전 가드레일)와 '최종 승인관'(인적 검토)을 갖춘 것처럼 입구와 출구 두 단계에서 철저히 관리하며 시스템의 안전과 안정성을 보장합니다.

이 프로젝트의 가치는 안전하고 신뢰할 수 있으며 전문적인 기업용 AI 고객 서비스 시스템을 구축하기 위한 완전한 사고방식과 실천 방법을 제공한다는 점에 있습니다.

개발자에게는:

• 이는 LangGraph와 LangChain을 학습하기 위한 훌륭한 사례이며, 코드를 사용하여 복잡한 멀티 에이전트(Multi-agent) 협업 프로세스를 구축하는 방법을 보여줍니다. - 재사용 가능한 안전 메커니즘 템플릿(안전 가드레일 + 인적 검토)을 제공하여 다른 유사한 AI 애플리케이션에도 적용할 수 있습니다. - RAG, 도구 호출 (Function Calling), 상태 관리 (State Management), 워크플로우 오케스트레이션 (Workflow Orchestration) 등 다양한 핵심 기술을 통합한 훌륭한 종합 실습 프로젝트입니다.

기업 또는 제품 관리자(PM)에게는:

• AI 능력을 추구하면서도 안전성을 희생하지 않는 방법을 명확하게 보여줍니다. - '멀티 에이전트' 아키텍처의 사고방식은 복잡한 의사결정과 교차 도메인 협업이 필요한 다양한 비즈니스 시나리오에 적용될 수 있습니다. - '인적 검토'는 핵심 비즈니스에서 마지막 방어선으로서 필수적이며, 이 프로젝트는 이를 어떻게 자동화하고 프로세스화할 수 있는지에 대한 참고 자료를 제공합니다.

직접 시도해 보세요: 코드는 모두 GitHub에 올려두었습니다. 개발자라면 클론(clone)하여 직접 실행해 보시기를 강력히 권장합니다. 코드 구조가 명확하고 문서도 비교적 잘 갖춰져 있어(최근에 업데이트했습니다), README.md의 단계를 따르면 원활하게 실행할 수 있을 것입니다. 사고방식 이해: 반드시 제 코드를 그대로 복사할 필요는 없지만, 그 안에 담긴 '멀티 에이전트', 'RAG', '안전 가드레일', '인적 검토'의 설계 사고방식은 매우 배울 가치가 있습니다. 이를 이해하면 자신의 프로젝트에 유연하게 적용할 수 있습니다. 개선 사항 고민: 이 프로젝트에는 제가 README에서 언급한 '적응형 RAG (Adaptive RAG)', '메모리 통합 (Memory Integration)' 등 최적화할 수 있는 부분이 아직 많습니다. 이를 시작점으로 삼아 어떻게 하면 더 강력하게 만들 수 있을지 고민해 보세요.

요약하자면, 이 프로젝트는 단순히 '대화할 수 있는' AI가 아니라, 강력하면서도 신뢰할 수 있는 지능형 시스템을 구축하는 방법을 보여주는 모범 사례입니다. 저의 공유가 여러분에게 영감을 줄 수 있기를 바랍니다!