LangGraph 가이드: persistence·checkpoint와 내구성 있는 에이전트 복구

InYourLeague 리서치 · 2026-08-27

Answer in brief

LangGraph의 checkpointer는 스레드별 그래프 상태를 checkpoint로 저장하여 대화 연속성, 중단 후 복구, human-in-the-loop, time travel, fault tolerance를 지원합니다. 같은 논리적 작업을 이어가려면 동일한 thread_id를 사용해야 하며, 여러 스레드에서 공유할 정보는 store에 저장해야 합니다. 제공된 공식 문서만으로는 정확한 checkpoint 확정 시점이나 보류 중인 쓰기의 재처리 방식을 판단할 수 없습니다.

Key facts at a glance

Failure modes and verification

FAQ

복구 가능한 LangGraph 스레드는 무엇으로 식별합니까?

그래프 호출이 configurable.thread_id를 전달하고, checkpointer가 해당 스레드의 그래프 상태를 checkpoint로 저장합니다. 같은 논리적 대화나 작업을 다시 가리킬 때만 동일한 ID를 사용해야 합니다.

Checkpoint는 정확히 언제 확정되며 보류 중인 쓰기는 어떻게 처리됩니까?

제공된 공식 발췌문은 정확한 checkpoint 경계나 보류 중인 쓰기의 저장 위치, 수명, 재실행 방식을 정의하지 않습니다. 이 자료만으로 노드 단위 원자성이나 재실행 보장을 추론해서는 안 됩니다.

재개하면 LangGraph가 항상 특정 노드부터 다시 실행합니까?

문서는 중단 후 연속 실행과 장애 복구 기능을 설명하지만, 정확한 재실행 지점이나 상태 병합 알고리즘은 명시하지 않습니다. 선택한 checkpointer와 예상 장애 조건으로 해당 동작을 직접 시험해야 합니다.

Human-in-the-loop와 time travel은 persistence를 어떻게 사용합니까?

Checkpointer는 사람의 검토, 상태 검사 또는 수정, time travel에 필요한 스레드 상태를 보관합니다. 접근 권한, 승인 정책, 충돌 처리, 과거 상태 선택 방식은 애플리케이션에서 별도로 설계해야 합니다.

어떤 checkpointer를 선택해야 합니까?

프로세스 재시작 때 checkpoint가 사라져도 되는 경우에만 메모리 기반 saver를 사용합니다. 제공된 문제 해결 발췌문은 지속성 있는 PostgreSQL 예시로 PostgresSaver를, 로컬 개발 예시로 SqliteSaver를 제시하지만 이를 전체 선택지라고 설명하지는 않습니다.

Sources and freshness

• Official source
• Official source
• Last verified: 2026-08-27

Extended guide

직접 답변

LangGraph는 checkpointer를 사용해 각 스레드의 그래프 상태를 checkpoint로 저장합니다. 그래프를 호출할 때 configurable.thread_id를 전달하면 읽거나 갱신할 스레드를 식별할 수 있습니다. 동일한 ID를 다시 사용하면 같은 논리적 대화나 작업의 저장 상태를 가리키고, 다른 ID를 사용하면 별도의 스레드 상태를 다루게 됩니다. Store의 범위는 다릅니다. Store는 한 스레드의 그래프 상태가 아니라 여러 스레드에서 사용할 애플리케이션 정의 데이터를 저장합니다. 이러한 역할은 공식 LangGraph 개요와 persistence 가이드에 설명되어 있습니다.

근거로 확인되는 persistence 모델

안전한 적용 순서

1. 그래프를 checkpointer와 함께 compile합니다. 한 스레드 밖에서도 유지해야 하는 정보가 있을 때만 store를 추가합니다. 공식 예시의 형태는 builder.compile(checkpointer=checkpointer, store=store)입니다.
2. 논리적 대화나 작업마다 안정적인 ID 하나를 할당하고 {"configurable": {"thread_id": "thread-1"}} 형식으로 그래프를 호출합니다. 이 값은 애플리케이션이 관리하는 실행 식별자입니다.
3. 저장된 동일 스레드를 다시 가리킬 때 같은 thread_id를 사용합니다. 서로 무관한 사용자나 작업에 같은 값을 사용하면 동일한 스레드 식별자로 상태가 연결될 수 있으므로 ID 할당 규칙을 명확히 정해야 합니다.
4. 재개는 저장된 스레드 상태를 활용한 연속 실행으로 이해합니다. 이를 특정 노드부터 반드시 재실행한다는 보장으로 확대 해석하지 말고, 선택한 checkpointer로 중단과 장애 상황을 직접 시험해야 합니다.
5. Human-in-the-loop나 time travel에는 저장된 상태를 활용하되, 접근 권한, 승인 절차, 충돌 처리, 과거 상태 선택 방식은 애플리케이션에서 별도로 설계합니다. 제공된 문서는 이러한 정책까지 정하지 않습니다.
6. 여러 스레드에서 공유해야 하는 정보는 store에 저장합니다. Subgraph는 별도의 checkpoint namespace를 관리하므로 변경 사항이 parent graph에 즉시 보이지 않을 수 있습니다. 가이드는 공유 store를 사용하거나 subgraph가 parent checkpoint에 기록하도록 구성하는 방안을 제시합니다.

Checkpointer 선택과 유지 관리

MemorySaver와 InMemorySaver는 checkpoint를 RAM에 저장하므로 프로세스를 재시작하면 데이터가 사라집니다. 제공된 문제 해결 안내는 지속성 있는 예시로 비동기 처리를 지원하는 PostgreSQL용 PostgresSaver를 제시하고, 개발 환경의 로컬 파일 저장 예시로 SqliteSaver를 제시합니다. 이는 발췌문에 나온 예시이며 전체 checkpointer 목록을 뜻하지 않습니다. Agent Server를 사용하면 서버가 persistence 인프라를 자동으로 관리하므로 checkpointer나 store를 직접 설정할 필요가 없습니다.

PostgresSaver에서는 thread_id를 255자 미만으로 유지해야 합니다. 무작위 UUID는 길이가 짧지만 결정적 식별자는 아닙니다. 같은 원본 식별자가 항상 같은 스레드 ID로 변환되어야 한다면 적절한 해시나 애플리케이션이 관리하는 매핑을 사용해야 합니다. 또한 장시간 실행되는 스레드에서는 checkpoint가 계속 누적될 수 있으므로 오래된 기록을 주기적으로 정리하거나 보존 기간 정책을 설정해야 합니다.

공개 가능한 근거의 경계

공식 문서로 확인되는 범위는 persistence 구성 요소의 역할과 범위, 그리고 위에 정리한 사용 사례입니다. 정확한 checkpoint 확정 시점, 보류 중인 쓰기의 수명, 재실행 순서, 상태 병합 방식, 트랜잭션 보장은 제공된 근거에서 확인되지 않습니다. 이러한 동작을 보장 사항으로 설명하려면 더 구체적인 공식 문서를 확인하거나 실제 배포 환경을 대표하는 시험으로 검증해야 합니다.

모델 제공 범위 안내: 공식 출처는 선택 가능한 모델 ID를 지정하지 않습니다.