LangGraph Fault Tolerance 장애 복구 완벽 가이드

LangGraph 애플리케이션의 장애 복구 메커니즘을 실무 중심으로 배웁니다. Durable Execution부터 Graph Migrations까지 체크포인트 기반 복구 시스템을 스토리텔링으로 쉽게 이해할 수 있습니다.

---

목차

1. Durable_Execution_개념
2. 마지막_체크포인트에서_재개
3. pending_write_보관
4. 중복_처리_방지
5. 재귀_제한_설정
6. Graph_Migrations

---

1. Durable Execution 개념

어느 날 김개발 씨가 LangGraph로 챗봇 서비스를 운영하던 중, 서버가 갑자기 재시작되었습니다. 사용자들의 대화 내역이 모두 사라져버렸고, 처음부터 다시 시작해야 했습니다.

박시니어 씨가 다가와 말했습니다. "Durable Execution을 적용하지 않았네요?"

Durable Execution은 LangGraph가 그래프 실행 중 발생하는 모든 상태를 체크포인트로 저장하는 메커니즘입니다. 마치 게임을 하다가 중간 저장을 해두는 것처럼, 프로그램이 중단되어도 마지막으로 저장된 지점부터 다시 시작할 수 있습니다.

이를 통해 안정적이고 복원력 있는 AI 애플리케이션을 구축할 수 있습니다.

다음 코드를 살펴봅시다.

from langgraph.checkpoint.memory import MemorySaver
from langgraph.graph import StateGraph

# 체크포인트 저장소 설정 - 메모리 기반
checkpointer = MemorySaver()

# StateGraph 정의
workflow = StateGraph(state_schema=dict)

def process_step(state):
    # 각 단계 실행마다 자동으로 체크포인트 생성
    return {"messages": state["messages"] + ["처리 완료"]}

workflow.add_node("process", process_step)
workflow.set_entry_point("process")

# Durable Execution 활성화
app = workflow.compile(checkpointer=checkpointer)

김개발 씨는 입사 6개월 차 AI 개발자입니다. 최근 LangGraph를 사용해 고객 상담 챗봇을 개발했는데, 서비스가 안정적이지 못하다는 피드백을 받았습니다.

고객과 대화 중에 서버가 재시작되면 모든 대화 내역이 사라져버렸기 때문입니다. 박시니어 씨가 김개발 씨의 모니터를 들여다보더니 말했습니다.

"아, Durable Execution을 적용하지 않았군요. 그래서 장애 복구가 안 되는 거예요." 그렇다면 Durable Execution이란 정확히 무엇일까요?

쉽게 비유하자면, Durable Execution은 마치 워드 프로세서의 자동 저장 기능과 같습니다. 글을 쓰다가 갑자기 컴퓨터가 꺼져도 마지막으로 저장된 지점부터 다시 작업할 수 있듯이, LangGraph도 그래프 실행 중 각 단계마다 상태를 자동으로 저장합니다.

이처럼 Durable Execution은 애플리케이션의 실행 상태를 지속적으로 보존하는 역할을 담당합니다. Durable Execution이 없던 시절에는 어땠을까요?

개발자들은 장애가 발생하면 처음부터 모든 작업을 다시 실행해야 했습니다. 시간도 오래 걸리고, 사용자 경험도 나빴습니다.

더 큰 문제는 복잡한 멀티 에이전트 시스템에서는 어느 단계까지 진행되었는지조차 파악하기 어려웠다는 점입니다. 프로젝트가 커질수록 이런 문제는 눈덩이처럼 불어났습니다.

바로 이런 문제를 해결하기 위해 Durable Execution이 등장했습니다. Durable Execution을 사용하면 그래프의 각 노드 실행 후 자동으로 체크포인트가 생성됩니다.

또한 장애 발생 시 마지막 체크포인트부터 즉시 재개할 수 있습니다. 무엇보다 사용자는 중단 없는 경험을 얻을 수 있다는 큰 이점이 있습니다.

위의 코드를 한 줄씩 살펴보겠습니다. 먼저 2번째 줄에서 MemorySaver를 임포트하는데, 이것이 체크포인트를 저장할 저장소입니다.

