LangGraph CLI

LangGraph CLI 是一个用于在本地构建和运行代理服务器的命令行工具。生成的服务器会暴露所有用于运行、线程、助手等的 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 部署。
`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` 的对象，用于控制检查点过期。 `serde`（可选，0.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 交付（不是路由切换）。请参阅禁用 webhooks。 `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` 的对象，用于控制检查点过期。 `serde`（可选，0.5+）：包含 `allowed_json_modules` 和 `pickle_fallback` 的对象，用于调整反序列化行为。
`http`	HTTP 服务器配置，镜像 Python 选项： `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]  # 维度向量

添加自定义认证

{
  "$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，共同设置检查点如何过期。
serde （代理服务器 0.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 环境变量的功能。

配置 webhooks

你可以为出站 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 限制的详细信息，请参阅使用 webhooks。

固定 API 版本

（在 v0.3.7 中添加）你可以使用 api_version 键固定代理服务器的 API 版本。如果你想确保服务器使用特定版本的 API，这很有用。默认情况下，云部署中的构建使用服务器的最新稳定版本。可以通过将 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 和 webhooks，请参阅各自的指南：禁用 MCP、禁用 A2A、禁用 webhooks。

基本配置

{
  "$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” 扩展：

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 镜像进行构建。使用 `--no-pull` 以使用本地构建的镜像运行 LangSmith API 服务器。
`-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 部署。此命令在本地构建 Docker 镜像，将其推送到托管注册表，并创建或更新部署——所有这些都在一个步骤中完成。先决条件

必须安装 Docker 并且 Docker 守护程序必须正在运行。安装 Docker Desktop。
在非 x86_64 机器（例如 Apple Silicon）上，需要 Docker Buildx 才能为 linux/amd64 进行交叉编译。了解更多关于 Buildx 的信息。
一个具有访问部署权限的 LangSmith API 密钥。

远程构建（无需 Docker）将在未来的更新中推出。

用法

langgraph deploy [OPTIONS] [DOCKER_BUILD_ARGS]

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

选项	默认值	描述
`--api-key TEXT`		LangSmith 部署的 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`	`dev`	部署类型（`dev` 或 `prod`）。在创建新部署时使用。
`--no-wait`	`False`	推送后跳过等待部署状态。
`--verbose`	`False`	显示详细输出，包括 Docker 构建和推送日志。
`--help`		显示命令文档。

示例

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

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

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

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

langgraph deploy 命令只能更新最初由 langgraph deploy 创建的部署。通过其他方法（例如 LangSmith UI 或 GitHub 集成）创建的部署无法使用此命令更新。

`deploy list`

列出 LangSmith 部署。用法

langgraph deploy list [OPTIONS]

选项

选项	默认值	描述
`--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]...

选项

选项	默认值	描述
`--help`		显示此消息并退出。

命令

命令	描述
`list`	[Beta] 列出 LangSmith 部署的修订版。

`deploy revisions list`

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

langgraph deploy revisions list [OPTIONS] DEPLOYMENT_ID

选项

选项	默认值	描述
`--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

选项

选项	默认值	描述
`--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]

选项

选项	默认值	描述
`-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]

选项

选项	默认值	描述
`--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]

选项

选项	默认值	描述
`--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

选项

选项	默认值	描述
`-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 dockerfile 命令将你的 langgraph.json 文件中的所有配置转换为 Dockerfile 命令。使用此命令时，每次更新 langgraph.json 文件后都必须重新运行它。否则，你的更改在构建或运行 dockerfile 时不会反映出来。

生成用于构建 LangSmith 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

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

将这些文档连接到 Claude、VSCode 等，通过 MCP 获取实时答案。

在 GitHub 上编辑此页面或提交问题。

LangSmith Deployment

Releases

安装

快速命令

配置文件

示例

基本配置

使用 Wolfi 基础镜像

向存储添加语义搜索

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

添加自定义认证

配置存储项目生存时间

配置检查点生存时间

配置检查点 serde

自定义 HTTP 中间件和头

配置 webhooks

固定 API 版本

禁用内置路由

基本配置

固定 API 版本

禁用内置路由

命令

`dev`

`build`

`deploy`

`deploy list`

`deploy revisions`

`deploy revisions list`

`deploy delete`

`deploy logs`

`up`

`dockerfile`

​安装

​快速命令

​配置文件

​示例

​基本配置

​使用 Wolfi 基础镜像

​向存储添加语义搜索

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

​添加自定义认证

​配置存储项目生存时间

​配置检查点生存时间

​配置检查点 serde

​自定义 HTTP 中间件和头

​配置 webhooks

​固定 API 版本

​禁用内置路由

​基本配置

​固定 API 版本

​禁用内置路由

​命令

​dev

​build

​deploy

​deploy list

​deploy revisions

​deploy revisions list

​deploy delete

​deploy logs

​up

​dockerfile

安装

快速命令

配置文件

示例

基本配置

使用 Wolfi 基础镜像

向存储添加语义搜索

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

添加自定义认证

配置存储项目生存时间

配置检查点生存时间

配置检查点 serde

自定义 HTTP 中间件和头

配置 webhooks

固定 API 版本

禁用内置路由

基本配置

固定 API 版本

禁用内置路由

命令

`dev`

`build`

`deploy`

`deploy list`

`deploy revisions`

`deploy revisions list`

`deploy delete`

`deploy logs`

`up`

`dockerfile`