LangGraph CLI

LangGraph CLI 是一个用于在本地构建和运行 Agent Server 的命令行工具。生成的服务器会公开用于运行、线程、助手等功能的所有 API 端点，并包含检查点和存储所需的托管数据库等支持服务。

安装

确保已安装 Docker（例如：docker --version）。

安装 CLI：

pip install langgraph-cli

# 按需使用最新版本
npx @langchain/langgraph-cli

# 或全局安装（安装后可使用 `langgraphjs`）
npm install -g @langchain/langgraph-cli

验证安装

langgraph --help

npx @langchain/langgraph-cli --help

快速命令

命令	功能
`langgraph dev`	启动轻量级本地开发服务器（无需 Docker），适合快速测试。
`langgraph build`	构建用于部署的 LangGraph API 服务器 Docker 镜像。
`langgraph deploy`	构建 LangGraph 镜像并将其直接部署到 LangSmith Deployments，一步完成。
`langgraph dockerfile`	根据配置生成 Dockerfile，用于自定义构建。
`langgraph up`	在本地 Docker 中启动 LangGraph API 服务器。需要运行 Docker；本地开发需要 LangSmith API 密钥，生产环境需要许可证。

对于 JS，请使用 npx @langchain/langgraph-cli <command>（如果已全局安装，也可以使用 langgraphjs）。

配置文件

要构建和运行有效的应用程序，LangGraph CLI 需要一个符合此架构的 JSON 配置文件。该文件包含以下属性：

LangGraph CLI 默认使用当前目录中名为 langgraph.json 的配置文件。

Python
JS

键	描述
`dependencies`	必需。LangSmith API 服务器的依赖项数组。依赖项可以是以下内容之一：单个句点（`"."`），表示查找本地 Python 包。 `pyproject.toml`、`setup.py` 或 `requirements.txt` 所在的目录路径。例如，如果 `requirements.txt` 位于项目目录的根目录中，请指定 `"./"`。如果它位于名为 `local_package` 的子目录中，请指定 `"./local_package"`。不要直接指定字符串 `"requirements.txt"`。 Python 包名称。
`graphs`	必需。将图 ID 映射到已编译图或图构建函数所在路径。例如： `./your_package/your_file.py:variable`，其中 `variable` 是 `langgraph.graph.state.CompiledStateGraph` 的实例。 `./your_package/your_file.py:make_graph`，其中 `make_graph` 是一个接收配置字典（`langchain_core.runnables.RunnableConfig`）并返回 `langgraph.graph.state.StateGraph` 或 `langgraph.graph.state.CompiledStateGraph` 实例的函数。更多详情请参阅如何在运行时重新构建图。
`auth`	(在 v0.0.11 中添加)。身份验证配置，包含身份验证处理程序的路径。例如：`./your_package/auth.py:auth`，其中 `auth` 是 `langgraph_sdk.Auth` 的实例。详情请参阅身份验证指南。
`base_image`	可选。LangGraph API 服务器使用的基础镜像。默认为 `langchain/langgraph-api` 或 `langchain/langgraphjs-api`。可使用此项将构建固定到特定版本的 langgraph API，例如 `"langchain/langgraph-server:0.2"`。更多详情请参阅 https://hub.docker.com/r/langchain/langgraph-server/tags。（在 `langgraph-cli==0.2.8` 中添加）
`image_distro`	可选。基础镜像使用的 Linux 发行版。必须是 `"debian"`、`"wolfi"`、`"bookworm"` 或 `"bullseye"` 之一。省略时默认为 `"debian"`。适用于 `langgraph-cli>=0.2.11`。
`env`	`.env` 文件的路径，或从环境变量到其值的映射。
`store`	用于向 BaseStore 添加语义搜索和/或生存时间（TTL）的配置。包含以下字段： `index`（可选）：语义搜索索引配置，包含 `embed`、`dims` 和可选的 `fields` 字段。 `ttl`（可选）：条目过期配置。对象包含以下可选字段：`refresh_on_read`（布尔值，默认为 `true`）、`default_ttl`（浮点数，生命周期以分钟为单位；仅应用于新创建的条目；现有条目不会更改；默认为不过期）以及 `sweep_interval_minutes`（整数，检查过期条目的频率，默认为不执行清理）。
`ui`	可选。由代理生成的 UI 组件的命名定义，每个定义指向一个 JS/TS 文件。（在 `langgraph-cli==0.1.84` 中添加）
`python_version`	`3.11`、`3.12` 或 `3.13`。默认为 `3.11`。
`node_version`	指定 `node_version: 20` 以使用 LangGraph.js。
`pip_config_file`	`pip` 配置文件的路径。
`pip_installer`	(在 v0.3 中添加) 可选。Python 包安装程序选择器。可以设置为 `"auto"`、`"pip"` 或 `"uv"`。从 0.3 版本开始，默认策略是运行 `uv pip`，通常可以在保持即插即用替代能力的同时提供更快的构建速度。如果 `uv` 无法处理依赖关系图或 `pyproject.toml` 的结构这一少见情况，请在此处指定 `"pip"`，以恢复之前的行为。
`keep_pkg_tools`	(在 v0.3.4 中添加) 可选。控制是否在最终镜像中保留 Python 打包工具（`pip`、`setuptools`、`wheel`）。可接受的值： `true`：保留全部三个工具（跳过卸载）。 `false` / 省略：卸载全部三个工具（默认行为）。 `list[str]`：指定要保留的工具名称。每个值必须是 “pip”、“setuptools”、“wheel” 之一。。默认情况下，三个工具都会被卸载。
`dockerfile_lines`	要添加到 Dockerfile 中、位于从父镜像导入内容之后的附加行数组。
`checkpointer`	检查点器配置。支持： `backend`（可选）：`"default"`、`"mongo"` 或 `"custom"`。默认为 `"default"`（PostgreSQL）。请参阅配置检查点器后端。 `path`（可选）：自定义检查点器工厂的路径（当 `backend` 为 `"custom"` 时）。请参阅自定义检查点器。 `ttl`（可选）：包含 `strategy`、`sweep_interval_minutes`、`default_ttl` 和 `sweep_limit` 的对象（Agent server v0.8+），用于控制检查点过期。 `serde`（可选，Agent server v0.5+）：包含 `allowed_json_modules` 和 `pickle_fallback` 的对象，用于调整反序列化行为。
`http`	HTTP 服务器配置，包含以下字段： `app`：自定义 Starlette/FastAPI 应用的路径（例如 `"./src/agent/webapp.py:app"`）。请参阅自定义路由指南。 `cors`：CORS 配置，包含 `allow_origins`、`allow_methods`、`allow_headers`、`allow_credentials`、`allow_origin_regex`、`expose_headers` 和 `max_age` 等字段。 `configurable_headers`：通过 `includes` / `excludes` 模式定义要公开为可配置值的请求标头。 `logging_headers`：`configurable_headers` 的镜像配置，用于从日志中排除敏感标头。 `middleware_order`：选择自定义中间件与身份验证的交互方式。`auth_first` 会先运行身份验证钩子，再运行自定义中间件；`middleware_first`（默认值）则先运行中间件。 `enable_custom_route_auth`：将身份验证检查应用于通过 `app` 添加的路由。路由禁用标志——按需关闭内置端点组： `disable_meta`：禁用 `/`（根路径）、`/info`、`/metrics`、`/docs` 和 `/openapi.json` 系统路由。`/ok` 健康检查仍可用。 `disable_assistants`：禁用所有 `/assistants/` 路由。 `disable_runs`：禁用所有 `/runs/` 路由。 `disable_threads`：禁用所有 `/threads/` 路由。 `disable_store`：禁用所有 `/store/` 路由。 `disable_ui`：禁用所有 `/ui/` 路由。 `disable_mcp`：禁用 `/mcp` 端点。请参阅禁用 MCP。 `disable_a2a`：禁用 `/a2a/` 端点。请参阅禁用 A2A。 `disable_webhooks`：禁用运行完成时的 Webhook 传送（不是路由开关）。请参阅禁用 Webhook。 `mount_prefix`：挂载路由的前缀（例如 `"/my-deployment/api"`）。
`webhooks`	(在 v0.5.36 中添加) 出站 Webhook 传送配置。包含： `env_prefix`：标头模板中引用的环境变量所需的前缀（默认为 `LG_WEBHOOK_`）。 `headers`：随 Webhook 请求发送的静态标头。值可以包含 `${{ env.VAR }}` 等模板。 `url`：URL 验证策略，包含 `allowed_domains`、`allowed_ports`、`require_https`、`disable_loopback` 和 `max_url_length`。
`api_version`	(在 v0.3.7 中添加) 要使用的 LangGraph API 服务器语义版本（例如 `"0.3"`）。默认为最新版本。有关各版本的详情，请查看服务器更新日志。

