LangGraph로 상태와 조건부 경로 구성하기

반복을 그래프로 드러내기

작은 에이전트는 while 반복문 하나로도 만들 수 있습니다. 그러나 도구 종류가 늘고 실패 시 재시도하거나 사람의 승인을 기다려야 하면 조건문이 서로 얽힙니다. 현재 값이 어디에서 바뀌었는지, 중단된 작업을 어느 지점부터 이어야 하는지 알기 어려워지고 테스트도 전체 루프에 의존하게 됩니다. 실행 경로와 데이터를 분리해 표현할 필요가 생깁니다.

LangGraph는 공유 상태를 읽고 부분 갱신을 반환하는 노드와, 다음 노드를 정하는 엣지로 실행 흐름을 표현합니다. 노드는 모델 호출, 도구 실행이나 검증처럼 한 단계의 작업이고, 일반 엣지는 고정된 다음 단계를 연결합니다. 조건부 엣지는 현재 상태를 보고 반복, 다른 분기 또는 종료를 선택합니다. 그래프라는 이름은 그림을 그리기 위한 것이 아니라 가능한 실행 경로를 코드에 명시한다는 뜻입니다.

그림: 조건부 엣지가 도구 실행 반복과 종료 경로를 구분합니다.

다음 코드는 외부 모델 없이 조건부 경로의 모양만 확인합니다.

pip install -U langgraph

from typing_extensions import TypedDict
from langgraph.graph import END, START, StateGraph
 
class State(TypedDict):
    count: int
 
def step(state: State):
    return {"count": state["count"] + 1}
 
def route(state: State):
    return END if state["count"] >= 2 else "step"
 
builder = StateGraph(State)
builder.add_node("step", step)
builder.add_edge(START, "step")
builder.add_conditional_edges("step", route)
graph = builder.compile()
 
print(graph.invoke({"count": 0}))

langgraph를 설치한 환경에서 실행하면 최종 count가 2인 상태를 확인할 수 있습니다. 노드는 전체 상태를 직접 바꾸는 대신 갱신할 값을 반환합니다.

실행 경로를 따라가면 상태는 0 → 1 → 2로 변합니다. START에서 step 노드로 들어가고 첫 실행 뒤에는 조건이 충족되지 않아 다시 step으로 돌아갑니다. 두 번째 실행 뒤 route가 END를 반환하며 그래프가 끝납니다. 모델이 없어도 반복과 종료 규칙을 독립적으로 시험할 수 있다는 점이 이 예제의 목적입니다.

상태와 제어를 분리하기

상태는 노드 사이의 계약입니다. 다음 판단에 필요한 메시지, 도구 결과, 시도 횟수와 승인 상태처럼 이름과 자료형이 분명한 값을 저장합니다. 여러 노드가 같은 목록을 갱신한다면 덮어쓸지 누적할지 병합 규칙도 정해야 합니다. 비밀값이나 큰 바이너리를 무조건 넣으면 체크포인트 크기와 노출 범위가 커지므로 외부 저장소의 안전한 참조만 남기는 편이 낫습니다.

조건부 엣지는 모델의 긴 자연어를 직접 해석하기보다 next_action, approved, error_type 같은 구조화된 필드로 분기해야 예측 가능한 경로를 만들 수 있습니다. 각 노드는 작은 입력 상태를 넣고 반환된 갱신값을 확인하는 단위 테스트가 가능해야 합니다. 라우팅 함수도 경계값에서 예상 노드를 고르는지 따로 검사할 수 있습니다.

실패 복구나 긴 작업에는 실행 상태를 저장하는 체크포인터와 대화를 구분하는 고유한 스레드 식별자가 필요합니다. 체크포인트가 있으면 프로세스가 끝나거나 승인 대기 시간이 길어져도 같은 실행을 이어갈 수 있습니다. 반대로 짧고 순서가 고정된 변환 작업에는 그래프와 영속화가 불필요한 복잡성을 더할 수 있습니다. 분기, 반복, 재개 요구가 실제로 있을 때 도입합니다.

사람의 판단을 기다렸다가 이어가는 방법은 중단·재개와 사람 승인에서 살펴봅니다.

참고 문서

• LangGraph 공식 문서 — Graph API
• LangGraph 공식 문서 — Overview