에이전트 워크플로 모듈화 — 경계를 어디에 긋는가

노드를 다 짤 줄 아는 사람에게 남는 질문은 하나다. 그걸 어떻게 배치해야 6개월 뒤에도 고칠 수 있는가. 마크다운 출력 한 줄을 고치려고 PDF 파싱부터 20초와 $0.21을 다시 내야 하는 구조라면, 코드가 동작하더라도 개선이 멈춘다.

이 글은 그 배치 문제를 다룬다. RAG에 검증을 붙이다 보면 왜 코드가 반드시 복잡해지는지, 단방향 파이프라인의 구조적 한계가 무엇인지 짚고, 모듈 경계를 정하는 일곱 가지 기준과 앞 단계를 다시 돌리지 않고 이어서 개발하는 기법으로 이어진다. 이어지는 두 편은 그 경계를 실제로 조립하는 서브그래프와 레거시 개조, 그리고 동시 실행과 확장을 다루는 병렬 처리와 멀티에이전트다.

용어 정리

이 글은 State·Node·Edge·Checkpointer의 개념을 안다고 전제한다. 최소한 아래 다섯 줄이 읽히면 충분하다.

왜 모듈화인가 — 코드는 반드시 복잡해진다

RAG를 붙이고 나면 순서대로 다음 갈등을 만난다.

결말은 둘이다. 코드가 점점 길어지고 복잡해진다. 그리고 LLM의 일관되지 않은 답변이 나비효과처럼 번져 최종 품질 저하로 이어진다.

근본 원인은 파이프라인이 단방향이라는 것

로드 → 분할 → 임베딩 → 검색 → 답변으로 흐르는 선형 구조의 한계는 셋이다.

여기에 사전에 고정된 것들이 겹친다 — 정해진 데이터 소스, 고정 크기 청크, 정해진 검색 방법, 고정된 프롬프트 형식. 그 위에 신뢰하기 어려운 LLM이 얹힌다.

그래프가 바꾸는 것

LangGraph는 상태 저장 멀티 액터 애플리케이션 구축에 특화된 워크플로 프레임워크로, 핵심 기능이 셋이다 — 루프와 조건문을 구현하는 Cycle & Branching, 각 단계 후 자동으로 상태를 저장하는 Persistence, 흐름을 세밀하게 직접 제어하는 Low Level Control.

LangGraph는 LangChain을 만든 곳에서 나왔지만 LangChain 없이도 사용 가능하다. 워크플로 엔진으로서 독립적이라는 뜻이다. 그래프 구성은 networkx의 개념을 차용했다.

모듈화가 주는 것

협업 구조와 직결된다

이 분리가 성립하려면 State 스키마가 계약(contract) 역할을 해야 한다. 스키마가 흔들리면 두 역할이 다시 한 사람에게 합쳐진다. 조직을 나누는 능력이 스키마 설계에 달려 있는 셈이다.

실험이 코드 한 줄로 끝난다

답변 생성 단계에서 모델을 바꿔가며 실험할 때, 노드를 같은 베이스로 구현해 두면 등록만 바꾸면 된다.

O3_GenerateNode(BaseNode)
DeepSeek_GenerateNode(BaseNode)
Claude_GenerateNode(BaseNode)

세 노드가 같은 State 키를 읽고 같은 키를 쓰면 그래프 코드는 한 줄만 바뀐다.

경계를 긋는 일곱 가지 기준

핵심 기준은 재실행 단위다. 다시 돌릴 일이 잦거나, 외부 API 비용이 걸리거나, 구현을 갈아끼울 가능성이 있거나, 담당자가 다르면 자른다. 반대로 State 키를 계속 주고받는 구간을 억지로 나누면 매핑 코드만 늘어난다. 매핑 코드가 길어지면 경계를 잘못 그은 신호로 본다.

Before — 한 덩어리 그래프

After — 모듈 단위로 쪼갠 그래프

