如何为您的LangGraph应用程序添加TTL¶

先决条件

仅限LangGraph平台

TTL仅支持LangGraph平台部署。此指南不适用于LangGraph OSS。

LangGraph平台会持久化检查点（线程状态）和跨线程内存（存储项）。您可以在langgraph.json中配置时间至失效（TTL）策略，以自动管理这些数据的生命周期，防止无限积累。

配置检查点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"，这意味着当检查点过期时会删除该线程中的所有检查点。
sweep_interval_minutes: 定义系统检查过期检查点的频率，单位为分钟。
default_ttl: 设置检查点默认的有效期，单位为分钟（例如，43200分钟=30天）。

配置存储项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: （可选）定义系统检查过期项的频率（以分钟为单位）。如果未指定，则不会执行清理操作。
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
    }
  }
}

运行时覆盖¶

可以通过在SDK方法调用（如get、put和search）中提供特定的TTL值来覆盖来自langgraph.json的默认store.ttl设置。

部署流程¶

在配置了 langgraph.json 中的 TTL 值后，部署或重启你的 LangGraph 应用程序以使更改生效。使用 langgraph dev 进行本地开发，或使用 langgraph up 进行 Docker 部署。

更多关于其他可配置选项的细节，请参阅 langgraph.json CLI 参考。