AI 텍스트 기반 문서 포맷팅 에이전트 설계 1. 시스템 개요

1. 시스템 개요 및 목표

본 시스템은 사용자가 입력한 텍스트(AI 생성 텍스트 포함)와 업로드한 샘플 .docx 문서를 분석하여, 샘플 문서의 서식(스타일, 글꼴, 여백, 헤더/푸터 등)을 동일하게 적용한 새로운 .docx 문서를 생성하는 에이전트입니다. 단순한 텍스트 병합을 넘어, LangGraph를 활용하여 상태 기반(Stateful)의 복잡한 에이전트 워크플로우를 구성하며, 업로드된 샘플 문서는 재사용 가능한 스킬(Skill)로 변환되어 지속적으로 관리됩니다.

이 시스템은 기존의 노트 데이터를 AI가 검색하고 활용하는 [[Vectorize]] 아키텍처와 유사하게, 문서 포맷팅이라는 특정 작업을 토큰 기반의 API 호출과 파일 처리 파이프라인으로 분리하여 처리합니다. 또한, Claude Code와 노트 시스템이 연동되었던 [[Mcp 연동 방법]]처럼, 에이전트가 외부 도구(문서 파서, 스타일 라이브러리)를 유기적으로 호출하여 최종 결과물을 도출하는 구조를 목표로 합니다.

2. 핵심 아키텍처: LangGraph 기반 에이전트 워크플로우

LangGraph를 사용하여 각 단계를 명확한 노드(Node)와 엣지(Edge)로 정의합니다. 상태(State) 그래프를 통해 문서 생성 과정의 데이터 흐름을 추적하고, 오류 발생 시 특정 노드로 재진입할 수 있는 유연성을 확보합니다.

1. 상태(State) 정의

• raw_text: 사용자가 입력한 원본 텍스트
• uploadedfilepath: 업로드된 샘플 docx 파일 경로
• parsed_styles: 샘플 문서에서 추출된 스타일 정보 (스킬 데이터)
• structured_content: 원본 텍스트를 문서 구조에 맞게 분해한 데이터
• finaldocxbuffer: 최종 생성된 docx 파일 바이트
• error: 예외 발생 시 에러 로그

1. 노드(Node) 구성

• File Parser Node: 업로드된 .docx 파일을 분석하여 스타일 정보(폰트, 크기, 정렬, 문단 간격, 표 스타일 등)를 추출합니다.
• Skill Manager Node: 추출된 스타일 정보를 데이터베이스에 '스킬'로 저장하거나, 기존에 저장된 스킬을 불러옵니다.
• Content Structuring Node: LLM을 활용하여 입력된 텍스트를 문서의 목차 및 구조(제목, 본문, 목록 등)에 맞게 매핑합니다.
• Document Generator Node: 구조화된 콘텐츠와 적용할 스킬 데이터를 바탕으로 python-docx 등의 라이브러리를 사용해 최종 문서를 생성합니다.
• QA Node: 생성된 문서가 샘플 문서의 서식을 정확히 따르고 있는지 검증합니다. 실패 시 Content Structuring Node로 피드백 루프를 발생시킵니다.

1. 엣지(Edge) 및 제어 흐름

• 조건부 엣지(Conditional Edges)를 사용하여, 새로운 샘플이 업로드된 경우 File Parser로 이동하고, 기존 스킬을 선택한 경우 Skill Manager에서 바로 데이터를 로드하도록 분기합니다.

3. 샘플 문서 스킬(Skill)화 관리 시스템

업로드된 샘플 문서를 일회성으로 사용하는 것이 아니라, 재사용 가능한 '포맷팅 스킬'로 관리합니다. 이는 [[Hive note 소개]]에서 언급된 노트의 메타데이터 관리 및 확장성 개념과 맥락을 같이합니다.

• 스킬 추출 및 저장: 문서의 XML 내부 구조를 분석하여 스타일 정보를 JSON 형태로 직렬화하여 저장합니다.
• 스킬 메타데이터 구조:

{

"skill*id": "skill*corporate*report*v2",

"name": "기업 공시용 보고서 포맷",

"style_data": {

"heading_1": { "font": "NanumSquare", "size": 18, "bold": true, "color": "#1F4E79" },

"normal": { "font": "맑은 고딕", "size": 10, "line_spacing": 1.5 },

"table_style": "Grid Table 4 Accent 1"

},

"created_at": "2023-10-27T10:00:00Z"

}

• 스킬 관리 API: 사용자는 웹 인터페이스나 API를 통해 자신이 등록한 스킬 목록을 조회하고, 특정 스킬을 기본값으로 설정하거나 삭제할 수 있습니다.

4. 백엔드 구조 및 데이터 파이프라인

에이전트의 실행 환경은 서버리스 또는 컨테이너 환경에서 구동되며, 문서 처리를 위한 안정적인 스토리지와 연동되어야 합니다.

1. API 계층 (FastAPI 등)

• POST /api/format-document: 텍스트와 샘플 파일(또는 스킬 ID)을 수신하여 LangGraph 워크플로우를 트리거합니다.
• GET /api/skills: 등록된 포맷팅 스킬 목록을 반환합니다.
• GET /api/download/{task_id}: 처리가 완료된 최종 .docx 파일을 다운로드합니다.

1. 저장소 분리

• 데이터베이스 (PostgreSQL or D1): 스킬 메타데이터, 사용자 정보, 에이전트 실행 상태 및 로그를 저장합니다. [[Vectorize]]에서 원본과 임베딩을 분리했던 것처럼, 본 시스템에서도 스킬 정의(JSON)와 실제 파일을 분리하여 관리합니다.
• 오브젝트 스토리지 (S3 or R2): 업로드된 샘플 문서 원본과 생성된 최종 문서를 저장합니다.

1. 문서 생성 엔진

• LangGraph의 Document Generator Node 내부에서 python-docx 라이브러리를 래핑(Wrapping)하여 사용합니다.
• LLM이 텍스트를 마크다운이나 JSON 구조로 변환하면, 이를 파싱하여 docx 객체의 addparagraph*, *addheading, add_table 등의 메서드에 매핑합니다. 이때 미리 정의된 스킬의 스타일 속성을 주입합니다.

5. 에이전트 워크플로우 시나리오

사용자가 "AI가 작성한 시장 분석 보고서 텍스트"와 "사내 표준 양식 docx 파일"을 업로드했을 때의 처리 흐름은 다음과 같습니다.

1. 요청 수신: API를 통해 원본 텍스트와 샘플 docx 파일이 서버로 전송됩니다.
2. 스킬 파싱 (File Parser Node): 업로드된 docx에서 헤더, 본문 폰트, 표 디자인 등을 추출하여 parsed_styles 상태에 저장합니다.
3. 스킬 저장 (Skill Manager Node): 추출된 스타일을 "사내 표준 양식 v1"이라는 이름으로 데이터베이스에 스킬로 등록합니다.
4. 콘텐츠 구조화 (Content Structuring Node): LLM이 원본 텍스트를 읽고, 보고서에 적합한 구조(대제목, 소제목, 개조식 항목, 표 데이터 등)로 분류합니다.
5. 문서 생성 (Document Generator Node): 구조화된 텍스트를 앞서 추출한 스킬의 서식을 적용하여 .docx 파일로 물리적으로 작성합니다.
6. 검증 및 반환 (QA Node): 생성된 문서의 페이지 여백이나 폰트 깨짐이 없는지 확인 후, 사용자에게 다운로드 링크를 제공합니다.

이 설계를 통해 단순한 텍스트 복사-붙여넣기가 아닌, 문서의 맥락과 서식을 이해하고 재사용 가능한 자산(스킬)으로 축적하는 지능형 문서 자동화 시스템을 구축할 수 있습니다.