[RFC] 에이전틱 AI 시스템 고도화 — 프레임워크·API·통합 종합 기술 검토

[siuJang]

1. 배경 및 목표

GovOn 프로젝트를 에이전틱 AI 시스템으로 고도화하기 위한 기술 검토 결과입니다.

추가 목표 기능

1. 공문서 자동 생성 — 공공데이터포털 데이터셋 기반 두문/본문/결문 구조의 행정 문서 생성
2. LLM 도구 호출(Tool Calling) — 공공 API를 LLM 도구로 래핑하여 에이전트가 자율적으로 호출
3. 에이전틱 오케스트레이션 — 사용자 쿼리 의도 파악 → 도구 선택 → 실행 → 결과 종합

---

2. 현재 GovOn 아키텍처 요약

구성요소	현재 상태
모델	EXAONE-Deep-7.8B (QLoRA → AWQ 양자화)
서빙	vLLM AsyncLLMEngine + FastAPI
RAG	FAISS + BM25 하이브리드 검색 (RRF 퓨전)
에이전트	AgentManager (classifier/generator/retriever 3개 페르소나)
보안	API Key, Rate Limiting, Prompt Injection 방어, PII 마스킹
DB	PostgreSQL + SQLAlchemy + Alembic
Tool Calling	❌ 미지원 (프롬프트 엔지니어링 + JSON 파싱으로 우회 중)

핵심 한계: EXAONE-Deep-7.8B의 Tool Calling 미지원

EXAONE-Deep-7.8B은 추론(reasoning) 특화 모델로, <thought> 태그 기반 사고 과정을 출력합니다.
네이티브 function calling/tool calling을 지원하지 않습니다.

반면, EXAONE 4.0 시리즈(1.2B, 32B)는 네이티브 tool calling을 지원하며,
vLLM에서 --enable-auto-tool-choice --tool-call-parser hermes 옵션으로 사용 가능합니다.

이것이 프레임워크 선택의 가장 중요한 제약 조건입니다.

---

3. 활용 가능한 공공데이터 API

3-1. 행정표준코드 API (자동 승인, 일 10,000건)

API	Base URL	용도
기관코드	apis.data.go.kr/1741000/StanOrgCd2	발신/수신 기관 식별, 공문서 두문/결문
법정동코드	apis.data.go.kr/1741000/StanReginCd	관할구역 판별, 주소 정규화
도로명주소	apis.data.go.kr (15057017)	실시간 주소 검색, 우편번호

3-2. 민원빅데이터 분석정보 API (개발 100건, 운영 확장 필요)

엔드포인트	기능	에이전트 활용 시나리오
minSimilarInfo5	유사 민원 사례 검색	답변 생성 전 선례 참조
minStaticsInfo5	민원 통계 (일/월/년)	보고서에 통계 근거 삽입
minRisingKeyword5	급상승 키워드	트렌드 파악
minClfcInfo5	ML 기반 민원 분류 체계	카테고리 매핑 검증
minAnalsRptstInfo5	분석 보고서	주간/월간 리포트 참조

3-3. 2025 신규 API (2개 엔드포인트)

엔드포인트	기능
minPrcsInstInfo	키워드별 민원 처리 기관 조회
minActsSubordinateStatutesInfo	키워드별 관련 법령 조회

제약사항

• 모든 API는 serviceKey 필요 (data.go.kr 회원가입 후 발급)
• 민원빅데이터 API는 CC BY-NC 2.0 (비상업 용도)
• 개발 단계 100건 제한 → 운영 전환 시 사용 사례 제출 필요

---

4. 에이전틱 프레임워크 비교 분석

4-1. 프레임워크별 평가

프레임워크	vLLM 호환	Tool Calling	프로덕션 성숙도	학습 곡선	우리 적합도
LangGraph	✅ OpenAI 호환 엔드포인트	✅ 네이티브 + 프롬프트 기반	⭐⭐⭐⭐⭐ (1.0 출시)	중간	⭐⭐⭐⭐
Smolagents	✅ VLLMModel 클래스	✅ 코드 에이전트 방식	⭐⭐⭐	낮음	⭐⭐⭐⭐⭐
LlamaIndex	✅	✅	⭐⭐⭐⭐	중간	⭐⭐⭐
CrewAI	⚠️ 간접	✅	⭐⭐⭐	낮음	⭐⭐
커스텀 ReAct	✅ 직접 제어	직접 구현	직접 관리	높음	⭐⭐⭐

4-2. 상세 분석

LangGraph (추천도: ⭐⭐⭐⭐)

장점:

• 2025년 10월 1.0 정식 출시, 프로덕션 검증 (Klarna, Replit 등)
• StateGraph 기반 명시적 워크플로우 정의 (노드/엣지/조건 분기)
• vLLM의 OpenAI 호환 API를 ChatOpenAI(base_url="http://localhost:8000/v1")로 바로 연결
• FastAPI 통합 가이드/템플릿 풍부 (SSE 스트리밍 포함)
• Human-in-the-loop, 체크포인팅, 관찰성(Langfuse) 내장

