MoveMate Agent

LangGraph 기반 AI 이사 행정 · 주거 정책 멀티 에이전트.
Supervisor가 질문을 분석해 세 전문 에이전트로 라우팅하고, 복합 질문은 결과를 하나의 답변으로 합성한다.

---

아키텍처

사용자 질문
│
▼
[supervisor_node] ─ 키워드 매칭 → LLM 폴백으로 라우팅 결정
│
├─ legal ──▶ [legal_agent_node] 이사 행정 하위 그래프
│ └─ classify → direct_tool / react_agent
│
├─ policy ──▶ [policy_agent_node] 주거 정책 RAG 에이전트
│ └─ housing_policy_rag (9-node LangGraph)
│
├─ schedule ──▶ [schedule_agent_node] 이사 일정 ReAct 에이전트
│ └─ Google Calendar MCP 연동
│
└─ both ──▶ legal + policy 병렬 실행
│
▼
[synthesize_node] ─ 단일 답변 통과 / 복합 시 LLM 합성
│
▼
최종 답변

라우팅 규칙

route	조건	동작
legal	이사 행정 · 법령 키워드	이사 행정 에이전트
policy	청년 · 지원금 · 대출 키워드	주거 정책 RAG 에이전트
schedule	일정 · 체크리스트 · D-Day 키워드	이사 일정 에이전트
both	두 영역 키워드 혼재	legal + policy 병렬 실행 후 합성

---

에이전트 상세

1. legal_agent — 이사 행정 · 법령

사용자 의도를 분류한 후 ChromaDB에서 관련 문서를 검색해 LLM이 답변을 생성한다.

인텐트	설명	Tool
legal_qa	법령 · 개념 질문	search_legal_info
admin_procedure	행정 절차 방법	search_admin_procedure + search_legal_info (병합)
checklist	체크리스트 요청	get_checklist
region_price	지역 시세 조회	get_region_price
complex / unknown	복합 · 미분류 질문	ReAct Agent

ChromaDB 컬렉션 (moving_helper_db_v2/)

컬렉션	내용	청크 수
legal_knowledge	주택임대차보호법 · 법령 가이드	363
admin_procedures	이사 단계별 행정 절차	24
checklist_items	이사 체크리스트	12

임베딩 모델: jhgan/ko-sroberta-multitask

---

2. policy_agent — 주거 정책 RAG

housing_policy_rag/ 서브 패키지를 직접 임포트해 사용한다.
9개 노드 LangGraph 파이프라인으로 사용자 프로필을 추출하고 정책을 검색·재랭킹해 답변을 생성한다.

profile_extract → intent_classify
→ (clarify | region_resolve | follow_up)
→ rag_retrieve → rerank_filter → prepare_policies → generate_answer

ChromaDB (housing_policy_rag/vectorstore/chroma_db_new/)
임베딩 모델: sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2
재랭킹 모델: BAAI/bge-reranker-base
LLM: OpenAI gpt-4o-mini → 쿼터 초과 시 Groq llama-3.3-70b-versatile 자동 폴백

---

3. schedule_agent — 이사 일정

Google Calendar MCP를 연동해 캘린더를 조회하고 최적 일정을 제안한다.

Tool	역할
get_schedule_tool	이사 날짜 기반 체크리스트 마감일 계산
get_google_calendar_events	구글 캘린더 일정 조회
suggest_schedule_tool	바쁜 날 피해 최적 일정 제안
create_calendar_event	구글 캘린더에 일정 등록

---

프로젝트 구조

movemate_agent/
├── main.py # CLI 진입점
├── .env # API 키 설정 (git 제외)
├── .env.template # 환경변수 예시
├── requirements.txt
│
├── config/
│ ├── llm_factory.py # LLM 제공자 팩토리 (get_llm())
│ ├── mcp_client.py # Google Calendar MCP 설정
│ ├── prompts.py # 시스템 · 라우팅 · 합성 프롬프트
│ └── settings.py / constants.py
│
├── state/
│ ├── schema.py # MovingAgentState (이사 행정)
│ └── supervisor_schema.py # SupervisorState (상위 그래프)
│
├── graph/
│ ├── supervisor_graph.py # 상위 Supervisor StateGraph
│ ├── main_graph.py # 이사 행정 하위 그래프
│ ├── react_graph.py # ReAct 에이전트
│ └── nodes/
│ ├── supervisor_node.py # 라우팅
│ ├── legal_agent_node.py # 이사 행정 에이전트 래퍼
│ ├── policy_agent_node.py # 정책 RAG 에이전트 래퍼
│ ├── schedule_agent_node.py # 일정 에이전트 (ReAct)
│ ├── synthesize_node.py # 복합 답변 합성
│ ├── classify_node.py # 인텐트 분류
│ ├── direct_tool_node.py # Tool 검색 + LLM 합성
│ └── react_agent_node.py
│
├── tools/
│ ├── search_legal_info.py
│ ├── search_admin_procedure.py
│ ├── get_checklist.py
│ ├── get_region_price.py
│ └── schedule/
│ ├── get_calendar.py # 구글 캘린더 조회 (MCP)
│ ├── create_calendar.py # 일정 등록
│ ├── get_schedule.py # 마감일 계산
│ └── suggest_schedule.py # 최적 일정 제안
│
├── db/
│ ├── client.py # ChromaDB 연결
│ ├── collections/ # 컬렉션별 쿼리 함수
│ └── utils/
│
├── intent/
│ ├── rules.py # IntentType Enum + 키워드 규칙
│ ├── classifier.py # 규칙 기반 분류
│ └── llm_fallback.py
│
├── housing_policy_rag/ # 주거 정책 RAG 서브 패키지
│ ├── agent/ # LangGraph 파이프라인
│ │ ├── graph.py # run_agent() 진입점
│ │ ├── llm_helper.py # OpenAI → Groq 폴백 헬퍼
│ │ └── nodes/ # 9개 파이프라인 노드
│ ├── src/ # RAG 인프라 (벡터스토어, 임베딩)
│ └── main.py # 독립 실행 / 벡터스토어 빌드
│
├── moving_helper_db_v2/ # 이사 행정 ChromaDB (git 제외)
└── tests/

