시리즈: DevDocAI 구축하기 — 프로덕션급 멀티 에이전트 LangGraph 시스템

파트 2 — LangGraph 코어, Human-in-the-Loop 워크플로우, 에이전트(Agents) 및 RAG

요약 (Recap)

파트 1에서는 DevDocAI의 기반을 구축했습니다:

• FastAPI 백엔드
• PostgreSQL 데이터베이스
• JWT 인증
• GitHub OAuth
• GitHub 도구를 위한 MCP 서버
• 깔끔한 계층형 아키텍처 (Clean layered architecture)

그 시점에는 인프라는 준비되었지만, 실제 AI 시스템은 아직 존재하지 않았습니다.

이번 단계에서 그것이 바뀝니다.

이 글에서는 DevDocAI가 마침내 LangGraph로 구동되는 실제 멀티 에이전트 시스템이 되는 **3단계(Phase 3)와 4단계(Phase 4)**를 다룹니다.

이번 단계에서 구축한 것

목표는 간단했습니다:

GitHub 저장소를 가져와 오케스트레이션된 AI 워크플로우를 통해 살아있는 문서로 변환하는 것.

이를 실현하기 위해 다음을 구축했습니다:

3단계 — LangGraph 코어

• 상태 관리 (State Management)
• 워크플로우 파이프라인 (Workflow Pipeline)
• Human-in-the-Loop (HITL)
• PostgreSQL 체크포인팅 (Checkpointing)
• 조건부 라우팅 (Conditional Routing)

4단계 — 에이전트(Agents) 및 RAG

• AST 기반 코드 파서 에이전트 (AST-based Code Parser Agent)
• 문서 생성 에이전트 (Documentation Generator Agent)
• Brave 리서처 에이전트 (Brave Researcher Agent)
• 문서 발행 에이전트 (Documentation Publisher Agent)
• Qdrant 벡터 스토어 (Vector Store)
• 임베딩 파이프라인 (Embeddings Pipeline)
• 온보딩 챗봇 (Onboarding Chatbot)

이 단계에서 DevDocAI는 "백엔드 프로젝트"에서 "실제 AI 제품"으로 진화했습니다.

업데이트된 워크플로우

전체 파이프라인은 이제 다음과 같습니다:

START
  ↓
codebase_parser
...

모든 노드(node)는 특정 작업을 수행하고 공유된 그래프 상태(graph state)를 통해 다음 노드로 정보를 전달합니다.

3단계 — LangGraph 코어

에이전트를 구축하기 전에 신뢰할 수 있는 워크플로우 엔진이 필요했습니다.

여기에서 LangGraph가 등장합니다.

단순한 체인(chain)과 달리, LangGraph는 다음을 가능하게 합니다:

• 상태 유지 실행 (Stateful execution)
• 체크포인팅 (Checkpointing)
• 인간 승인 워크플로우 (Human approval workflows)
• 조건부 라우팅 (Conditional routing)
• 중단 후 재개 (Resume after interruption)

이는 프로덕션 문서 시스템에 정확히 필요한 기능들입니다.

상태 관리 (State Management)

가장 먼저 구축한 것은 중앙 상태 객체(central state object)였습니다.

그래프 내의 모든 에이전트는 동일한 상태를 읽고 씁니다.

class DevDocState(TypedDict):
    user_id: str
    repo_full_name: str
...

이것을 전체 워크플로우 (workflow)의 메모리라고 생각하세요.

에이전트 (agents) 사이에 수십 개의 변수를 전달하는 대신, 모든 것이 하나의 구조화된 상태 (structured state)를 통해 흐릅니다.

이를 통해 디버깅 (debugging)이 훨씬 쉬워집니다.

파이프라인 구축하기 (Building the Pipeline)

상태가 정의된 후, 저는 그래프 (graph) 자체를 생성했습니다.

START
  ↓
code_parser_node
...

각 노드 (node)는 하나의 책임만을 수행합니다.

코드 파서 노드 (Code Parser Node)

저장소를 읽고 코드 구조를 분석합니다.

문서 생성 노드 (Documentation Generator Node)

파싱된 출력물을 사용하여 문서를 생성합니다.

HITL 노드

실행을 일시 중단하고 인간의 결정을 기다립니다.

게시 노드 (Publisher Node)

승인된 문서를 게시합니다.

이러한 분리를 통해 그래프를 모듈화 (modular)하고 확장하기 쉽게 유지할 수 있습니다.

Human-in-the-Loop (HITL)

이 부분은 이 프로젝트에서 가장 흥미로운 부분 중 하나였습니다.

저는 문서를 프로덕션 (production)에 자동으로 푸시하는 AI를 원하지 않았습니다.

개발자에게는 통제권이 필요합니다.

그래서 그래프는 게시하기 전에 일시 중단됩니다.

Generated Docs
      ↓
    Review
...

워크플로우는 말 그대로 개발자의 결정을 기다립니다.

이것은 프롬프트 기반 (prompt-based)의 승인이 아닙니다.