export_output 서브그래프 내부는 Fan-out 구조다.

모듈 단위로 "이어서" 개발하기

모듈화의 진짜 이득은 구조가 예뻐지는 게 아니라 개발 루프가 짧아지는 것이다.

앞 단계를 한 번만 돌린다

import uuid
from langchain_core.runnables import RunnableConfig

# batch_size: 한번에 처리할 페이지 수
# test_page : 테스트할 페이지 번호
parser_graph = create_upstage_parser_graph(
    batch_size=30, test_page=None, verbose=True, visualize=True
)

config = RunnableConfig(
    recursion_limit=300,
    configurable={"thread_id": str(uuid.uuid4())},
)

parser_graph.invoke({"filepath": "data/report.pdf"}, config=config)

실행 로그는 이렇게 찍힌다.

[SplitPDFNode] 파일의 전체 페이지 수: 21 Pages.
[SplitPDFNode] 분할 PDF 생성: data/report_0000_0020.pdf
[DocumentParseNode] Start Parsing: data/report_0000_0020.pdf
[DocumentParseNode] Finished Parsing in 20.78 seconds
[PostDocumentParseNode] Total Post-processed Elements: 465
[PostDocumentParseNode] Total Cost: $0.21

이 여섯 줄이 모듈화의 경제적 근거다. 뒷단을 한 번 고칠 때마다 20초와 $0.21을 다시 낼 것인가.

노드 이름이 로그 접두어로 그대로 찍히는 것도 주목할 점이다. 모듈 경계가 곧 관측 경계가 된다.

체크포인터에서 State를 꺼내 다음 모듈의 입력으로 쓴다

# 이전 단계의 실행 결과를 그대로 가져온다
previous_state = parser_graph.get_state(config).values
inputs = previous_state.copy()

get_state(config).values는 해당 thread_id의 최신 스냅샷을 그대로 돌려준다. 즉 체크포인터가 개발 중에는 캐시 역할을 한다. 이 한 줄 덕분에 앞단을 다시 안 돌린다.

노드를 그래프 없이 함수처럼 호출해 검증한다

import importlib

# 모듈을 리로드해 최신 코드를 반영한다
importlib.reload(export)

export_image = export.ExportImage(verbose=True)
export_html = export.ExportHTML(verbose=True, ignore_new_line_in_text=True)
export_markdown = export.ExportMarkdown(
    verbose=True, ignore_new_line_in_text=True, show_image=False
)

# 단계별 상태를 업데이트 후 반영한다
inputs2 = export_image(inputs)
inputs.update(inputs2)

export_html(inputs)
# [ExportHTML] HTML 파일이 성공적으로 생성되었습니다: data/report.html
# {'export': ['data/report.html']}

여기서 드러나는 규약이 모듈화의 전제다.

노드가 순수 함수처럼 State in / partial State out 계약을 지키면 그래프 없이도 단위 테스트가 가능하다.

반대로 노드가 전역 상태나 그래프 런타임에 의존하면 이 기법이 전부 무너진다. 계약을 지키는 것이 모듈화의 전제이지 결과가 아니다.

검증이 끝나면 그래프로 승격시킨다

여기까지가 하나의 개발 루프다.

가운데 C → D → C 순환이 이 루프의 핵심이다. 앞단을 다시 돌리지 않고 신규 로직만 반복해서 고친다. 검증이 끝난 뒤에야 그래프로 올라간다.

경계를 그었다면 다음 문제는 그 모듈을 어떻게 상위 그래프에 꽂고, 이미 돌아가는 그래프를 안 깨고 확장하느냐다. 다음 편에서 서브그래프와 레거시 개조를 다룬다.

모듈 경계보다 한 층 아래 — State 스키마와 채널별 리듀서를 어떻게 정하는지, 그 결정이 병렬 처리에서 왜 정합성을 좌우하는지 — 는 State와 Reducer가 정하는 것에서 다룬다.