---

설치

1. 가상환경 생성

python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS / Linuxsource .venv/bin/activate

2. 패키지 설치

pip install -r requirements.txt

3. 환경변수 설정

.env.template을 복사해 .env를 만들고 키를 채운다.

cp .env.template .env

# ── 메인 에이전트 LLM ───────────────────────────────────────────# 사용할 제공자: groq | openai | anthropicLLM_PROVIDER=groqLLM_MODEL=# 비워두면 제공자별 기본 모델 적용GROQ_API_KEY=your_groq_api_keyOPENAI_API_KEY=# 정책 에이전트 1순위 LLM (없으면 Groq 폴백)ANTHROPIC_API_KEY=# ── 정책 에이전트 (housing_policy_rag) ──────────────────────────GOOGLE_API_KEY=# Gemini 사용 시 (선택)VECTORSTORE_PATH=housing_policy_rag/vectorstore/chroma_db_newDATA_PATH=housing_policy_rag/data# ── Google Calendar MCP ─────────────────────────────────────────GOOGLE_CLIENT_ID=your_client_idGOOGLE_CLIENT_SECRET=your_client_secret

제공자별 기본 모델

제공자	기본 모델
groq	llama-3.3-70b-versatile
openai	gpt-4o-mini
anthropic	claude-haiku-4-5-20251001

---

ChromaDB 구축

이사 행정 DB (moving_helper_db_v2/)

이미 커밋된 DB를 그대로 사용한다. 재구축이 필요하면:

python checklist_seed.py

주거 정책 DB (housing_policy_rag/vectorstore/)

팀원에게 받은 ChromaDB를 housing_policy_rag/vectorstore/chroma_db_new/에 복사하거나,
샘플 데이터로 직접 구축한다.

cd housing_policy_rag
python main.py build --use-sample

---

실행

python main.py

====================================
AI 이사 행정 · 주거 정책 에이전트
====================================
질문을 입력하세요. 종료하려면 'exit'를 입력하세요.
질문: 확정일자란 뭐야?
답변: 확정일자는 주택임대차계약서가 실제로 그 날에 존재했음을 공적으로 증명하는 날짜입니다 ...
질문: 서울 청년 전세 지원 정책 알려줘
답변: 서울 청년 전세 지원 정책으로는 청년 버팀목 전세자금 대출과 ...
질문: 8월 15일 이사인데 일정 짜줘
답변: 이사 날짜 2026-08-15 기준으로 체크리스트를 정리했습니다 ...

---

테스트

# 통합 E2E 테스트 (세 에이전트 + 라우팅, 22개 케이스)$env:PYTHONUTF8 = "1"
.venv\Scripts\python.exe _test_e2e.py
# 단위 테스트
pytest tests/ -v

---

기술 스택

구분	내용
에이전트 프레임워크	LangGraph 1.x (Supervisor + 하위 그래프)
LLM (메인)	Groq / OpenAI / Anthropic (.env로 전환)
LLM (정책 에이전트)	OpenAI gpt-4o-mini → Groq llama-3.3-70b 자동 폴백
벡터 DB	ChromaDB (PersistentClient)
임베딩 (이사 행정)	jhgan/ko-sroberta-multitask
임베딩 (정책)	paraphrase-multilingual-MiniLM-L12-v2
재랭킹 (정책)	BAAI/bge-reranker-base (CrossEncoder)
캘린더 연동	Google Calendar MCP (@cocal/google-calendar-mcp)
언어	Python 3.11+

---

유의 사항

• moving_helper_db_v2/ 내부 파일은 수동으로 수정하지 않는다
• housing_policy_rag/vectorstore/ 및 housing_policy_rag/data/는 .gitignore 처리됨 — 팀원에게 별도 수령
• 메타데이터 필드명은 반드시 move_stage를 사용한다 (moving_stage 사용 금지)
• Google Calendar 연동은 gcp-oauth.keys.json OAuth 키 파일이 필요하다 (git 제외)