이것은 실제 워크플로우 오케스트레이션 (workflow orchestration)입니다.

그래프 실행은 중단되었다가 사용자 입력에 따라 나중에 재개됩니다.

PostgreSQL 체크포인팅 (PostgreSQL Checkpointing)

상태가 사라진다면 일시 중단된 워크플로우는 무용지물입니다.

그렇기 때문에 저는 체크포인트 지속성 (checkpoint persistence)을 구현했습니다.

전체 그래프 상태는 PostgreSQL에 저장됩니다.

checkpoint -> database
resume -> restore state
continue execution

장점:

• 워크플로우가 서버 재시작 후에도 유지됨
• 장시간 실행되는 작업이 가능해짐
• 몇 시간 뒤에도 인간의 승인이 가능함
• 완전한 감사 가능성 (auditability)

이것이 LangGraph를 선택한 가장 큰 장점 중 하나였습니다.

조건부 라우팅 (Conditional Routing)

검토 후에 그래프는 결정을 내립니다.

def should_publish(state):
    if state["review_status"] == "approved":
        return "publish"
...

그래프는 실행 경로를 동적으로 라우팅 (routes)합니다.

Review
   ↓
Approved?
...

단순한 아이디어입니다.

하지만 프로덕션 워크플로우 (production workflows)에서는 매우 강력합니다.

4단계 — 에이전트 (Agents) 구축하기

그래프가 준비되었으므로, 이제 지능 계층 (intelligence layer)을 구축할 차례입니다.

저는 네 개의 특화된 에이전트 (agents)를 만들었습니다.

각 에이전트는 특정 문제를 해결합니다.

에이전트 1 — 코드베이스 파서 (Codebase Parser)

이 에이전트는 저장소 (repository)를 이해하는 역할을 담당합니다.

소스 코드를 단순한 텍스트로 취급하는 대신, Python의 AST (Abstract Syntax Tree)를 사용하여 코드를 분석합니다.

추출 항목

• 함수 (Functions)
• 클래스 (Classes)
• 임포트 (Imports)
• 모듈 (Modules)
• 의존성 (Dependencies)
• 문서화 패턴 (Documentation patterns)

예시:

def process_payment(amount):
    pass

파서는 다음을 이해합니다:

• 함수 이름 (Function name)
• 매개변수 (Parameters)
• 관계 (Relationships)
• 의존성 (Dependencies)

단순한 원시 텍스트가 아닙니다.

실제 코드 구조 (code structure)입니다.

이것이 문서 생성의 토대가 됩니다.

에이전트 2 — 문서 생성기 (Documentation Generator)

파싱 (parsing) 후의 다음 과제는 코드를 유용한 문서로 변환하는 것입니다.

이 에이전트는 구조화된 정보를 가져와 문서를 생성합니다.

주요 기능은 다음과 같습니다:

• Markdown 생성
• HTML 생성
• 함수 설명
• 사용 예시 (Usage examples)
• API 문서화
• 다양한 문서 스타일 지원

Input:
Parsed AST Structure

...

이것이 DevDocAI의 핵심 가치 제안 (value proposition)입니다.

에이전트 3 — Brave 리서처 (Brave Researcher)

코드만으로 생성된 문서는 종종 불완전합니다.

라이브러리 (libraries), 프레임워크 (frameworks) 및 외부 도구들에 대한 컨텍스트 (context)도 필요합니다.

이를 해결하기 위해, 저는 Brave 리서처를 구축했습니다.

이 에이전트는 Brave Search API를 사용하여 추가 정보를 수집합니다.

예시:

• 라이브러리 설명
• 프레임워크 문서
• 베스트 프랙티스 (Best practices)
• 외부 참조 (External references)

이를 통해 코드 분석만 할 때보다 더 풍부한 문서를 만들어냅니다.

에이전트 4 — 문서 퍼블리셔 (Documentation Publisher)

문서를 생성하는 것만으로는 충분하지 않습니다.

문서는 배포되어야 합니다.

퍼블리셔 에이전트가 그 책임을 맡습니다.

지원되는 대상은 다음과 같습니다:

• GitHub Wiki
• README 생성
• 파일 저장소
• 버전 관리되는 문서 (Versioned documentation)

시스템의 나머지 부분은 문서가 어디로 가는지 신경 쓰지 않습니다.

발행기(Publisher)가 그 부분을 추상화하여 처리합니다.

Qdrant를 이용한 RAG 추가

다음 과제는 온보딩(Onboarding)이었습니다.

새로운 엔지니어가 프로젝트에 합류한다고 상상해 보세요.

수백 개의 파일을 읽는 대신, 다음과 같이 질문할 수 있어야 합니다.

인증 흐름(Authentication flow)은 어떻게 되나요?

또는

어떤 서비스가 결제 처리(Payment processing)를 담당하나요?

이를 가능하게 하기 위해, 검색 증강 생성 (RAG, Retrieval-Augmented Generation)을 추가했습니다.