键	描述
`graphs`	必需。将图 ID 映射到已编译图或图构建函数所在路径。例如： `./src/graph.ts:variable`，其中 `variable` 是 `CompiledStateGraph` 的实例。 `./src/graph.ts:makeGraph`，其中 `makeGraph` 是一个接收配置字典（`LangGraphRunnableConfig`）并返回 `StateGraph` 或 `CompiledStateGraph` 实例的函数。更多详情请参阅如何在运行时重新构建图。
`env`	`.env` 文件的路径，或从环境变量到其值的映射。
`store`	用于向 BaseStore 添加语义搜索和/或生存时间（TTL）的配置。包含以下字段： `index`（可选）：语义搜索索引配置，包含 `embed`、`dims` 和可选的 `fields` 字段。 `ttl`（可选）：条目过期配置。对象包含以下可选字段：`refresh_on_read`（布尔值，默认为 `true`）、`default_ttl`（浮点数，生命周期以分钟为单位；仅应用于新创建的条目；现有条目不会更改；默认为不过期）以及 `sweep_interval_minutes`（整数，检查过期条目的频率，默认为不执行清理）。
`node_version`	指定 `node_version: 20` 以使用 LangGraph.js。
`dockerfile_lines`	要添加到 Dockerfile 中、位于从父镜像导入内容之后的附加行数组。
`checkpointer`	检查点器配置。支持： `backend`（可选）：`"default"`、`"mongo"` 或 `"custom"`。默认为 `"default"`（PostgreSQL）。请参阅配置检查点器后端。 `path`（可选）：自定义检查点器工厂的路径（当 `backend` 为 `"custom"` 时）。请参阅自定义检查点器。 `ttl`（可选）：包含 `strategy`、`sweep_interval_minutes`、`default_ttl` 和 `sweep_limit` 的对象（Agent server v0.8+），用于控制检查点过期。 `serde`（可选，Agent server v0.5+）：包含 `allowed_json_modules` 和 `pickle_fallback` 的对象，用于调整反序列化行为。
`http`	与 Python 选项对应的 HTTP 服务器配置： `cors`，包含 `allow_origins`、`allow_methods`、`allow_headers`、`allow_credentials`、`allow_origin_regex`、`expose_headers` 和 `max_age`。 `configurable_headers` 和 `logging_headers` 模式列表。 `middleware_order`（`auth_first` 或 `middleware_first`）。 `enable_custom_route_auth` 以及与上文相同的布尔路由开关。
`webhooks`	(在 v0.5.36 中添加) 出站 Webhook 传送配置。包含： `env_prefix`：标头模板中引用的环境变量所需的前缀（默认为 `LG_WEBHOOK_`）。 `headers`：随 Webhook 请求发送的静态标头。值可以包含 `${{ env.VAR }}` 等模板。 `url`：URL 验证策略，包含 `allowed_domains`、`allowed_ports`、`require_https`、`disable_loopback` 和 `max_url_length`。
`api_version`	(在 v0.3.7 中添加) 要使用的 LangGraph API 服务器语义版本（例如 `"0.3"`）。默认为最新版本。有关各版本的详情，请查看服务器更新日志。

