如何为你的应用添加 TTL

TIP

前置条件 本指南假设你已熟悉 LangSmith、持久化和跨线程持久化等概念。

LangSmith 会同时持久化检查点（线程状态）和跨线程记忆（存储项）。你可以在 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"。
  • "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）。

NOTE

全局 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
    }
)

NOTE

线程级别的 TTL 会覆盖该线程的默认 TTL，并沿用上文所述的策略行为。

运行时覆盖

对于存储项，可以向 put 传入 ttl 来覆盖默认的生命周期。向 get 或 search 传入 refresh_ttl，可以控制读取操作是否刷新过期时间。

部署流程

在 langgraph.json 中配置完 TTL 后，请部署或重启你的 LangGraph 应用，以使更改生效。本地开发可使用 langgraph dev，Docker 部署可使用 langgraph up。

有关其他可配置选项的详细信息，请参阅 LangGraph CLI 参考页。

---