5번째 줄에서 checkpointer 인스턴스를 생성하면 메모리에 체크포인트를 저장할 준비가 완료됩니다. 8번째 줄에서 StateGraph를 정의하고, 17번째 줄에서 compile 메서드에 checkpointer를 전달하면 Durable Execution이 활성화됩니다.

이제 그래프의 각 노드가 실행될 때마다 자동으로 체크포인트가 생성됩니다. 실제 현업에서는 어떻게 활용할까요?

예를 들어 의료 상담 AI 서비스를 개발한다고 가정해봅시다. 환자와 AI의 대화가 길어질 수 있고, 중간에 네트워크 장애나 서버 재시작이 발생할 수 있습니다.

Durable Execution을 활용하면 어떤 상황에서도 대화 맥락을 유지하면서 서비스를 재개할 수 있습니다. 많은 엔터프라이즈 AI 플랫폼에서 이런 패턴을 적극적으로 사용하고 있습니다.

하지만 주의할 점도 있습니다. 초보 개발자들이 흔히 하는 실수 중 하나는 체크포인터를 설정하지 않고 그래프를 컴파일하는 것입니다.

이렇게 하면 Durable Execution이 작동하지 않아 장애 복구가 불가능합니다. 따라서 반드시 compile 메서드에 checkpointer를 전달해야 합니다.

다시 김개발 씨의 이야기로 돌아가 봅시다. 박시니어 씨의 설명을 들은 김개발 씨는 고개를 끄덕였습니다.

"아, 그래서 체크포인터가 필요했군요!" Durable Execution을 제대로 이해하면 더 안정적이고 복원력 있는 AI 애플리케이션을 구축할 수 있습니다. 여러분도 오늘 배운 내용을 실제 프로젝트에 적용해 보세요.

실전 팁

💡 - 프로덕션 환경에서는 MemorySaver 대신 PostgresSaver나 SqliteSaver를 사용하세요

• 각 체크포인트에는 고유한 thread_id를 부여해 세션을 구분할 수 있습니다

---

2. 마지막 체크포인트에서 재개

김개발 씨가 Durable Execution을 적용한 후, 이번에는 서버가 재시작되었을 때 실제로 어떻게 재개되는지 테스트해보고 싶어졌습니다. 박시니어 씨가 말했습니다.

"thread_id와 체크포인트 ID만 있으면 정확히 그 지점부터 다시 시작할 수 있어요."

체크포인트 재개는 저장된 체크포인트 ID를 사용해 중단된 그래프 실행을 이어가는 메커니즘입니다. 마치 책갈피를 꽂아둔 페이지부터 책을 다시 읽는 것처럼, 특정 체크포인트부터 그래프 실행을 계속할 수 있습니다.

이를 통해 장애가 발생해도 처음부터 다시 시작할 필요가 없습니다.

다음 코드를 살펴봅시다.

from langgraph.checkpoint.memory import MemorySaver

# 체크포인트 저장소
checkpointer = MemorySaver()
app = workflow.compile(checkpointer=checkpointer)

# 초기 실행 - thread_id로 세션 구분
config = {"configurable": {"thread_id": "user-123"}}
result = app.invoke({"messages": []}, config)

# 마지막 체크포인트 조회
state = app.get_state(config)
print(f"현재 체크포인트 ID: {state.checkpoint_id}")

# 동일한 thread_id로 재개 - 마지막 상태부터 이어짐
result = app.invoke({"messages": ["추가 입력"]}, config)

Durable Execution을 적용한 김개발 씨는 이제 실제로 재개가 어떻게 동작하는지 궁금해졌습니다. 테스트 서버를 강제로 재시작한 후, 과연 이전 대화가 복원될까요?

박시니어 씨가 옆에서 지켜보며 말했습니다. "걱정 마세요.

thread_id만 기억하고 있으면 언제든지 그 세션을 이어갈 수 있어요." 그렇다면 체크포인트 재개는 정확히 어떻게 작동할까요? 쉽게 비유하자면, 체크포인트 재개는 마치 넷플릭스에서 영화를 보다가 중단했을 때 이어보기 기능과 같습니다.

사용자마다 고유한 시청 기록이 있고, 다음에 접속하면 마지막으로 본 장면부터 자동으로 시작됩니다. 이처럼 LangGraph도 각 세션에 고유한 thread_id를 부여하고, 해당 ID로 접근하면 마지막 체크포인트부터 실행을 재개합니다.