示例

Python
JS

基本配置

{
  "$schema": "https://langgra.ph/schema.json",
  "dependencies": ["."],
  "graphs": {
    "chat": "chat.graph:graph"
  }
}

使用 Wolfi 基础镜像

可以使用 image_distro 字段指定基础镜像的 Linux 发行版。有效选项包括 debian、wolfi、bookworm 和 bullseye。推荐使用 Wolfi，因为它可以提供更小、更安全的镜像。此功能适用于 langgraph-cli>=0.2.11。

{
  "$schema": "https://langgra.ph/schema.json",
  "dependencies": ["."],
  "graphs": {
    "chat": "chat.graph:graph"
  },
  "image_distro": "wolfi"
}

向存储添加语义搜索

所有部署都自带由数据库支持的 BaseStore。在 langgraph.json 中添加 "index" 配置，即可在部署的 BaseStore 中启用语义搜索。index.fields 配置决定要嵌入文档中的哪些部分：

如果省略或设置为 ["$"]，则会嵌入整个文档
若要嵌入特定字段，请使用 JSON 路径表示法：["metadata.title", "content.text"]
缺少指定字段的文档仍会被存储，但这些字段不会生成嵌入
在调用 put 时，仍可以通过 index 参数覆盖特定条目要嵌入的字段

{
  "dependencies": ["."],
  "graphs": {
    "memory_agent": "./agent/graph.py:graph"
  },
  "store": {
    "index": {
      "embed": "openai:text-embedding-3-small",
      "dims": 1536,
      "fields": ["$"]
    }
  }
}

常见模型维度

openai:text-embedding-3-large：3072
openai:text-embedding-3-small：1536
openai:text-embedding-ada-002：1536
cohere:embed-english-v3.0：1024
cohere:embed-english-light-v3.0：384
cohere:embed-multilingual-v3.0：1024
cohere:embed-multilingual-light-v3.0：384

使用自定义嵌入函数进行语义搜索

如果希望使用自定义嵌入函数进行语义搜索，可以传入自定义嵌入函数的路径：

{
  "dependencies": ["."],
  "graphs": {
    "memory_agent": "./agent/graph.py:graph"
  },
  "store": {
    "index": {
      "embed": "./embeddings.py:embed_texts",
      "dims": 768,
      "fields": ["text", "summary"]
    }
  }
}

存储配置中的 embed 字段可以引用一个自定义函数，该函数接收字符串列表并返回嵌入列表。实现示例：

# embeddings.py
def embed_texts(texts: list[str]) -> list[list[float]]:
    """用于语义搜索的自定义嵌入函数。"""
    # 使用你首选的嵌入模型实现
    return [[0.1, 0.2, ...] for _ in texts]  # 维度为 dims 的向量

添加自定义身份验证

{
  "$schema": "https://langgra.ph/schema.json",
  "dependencies": ["."],
  "graphs": {
    "chat": "chat.graph:graph"
  },
  "auth": {
    "path": "./auth.py:auth",
    "openapi": {
      "securitySchemes": {
        "apiKeyAuth": {
          "type": "apiKey",
          "in": "header",
          "name": "X-API-Key"
        }
      },
      "security": [{ "apiKeyAuth": [] }]
    },
    "disable_studio_auth": false
  }
}

详情请参阅身份验证概念指南，实际操作流程请参阅设置自定义身份验证指南。

配置存储条目的生存时间

可以使用 store.ttl 键配置 BaseStore 中条目/记忆的默认数据过期时间。该设置决定条目在最后一次访问后保留多长时间（读取操作是否刷新计时器取决于 refresh_on_read）。请注意，可以通过修改 get、search 等操作中的相应参数，针对每次调用覆盖这些默认值。ttl 配置是一个包含以下可选字段的对象：