단점:

• LangChain 생태계 의존성 (langchain-core, langchain-openai 등)
• EXAONE-Deep-7.8B이 네이티브 tool calling 미지원 → 프롬프트 기반 tool calling 구현 필요
• 추상화 레이어가 많아 디버깅 시 복잡

GovOn 통합 방식:

from langchain_openai import ChatOpenAI
from langgraph.graph import StateGraph

# vLLM 서버를 OpenAI 호환 엔드포인트로 연결
llm = ChatOpenAI(
    base_url="http://localhost:8000/v1",
    api_key="govon-api-key",
    model="EXAONE-Deep-7.8B"
)

Smolagents (추천도: ⭐⭐⭐⭐⭐)

장점:

• HuggingFace 공식 프레임워크, 코어 로직 ~1,000줄 — 경량
• smolagents[vllm] 설치로 VLLMModel 네이티브 지원 (v1.11.0+)
• 코드 에이전트 방식 — 도구를 Python 코드로 호출 (JSON function calling 불필요)
• 네이티브 tool calling이 없는 모델에서도 프롬프트 기반으로 도구 호출 가능
• 26,000+ GitHub Stars, 활발한 유지보수 (2026.03 최신 커밋)

단점:

• 복잡한 멀티스텝 워크플로우 정의는 LangGraph보다 약함
• 체크포인팅, Human-in-the-loop 등 프로덕션 기능은 직접 구현 필요
• 상대적으로 새로운 프레임워크

GovOn 통합 방식:

from smolagents import CodeAgent, Tool, VLLMModel

model = VLLMModel(
    model_id="EXAONE-Deep-7.8B",
    url="http://localhost:8000/v1"
)

# 도구 정의 예시
class LookupOrgCode(Tool):
    name = "lookup_org_code"
    description = "행정표준코드 기관코드를 조회합니다"
    inputs = {"org_name": {"type": "string", "description": "기관명"}}
    output_type = "string"

    def forward(self, org_name: str) -> str:
        # API 호출 로직
        ...

agent = CodeAgent(tools=[LookupOrgCode()], model=model)
result = agent.run("서울시 강남구청의 기관코드를 알려줘")

커스텀 ReAct (추천도: ⭐⭐⭐)

장점:

• 외부 의존성 없음, 기존 vLLMEngineManager 위에 직접 구축
• EXAONE 채팅 템플릿과 완벽한 호환
• 최대 유연성, 성능 오버헤드 최소

단점:

• 모든 것을 직접 구현 (파싱, 에러 핸들링, 재시도, 상태 관리)
• 유지보수 부담 큼
• 커뮤니티/생태계 활용 불가

---

5. 핵심 의사결정: EXAONE-Deep vs EXAONE 4.0

현재 가장 큰 기술적 분기점입니다:

옵션 A: EXAONE-Deep-7.8B 유지 + 프롬프트 기반 Tool Calling

[장점] 기존 파인튜닝/양자화 파이프라인 재활용
[장점] 추론 능력 우수 (MATH 94.8%, AIME 70.0%)
[단점] Tool calling을 프롬프트 엔지니어링으로 구현해야 함
[단점] JSON 파싱 불안정 → structured output 보장 어려움
[적합 프레임워크] Smolagents (코드 에이전트라 JSON 파싱 불필요)

옵션 B: EXAONE 4.0으로 모델 업그레이드

[장점] 네이티브 tool calling 지원
[장점] vLLM --enable-auto-tool-choice로 바로 사용
[장점] LangGraph 등 모든 프레임워크와 원활한 통합
[단점] 재파인튜닝 필요 (민원 도메인)
[단점] 4.0-1.2B는 작고, 4.0-32B는 GPU 요구사항 높음
[적합 프레임워크] LangGraph (네이티브 tool calling 활용)

옵션 C: 하이브리드 (추천)

EXAONE-Deep-7.8B → 추론/생성 담당 (기존 유지)
EXAONE 4.0-1.2B  → 에이전트 라우팅/도구 호출 담당 (신규 추가)

[장점] 각 모델의 장점 활용
[장점] 1.2B는 가벼워서 같은 GPU에서 동시 서빙 가능
[단점] 듀얼 모델 관리 복잡성

---

6. LangGraph 바로 적용할 수 있는가?

결론: 조건부 YES

바로 가능한 것

• vLLM 서버가 OpenAI 호환 API 제공 → LangGraph ChatOpenAI로 바로 연결
• 기존 FastAPI 앱에 LangGraph 워크플로우 엔드포인트 추가 가능
• create_react_agent()로 기본 ReAct 에이전트 즉시 생성

추가 작업 필요한 것

• EXAONE-Deep-7.8B은 네이티브 tool calling 미지원 → 커스텀 tool calling 파서 구현 필요
  • vLLM의 --tool-call-parser에 EXAONE-Deep용 커스텀 파서 등록
  • 또는 프롬프트에 tool calling 포맷을 명시하고 응답에서 JSON 추출
• LangChain 의존성 추가 (langchain-core, langchain-openai, langgraph)
• 기존 AgentManager와의 역할 분담 정리