체크포인트 재개 기능이 없다면 어떤 문제가 있을까요? 사용자가 대화 중에 앱을 종료했다가 다시 접속하면 모든 맥락이 사라집니다.

AI는 이전 대화를 전혀 기억하지 못하고, 사용자는 같은 질문을 반복해야 합니다. 특히 복잡한 업무를 처리하는 AI 에이전트의 경우, 중간에 작업이 중단되면 처음부터 다시 시작해야 하는 심각한 문제가 발생합니다.

바로 이런 문제를 해결하기 위해 체크포인트 재개 메커니즘이 설계되었습니다. 체크포인트 재개를 사용하면 각 사용자 세션을 독립적으로 관리할 수 있습니다.

또한 서버 장애나 네트워크 중단 후에도 즉시 작업을 이어갈 수 있습니다. 무엇보다 사용자는 끊김 없는 대화 경험을 얻을 수 있다는 큰 이점이 있습니다.

위의 코드를 한 줄씩 살펴보겠습니다. 먼저 8번째 줄에서 config 딕셔너리를 생성하는데, 여기에 thread_id를 지정합니다.

이것이 세션 식별자 역할을 합니다. 9번째 줄에서 첫 번째 invoke를 호출하면 체크포인트가 생성됩니다.

12번째 줄의 get_state 메서드로 현재 상태와 체크포인트 ID를 확인할 수 있습니다. 마지막으로 16번째 줄에서 동일한 config로 다시 invoke하면, LangGraph는 자동으로 마지막 체크포인트를 찾아 그 지점부터 실행을 재개합니다.

실제 현업에서는 어떻게 활용할까요? 예를 들어 복잡한 문서 분석 AI 서비스를 개발한다고 가정해봅시다.

사용자가 100페이지짜리 계약서를 업로드하고 분석을 요청했는데, 50페이지까지 분석한 상태에서 네트워크가 끊겼습니다. 체크포인트 재개 기능이 있다면 재접속 시 51페이지부터 이어서 분석할 수 있습니다.

많은 SaaS 기업에서 이런 방식으로 사용자 경험을 개선하고 있습니다. 하지만 주의할 점도 있습니다.

초보 개발자들이 흔히 하는 실수 중 하나는 매번 새로운 thread_id를 생성하는 것입니다. 이렇게 하면 세션이 연결되지 않아 재개가 불가능합니다.

따라서 사용자 ID나 세션 토큰을 기반으로 일관된 thread_id를 사용해야 합니다. 다시 김개발 씨의 이야기로 돌아가 봅시다.

테스트를 마친 김개발 씨는 감탄했습니다. "정말로 마지막 대화부터 이어지네요!" 체크포인트 재개 메커니즘을 제대로 이해하면 사용자 친화적인 AI 애플리케이션을 구축할 수 있습니다.

여러분도 오늘 배운 내용을 실제 프로젝트에 적용해 보세요.

실전 팁

💡 - thread_id는 UUID 형식을 사용하면 충돌을 방지할 수 있습니다

• get_state_history로 모든 체크포인트 이력을 조회할 수 있습니다

---

3. pending write 보관

김개발 씨가 그래프를 실행하던 중, 노드에서 에러가 발생했습니다. 그런데 신기하게도 에러가 발생한 노드 이전까지의 작업 결과는 모두 보존되어 있었습니다.

박시니어 씨가 설명했습니다. "pending write 덕분이에요.

각 노드의 실행 결과가 임시로 보관되거든요."

Pending write는 그래프의 각 노드가 실행될 때 생성되는 상태 변경 사항을 체크포인트에 임시로 저장하는 메커니즘입니다. 마치 데이터베이스 트랜잭션의 임시 버퍼처럼, 노드 실행 결과를 즉시 반영하지 않고 보관했다가 성공적으로 완료되면 커밋합니다.

이를 통해 부분 실패 시에도 안전하게 복구할 수 있습니다.

다음 코드를 살펴봅시다.

from langgraph.checkpoint.memory import MemorySaver

app = workflow.compile(checkpointer=MemorySaver())
config = {"configurable": {"thread_id": "session-456"}}