refresh_on_read：如果为 true（默认值），通过 get 或 search 访问条目时会重置其过期计时器。设置为 false 后，只有写入操作（put）会刷新 TTL。
default_ttl：条目的默认生命周期，单位为分钟。仅应用于新创建的条目；现有条目不会被修改。如果未设置，条目默认不会过期。
sweep_interval_minutes：系统运行后台进程删除过期条目的频率，单位为分钟。如果未设置，则不会自动执行清理。

以下示例启用了 7 天 TTL（10080 分钟），在读取时刷新，并每小时执行一次清理：

{
  "$schema": "https://langgra.ph/schema.json",
  "dependencies": ["."],
  "graphs": {
    "memory_agent": "./agent/graph.py:graph"
  },
  "store": {
    "ttl": {
      "refresh_on_read": true,
      "sweep_interval_minutes": 60,
      "default_ttl": 10080
    }
  }
}

配置检查点生存时间

可以使用 checkpointer 键配置检查点的生存时间（TTL）。该设置决定检查点数据在根据指定策略（例如删除）自动处理前保留多长时间。支持以下两个可选子对象：

ttl：包含 strategy、sweep_interval_minutes、default_ttl 和 sweep_limit（Agent server v0.8+），这些字段共同决定检查点的过期方式。
serde （Agent server v0.5+）：用于控制检查点负载的反序列化行为。

以下示例将默认 TTL 设置为 30 天（43200 分钟）：

{
  "$schema": "https://langgra.ph/schema.json",
  "dependencies": ["."],
  "graphs": {
    "chat": "chat.graph:graph"
  },
  "checkpointer": {
    "ttl": {
      "strategy": "delete",
      "sweep_interval_minutes": 10,
      "default_ttl": 43200
    }
  }
}

在此示例中，超过 30 天的检查点将被删除，并且每 10 分钟检查一次。

配置检查点器 serde

checkpointer.serde 对象用于调整反序列化行为：

allowed_json_modules 定义一个允许列表，指定服务器可以从以 “json” 模式保存的负载中反序列化的自定义 Python 对象。这是一个由 [path, to, module, file, symbol] 序列组成的列表。如果省略，则只允许 LangChain 安全默认值。也可以不安全地将其设置为 true，允许反序列化任何模块。
pickle_fallback：JSON 解码失败时是否回退到 pickle 反序列化。

{
  "checkpointer": {
    "serde": {
      "allowed_json_modules": [
        ["my_agent", "auth", "SessionState"]
      ]
    }
  }
}

自定义 HTTP 中间件和标头

http 块用于精细调整请求处理：

middleware_order：选择 "auth_first"，先运行身份验证，再运行中间件；或者选择 "middleware_first"（默认值），反转这一顺序。
enable_custom_route_auth：将身份验证扩展到通过 http.app 挂载的路由。
configurable_headers / logging_headers：每项都接受一个包含可选 includes 和 excludes 数组的对象；支持通配符，并且会先处理排除项，再处理包含项。

cors：自定义服务器的 CORS（跨域资源共享）配置。以下是用于配置 CORS 的 langgraph.json 文件示例：

{
  ...
  "http": {
    "cors": {
      "allow_origins": ["https://example.com", "https://app.example.com"],
      "allow_methods": ["GET", "POST"],
      "allow_headers": ["Authorization", "Content-Type"],
      "allow_credentials": true,
      "allow_origin_regex": "^https://.*\\.example\\.com$",
      "expose_headers": ["x-pagination-total", "x-pagination-next", "x-request-id"],
      "max_age": 600
    }
  },
  ...
}

自定义服务器的 CORS 配置会覆盖设置 CORS_ALLOW_ORIGINS 环境变量的功能。

配置 Webhook

可以为出站 Webhook 请求配置自定义标头和 URL 限制：

{
  "$schema": "https://langgra.ph/schema.json",
  "dependencies": ["."],
  "graphs": {
    "chat": "chat.graph:graph"
  },
  "webhooks": {
    "headers": {
      "Authorization": "Bearer ${{ env.LG_WEBHOOK_TOKEN }}"
    },
    "url": {
      "allowed_domains": ["*.mycompany.com"],
      "require_https": true
    }
  }
}

有关标头配置、环境变量模板和 URL 限制的详情，请参阅使用 Webhook。

固定 API 版本

(在 v0.3.7 中添加)可以使用 api_version 键固定 Agent Server 的 API 版本。如果希望确保服务器使用特定版本的 API，这会很有用。默认情况下，Cloud 部署中的构建使用服务器的最新稳定版本。可以将 api_version 键设置为特定版本来固定版本。

{
  "$schema": "https://langgra.ph/schema.json",
  "dependencies": ["."],
  "graphs": {
    "chat": "chat.graph:graph"
  },
  "api_version": "0.2"
}

禁用内置路由

可以使用 http 配置块中的布尔标志，按需禁用内置 HTTP 路由组。这对于希望尽量减少服务器公开接口范围的生产部署非常有用。例如，要禁用系统信息和文档路由：

{
  "$schema": "https://langgra.ph/schema.json",
  "dependencies": ["."],
  "graphs": {
    "chat": "chat.graph:graph"
  },
  "http": {
    "disable_meta": true
  }
}

