🏢 기업 데이터 연동을 위한 에이전틱 RAG 아키텍처 구축 실무

사내 규정(Markdown), 산업 보고서(PDF), 조직 정보(그래프)를 연동하는 Agentic RAG 시스템을 하루 동안 단계별로 만들어 보는 핸즈온 과정

에이전트 루프는 create_agent 한 줄로 만들어집니다. 이 과정은 그 바깥, 즉 에이전트가 쓰는 도구와 데이터 계층을 설계하고 평가하는 데 집중합니다.

---

🌿 브랜치 안내

💡 미션 중 막히면 instructor 브랜치의 같은 파일과 비교해 보세요: git diff main origin/instructor --

---

🚀 시작하기 (환경 세팅)

1. GitHub Codespaces (권장 · 사전 빌드 Docker 이미지)

Codespaces는 사전 빌드된 Docker 이미지(hukimartia/agentic-rag-lab:latest)로 구동되므로 별도의 패키지 설치가 필요하지 않습니다. (Python 3.12, LangChain/LangGraph, Chroma, GraphRAG, FastMCP, Chainlit, Node.js 22, 한글 폰트/로케일 포함)

1. 리포지토리 상단 [Code] ➔ [Codespaces] ➔ [Create codespace] 로 실습 환경을 생성합니다.
2. 컨테이너가 뜨면 .env.example이 .env로 자동 복사됩니다. (CHAINLIT_AUTH_SECRET, ENTERPRISE_RAG_MCP_TOKEN은 미리 채워져 있습니다.)
3. .env를 열어 API 키를 입력합니다.

   OPENAI_API_KEY=...        # 임베딩 (text-embedding-3-large)
   GOOGLE_API_KEY=...        # 에이전트 LLM (gemini-3.8-flash), GraphRAG
   

2. 로컬 환경 (WSL2 / Linux 수동 설치)

Docker를 쓰지 않는 경우 설치 스크립트를 실행합니다. 한글 폰트/로케일, Python 패키지 설치와 .env 생성이 순서대로 진행됩니다.

bash install/install_all.sh

💡 위키백과 MCP 서버(npx -y wikipedia-mcp)를 쓰려면 로컬에 Node.js 18+ 가 필요합니다.

3. 설치 확인

python app/mcp/test_database.py     # 4대 DB 검색이 모두 ✅로 끝나면 준비 완료

🔍 LangSmith 트레이싱 (선택)

LANGCHAIN_API_KEY=...
LANGCHAIN_TRACING_V2=true
LANGCHAIN_PROJECT=agentic-rag

---

📚 커리큘럼: 노트북 → 미션

학습 흐름은 노트북(개념 학습) → 미션(서비스 코드 실습) 입니다.

notebooks/0_Template.ipynb는 노트북 공통 환경 설정(루트 경로, .env, nest_asyncio) 템플릿입니다. 미션에서 직접 작성하는 파일은 위 브랜치 안내 표를 참고하세요.

---

🖥️ 서비스 실행

# 터미널 1: FastAPI 에이전트 서버 (8000)
python app/server.py

# 터미널 2: Chainlit 웹 UI (8080) → 로그인 user / 1234
chainlit run app/chainlit_ui.py --port 8080

# 터미널 3: Enterprise RAG MCP 서버 (8010, skill_rag_agent용 · Mission 03 완료 후)
python app/mcp/enterprise_rag_server.py

평가 실행

python -m app.eval.rag_eval --agent tool_rag_agent
python -m app.eval.rag_eval --agent tool_rag_agent --compare artifacts/eval_runs/.json

---

🤖 에이전트

두 RAG 에이전트는 같은 ReAct 루프와 같은 검색 로직을 쓰고, 도구를 연결하는 방식만 다릅니다.

---

🗄️ 데이터베이스 (app/database/)

사전 구축된 DB가 함께 배포되므로 다시 빌드할 필요가 없습니다. 빌드 옵션은 python app/mcp/build_database.py --help를 참고하세요.

# 신규 문서를 사내 규정에 추가 인덱싱 (24 → 30청크)
python app/mcp/build_database.py --targets policy --extra-docs data/new_documents

# 사내 규정만 원래 상태로 되돌리기 (24청크)
python app/mcp/build_database.py --targets policy

# 사전 구축본 전체로 되돌리기
git checkout -- app/database

---

🔌 MCP 서버 레지스트리 (skills/mcp/references/mcp_servers.json)

python skills/mcp/scripts/list_tools.py --url "npx -y wikipedia-mcp"
python skills/mcp/scripts/list_tools.py --url http://localhost:8010/mcp --token-env ENTERPRISE_RAG_MCP_TOKEN

🔐 인증

app/mcp/enterprise_rag_server.py는 .env의 ENTERPRISE_RAG_MCP_TOKEN과 일치하는 Bearer 토큰만 허용합니다. 스킬 CLI는 토큰 값 대신 환경 변수 이름을 받으므로(--token-env ENTERPRISE_RAG_MCP_TOKEN), 토큰이 에이전트의 프롬프트나 대화 기록에 남지 않습니다.

---

📂 프로젝트 구조

├── app/
│   ├── agents/
│   │   ├── chatbot.py
│   │   ├── tool_rag_agent/      # agent.py, prompt.py, tools.py
│   │   └── skill_rag_agent/     # agent.py, prompt.py, tools.py
│   ├── mcp/
│   │   ├── enterprise_rag_server.py   # Bearer 인증 FastMCP 서버
│   │   ├── build_database.py          # 인덱싱 파이프라인으로 DB 빌드
│   │   └── test_database.py           # 4대 DB 검색 검증
│   ├── eval/rag_eval.py         # 오프라인 평가 하네스 러너
│   ├── middleware/              # 로깅, 스킬 카탈로그, RAG 평가 하네스 미들웨어
│   ├── tools/                   # 범용 도구 (file_read, bash_command 등)
│   ├── utils/                   # 모델 팩토리, 메시지/DB 유틸
│   ├── database/                # 사전 구축된 4대 DB
│   ├── server.py                # FastAPI 에이전트 서버
│   └── chainlit_ui.py           # Chainlit 웹 UI
├── rag/                         # 공용 RAG 모듈: preprocessing · indexing · retrieval · graph
├── skills/mcp/                  # MCP CLI 스킬 (SKILL.md, references/mcp_servers.json, scripts/)
├── data/                        # 원천 문서, 골든 평가셋, 미션용 새 문서
├── notebooks/                   # 교시별 실습 노트북
├── missions/                    # 교시별 미션 가이드
├── install/                     # 설치 스크립트, requirements.txt
├── Dockerfile                   # Codespaces 사전 빌드 이미지 정의
└── .devcontainer/               # Codespaces 설정 (이미지, 포트 포워딩)

---

🔧 트러블슈팅