# 그래프 실행 중 에러 발생
try:
    result = app.invoke({"input": "데이터"}, config)
except Exception as e:
    print(f"에러 발생: {e}")

    # 마지막 성공한 체크포인트 조회
    state = app.get_state(config)
    print(f"보관된 pending writes: {state.pending_writes}")

    # 다음 실행 시 pending write부터 재시작
    result = app.invoke(None, config)

김개발 씨는 복잡한 데이터 처리 그래프를 실행하다가 중간 노드에서 에러를 만났습니다. 처음부터 다시 시작해야 하나 걱정했는데, 이전 단계의 처리 결과는 그대로 남아있었습니다.

박시니어 씨가 모니터를 가리키며 말했습니다. "보세요, pending write 목록이 보이죠?

각 노드의 실행 결과가 여기에 임시로 저장되어 있어요." 그렇다면 pending write란 정확히 무엇일까요? 쉽게 비유하자면, pending write는 마치 요리를 할 때 중간 재료들을 별도의 그릇에 담아두는 것과 같습니다.

야채를 썰고, 고기를 양념하고, 소스를 만들 때 각각을 다른 그릇에 담아둡니다. 만약 마지막 단계에서 실수가 생겨도 이전에 준비한 재료들은 그대로 사용할 수 있습니다.

이처럼 pending write도 각 노드의 실행 결과를 별도로 보관했다가 전체 작업이 완료되면 최종 상태에 반영합니다. pending write 메커니즘이 없다면 어떤 일이 벌어질까요?

노드 실행 중 에러가 발생하면 이전 단계의 모든 작업이 무효화됩니다. 시간이 오래 걸리는 API 호출이나 데이터 처리 작업을 다시 해야 하므로 비효율적입니다.

더 큰 문제는 외부 시스템과의 동기화가 깨질 수 있다는 점입니다. 바로 이런 문제를 해결하기 위해 pending write 시스템이 설계되었습니다.

pending write를 사용하면 각 노드의 실행 결과가 즉시 저장됩니다. 또한 에러 발생 시 마지막 성공한 지점부터 재시작할 수 있습니다.

무엇보다 부분 실패에 대한 복원력이 크게 향상된다는 큰 이점이 있습니다. 위의 코드를 한 줄씩 살펴보겠습니다.

먼저 7번째 줄에서 try 블록 안에서 그래프를 실행합니다. 13번째 줄에서 get_state를 호출하면 현재 상태와 함께 pending_writes 목록을 확인할 수 있습니다.

이것은 아직 최종 커밋되지 않은 노드 실행 결과들입니다. 17번째 줄에서 동일한 config로 다시 invoke하면, LangGraph는 pending write를 찾아 그 지점부터 실행을 재개합니다.

실제 현업에서는 어떻게 활용할까요? 예를 들어 이미지 처리 파이프라인을 개발한다고 가정해봅시다.

원본 이미지를 다운로드하고, 리사이징하고, 필터를 적용하고, 최종적으로 저장하는 여러 단계가 있습니다. 필터 적용 단계에서 에러가 발생해도 다운로드와 리사이징 결과는 pending write로 보관되어 있으므로, 필터 단계만 다시 실행하면 됩니다.

많은 이미지 처리 서비스에서 이런 방식으로 처리 시간을 단축하고 있습니다. 하지만 주의할 점도 있습니다.

초보 개발자들이 흔히 하는 실수 중 하나는 pending write를 수동으로 조작하려는 것입니다. pending write는 LangGraph 내부에서 자동으로 관리되므로 직접 수정하면 상태 불일치가 발생할 수 있습니다.

따라서 get_state로 조회만 하고, 실제 상태 변경은 그래프 실행으로만 해야 합니다. 다시 김개발 씨의 이야기로 돌아가 봅시다.

박시니어 씨의 설명을 들은 김개발 씨는 안도했습니다. "다행이네요, 처음부터 다시 안 해도 되겠어요!" pending write 메커니즘을 제대로 이해하면 더 효율적이고 복원력 있는 그래프를 설계할 수 있습니다.

여러분도 오늘 배운 내용을 실제 프로젝트에 적용해 보세요.

실전 팁

💡 - get_state_history로 과거 pending write 이력도 추적할 수 있습니다