将 disable_meta 设置为 true 会禁用以下路由：

/ — 根健康检查
/info — 服务器版本和配置信息
/metrics — Prometheus 和 JSON 指标
/docs — API 文档 UI
/openapi.json — OpenAPI 规范

即使设置了 disable_meta，/ok 健康检查端点仍然可用，因此 Kubernetes 等编排器仍可以执行存活性和就绪性探测。其他路由禁用标志包括 disable_assistants、disable_runs、disable_threads、disable_store 和 disable_ui。有关 MCP、A2A 和 Webhook，请参阅相应指南：禁用 MCP、禁用 A2A、禁用 Webhook。

基本配置

{
  "$schema": "https://langgra.ph/schema.json",
  "graphs": {
    "chat": "./src/graph.ts:graph"
  }
}

固定 API 版本

{
  "$schema": "https://langgra.ph/schema.json",
  "dependencies": ["."],
  "graphs": {
    "chat": "./src/chat/graph.ts:graph"
  },
  "api_version": "0.2"
}

禁用内置路由

{
  "$schema": "https://langgra.ph/schema.json",
  "graphs": {
    "chat": "./src/chat/graph.ts:graph"
  },
  "http": {
    "disable_meta": true
  }
}

将 disable_meta 设置为 true 会禁用以下路由：

/ — 根健康检查
/info — 服务器版本和配置信息
/metrics — Prometheus 和 JSON 指标
/docs — API 文档 UI
/openapi.json — OpenAPI 规范

命令

用法

Python
JS

LangGraph CLI 的基础命令是 langgraph。

langgraph [OPTIONS] COMMAND [ARGS]

LangGraph.js CLI 的基础命令是 langgraphjs。

npx @langchain/langgraph-cli [OPTIONS] COMMAND [ARGS]

建议使用 npx，以始终使用 CLI 的最新版本。

`dev`

Python
JS

以开发模式运行 LangGraph API 服务器，支持热重载和调试功能。此轻量级服务器无需安装 Docker，适合开发和测试。状态会持久化到本地目录。

目前，CLI 仅支持 Python >= 3.11。

如需了解何时使用 langgraph dev 或 langgraph up，请参阅本地开发与测试指南，其中包含详细对比。

安装此命令要求安装 "inmem" extra：

pip install -U "langgraph-cli[inmem]"

用法

langgraph dev [OPTIONS]

选项

选项	默认值	描述
`-c, --config FILE`	`langgraph.json`	声明依赖项、图和环境变量的配置文件路径
`--host TEXT`	`127.0.0.1`	服务器要绑定的主机
`--port INTEGER`	`2024`	服务器要绑定的端口
`--no-reload`		禁用自动重载
`--n-jobs-per-worker INTEGER`		每个工作进程的任务数。默认为 10
`--debug-port INTEGER`		调试器监听的端口
`--wait-for-client`	`False`	启动服务器前等待调试器客户端连接到调试端口
`--no-browser`		服务器启动时跳过自动打开浏览器
`--studio-url TEXT`		要连接的 Studio 实例 URL。默认为 https://smith.langchain.com
`--allow-blocking`	`False`	不为代码中的同步 I/O 阻塞操作抛出错误（在 `0.2.6` 中添加）
`--tunnel`	`False`	通过公共隧道（Cloudflare）公开本地服务器，以便远程前端访问。这样可以避免 Safari 等浏览器或阻止 localhost 连接的网络所导致的问题
`--help`		显示命令文档

以开发模式运行 LangGraph API 服务器，支持热重载。此轻量级服务器无需安装 Docker，适合开发和测试。状态会持久化到本地目录。用法

npx @langchain/langgraph-cli dev [OPTIONS]

选项

选项	默认值	描述
`-c, --config FILE`	`langgraph.json`	声明依赖项、图和环境变量的配置文件路径
`--host TEXT`	`127.0.0.1`	服务器要绑定的主机
`--port INTEGER`	`2024`	服务器要绑定的端口
`--no-reload`		禁用自动重载
`--n-jobs-per-worker INTEGER`		每个工作进程的任务数。默认为 10
`--debug-port INTEGER`		调试器监听的端口
`--wait-for-client`	`False`	启动服务器前等待调试器客户端连接到调试端口
`--no-browser`		服务器启动时跳过自动打开浏览器
`--studio-url TEXT`		要连接的 Studio 实例 URL。默认为 https://smith.langchain.com
`--allow-blocking`	`False`	不为代码中的同步 I/O 阻塞操作抛出错误
`--tunnel`	`False`	通过公共隧道（Cloudflare）公开本地服务器，以便远程前端访问。这样可以避免浏览器或网络阻止 localhost 连接所导致的问题
`--help`		显示命令文档

`build`

Python
JS

构建 LangSmith API 服务器 Docker 镜像。用法

langgraph build [OPTIONS]

选项

