랭그래프(LangGraph)로 만드는 상태 기반 AI 워크플로 개발 가이드

개발하다 보면 이런 순간이 옵니다. “대화는 잘 되는데, 여러 단계 작업(검색→정리→검증→재시도)을 안정적으로 굴리려면 어떻게 하지?” 프롬프트만으로는 흐름이 자꾸 흔들리고, 예외 처리도 어렵죠. 이럴 때 랭그래프는 상태(state)와 그래프 구조로 AI 작업을 눈에 보이는 흐름으로 만들 수 있게 도와줍니다.

랭그래프란 무엇인가

랭그래프는 LLM 기반 애플리케이션을 노드(node)와 엣지(edge)로 연결해, “어떤 순서로 어떤 작업을 수행할지”를 그래프 형태로 구성하는 방식입니다. 핵심은 다음 두 가지예요.

• 상태(State): 워크플로가 공유하는 데이터(사용자 입력, 중간 결과, 최종 답 등)
• 조건 분기(Conditional routing): 결과에 따라 다음 노드를 선택(예: “검증 실패면 재시도”) 즉, 단순 체인보다 복잡한 흐름을 훨씬 안정적으로 다룰 수 있습니다.

언제 랭그래프가 특히 유용할까

1) “검증 → 재시도”가 필요한 개발 기능

예를 들어 코드 생성 후 테스트/규칙 검사를 돌리고 실패하면 다시 생성하도록 만들 때요.

2) 도구 호출이 섞인 다단계 작업

• 요약 노드 → 검색/DB 조회 노드 → 정리 노드 → 최종 답변 노드 이런 식으로 책임을 쪼개면 디버깅이 쉬워집니다.

3) 사용자 대화를 ‘흐름’으로 관리하고 싶을 때

상담봇처럼 “정보가 충분한지 확인 → 부족하면 추가 질문” 같은 구조에 강합니다.

기본 구성: 상태, 노드, 라우팅

아래 예시는 “요청을 분석 → 초안 작성 → 간단 검증 → 통과면 종료/실패면 재작성” 흐름입니다. (라이브러리 버전에 따라 API가 조금씩 다를 수 있어, 실행 환경에 맞게 함수명은 조정하세요.)

from typing import TypedDict, Optional

# 상태 정의: 그래프 전체가 공유하는 데이터
class State(TypedDict):
    user_input: str
    draft: Optional[str]
    is_valid: Optional[bool]
    attempts: int

def analyze(state: State) -> State:
    text = state["user_input"]
    # 규칙: 요구사항을 뽑아내는 단계라고 가정
    return {**state, "draft": None, "is_valid": None}

def write_draft(state: State) -> State:
    # 실제로는 LLM 호출 결과가 들어간다고 보면 됩니다.
    draft = f"초안: {state['user_input']}에 대한 답변을 생성했습니다."
    return {**state, "draft": draft, "attempts": state["attempts"] + 1}

def validate(state: State) -> State:
    draft = state["draft"] or ""
    # 예시 검증: 길이가 너무 짧으면 실패 처리
    is_valid = len(draft) > 20
    return {**state, "is_valid": is_valid}

def route(state: State) -> str:
    
     state[]:
         
     state[] >= :
           
     

이 구조의 장점은 실패를 전제로 설계할 수 있다는 점입니다. “한 번에 잘 되면 좋고, 아니면 안전하게 다시 돌린다”가 코드 레벨에서 자연스럽게 표현돼요.

실전 팁: 개발자가 바로 체감하는 포인트

1) 상태는 ‘최소 공유, 최대 명확’

상태에 너무 많은 값을 넣으면 어느 노드가 무엇을 바꾸는지 추적이 어려워집니다. draft, sources, errors, attempts처럼 역할이 분명한 필드만 두세요.

2) 노드는 작게, 책임은 하나씩

• “초안 작성”과 “형식 맞추기”를 한 노드에 몰아넣으면 수정이 힘듭니다. 노드를 쪼개면 나중에 특정 단계만 교체하기 쉽습니다.

3) 라우팅 조건을 로그로 남기기

분기 기준이 복잡해질수록 “왜 이쪽으로 갔지?”가 빈번해집니다. 라우팅 함수에서 조건 판단 근거(is_valid, attempts 등)를 기록하면 디버깅 시간이 확 줄어요.

간단한 적용 시나리오: 개발 문서 생성기

개발팀에서 흔한 요구를 예로 들어볼게요.

1. 요구사항 입력(기능 설명, 제약, API 스펙)
2. 초안 생성
3. 규칙 검사: 필수 섹션(개요/입출력/에러/예제) 누락 여부 확인
4. 누락 시 보강 질문 생성 또는 초안 보강
5. 통과하면 최종 문서 출력 이걸 체인으로 만들면 중간에 빠진 정보가 있어도 그대로 흘러가 버리는데, 랭그래프 스타일이면 누락을 감지하고 다시 묻는 흐름을 구조적으로 넣을 수 있습니다.

마무리: 랭그래프를 시작할 때의 현실적인 한 줄 조언

처음부터 거대한 그래프를 만들기보다, “검증 → 재시도” 한 가지 흐름만 넣어도 체감이 큽니다. 개발은 결국 예외와 실패를 다루는 일이고, 랭그래프는 그 실패를 설계 가능한 흐름으로 바꿔주는 도구에 가깝습니다.