配置检查点器后端

配置 Agent Server 使用 PostgreSQL、MongoDB 或自定义实现来存储检查点。

Agent Server 通过检查点器后端持久化图状态。默认情况下，LangSmith 会将检查点与其他服务器数据一起存储在 PostgreSQL 中。你可以切换到 MongoDB，或者提供自定义实现。

NOTE

无论使用哪种检查点器后端，LangSmith 始终需要 PostgreSQL 来存储线程、运行、助手、cron 定时任务以及记忆存储。检查点器后端只负责决定检查点数据存放在哪里。

可用后端

后端	存储	配置	适用场景
default	PostgreSQL	无需配置（内置）	标准部署
mongo	MongoDB	langgraph.json 或 LS_DEFAULT_CHECKPOINTER_BACKEND 环境变量	已有 MongoDB 基础设施的团队
custom	由用户提供	langgraph.json	自定义存储后端（参见自定义检查点器）

默认（PostgreSQL）

PostgreSQL 是默认的检查点器后端，无需任何配置。若要使用自定义的 PostgreSQL 实例，请设置 POSTGRES_URI_CUSTOM 环境变量。

设置 MongoDB 检查点持久化

INFO

需要 Agent Server v0.7.64 或更高版本。

前提条件

• 一个 MongoDB 副本集（不支持单机版 mongod）。它可以是自管理的副本集、mongos 路由，或 MongoDB Atlas 这类托管服务。
• 一个在路径中包含数据库名的连接 URI（例如 /langgraph）。

选择后端

使用以下任一方式将后端设置为 "mongo"：

在 langgraph.json 中（应用级——与应用代码打包在一起）：

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

通过环境变量（平台级——适用于管理独立部署的运维人员）：

LS_DEFAULT_CHECKPOINTER_BACKEND=mongo

该环境变量会为那些没有在 langgraph.json 中指定后端的 agent server 设置默认后端。如果 langgraph.json 中包含 backend 值，则以它的取值为准。

提供 MongoDB URI

在部署时设置 LS_MONGODB_URI 环境变量：

LS_MONGODB_URI="mongodb://user:password@host:27017/langgraph?replicaSet=rs0"

连接 URI 要求

该 URI 必须：

• 指向副本集的某个成员或 mongos 路由
• 在路径中包含目标数据库名

有效示例：

mongodb://user:password@host:27017/langgraph?replicaSet=rs0
mongodb://host1:27017,host2:27017,host3:27017/mydb?replicaSet=prod-rs
mongodb+srv://user:password@cluster.example.net/langgraph

按环境部署

langgraph-cloud Helm chart（v0.2.6 及以上版本）内置了 MongoDB 支持。在你的 values 文件中启用它：

内置 MongoDB（开发与测试）：

mongo:
  enabled: true
  resources:
    requests:
      cpu: 500m
      memory: 1Gi
  persistence:
    size: 8Gi

该 chart 会部署一个单节点 MongoDB 副本集，并自动将服务器配置为使用它。

外部 MongoDB（生产环境）：

mongo:
  enabled: true
  external:
    enabled: true
    connectionUrl: "mongodb://user:password@mongo.example.net:27017/langgraph?replicaSet=rs0"

或者引用一个已有的 Kubernetes Secret：

mongo:
  enabled: true
  external:
    enabled: true
    existingSecretName: "my-mongo-secret"

该 Secret 必须包含 mongodb_connection_url 键。

自定义检查点器

若要使用 PostgreSQL 或 MongoDB 之外的存储后端，请实现自定义的 BaseCheckpointSaver。详见添加自定义检查点器。

相关

• 为检查点和存储项的过期配置 TTL
• LangGraph 中的持久化概念
• 数据平面架构
• 环境变量参考

---