벡터 스토어 아키텍처 (Vector Store Architecture)

생성된 문서는 임베딩(Embedding)되어 Qdrant에 저장됩니다.

Generated Docs
       ↓
Embeddings
...

시스템은 키워드 매칭 대신 의미론적 검색 (Semantic retrieval)을 수행합니다.

이를 통해 개발자는 자연어로 질문할 수 있습니다.

임베딩 파이프라인 (Embeddings Pipeline)

모든 문서는 벡터(Vectors)로 변환됩니다.

Document
   ↓
Embedding Model
...

이 벡터들은 정확한 단어보다는 의미를 포착합니다.

덕분에 검색 성능이 비약적으로 향상됩니다.

온보딩 챗봇 (The Onboarding Chatbot)

4단계의 마지막 조각은 온보딩 어시스턴트였습니다.

이 챗봇은 벡터 스토어(Vector store) 상단에 위치합니다.

워크플로우:

Developer Question
        ↓
Vector Search
...

이제 개발자는 파일을 수동으로 검색하지 않고도 코드베이스에 대해 질문할 수 있습니다.

답변은 일반적인 인터넷 응답이 아니라, 생성된 문서와 저장소 지식으로부터 나옵니다.

특화된 에이전트(Specialized Agents)를 선택한 이유

기술적으로는 하나의 거대한 프롬프트(Prompt)가 모든 것을 수행할 수도 있습니다.

하지만 프로덕션 시스템(Production systems)은 그런 방식으로 확장되지 않습니다.

대신 다음과 같이 구성합니다:

Parser Agent
      ↓
Research Agent
...

각 에이전트는 다음을 갖습니다:

• 하나의 책임 (One responsibility)
• 명확한 입력 (Clear inputs)
• 명확한 출력 (Clear outputs)
• 독립적인 테스트 (Independent testing)

이는 시스템을 더 유지보수하기 쉽고 개선하기 용이하게 만듭니다.

현재 프로젝트 구조의 모습

backend/
├── agents/
│   ├── brave_researcher.py
...

아키텍처가 실제 프로덕션 AI 플랫폼과 닮아가기 시작했습니다.

3단계 및 4단계의 핵심 학습 내용 (Key Learnings)

1. 에이전트(Agents)에는 구조가 필요합니다

대부분의 AI 프로젝트는 모든 책임을 하나의 프롬프트(Prompt)에 몰아넣기 때문에 실패합니다.

책임을 전문화된 에이전트(Agents)로 분리하면 시스템의 신뢰성을 극적으로 높일 수 있습니다.

2. 인간의 승인(Human Approval)이 중요합니다

완전 자율적인 문서 발행은 잘못된 내용을 발행하기 전까지는 멋지게 들립니다.

인간 참여형(Human-in-the-loop, HITL) 워크플로우는 프로덕션 시스템에 필요한 안전망을 제공합니다.

3. RAG는 문서의 품질만큼만 성능을 발휘합니다

기반이 되는 지식 베이스(Knowledge base)가 부실하다면 챗봇은 무용지물입니다.

품질 높은 문서 생성에 투자하는 것은 이후의 모든 프로세스를 개선합니다.

4. 상태 관리(State Management)가 결정적인 역할을 합니다

워크플로우가 여러 에이전트(Agents)에 걸쳐 확장되면, 체크포인트(Checkpoints)와 지속성(Persistence)은 필수 사항이 됩니다.

상태 관리(State management)가 없다면 디버깅(Debugging)은 악몽이 될 것입니다.

다음 단계 — 파트 3

이제 핵심 AI 시스템이 완성되었습니다.

다음으로, 저는 5단계에 집중할 것입니다:

• GitHub 웹훅 (Webhooks)
• 자동 PR 감지 (Automatic PR Detection)
• 증분 문서 업데이트 (Incremental Documentation Updates)
• Redis 캐싱 (Redis Caching)
• 이벤트 기반 파이프라인 실행 (Event-Driven Pipeline Execution)

이 단계에서 DevDocAI는 진정으로 자율적이 됩니다.

머지(Merged)된 모든 PR은 자동으로 문서 업데이트를 트리거합니다.

수동 개입은 필요하지 않습니다.

GitHub

Nevin100 / DevdocxAI

DevDocxAI는 사용자를 깊이 이해함으로써 엔지니어링 문서를 자동으로 생성, 유지 관리 및 업데이트하는 프로덕션급 멀티 에이전트(Multi-agent) AI 시스템입니다... DevDocAI는 깊은 이해를 통해 문서를 자동으로 생성, 유지 관리 및 업데이트하는 프로덕션급 멀티 에이전트(Multi-agent) AI 시스템입니다.

DevDocxAI 🤖📄

DevDocxAi는 사용자의 GitHub 코드베이스로부터 엔지니어링 문서를 자동으로 생성하고 업데이트하는 프로덕션급 멀티 에이전트(Multi-agent) LangGraph 시스템입니다.