대안: Smolagents가 더 쉬울 수 있음

• 코드 에이전트 방식이라 네이티브 tool calling 없이도 작동
• VLLMModel 클래스로 직접 연결
• 의존성이 가볍고 기존 코드와 충돌 적음

---

7. 기존 프로젝트와의 통합 가능성 검토

7-1. 충돌 없이 통합 가능한 부분

기존 모듈	통합 방식
api_server.py	새 엔드포인트 추가 (/v1/agent/run, /v1/document/generate)
schemas.py	도구 요청/응답 Pydantic 모델 추가
agent_manager.py	새 페르소나 추가 (document_generator, tool_router)
retriever.py + hybrid_search.py	에이전트 도구로 래핑
db/models.py	DocumentSource 모델 확장 (공문서 유형 추가)

7-2. 제안 디렉토리 구조

src/
├── inference/           # 기존 유지
│   ├── api_server.py
│   ├── ...
│   └── tools/           # 🆕 LLM 도구 모듈
│       ├── __init__.py
│       ├── registry.py          # 도구 레지스트리
│       ├── org_code.py          # 기관코드 조회
│       ├── district_code.py     # 법정동코드 조회
│       ├── complaint_search.py  # 민원 유사사례 검색 (외부 API)
│       ├── statute_search.py    # 관련 법령 조회
│       └── document_gen.py      # 공문서 생성
│
├── agent/               # 🆕 에이전틱 시스템
│   ├── __init__.py
│   ├── orchestrator.py  # 에이전트 오케스트레이터
│   ├── planner.py       # 작업 계획 수립
│   └── executor.py      # 도구 실행기
│
└── ...

7-3. 의존성 영향

# 추가 필요한 패키지
# 옵션 1: LangGraph
langgraph >= 0.4.0
langchain-core >= 0.3.0
langchain-openai >= 0.3.0

# 옵션 2: Smolagents (더 가벼움)
smolagents[vllm] >= 1.11.0

# 공통
httpx >= 0.27.0     # 외부 API 비동기 호출 (기존 requests 대체)

7-4. 리스크 및 대응

리스크	심각도	대응 방안
EXAONE-Deep의 tool calling 불안정	높음	Smolagents 코드 에이전트 또는 EXAONE 4.0 도입 검토
외부 API 장애 시 에이전트 실패	중간	타임아웃/폴백 전략, 캐싱 레이어
vLLM 메모리 부족 (듀얼 모델)	중간	EXAONE 4.0-1.2B는 AWQ 양자화 시 ~1.5GB
LangChain 의존성 버전 충돌	낮음	버전 핀닝, 가상환경 분리

---

8. 최종 추천 로드맵

Phase 1: 도구 레이어 구축 (1~2주)

• src/inference/tools/ 디렉토리 생성
• 행정표준코드 API 클라이언트 구현 (기관코드, 법정동코드)
• 민원빅데이터 API 클라이언트 구현 (유사사례, 통계, 법령)
• data.go.kr API 키 발급 및 환경변수 설정
• 각 도구의 단위 테스트 작성

Phase 2: 에이전트 프레임워크 도입 (1~2주)

• Smolagents 우선 도입 (EXAONE-Deep과 호환성 최고)
• 기존 RAG 검색을 Smolagents Tool로 래핑
• 새 공공 API 도구를 Tool로 등록
• 에이전트 오케스트레이터 구현 (의도 파악 → 도구 선택 → 실행)
• /v1/agent/run 엔드포인트 추가

Phase 3: 공문서 생성 (1~2주)

• 공문서 템플릿 정의 (기안문, 시행문, 회신문, 공고문)
• 문서 생성 도구 구현 (두문/본문/결문 자동 구성)
• 기관코드 + 유사사례 + 법령 → 문서 생성 파이프라인 연결
• /v1/document/generate 엔드포인트 추가

Phase 4: 고도화 (선택)

• EXAONE 4.0-1.2B 라우터 모델 도입 검토
• LangGraph로 복잡한 멀티스텝 워크플로우 구현
• Human-in-the-loop 검토/승인 플로우
• 공문서 HWP/PDF 출력 지원

---

9. 참고 자료

• Building High-Performance Agentic AI with vLLM and LangGraph
• LangGraph + vLLM Discussion
• LangGraph 1.0 Released
• vLLM Tool Calling Docs
• vLLM Structured Outputs
• Smolagents + vLLM 지원
• Smolagents GitHub
• EXAONE-Deep-7.8B
• EXAONE 4.0 (Tool Calling 지원)
• FastAPI + LangGraph Template
• 민원빅데이터 분석정보 API
• 행정표준코드 기관코드 API
• 행정표준코드 법정동코드 API

[umyunsang]

langgraph 사용을 위해 하이브리드 방식으로 진행하고 #402 우리 로드맵의 기존 작업 테스크를 확인하여 수정이 필요한 테스크 이슈는 수정해주고 추가할 테스크 이슈는 추가해줘

[umyunsang]

이작업 내가 할게