配置检查点后端

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

无论使用哪种检查点后端，LangSmith 始终需要 PostgreSQL 来存储线程、运行、助手、定时任务和内存存储的数据。检查点后端只控制检查点数据的存储位置。

可用后端

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

默认后端（PostgreSQL）

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

设置 MongoDB 检查点

需要 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

按环境部署

Standalone (Kubernetes)
Standalone (Docker)
Cloud

langgraph-cloud Helm 图表（v0.2.6+）内置了 MongoDB 支持。可以在 values 文件中启用：内置 MongoDB（开发和测试）：

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

该图表会部署单节点 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 键。

如果你的 langgraph.json 已经将 backend 设置为 "mongo"，则只需提供 URI。否则，请同时设置这两个环境变量：

docker run \
    --env-file .env \
    -p 8123:8000 \
    -e REDIS_URI="redis://redis:6379" \
    -e DATABASE_URI="postgres://postgres:postgres@postgres:5432/postgres" \
    -e LS_DEFAULT_CHECKPOINTER_BACKEND=mongo \
    -e LS_MONGODB_URI="mongodb://mongo:27017/langgraph?replicaSet=rs0" \
    -e LANGSMITH_API_KEY="..." \
    my-image

有关包含 MongoDB 的完整 Docker Compose 示例，请参阅独立服务器指南。

在 langgraph.json 中将 backend 设置为 "mongo"，然后在 LangSmith UI 的部署设置中添加 LS_MONGODB_URI 环境变量。MongoDB 实例必须能够从 Cloud 数据平面访问。使用 MongoDB Atlas 等托管服务是一个不错的选择。非检查点数据仍会自动配置 PostgreSQL。

自定义检查点

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

Develop your application

Capabilities

How to build

Auth & access control

Server customization

可用后端

默认后端（PostgreSQL）

设置 MongoDB 检查点

前提条件

选择后端

提供 MongoDB URI

连接 URI 要求

按环境部署

自定义检查点

相关内容

​可用后端

​默认后端（PostgreSQL）

​设置 MongoDB 检查点

​前提条件

​选择后端

​提供 MongoDB URI

​连接 URI 要求

​按环境部署

​自定义检查点

​相关内容

可用后端

默认后端（PostgreSQL）

设置 MongoDB 检查点

前提条件

选择后端

提供 MongoDB URI

连接 URI 要求

按环境部署

自定义检查点

相关内容