• pending write는 체크포인트가 커밋되면 자동으로 정리됩니다

---

4. 중복 처리 방지

김개발 씨가 재개 기능을 테스트하다가 이상한 현상을 발견했습니다. 같은 메시지가 두 번 처리되어 API 호출이 중복으로 발생한 것입니다.

박시니어 씨가 코드를 보더니 말했습니다. "체크포인트 ID를 확인하지 않아서 생긴 문제네요.

멱등성을 보장해야 해요."

중복 처리 방지는 동일한 체크포인트에서 재개할 때 이미 처리된 노드를 다시 실행하지 않도록 하는 메커니즘입니다. 마치 은행 이체에서 같은 거래가 두 번 일어나지 않도록 거래 ID를 체크하는 것처럼, 체크포인트 ID를 기반으로 멱등성을 보장합니다.

이를 통해 안전하게 재시도할 수 있습니다.

다음 코드를 살펴봅시다.

from langgraph.checkpoint.memory import MemorySaver

app = workflow.compile(checkpointer=MemorySaver())
config = {"configurable": {"thread_id": "session-789"}}

# 초기 실행
state1 = app.invoke({"count": 0}, config)
checkpoint_id_1 = app.get_state(config).checkpoint_id

# 재개 시도 - 새로운 체크포인트 생성됨
state2 = app.invoke({"count": state1["count"]}, config)
checkpoint_id_2 = app.get_state(config).checkpoint_id

# 체크포인트 ID 비교로 중복 방지
if checkpoint_id_1 != checkpoint_id_2:
    print("새로운 처리 완료")
else:
    print("이미 처리됨 - 스킵")

김개발 씨는 재개 기능을 테스트하던 중 심각한 버그를 발견했습니다. 네트워크 불안정으로 같은 요청이 두 번 들어왔고, AI가 동일한 메시지를 두 번 처리해 외부 API에 중복 호출이 발생했습니다.

비용도 문제지만, 데이터 정합성도 깨질 수 있는 위험한 상황이었습니다. 박시니어 씨가 로그를 살펴보더니 말했습니다.

"체크포인트 ID를 제대로 확인하지 않았네요. 멱등성 처리가 필요해요." 그렇다면 중복 처리 방지는 정확히 어떻게 구현할까요?

쉽게 비유하자면, 중복 처리 방지는 마치 택배 배송에서 운송장 번호를 확인하는 것과 같습니다. 같은 운송장 번호로 이미 배송이 완료되었다면, 다시 배송하지 않습니다.

이처럼 LangGraph도 각 실행마다 고유한 체크포인트 ID를 부여하고, 동일한 ID로 재시도하면 이미 처리된 것으로 간주해 건너뜁니다. 중복 처리 방지 메커니즘이 없다면 어떤 문제가 생길까요?

같은 작업이 여러 번 실행되어 리소스가 낭비됩니다. 외부 API 호출 비용이 불필요하게 증가하고, 데이터베이스에 중복 레코드가 생성될 수 있습니다.

특히 결제나 주문 같은 중요한 작업에서는 심각한 비즈니스 문제로 이어질 수 있습니다. 바로 이런 문제를 해결하기 위해 체크포인트 기반 멱등성 보장 시스템이 설계되었습니다.

체크포인트 ID를 활용하면 동일한 요청을 쉽게 식별할 수 있습니다. 또한 재시도 로직을 안전하게 구현할 수 있습니다.

무엇보다 분산 시스템에서도 일관성을 유지할 수 있다는 큰 이점이 있습니다. 위의 코드를 한 줄씩 살펴보겠습니다.

먼저 7번째 줄에서 첫 번째 invoke를 실행하고, 8번째 줄에서 그때 생성된 체크포인트 ID를 저장합니다. 11번째 줄에서 두 번째 invoke를 실행하면 새로운 체크포인트가 생성됩니다.

14번째 줄에서 두 체크포인트 ID를 비교하면, 다른 경우에만 실제로 새로운 처리가 일어난 것임을 알 수 있습니다. 같은 경우라면 중복 요청이므로 처리를 건너뛰면 됩니다.

실제 현업에서는 어떻게 활용할까요? 예를 들어 전자상거래 주문 처리 시스템을 개발한다고 가정해봅시다.

