애플리케이션에 TTL 추가하기

사전 요구 사항 이 가이드는 LangSmith, 영속성, 크로스 스레드 영속성 개념에 익숙하다고 가정해요.

LangSmith는 체크포인트(스레드 상태)와 크로스 스레드 메모리(스토어 항목)를 모두 영구 저장해요. langgraph.json에서 TTL(Time-to-Live) 정책을 구성해서 이 데이터의 수명 주기를 자동으로 관리하고, 무한정 축적되는 것을 방지할 수 있어요.

출처: 문서

본문

스레드 및 체크포인트 TTL 구성하기

체크포인트는 대화 스레드의 상태를 캡처해요. TTL을 설정하면 만료된 데이터가 자동으로 삭제되거나 정리돼요.

langgraph.json 파일에 checkpointer.ttl 구성을 추가하세요:

{
  "dependencies": ["."],
  "graphs": {
    "agent": "./agent.py:graph"
  },
  "checkpointer": {
    "ttl": {
      "strategy": "delete",
      "sweep_interval_minutes": 60,
      "default_ttl": 43200
    }
  }
}

strategy: 만료 시 수행할 작업을 지정해요. 기본값은 "delete"예요.
- "delete": TTL이 만료되면 연결된 모든 런 및 체크포인트 데이터를 포함한 전체 스레드를 제거해요.
- "keep_latest": 스레드와 최신 체크포인트는 유지하지만, 이후 런에 필요하지 않은 이전 체크포인트 데이터는 삭제해요.
sweep_interval_minutes: 시스템이 만료된 체크포인트를 확인하는 주기(분)를 정의해요. 기본값은 5분이에요.
default_ttl: 기본 TTL 창(분)을 설정해요 (예: 43200분 = 30일). delete 창은 TTL이 적용될 때 시작되며 활동에 따라 갱신되지 않아요. keep_latest 창은 런이 끝나거나 스레드 상태가 업데이트될 때 갱신돼요. 생략하면 스레드는 기본적으로 만료되지 않아요.
sweep_limit: (Agent server v0.8+) 스위퍼가 단일 반복에서 처리하는 스레드 수를 설정해요. 기본값은 10000 (Agent server v0.12+) 또는 1000 (Agent server v0.8-0.11)이에요.

전역 TTL 구성은 새 스레드에 적용돼요. delete 전략은 기존 스레드에 소급 적용되지 않아요. keep_latest 전략은 런이 끝나거나 상태가 업데이트된 후 기존 스레드에 적용돼요. 비활성 기존 스레드는 변경되지 않아요.

스토어 항목 TTL 구성하기

스토어 항목은 크로스 스레드 데이터 영속성을 가능하게 해요. 스토어 항목에 대한 TTL을 구성하면 오래된 데이터를 제거해서 메모리를 관리하는 데 도움이 돼요.

langgraph.json 파일에 store.ttl 구성을 추가하세요:

{
  "dependencies": ["."],
  "graphs": {
    "agent": "./agent.py:graph"
  },
  "store": {
    "ttl": {
      "refresh_on_read": true,
      "sweep_interval_minutes": 120,
      "default_ttl": 10080
    }
  }
}

refresh_on_read: (선택, 기본값 true) true면 get 또는 search로 항목에 접근하면 만료 타이머가 초기화돼요. false면 TTL은 put에서만 갱신돼요.
sweep_interval_minutes: (선택, 기본값 5) 시스템이 만료된 항목을 확인하는 주기(분)를 정의해요.
default_ttl: (선택) 스토어 항목의 기본 수명(분)을 설정해요 (예: 10080분 = 7일). 이 구성이 배포된 후 생성된 항목에만 적용되며, 기존 항목은 변경되지 않아요. 이전 항목을 지워야 한다면 수동으로 삭제하세요. 생략하면 항목은 기본적으로 만료되지 않아요.

TTL 구성 결합하기

동일한 langgraph.json 파일에서 체크포인트와 스토어 항목 모두에 대해 TTL을 구성해서 각 데이터 유형에 다른 정책을 설정할 수 있어요. 예시는 다음과 같아요:

{
  "dependencies": ["."],
  "graphs": {
    "agent": "./agent.py:graph"
  },
  "checkpointer": {
    "ttl": {
      "strategy": "delete",
      "sweep_interval_minutes": 60,
      "default_ttl": 43200
    }
  },
  "store": {
    "ttl": {
      "refresh_on_read": true,
      "sweep_interval_minutes": 120,
      "default_ttl": 10080
    }
  }
}

스레드별 TTL 구성하기

스레드별 TTL 구성을 적용할 수 있어요.

thread = await client.threads.create(
    ttl={
        "strategy": "delete",
        "ttl": 43200  # 30 days in minutes
    }
)

스레드 레벨 TTL은 해당 스레드의 기본 TTL을 재정의하고 위에서 설명한 전략 동작을 사용해요.

런타임 재정의

스토어 항목의 경우 기본 수명을 재정의하려면 put에 ttl을 전달하세요. 읽기가 만료를 갱신할지 제어하려면 get 또는 search에 refresh_ttl을 전달하세요.

배포 프로세스

langgraph.json에서 TTL을 구성한 후 변경 사항을 적용하려면 LangGraph 애플리케이션을 배포하거나 재시작하세요. 로컬 개발에는 langgraph dev를, Docker 배포에는 langgraph up을 사용하세요.

다른 구성 가능한 옵션에 대한 자세한 내용은 LangGraph CLI 참조 페이지를 참고하세요.

애플리케이션에 TTL 추가하기