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

前提条件

仅适用于 LangGraph 平台

TTL 仅支持 LangGraph 平台部署。本指南不适用于 LangGraph 开源版本。

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（Time-To-Live，生存时间）有助于通过移除陈旧数据来管理内存。

在你的 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
    }
  }
}

运行时覆盖¶

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

部署流程¶

在 langgraph.json 中配置 TTL（生存时间）后，部署或重启你的 LangGraph 应用程序以使更改生效。对于本地开发，使用 langgraph dev；对于 Docker 部署，使用 langgraph up。

有关其他可配置选项的更多详细信息，请参阅 langgraph.json CLI 参考。