사용자가 주문 버튼을 실수로 두 번 클릭했거나, 네트워크 타임아웃으로 재시도가 발생할 수 있습니다. 체크포인트 ID를 활용해 중복 방지 로직을 구현하면 같은 주문이 두 번 생성되는 것을 막을 수 있습니다.

많은 금융 서비스와 결제 시스템에서 이런 방식으로 트랜잭션 안정성을 보장하고 있습니다. 하지만 주의할 점도 있습니다.

초보 개발자들이 흔히 하는 실수 중 하나는 체크포인트 ID만으로 모든 멱등성을 보장하려는 것입니다. 비즈니스 로직에 따라 추가적인 고유 키가 필요할 수 있습니다.

따라서 체크포인트 ID와 함께 주문 ID나 거래 ID 같은 비즈니스 키를 조합해서 사용해야 합니다. 다시 김개발 씨의 이야기로 돌아가 봅시다.

체크포인트 ID 검증 로직을 추가한 김개발 씨는 안심했습니다. "이제 중복 처리 걱정은 없겠어요!" 중복 처리 방지 메커니즘을 제대로 이해하면 더 안전하고 신뢰할 수 있는 시스템을 구축할 수 있습니다.

여러분도 오늘 배운 내용을 실제 프로젝트에 적용해 보세요.

실전 팁

💡 - 외부 API 호출 전에 항상 체크포인트 ID를 로깅하세요

• 비즈니스 크리티컬한 작업은 추가적인 멱등성 키를 사용하세요

---

5. 재귀 제한 설정

김개발 씨가 복잡한 에이전트 그래프를 실행했는데, 갑자기 무한 루프에 빠졌습니다. 시스템 리소스가 고갈되기 직전에 박시니어 씨가 프로세스를 강제 종료했습니다.

"recursion_limit을 설정하지 않았네요. 그래프가 무한히 실행될 수 있어요."

재귀 제한은 그래프가 실행될 수 있는 최대 단계 수를 제한하는 안전 장치입니다. 마치 프로그램에서 재귀 함수의 최대 깊이를 설정하는 것처럼, 그래프 실행이 일정 횟수를 초과하면 자동으로 중단됩니다.

이를 통해 무한 루프를 방지하고 시스템 리소스를 보호할 수 있습니다.

다음 코드를 살펴봅시다.

from langgraph.checkpoint.memory import MemorySaver
from langgraph.errors import GraphRecursionError

app = workflow.compile(checkpointer=MemorySaver())

# recursion_limit 설정 - 최대 25단계까지만 실행
config = {
    "configurable": {"thread_id": "session-999"},
    "recursion_limit": 25
}

try:
    # 무한 루프 가능성이 있는 그래프 실행
    result = app.invoke({"input": "시작"}, config)
except GraphRecursionError as e:
    print(f"재귀 제한 초과: {e}")
    # 마지막 체크포인트부터 재개 가능
    state = app.get_state(config)

김개발 씨는 멀티 에이전트 시스템을 개발하던 중 끔찍한 경험을 했습니다. 에이전트들이 서로 메시지를 주고받다가 무한 루프에 빠진 것입니다.

CPU 사용률이 치솟고 메모리가 부족해지기 시작했습니다. 박시니어 씨가 급히 달려와 프로세스를 종료하고 말했습니다.

"재귀 제한을 설정하지 않으면 이런 일이 생겨요. 안전 장치가 필요합니다." 그렇다면 재귀 제한은 정확히 무엇일까요?

쉽게 비유하자면, 재귀 제한은 마치 놀이공원의 회전목마에 탑승 시간을 제한하는 것과 같습니다. 정해진 시간이 지나면 자동으로 멈춰서 다른 사람에게 기회를 주고, 기계가 과열되는 것을 방지합니다.

이처럼 재귀 제한도 그래프가 일정 횟수 이상 실행되면 강제로 중단해 시스템을 보호합니다. 재귀 제한이 없다면 어떤 일이 벌어질까요?

잘못 설계된 그래프나 예상치 못한 입력으로 인해 무한 루프가 발생할 수 있습니다. 서버 리소스가 고갈되어 다른 사용자의 요청도 처리할 수 없게 됩니다.

