配置检查点存储后端

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

按环境部署

独立部署 (Kubernetes)
独立部署 (Docker)
云部署

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 键。

如果您的 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 实例必须能从云数据平面访问。像 MongoDB Atlas 这样的托管服务非常适合此用途。PostgreSQL 仍会为非检查点数据自动配置。

自定义检查点存储

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

Agent server

Core capabilities

Develop agents

Deployment guides

Studio

Auth & access control

Server customization

可用后端

默认（PostgreSQL）

设置 MongoDB 检查点存储

先决条件

选择后端

提供 MongoDB URI

连接 URI 要求

按环境部署

自定义检查点存储

相关内容

​可用后端

​默认（PostgreSQL）

​设置 MongoDB 检查点存储

​先决条件

​选择后端

​提供 MongoDB URI

​连接 URI 要求

​按环境部署

​自定义检查点存储

​相关内容

可用后端

默认（PostgreSQL）

设置 MongoDB 检查点存储

先决条件

选择后端

提供 MongoDB URI

连接 URI 要求

按环境部署

自定义检查点存储

相关内容