选项	默认值	描述
`--platform TEXT`		要构建 Docker 镜像的目标平台。示例：`langgraph build --platform linux/amd64,linux/arm64`
`-t, --tag TEXT`		必需。Docker 镜像的标签。示例：`langgraph build -t my-image`
`--pull / --no-pull`	`--pull`	使用最新的远程 Docker 镜像进行构建。在使用本地构建的镜像运行 LangSmith API 服务器时，请使用 `--no-pull`。
`-c, --config FILE`	`langgraph.json`	声明依赖项、图和环境变量的配置文件路径。
`--build-command TEXT`^*		要运行的构建命令。从 `langgraph.json` 文件所在目录运行。示例：`langgraph build --build-command "yarn run turbo build"`
`--install-command TEXT`^*		要运行的安装命令。从执行 `langgraph build` 的目录运行。示例：`langgraph build --install-command "yarn install"`
`--help`		显示命令文档。

^*仅 JS 部署支持，对 Python 部署没有影响。

构建 LangSmith API 服务器 Docker 镜像。用法

npx @langchain/langgraph-cli build [OPTIONS]

选项

选项	默认值	描述
`--platform TEXT`		要构建 Docker 镜像的目标平台。示例：`langgraph build --platform linux/amd64,linux/arm64`
`-t, --tag TEXT`		必需。Docker 镜像的标签。示例：`langgraph build -t my-image`
`--no-pull`		使用本地构建的镜像。默认为 `false`，即使用最新的远程 Docker 镜像进行构建。
`-c, --config FILE`	`langgraph.json`	声明依赖项、图和环境变量的配置文件路径。
`--help`		显示命令文档。

`deploy`

Python

此命令处于测试阶段，仍在积极开发中。预计会频繁更新和改进。

将 LangGraph 镜像直接构建并部署到 LangSmith Deployments。此命令会在本地构建 Docker 镜像，将其推送到托管注册表，然后创建或更新部署，一步完成。如果未安装 Docker，则会触发远程构建。前置条件

具有 Deployments 访问权限的 LangSmith API 密钥。
（可选）本地构建需要安装 Docker 并运行 Docker 守护进程。远程构建不需要 Docker。安装 Docker Desktop。

仅适用于 LangSmith Cloud。

用法

langgraph deploy [OPTIONS] [DOCKER_BUILD_ARGS]

此命令还接受所有 langgraph build 标志（--platform、-t、--pull、--no-pull、-c）。详情请参阅 langgraph build --help。选项

选项	默认值	描述
`--api-key TEXT`		LangSmith Deployments 的 API 密钥。也可以通过 `LANGGRAPH_HOST_API_KEY`、`LANGSMITH_API_KEY` 或 `LANGCHAIN_API_KEY` 环境变量或 `.env` 文件设置。
`--name TEXT`	当前目录名称	部署名称。也可以通过 `LANGSMITH_DEPLOYMENT_NAME` 环境变量或 `.env` 文件设置。
`--deployment-id TEXT`		要更新的现有部署 ID。如果省略，则使用 `--name` 查找或创建部署。
`--deployment-type TEXT`	`serverless`	在 Cloud 上创建新部署时的部署类型：采用新的基于用量的定价时为 `serverless` 或 `dedicated`；仍使用旧定价的组织则为 `dev` 或 `prod`。
`--remote / --no-remote`		强制使用远程或本地构建。默认情况下，如果本地没有 Docker，则使用远程构建。
`--no-wait`	`False`	推送后跳过等待部署状态。
`--verbose`	`False`	显示详细输出，包括 Docker 构建和推送日志。
`--help`		显示命令文档。

对于新的按使用量计费方式，请传递 --deployment-type serverless 或 --deployment-type dedicated。在 2026 年 10 月 1 日之前仍使用旧版定价的组织，请传递 --deployment-type dev 或 --deployment-type prod，以创建开发或生产部署。有关过渡时间表，请参阅管理账单。

示例

# 使用 .env 文件中的 API 密钥进行部署
langgraph deploy

# 使用内联 API 密钥进行部署
LANGSMITH_API_KEY=lsv2_... langgraph deploy

# 更新现有部署
langgraph deploy --deployment-id abc123

# 使用内联部署名称进行部署
LANGSMITH_DEPLOYMENT_NAME=my-agent langgraph deploy

# 部署到欧盟区域
LANGGRAPH_HOST_URL=https://eu.api.host.langchain.com langgraph deploy

通过其他方式（例如 LangSmith UI 或 GitHub 集成）创建的部署，也可以使用 langgraph deploy 命令进行更新。

`deploy list`

列出 LangSmith 部署。用法

langgraph deploy list [OPTIONS]

选项

Option	Default	Description
`--name-contains TEXT`		仅显示名称包含此值的部署。
`--api-key TEXT`		API 密钥。也可以通过 `LANGGRAPH_HOST_API_KEY`、`LANGSMITH_API_KEY` 或 `LANGCHAIN_API_KEY` 环境变量，或 `.env` 文件进行设置。
`--help`		显示此消息并退出。

`deploy revisions`

[Beta] 管理部署修订版本。用法

langgraph deploy revisions [OPTIONS] COMMAND [ARGS]...

选项

Option	Default	Description
`--help`		显示此消息并退出。

命令

Command	Description
`list`	[Beta] 列出 LangSmith 部署的修订版本。

`deploy revisions list`

[Beta] 列出 LangSmith 部署的修订版本。使用 deploy list 列出部署 ID。用法

langgraph deploy revisions list [OPTIONS] DEPLOYMENT_ID

选项

