LangGraph CLI¶

LangGraph 命令行界面包含在 Docker 中本地构建和运行 LangGraph Cloud API 服务器的命令。对于开发和测试，您可以使用 CLI 部署本地 API 服务器。

安装¶

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

安装 CLI 包

PythonJS

pip install langgraph-cli

npx @langchain/langgraph-cli

# Install globally, will be available as `langgraphjs`
npm install -g @langchain/langgraph-cli

运行命令 langgraph --help 或 npx @langchain/langgraph-cli --help 以确认 CLI 正常工作。

配置文件¶

LangGraph CLI 需要一个遵循此 schema 的 JSON 配置文件。它包含以下属性

注意

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

PythonJS

键	描述
`dependencies`	必需。LangGraph Cloud 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`）
`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` 配置文件的路径。
`dockerfile_lines`	在从父镜像导入后添加到 Dockerfile 的额外行数组。
`checkpointer`	checkpointer 的配置。包含一个 `ttl` 字段，它是一个包含以下键的对象 `strategy`：如何处理过期的检查点（例如，`"delete"`）。 `sweep_interval_minutes`：检查过期检查点的频率（整数，以分钟为单位）。 `default_ttl`：检查点的默认存活时间，以分钟为单位（整数）。定义在应用指定策略之前检查点保留多久。
`http`	HTTP 服务器配置，包含以下字段 `app`：自定义 Starlette/FastAPI 应用的路径（例如，`"./src/agent/webapp.py:app"`）。详见自定义路由指南。 `disable_assistants`：禁用 `/assistants` 路由 `disable_threads`：禁用 `/threads` 路由 `disable_runs`：禁用 `/runs` 路由 `disable_store`：禁用 `/store` 路由 `disable_meta`：禁用 `/ok`、`/info`、`/metrics` 和 `/docs` 路由 `cors`：CORS 配置，包含 `allow_origins`、`allow_methods`、`allow_headers` 等字段。 `configurable_headers`：定义哪些请求头应作为运行的可配置值被排除或包含。

键	描述
`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`	checkpointer 的配置。包含一个 `ttl` 字段，它是一个包含以下键的对象 `strategy`：如何处理过期的检查点（例如，`"delete"`）。 `sweep_interval_minutes`：检查过期检查点的频率（整数，以分钟为单位）。 `default_ttl`：检查点的默认存活时间，以分钟为单位（整数）。定义在应用指定策略之前检查点保留多久。

示例¶

PythonJS

基本配置¶

{
  "dependencies": ["."],
  "graphs": {
    "chat": "./chat/graph.py:graph"
  }
}

为存储添加语义搜索¶

所有部署都配备了基于数据库的 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]]:
    """Custom embedding function for semantic search."""
    # Implementation using your preferred embedding model
    return [[0.1, 0.2, ...] for _ in texts]  # dims-dimensional vectors

添加自定义认证¶

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

详见认证概念指南，以及设置自定义认证指南以获取实际操作步骤。

配置存储项存活时间 (TTL)¶

您可以使用 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 分钟）、读取时刷新以及每小时清理的示例

{
  "dependencies": ["."],
  "graphs": {
    "memory_agent": "./agent/graph.py:graph"
  },
  "store": {
    "ttl": {
      "refresh_on_read": true,
      "sweep_interval_minutes": 60,
      "default_ttl": 10080 
    }
  }
}

配置检查点存活时间 (TTL)¶

您可以使用 checkpointer 键配置检查点（checkpoint）的存活时间（TTL）。这决定了检查点数据在根据指定策略（例如，删除）自动处理之前保留多长时间。ttl 配置是一个包含以下字段的对象

strategy：对过期检查点执行的操作（目前 "delete" 是唯一接受的选项）。
sweep_interval_minutes：系统检查过期检查点的频率（以分钟为单位）。
default_ttl：检查点的默认生命周期，以**分钟**为单位（整数）。定义在应用指定策略之前检查点保留多久。

这是一个设置默认 TTL 为 30 天（43200 分钟）的示例

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

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

基本配置¶

{
  "graphs": {
    "chat": "./src/graph.ts:graph"
  }
}

命令¶

用法

PythonJS

LangGraph CLI 的基本命令是 langgraph。

langgraph [OPTIONS] COMMAND [ARGS]

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

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

我们建议使用 npx 来始终使用最新版本的 CLI。

dev¶

PythonJS

在开发模式下运行 LangGraph API 服务器，具有热重载和调试功能。这个轻量级服务器不需要安装 Docker，适用于开发和测试。状态会持久化到本地目录。

注意

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

安装

此命令需要安装 `"inmem"` 额外依赖项

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`		要连接到的 LangGraph 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`		要连接到的 LangGraph Studio 实例的 URL。默认为 https://smith.langchain.com
`--allow-blocking`	`False`	对代码中的同步 I/O 阻塞操作不引发错误
`--tunnel`	`False`	通过公共隧道 (Cloudflare) 暴露本地服务器，以便远程前端访问。这可以避免浏览器或网络阻止 localhost 连接的问题
`--help`		显示命令文档

build¶

PythonJS

构建 LangGraph Cloud 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 镜像构建。使用 `--no-pull` 运行使用本地构建镜像的 LangGraph Cloud API 服务器。
`-c, --config FILE`	`langgraph.json`	声明依赖项、图和环境变量的配置文件的路径。
`--help`		显示命令文档。

构建 LangGraph Cloud 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`		显示命令文档。

up¶

PythonJS

启动 LangGraph API 服务器。对于本地测试，需要一个具有 LangGraph Cloud 封闭测试访问权限的 LangSmith API 密钥。对于生产使用，需要许可证密钥。

用法

langgraph up [OPTIONS]

选项

选项	默认值	描述
`--wait`		返回前等待服务启动。隐含 `--detach`
`--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 服务器。对于本地测试，需要一个具有 LangGraph Cloud 封闭测试访问权限的 LangSmith API 密钥。对于生产使用，需要许可证密钥。

用法

npx @langchain/langgraph-cli up [OPTIONS]

选项

选项	默认值	描述
`--wait`		返回前等待服务启动。隐含 `--detach`
`--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¶

PythonJS

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

用法

langgraph dockerfile [OPTIONS] SAVE_PATH

选项

选项	默认值	描述
`-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_community 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.json 文件

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

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

用法

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

选项

选项	默认值	描述
`-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 "Prebuild script not found, skipping") || tsx /api/langgraph_api/js/build.mts

更新您的 langgraph.json 文件

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