최악의 경우 전체 시스템이 다운될 수 있습니다. 바로 이런 문제를 해결하기 위해 재귀 제한 메커니즘이 설계되었습니다.

재귀 제한을 설정하면 그래프 실행이 안전한 범위 내에서만 이루어집니다. 또한 제한 초과 시 명확한 에러가 발생해 문제를 쉽게 진단할 수 있습니다.

무엇보다 시스템의 안정성과 예측 가능성이 크게 향상된다는 큰 이점이 있습니다. 위의 코드를 한 줄씩 살펴보겠습니다.

먼저 7번째 줄에서 config 딕셔너리를 생성하는데, 9번째 줄에서 recursion_limit을 25로 설정합니다. 이것은 그래프가 최대 25단계까지만 실행될 수 있다는 의미입니다.

14번째 줄에서 그래프를 실행하면, 25단계를 초과하는 순간 GraphRecursionError가 발생합니다. 15번째 줄에서 이 에러를 잡아 적절히 처리할 수 있습니다.

실제 현업에서는 어떻게 활용할까요? 예를 들어 고객 상담 챗봇을 개발한다고 가정해봅시다.

사용자와 AI가 대화를 주고받는데, 특정 질문에서 AI가 계속 같은 답변만 반복하는 버그가 있습니다. 재귀 제한을 50으로 설정하면 최대 50번의 대화 턴 후에는 자동으로 중단되고, 관리자에게 알림을 보내 문제를 파악할 수 있습니다.

많은 대화형 AI 서비스에서 이런 방식으로 무한 루프를 방지하고 있습니다. 하지만 주의할 점도 있습니다.

초보 개발자들이 흔히 하는 실수 중 하나는 재귀 제한을 너무 낮게 설정하는 것입니다. 정상적인 복잡한 작업도 제한에 걸려 중단될 수 있습니다.

따라서 그래프의 평균 실행 단계를 모니터링하고, 여유를 두어 제한값을 설정해야 합니다. 다시 김개발 씨의 이야기로 돌아가 봅시다.

재귀 제한을 추가한 김개발 씨는 안도의 한숨을 쉬었습니다. "이제 무한 루프 걱정은 없겠네요!" 재귀 제한 메커니즘을 제대로 이해하면 더 안전하고 안정적인 AI 시스템을 구축할 수 있습니다.

여러분도 오늘 배운 내용을 실제 프로젝트에 적용해 보세요.

실전 팁

💡 - 개발 환경에서는 낮은 제한값으로 테스트해 문제를 조기 발견하세요

• 프로덕션에서는 모니터링 데이터를 기반으로 적절한 제한값을 설정하세요

---

6. Graph Migrations

김개발 씨가 프로덕션 환경에서 그래프 구조를 업데이트해야 하는 상황이 생겼습니다. 하지만 기존 사용자들의 진행 중인 세션은 어떻게 하죠?

박시니어 씨가 말했습니다. "Graph Migration을 사용하면 기존 체크포인트를 새로운 그래프 구조로 안전하게 마이그레이션할 수 있어요."

Graph Migrations는 그래프 구조가 변경되었을 때 기존 체크포인트를 새로운 스키마에 맞게 변환하는 메커니즘입니다. 마치 데이터베이스 스키마 마이그레이션처럼, 그래프의 노드나 엣지가 추가되거나 변경되어도 이전 세션을 계속 사용할 수 있게 합니다.

이를 통해 무중단으로 시스템을 업그레이드할 수 있습니다.

다음 코드를 살펴봅시다.

from langgraph.checkpoint.memory import MemorySaver
from langgraph.graph import StateGraph

# 기존 그래프 v1
workflow_v1 = StateGraph(state_schema=dict)
workflow_v1.add_node("old_node", lambda s: s)
app_v1 = workflow_v1.compile(checkpointer=MemorySaver())

# 새로운 그래프 v2 - 노드 추가
workflow_v2 = StateGraph(state_schema=dict)
workflow_v2.add_node("old_node", lambda s: s)
workflow_v2.add_node("new_node", lambda s: {**s, "updated": True})

# 마이그레이션 함수 정의
def migrate_state(old_state):
    # 새로운 필드 추가
    return {**old_state, "version": "v2"}

app_v2 = workflow_v2.compile(checkpointer=MemorySaver())