Option	Default	Description
`--limit INTEGER`	`10`	要返回的最大修订版本数。
`--api-key TEXT`		API 密钥。也可以通过 `LANGGRAPH_HOST_API_KEY`、`LANGSMITH_API_KEY` 或 `LANGCHAIN_API_KEY` 环境变量，或 `.env` 文件进行设置。
`--help`		显示此消息并退出。

`deploy delete`

删除 LangSmith 部署。使用 deploy list 查找要删除的部署 ID。用法

langgraph deploy delete [OPTIONS] DEPLOYMENT_ID

选项

Option	Default	Description
`--force`		无需提示确认即可删除。
`--api-key TEXT`		API 密钥。也可以通过 `LANGGRAPH_HOST_API_KEY`、`LANGSMITH_API_KEY` 或 `LANGCHAIN_API_KEY` 环境变量，或 `.env` 文件进行设置。
`--help`		显示此消息并退出。

`deploy logs`

获取 LangSmith 部署日志。使用 deploy 获取代理运行时日志，或使用 build 获取远程构建日志。用法

langgraph deploy logs [OPTIONS]

选项

Option	Default	Description
`-f, --follow`	`False`	持续轮询新日志。
`--end-time TEXT`		ISO8601 结束时间。例如：`2026-03-08T00:00:00Z`。
`--start-time TEXT`		ISO8601 开始时间。例如：`2026-03-08T00:00:00Z`。
`-q, --query TEXT`		搜索字符串过滤器。
`--limit INTEGER`	`100`	要获取的最大日志条目数。
`--level [DEBUG\|INFO\|WARNING\|ERROR\|CRITICAL]`		按日志级别过滤。
`--revision-id TEXT`		指定修订版本 ID。对于构建日志，默认为最新修订版本。
`--type [deploy\|build]`	`deploy`	要获取的日志流。`deploy` 显示代理服务器运行时日志。`build` 显示远程构建日志。
`--deployment-id TEXT`		部署 ID。如果未提供，则使用 `--name` 查找部署。
`--name TEXT`	当前目录名称	部署名称。也可以通过 `LANGSMITH_DEPLOYMENT_NAME` 环境变量或 `.env` 文件进行设置。当未提供 `--deployment-id` 时使用。
`--api-key TEXT`		API 密钥。也可以通过 `LANGGRAPH_HOST_API_KEY`、`LANGSMITH_API_KEY` 或 `LANGCHAIN_API_KEY` 环境变量，或 `.env` 文件进行设置。
`--help`		显示此消息并退出。

`up`

Python
JS

启动 LangGraph API 服务器。进行本地测试时，需要具有 LangSmith 访问权限的 LangSmith API 密钥。用于生产环境时，需要许可证密钥。

如果需要了解何时使用 langgraph dev 与 langgraph up，请参阅本地开发与测试指南，其中提供了详细比较。

用法

langgraph up [OPTIONS]

选项

Option	Default	Description
`--wait`		在返回前等待服务启动。隐含启用 —detach
`--base-image TEXT`	`langchain/langgraph-api`	用于 LangGraph API 服务器的基础镜像。使用版本标签固定到特定版本。
`--image TEXT`		用于 langgraph-api 服务的 Docker 镜像。如果指定，则跳过构建并直接使用此镜像。
`--postgres-uri TEXT`	本地数据库	用于数据库的 Postgres URI。
`--watch`		文件发生更改时重新启动
`--debugger-base-url TEXT`	`http://127.0.0.1:[PORT]`	调试器访问 LangGraph API 时使用的 URL。
`--debugger-port INTEGER`		在本地拉取调试器镜像，并在指定端口提供 UI
`--verbose`		显示更多服务器日志输出。
`-c, --config FILE`	`langgraph.json`	配置文件路径，其中声明了依赖项、图和环境变量。
`-d, --docker-compose FILE`		包含要启动的其他服务的 docker-compose.yml 文件路径。
`-p, --port INTEGER`	`8123`	要公开的端口。例如：`langgraph up --port 8000`
`--pull / --no-pull`	`pull`	拉取最新镜像。使用 `--no-pull` 可通过本地构建的镜像运行服务器。例如：`langgraph up --no-pull`
`--recreate / --no-recreate`	`no-recreate`	即使容器的配置和镜像未发生变化，也重新创建容器
`--help`		显示命令文档。

启动 LangGraph API 服务器。进行本地测试时，需要具有 LangSmith 访问权限的 LangSmith API 密钥。用于生产环境时，需要许可证密钥。用法

npx @langchain/langgraph-cli up [OPTIONS]

选项

Option	Default	Description
`--wait`		在返回前等待服务启动。隐含启用 —detach
`--base-image TEXT`	`langchain/langgraph-api`	用于 LangGraph API 服务器的基础镜像。使用版本标签固定到特定版本。
`--image TEXT`		用于 langgraph-api 服务的 Docker 镜像。如果指定，则跳过构建并直接使用此镜像。
`--postgres-uri TEXT`	本地数据库	用于数据库的 Postgres URI。
`--watch`		文件发生更改时重新启动
`-c, --config FILE`	`langgraph.json`	配置文件路径，其中声明了依赖项、图和环境变量。
`-d, --docker-compose FILE`		包含要启动的其他服务的 docker-compose.yml 文件路径。
`-p, --port INTEGER`	`8123`	要公开的端口。例如：`langgraph up --port 8000`
`--no-pull`		使用本地构建的镜像。默认为 `false`，以便使用最新的远程 Docker 镜像进行构建。
`--recreate`		即使容器的配置和镜像未发生变化，也重新创建容器
`--help`		显示命令文档。