김개발 씨는 고민에 빠졌습니다. 챗봇 서비스가 잘 운영되고 있는데, 새로운 기능을 추가하려면 그래프 구조를 바꿔야 합니다.

하지만 수천 명의 사용자가 이미 대화를 진행 중인데, 업데이트를 배포하면 모든 세션이 초기화될까요? 박시니어 씨가 옆에서 안심시켰습니다.

"걱정 마세요. Graph Migration을 사용하면 기존 세션을 유지하면서 업그레이드할 수 있어요." 그렇다면 Graph Migrations는 정확히 어떻게 작동할까요?

쉽게 비유하자면, Graph Migrations는 마치 건물을 사용하면서 리모델링하는 것과 같습니다. 사람들이 계속 거주하는 동안 한 층씩 인테리어를 바꾸고, 새로운 방을 추가합니다.

기존 거주자들은 자신의 물건을 그대로 사용하면서 새로운 시설을 이용할 수 있습니다. 이처럼 Graph Migrations도 기존 체크포인트를 보존하면서 새로운 그래프 구조로 전환합니다.

Graph Migrations가 없다면 어떤 문제가 생길까요? 그래프 구조를 변경하면 모든 기존 체크포인트가 무효화됩니다.

사용자들의 진행 중인 대화나 작업이 모두 초기화되어 사용자 경험이 크게 저하됩니다. 특히 장기간 진행되는 복잡한 업무의 경우 심각한 비즈니스 손실로 이어질 수 있습니다.

바로 이런 문제를 해결하기 위해 Graph Migrations 메커니즘이 설계되었습니다. Graph Migrations를 사용하면 그래프 구조를 자유롭게 변경할 수 있습니다.

또한 기존 사용자 세션을 중단 없이 유지할 수 있습니다. 무엇보다 지속적인 개선과 배포가 가능하다는 큰 이점이 있습니다.

위의 코드를 한 줄씩 살펴보겠습니다. 먼저 5번째 줄에서 기존 그래프 v1을 정의하고, old_node만 포함합니다.

10번째 줄부터는 새로운 그래프 v2를 정의하는데, 기존 old_node에 더해 new_node도 추가합니다. 15번째 줄에서 migrate_state 함수를 정의하면, 이 함수가 기존 상태를 새로운 스키마에 맞게 변환합니다.

예를 들어 17번째 줄에서는 version 필드를 추가해 상태를 업그레이드합니다. 실제 현업에서는 어떻게 활용할까요?

예를 들어 고객 지원 AI 시스템을 운영하는데, 새로운 감정 분석 기능을 추가한다고 가정해봅시다. 그래프에 sentiment_node를 추가해야 하는데, 수백 개의 진행 중인 고객 상담이 있습니다.

migrate_state 함수에서 기존 체크포인트에 sentiment 필드를 기본값으로 추가하면, 새로운 배포 후에도 모든 기존 세션이 정상적으로 작동합니다. 많은 엔터프라이즈 AI 플랫폼에서 이런 방식으로 무중단 업그레이드를 실현하고 있습니다.

하지만 주의할 점도 있습니다. 초보 개발자들이 흔히 하는 실수 중 하나는 마이그레이션 함수 없이 그래프 구조만 변경하는 것입니다.

이렇게 하면 기존 체크포인트를 읽을 때 에러가 발생하거나 데이터가 손실될 수 있습니다. 따라서 반드시 마이그레이션 함수를 작성하고, 충분한 테스트를 거쳐야 합니다.

다시 김개발 씨의 이야기로 돌아가 봅시다. 마이그레이션 코드를 작성한 김개발 씨는 안심했습니다.

"이제 언제든지 안전하게 업데이트할 수 있겠어요!" Graph Migrations 메커니즘을 제대로 이해하면 더 유연하고 진화 가능한 AI 시스템을 구축할 수 있습니다. 여러분도 오늘 배운 내용을 실제 프로젝트에 적용해 보세요.

실전 팁

💡 - 마이그레이션 함수는 항상 역호환성을 고려해 작성하세요

• 프로덕션 배포 전에 스테이징 환경에서 기존 체크포인트로 충분히 테스트하세요

---

이상으로 학습을 마칩니다. 위 내용을 직접 코드로 작성해보면서 익혀보세요!