`dockerfile`

Python
JS

生成用于构建 LangSmith API 服务器 Docker 镜像的 Dockerfile。用法

langgraph dockerfile [OPTIONS] SAVE_PATH

选项

Option	Default	Description
`-c, --config FILE`	`langgraph.json`	声明依赖项、图和环境变量的配置文件路径。
`--help`		显示此消息并退出。

示例：

langgraph dockerfile -c langgraph.json Dockerfile

这会生成一个类似如下内容的 Dockerfile：

FROM langchain/langgraph-api:3.11

ADD ./pipconf.txt /pipconfig.txt

RUN PIP_CONFIG_FILE=/pipconfig.txt PYTHONDONTWRITEBYTECODE=1 pip install --no-cache-dir -c /api/constraints.txt langchain_anthropic langchain_openai wikipedia scikit-learn

ADD ./graphs /deps/__outer_graphs/src
RUN set -ex && \
    for line in '[project]' \
                'name = "graphs"' \
                'version = "0.1"' \
                '[tool.setuptools.package-data]' \
                '"*" = ["**/*"]'; do \
        echo "$line" >> /deps/__outer_graphs/pyproject.toml; \
    done

RUN PIP_CONFIG_FILE=/pipconfig.txt PYTHONDONTWRITEBYTECODE=1 pip install --no-cache-dir -c /api/constraints.txt -e /deps/*

ENV LANGSERVE_GRAPHS='{"agent": "/deps/__outer_graphs/src/agent.py:graph", "storm": "/deps/__outer_graphs/src/storm.py:graph"}'

langgraph dockerfile 命令会将 langgraph.json 文件中的所有配置转换为 Dockerfile 命令。使用此命令时，每次更新 langgraph.json 文件后都必须重新运行该命令。否则，在构建或运行 Dockerfile 时不会反映这些更改。

生成用于构建 LangSmith API 服务器 Docker 镜像的 Dockerfile。用法

npx @langchain/langgraph-cli dockerfile [OPTIONS] SAVE_PATH

选项

Option	Default	Description
`-c, --config FILE`	`langgraph.json`	声明依赖项、图和环境变量的配置文件路径。
`--help`		显示此消息并退出。

示例：

npx @langchain/langgraph-cli dockerfile -c langgraph.json Dockerfile

这会生成一个类似如下内容的 Dockerfile：

FROM langchain/langgraphjs-api:20

ADD . /deps/agent

RUN cd /deps/agent && yarn install

ENV LANGSERVE_GRAPHS='{"agent":"./src/react_agent/graph.ts:graph"}'

WORKDIR /deps/agent

RUN (test ! -f /api/langgraph_api/js/build.mts && echo "未找到预构建脚本，跳过") || tsx /api/langgraph_api/js/build.mts

npx @langchain/langgraph-cli dockerfile 命令会将 langgraph.json 文件中的所有配置转换为 Dockerfile 命令。使用此命令时，每次更新 langgraph.json 文件后都必须重新运行该命令。否则，在构建或运行 Dockerfile 时不会反映这些更改。

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

Deployment components

Develop & test

Frameworks and platforms

Reference

安装

快速命令

配置文件

示例

基本配置

使用 Wolfi 基础镜像

向存储添加语义搜索

使用自定义嵌入函数进行语义搜索

添加自定义身份验证

配置存储条目的生存时间

配置检查点生存时间

配置检查点器 serde

自定义 HTTP 中间件和标头

配置 Webhook

固定 API 版本

禁用内置路由

基本配置

固定 API 版本

禁用内置路由

命令

`dev`

`build`

`deploy`

`deploy list`

`deploy revisions`

`deploy revisions list`

`deploy delete`

`deploy logs`

`up`

`dockerfile`

​安装

​快速命令

​配置文件

​示例

​基本配置

​使用 Wolfi 基础镜像

​向存储添加语义搜索

​使用自定义嵌入函数进行语义搜索

​添加自定义身份验证

​配置存储条目的生存时间

​配置检查点生存时间

​配置检查点器 serde

​自定义 HTTP 中间件和标头

​配置 Webhook

​固定 API 版本

​禁用内置路由

​基本配置

​固定 API 版本

​禁用内置路由

​命令

​dev

​build

​deploy

​deploy list

​deploy revisions

​deploy revisions list

​deploy delete

​deploy logs

​up

​dockerfile

安装

快速命令

配置文件

示例

基本配置

使用 Wolfi 基础镜像

向存储添加语义搜索

使用自定义嵌入函数进行语义搜索

添加自定义身份验证

配置存储条目的生存时间

配置检查点生存时间

配置检查点器 serde

自定义 HTTP 中间件和标头

配置 Webhook

固定 API 版本

禁用内置路由

基本配置

固定 API 版本

禁用内置路由

命令

`dev`

`build`

`deploy`

`deploy list`

`deploy revisions`

`deploy revisions list`

`deploy delete`

`deploy logs`

`up`

`dockerfile`